Ler em inglês

Partilhar via

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

  • Artigo

Nota

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

Aviso

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:

JavaScript embutido não é recomendado para aplicativos Blazor. Recomendamos o uso de JS de colocação combinada com JS módulos.

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 tag <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 adotam um modo de renderização interativo.

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.

Nota

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.

Nota

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>:

HTML 
<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.

Na marcação de componentes, os scripts podem ser carregados por meio de um componente HeadContent, com a ressalva habitual de que a abordagem retarda a carga da página no cliente, algo que recomendamos evitar. Quando um script é carregado com um componente HeadContent num aplicativo Blazor Server, num aplicativo Blazor WebAssembly ou num Blazor Web App usando um modo de renderização interativo (SSR interativo, CSR), sair da página do componente remove a etiqueta <script> do conteúdo renderizado <head>, mas não descarrega o JavaScript do script, incluindo manipuladores de eventos que o script registra, variáveis expostas e métodos que o script fornece. Somente Blazor Web Apps usando SSR estático descarregam o código JavaScript quando o usuário navega para fora da página. Geralmente, é melhor adicionar <script> tags ao conteúdo físico <head>, a menos que deseje explicitamente manter essas referências de script nos componentes que as usam e não se importe que o código não seja descarregado em eventos de navegação.

Na marcação de componentes, os scripts podem ser carregados por meio de um componente HeadContent, com a ressalva habitual de que a abordagem retarda a carga da página no cliente, algo que recomendamos evitar. Quando um script é carregado com um componente HeadContent, navegar para fora da página do componente remove a etiqueta <script> do conteúdo <head> renderizado, mas não descarrega o código JavaScript do script, incluindo os manipuladores de eventos que o script registra, as variáveis que o script expõe, e os métodos que o script fornece. Geralmente, é melhor adicionar <script> tags ao conteúdo físico <head>, a menos que deseje explicitamente manter essas referências de script nos componentes que as usam e não se importe que o código não seja descarregado em eventos de navegação.

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:

HTML 
<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 Razorciclo de vida do componente Core .

O componente JsCollocation1 a seguir carrega um script por meio de um componente HeadContent e chama uma função JS com IJSRuntime.InvokeAsync. O {PATH} é o marcador de posição que indica 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):

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

Componente JsCollocation1 ({PATH}/JsCollocation1.razor)

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:

JavaScript 
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 JsCollocation2 do componente OnAfterRenderAsync seguinte carrega um módulo JS em module, que é um IJSObjectReference da classe do componente. module é usado para chamar a função showPrompt2. O {PATH} é o marcador de posição que indica 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.

Componente JsCollocation2 ({PATH}/JsCollocation2.razor)

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 Blazor de SignalRseja 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:

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

Importante

Não coloque uma tag <script> para JsCollocation2.razor.js depois do script Blazor porque o módulo é carregado e armazenado em cache automaticamente quando o import() dinâmico é invocado.

O uso de scripts e módulos para JS colocados em uma biblioteca de classe Razor (RCL) só é suportado para o mecanismo de interoperabilidade Blazor do JSbaseado 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 {PATH} é o marcador de posição que indica 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.
C# 
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:

HTML 
<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 obter o local do script, consulte ASP.NET Core estrutura do projeto 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:

HTML 
<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:

HTML 
<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.
HTML 
<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.
HTML 
<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 Blazor de SignalRimpeç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: