Partilhar via

Localização do JavaScript nas aplicações ASP.NET Core Blazor

  • Artigo

Observação

Esta não é a versão mais recente deste artigo. Para a versão atual, consulte a versão .NET 9 deste artigo.

Advertência

Esta versão do ASP.NET Core não é mais suportada. Para obter mais informações, consulte a Política de suporte do .NET e .NET Core. Para a versão atual, consulte a versão .NET 9 deste artigo.

Importante

Estas informações referem-se a um produto de pré-lançamento que pode ser substancialmente modificado antes de ser lançado comercialmente. A Microsoft não oferece garantias, expressas ou implícitas, em relação às informações fornecidas aqui.

Para a versão atual, consulte a versão .NET 9 deste artigo.

Carregue o código JavaScript (JS) usando qualquer uma das seguintes abordagens:

Localização das tags <script>

Coloque apenas uma tag <script> em um arquivo de componente (.razor) se o componente tiver a garantia de adotar renderização estática do lado do servidor (SSR estático) porque a tag <script> não pode ser atualizada dinamicamente. Colocar uma marca <script> em um arquivo de componente não produz um aviso ou erro em tempo de compilação, mas o comportamento de carregamento de script pode não corresponder às suas expectativas em componentes que não adotam SSR estático quando o componente é renderizado.

Não coloque uma tag <script> em um arquivo de componente (.razor) porque a tag <script> não pode ser atualizada dinamicamente. Colocar uma tag <script> em um arquivo de componente produz um erro em tempo de compilação.

Observação

Exemplos de documentação geralmente colocam scripts em uma tag <script> ou carregam scripts globais de arquivos externos. Estas abordagens poluem o cliente com funções globais. Para aplicativos de produção, recomendamos colocáJS em módulos JS separados que podem ser importados quando necessário. Para obter mais informações, consulte a seção isolamento de JavaScript em módulos JavaScript.

Observação

Exemplos de documentação colocam scripts em uma tag <script> ou carregam scripts globais de arquivos externos. Estas abordagens poluem o cliente com funções globais. Colocar JS em módulos JS separados que podem ser importados quando necessário não suportado em Blazor anteriores ao ASP.NET Core 5.0. Se a aplicação exigir o uso de módulos JS para o isolamento de JS, recomendamos usar ASP.NET Core 5.0 ou posterior para construir a aplicação. Para obter mais informações, use a lista suspensa Versão para selecionar uma versão 5.0 ou posterior deste artigo e veja a secção isolamento de JavaScript em módulos JavaScript.

Carregar um script na marcação <head>

A abordagem nesta seção geralmente não é recomendada.

Coloque as tags JavaScript (JS) (<script>...</script>) na marcação do elemento <head>:

<head>
    ...

    <script>
      window.jsMethod = (methodParameter) => {
        ...
      };
    </script>
</head>

Carregar o JS a partir do <head> não é a melhor abordagem pelos seguintes motivos:

  • JS interoperabilidade pode falhar se o script depender de Blazor. Recomendamos carregar scripts usando uma das outras abordagens, não por meio da marcação <head>.
  • A página pode se tornar interativa mais lenta devido ao tempo que leva para analisar o JS no script.

Carregar um script na marcação <body>

Coloque as tags JavaScript (<script>...</script>) dentro do fechando </body> elemento após a referência de script Blazor:

<body>
    ...

    <script src="{BLAZOR SCRIPT}"></script>
    <script>
      window.jsMethod = (methodParameter) => {
        ...
      };
    </script>
</body>

No exemplo anterior, o espaço reservado {BLAZOR SCRIPT} é o caminho do script Blazor e o nome do ficheiro. Para obter o local do script, consulte ASP.NET Core estrutura do projeto Blazor.

Carregar um script a partir de um ficheiro JavaScript externo (.js) associado a um componente

A colocação de arquivos JavaScript (JS) para componentes Razor é uma maneira conveniente de organizar scripts numa aplicação.

Razor componentes de aplicações Blazor organizam JS ficheiros usando a extensão .razor.js e podem ser acedidos publicamente através do caminho do ficheiro no projeto:

{PATH}/{COMPONENT}.razor.js

  • O {PATH} é o marcador de posição que indica o caminho para o componente.
  • O placeholder {COMPONENT} é o componente.

Quando o aplicativo é publicado, a estrutura move automaticamente o script para a raiz da Web. Os scripts são movidos para bin/Release/{TARGET FRAMEWORK MONIKER}/publish/wwwroot/{PATH}/{COMPONENT}.razor.js, onde os espaços reservados são:

Nenhuma alteração é necessária na URL relativa do script, pois Blazor se encarrega de adicionar o arquivo JS nos ativos estáticos já publicados para você.

Esta seção e os exemplos a seguir concentram-se principalmente em explicar a colocação de ficheiros JS. O primeiro exemplo demonstra um arquivo JS colocado com uma função JS comum. O segundo exemplo demonstra o uso de um módulo para carregar uma função, que é a abordagem recomendada para a maioria dos aplicativos de produção. Chamar JS do .NET é totalmente coberto em Chamar funções JavaScript dos métodos .NET no ASP.NET Core Blazor, onde há mais explicações sobre a API BlazorJS com exemplos adicionais. A eliminação de componentes, que está presente no segundo exemplo, é abordada em ASP.NETciclo de vida do componente Core Razor .

O componente JsCollocation1 a seguir carrega um script por meio de um componente HeadContent e chama uma função JS com IJSRuntime.InvokeAsync. O espaço reservado {PATH} é o caminho para o componente.

Importante

Se você usar o código a seguir para uma demonstração em um aplicativo de teste, altere o espaço reservado {PATH} para o caminho do componente (exemplo: Components/Pages no .NET 8 ou posterior ou Pages no .NET 7 ou anterior). Em um Blazor Web App (.NET 8 ou posterior), o componente requer um modo de renderização interativo aplicado globalmente ao aplicativo ou à definição do componente.

Adicione o seguinte script, após o script Blazor, (localização do início do script Blazor):

<script src="{PATH}/JsCollocation1.razor.js"></script>

Componente JsCollocation1 ({PATH}/JsCollocation1.razor)

@page "/js-collocation-1"
@inject IJSRuntime JS

<PageTitle>JS Collocation 1</PageTitle>

<h1>JS Collocation Example 1</h1>

<button @onclick="ShowPrompt">Call showPrompt1</button>

@if (!string.IsNullOrEmpty(result))
{
    <p>
        Hello @result!
    </p>
}

@code {
    private string? result;

    public async Task ShowPrompt()
    {
        result = await JS.InvokeAsync<string>(
            "showPrompt1", "What's your name?");
        StateHasChanged();
    }
}

O arquivo JS é colocado ao lado do arquivo componente JsCollocation1 com o nome de JsCollocation1.razor.js. No componente JsCollocation1, o script é referenciado no caminho do arquivo colocado. No exemplo a seguir, a função showPrompt1 aceita o nome do usuário de um Window prompt() e o retorna ao componente JsCollocation1 para exibição.

{PATH}/JsCollocation1.razor.js:

function showPrompt1(message) {
  return prompt(message, 'Type your name here');
}

A abordagem anterior não é recomendada para uso geral em aplicativos de produção porque polui o cliente com funções globais. Uma abordagem melhor para aplicativos de produção é usar módulos JS. Os mesmos princípios gerais se aplicam ao carregamento de um módulo JS a partir de um arquivo JS colocado, como demonstra o próximo exemplo.

O método OnAfterRenderAsync do componente JsCollocation2 seguinte carrega um módulo JS em module, que é um IJSObjectReference da classe do componente. module é usado para chamar a função showPrompt2. O espaço reservado {PATH} é o caminho para o componente.

Importante

Se utilizar o seguinte código para uma demonstração numa aplicação de teste, altere o espaço reservado {PATH} para o caminho do componente. Em um Blazor Web App (.NET 8 ou posterior), o componente requer um modo de renderização interativo aplicado globalmente ao aplicativo ou à definição do componente.

JsCollocation2 componente ({PATH}/JsCollocation2.razor):

@page "/js-collocation-2"
@implements IAsyncDisposable
@inject IJSRuntime JS

<PageTitle>JS Collocation 2</PageTitle>

<h1>JS Collocation Example 2</h1>

<button @onclick="ShowPrompt">Call showPrompt2</button>

@if (!string.IsNullOrEmpty(result))
{
    <p>
        Hello @result!
    </p>
}

@code {
    private IJSObjectReference? module;
    private string? result;

    protected async override Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            /*
                Change the {PATH} placeholder in the next line to the path of
                the collocated JS file in the app. Examples:

                ./Components/Pages/JsCollocation2.razor.js (.NET 8 or later)
                ./Pages/JsCollocation2.razor.js (.NET 7 or earlier)
            */
            module = await JS.InvokeAsync<IJSObjectReference>("import",
                "./{PATH}/JsCollocation2.razor.js");
        }
    }

    public async void ShowPrompt()
    {
        if (module is not null)
        {
            result = await module.InvokeAsync<string>(
                "showPrompt2", "What's your name?");
            StateHasChanged();
        }
    }

    async ValueTask IAsyncDisposable.DisposeAsync()
    {
        if (module is not null)
        {
            try
            {
                await module.DisposeAsync();
            }
            catch (JSDisconnectedException)
            {
            }
        }
    }
}

No exemplo anterior, JSDisconnectedException é retido durante a eliminação do módulo, caso o circuito SignalR de Blazorseja perdido. Se o código anterior for usado em um aplicativo Blazor WebAssembly, não há conexão SignalR a perder, então você pode remover o bloco de try-catch e deixar a linha que descarta o módulo (await module.DisposeAsync();). Para obter mais informações, consulte ASP.NET Core Blazor interoperabilidade JavaScript (JS interop).

{PATH}/JsCollocation2.razor.js:

export function showPrompt2(message) {
  return prompt(message, 'Type your name here');
}

O uso de scripts e módulos para JS colocados em uma biblioteca de classe Razor (RCL) só é suportado para o mecanismo de interoperabilidade JS do Blazorbaseado na interface IJSRuntime. Se estiveres a implementar interop [JSImport]/[JSExport] JavaScript, consulta interop JSImport/JSExport com ASP.NET Core Blazor.

Para scripts ou módulos fornecidos por uma biblioteca de classes Razor (RCL) usando a interoperabilidade baseada em IJSRuntimede JS, o seguinte caminho é utilizado:

./_content/{PACKAGE ID}/{PATH}/{COMPONENT}.{EXTENSION}.js

  • O segmento de caminho para o diretório atual (./) é necessário para criar o caminho correto dos ativos estáticos para o ficheiro JS.
  • O espaço reservado {PACKAGE ID} é o identificador de pacote da RCL (ou o nome da biblioteca de uma biblioteca de classes referenciada pela aplicação).
  • O espaço reservado {PATH} é o caminho para o componente. Se um componente Razor estiver localizado na raiz da RCL, o segmento de caminho não será incluído.
  • O espaço reservado {COMPONENT} é o nome do componente.
  • O espaço reservado {EXTENSION} corresponde à extensão do componente, podendo ser razor ou cshtml.

No seguinte exemplo de aplicativo Blazor:

  • O identificador de pacote da RCL é AppJS.
  • Os scripts de um módulo são carregados para o componente JsCollocation3 (JsCollocation3.razor).
  • O componente JsCollocation3 está na pasta Components/Pages da RCL.
module = await JS.InvokeAsync<IJSObjectReference>("import", 
    "./_content/AppJS/Components/Pages/JsCollocation3.razor.js");

Para obter mais informações sobre RCLs, consulte Consumir componentes ASP.NET Core Razor de uma biblioteca de classes Razor (RCL).

Carregar um script a partir de um ficheiro JavaScript externo (.js)

Coloque as tags JavaScript (JS) (<script>...</script>) com um caminho de origem de script (src) dentro do fechando </body> elemento após a referência de script Blazor:

<body>
    ...

    <script src="{BLAZOR SCRIPT}"></script>
    <script src="{SCRIPT PATH AND FILE NAME (.js)}"></script>
</body>

Quanto aos marcadores do exemplo anterior:

  • O espaço reservado {BLAZOR SCRIPT} é o caminho e o nome do ficheiro do script Blazor. Para o local do script, consulte a estrutura do projeto ASP.NET Core Blazor.
  • O espaço reservado {SCRIPT PATH AND FILE NAME (.js)} refere-se ao caminho do ficheiro de script e ao seu nome no âmbito de wwwroot.

No exemplo a seguir da tag <script> anterior, o arquivo scripts.js está na pasta wwwroot/js do aplicativo:

<script src="js/scripts.js"></script>

Você também pode servir scripts diretamente da pasta wwwroot se preferir não manter todos os scripts em uma pasta separada em wwwroot:

<script src="scripts.js"></script>

Quando o arquivo JS externo for fornecido por uma biblioteca de classes Razor, especifique o arquivo JS usando seu caminho estável dos ativos web estáticos: _content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}:

  • O marcador de posição {PACKAGE ID} é o identificador do pacote da biblioteca. O ID do pacote assume como padrão o nome do assembly do projeto se <PackageId> não for especificado no arquivo do projeto.
  • O espaço reservado {SCRIPT PATH AND FILE NAME (.js)} é o caminho e o nome do arquivo em wwwroot.
<body>
    ...

    <script src="{BLAZOR SCRIPT}"></script>
    <script src="_content/{PACKAGE ID}/{SCRIPT PATH AND FILE NAME (.js)}"></script>
</body>

No exemplo a seguir da tag <script> anterior:

  • A biblioteca de classes Razor tem um nome de assembly de ComponentLibrarye um <PackageId> não é especificado no arquivo de projeto da biblioteca.
  • O arquivo scripts.js está na pasta wwwroot da biblioteca de classes.
<script src="_content/ComponentLibrary/scripts.js"></script>

Para obter mais informações, consulte Consumir componentes do ASP.NET Core Razor de uma biblioteca de classes (RCL) Razor.

Injetar um script antes ou depois do início de Blazor

Para garantir que os scripts sejam carregados antes ou depois de Blazor começar, use um inicializador JavaScript. Para obter mais informações e exemplos, consulte ASP.NET Core Blazor startup.

Injetar um script depois de Blazor começar

Para injetar um script após o início de Blazor, encadeie ao Promise que resulta de um arranque manual de Blazor. Para obter mais informações e um exemplo, consulte ASP.NET Core Blazor startup.

Isolamento de JavaScript em módulos JavaScript

Blazor permite o isolamento de JavaScript (JS) em módulos padrão de JS (especificação ECMAScript).

JS isolamento oferece os seguintes benefícios:

  • Os JS importados não poluem mais o namespace global.
  • Os utilizadores de uma biblioteca e dos seus componentes não são obrigados a importar os elementos JSrelacionados.

Em cenários de servidor, sempre intercepte JSDisconnectedException caso a perda do circuito SignalR de Blazorimpeça uma chamada de interop JS de descartar um módulo, resultando em uma exceção não tratada. Blazor WebAssembly aplicações não usam uma conexão SignalR durante a JS interoperabilidade, portanto, não há necessidade de capturar JSDisconnectedException em aplicações Blazor WebAssembly para eliminação de módulos.

Para obter mais informações, consulte os seguintes recursos: