Localização do JavaScript em aplicativos ASP.NET Core Blazor

• Carregar o script na <head> marcação (Geralmente não é recomendado)
• Carregar um script na marcação de <body>
• Carregar um script de um arquivo JavaScript externo (.js) localizado junto a um componente
• Carregar um script de um arquivo JavaScript externo (.js)
• Injetar um script antes ou após o Blazor início

• Carregar um script em marcação <head> (geralmente não recomendado)
• Carregar um script na marcação de <body>
• Carregar um script de um arquivo JavaScript externo (.js)
• Injetar um script após o início de Blazor

Coloque apenas uma marcação de <script> em um arquivo de componente (.razor) se for garantido que o componente adotará a renderização estática do lado do servidor (SSR estático) sem navegação aprimorada . 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 ou SSR estático aprimorado com navegação.

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

Na marcação de componente, os scripts podem ser carregados por meio de um componente HeadContent com a ressalva usual de que essa abordagem pode diminuir a velocidade de carregamento da página no cliente, o que recomendamos evitar. Quando um script é carregado com um componente HeadContent em um aplicativo Blazor Server, Blazor WebAssembly ou Blazor Web App usando um modo de renderização interativo (SSR interativo, CSR) ou SSR estático com navegação avançada, navegar para fora da página do componente remove a etiqueta <script> do conteúdo renderizado <head>, mas não descarrega o código 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 que usam SSR estático sem navegação aprimorada descarregam o código JavaScript quando o usuário sai da página. Geralmente, é melhor adicionar marcações <script> ao conteúdo <head> físico, a menos que você queira 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 componente, os scripts podem ser carregados por meio de um componente HeadContent com a ressalva usual de que essa abordagem pode diminuir a velocidade de carregamento da página no cliente, o que recomendamos evitar. Quando um script é carregado com um componente HeadContent, sair da página do componente remove a marcação <script> do conteúdo <head> renderizado, mas não descarrega o código JavaScript do script, incluindo manipuladores de eventos que o script registra, variáveis expostas e métodos fornecidos pelo script. Geralmente, é melhor adicionar marcações <script> ao conteúdo <head> físico, a menos que você queira 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 de um arquivo JavaScript externo (.js) localizado junto a um componente

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

Os componentes Razor de aplicativos Blazor colocam arquivos JS usando a extensão .razor.js e são endereçáveis publicamente usando o caminho para o arquivo no projeto:

{PATH}/{COMPONENT}.razor.js

• O {PATH} placeholder é o caminho para o componente.
• O placeholder {COMPONENT} é o componente.

Quando o aplicativo é publicado, o framework 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 estão os marcadores de posição:

• {TARGET FRAMEWORK MONIKER} é o Target Framework Moniker (TFM).
• {PATH} é o caminho para o componente.
• {COMPONENT} é o nome do componente.

Nenhuma alteração é necessária para a URL relativa do script, pois Blazor cuida de colocar o arquivo JS em ativos estáticos publicados para você.

Esta seção e os exemplos a seguir se concentram principalmente em explicar a colocação de arquivos JS. O primeiro exemplo demonstra um arquivo colocado JS com uma função comum JS. O segundo exemplo demonstra a utilização de um módulo para carregar uma função, que é a abordagem recomendada para a maioria dos aplicativos de produção. Chamar JS a partir do .NET é totalmente abordado em Chamar funções JavaScript de métodos .NET no ASP.NET Core Blazor, em que há mais explicações sobre a API BlazorJS com exemplos adicionais. O descarte de componentes, que está presente no segundo exemplo, é abordado no descarte de componentes do ASP.NET CoreRazor.

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.

Adicione o script a seguir após o script Blazor (local do script inicial 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 colocado JS é colocado ao lado do arquivo de componente JsCollocation1 com o nome do arquivo 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 a abordagem 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 co-localizado, como demonstra o próximo exemplo.

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

Componente JsCollocation2 ({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 Task 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 o descarte do módulo, caso o circuito de Blazor's SignalR seja perdido. Se o código anterior for usado em um aplicativo Blazor WebAssembly, não haverá conexão SignalR a perder, portanto, você poderá remover o bloco try-catch e deixar a linha que descarta o módulo (await module.DisposeAsync();). Para obter mais informações, confira Interoperabilidade ASP.NET Core Blazor JavaScript (interoperabilidade JS).

{PATH}/JsCollocation2.razor.js:

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

O uso de scripts e módulos para JS agrupados em uma biblioteca de classes de Razor (RCL) só tem suporte para JSmecanismo de interoperabilidade de Blazor com base na interface IJSRuntime. Se você estiver implementando a interop [JSImport]/[JSExport] JavaScript, consulte Interop JSImport/JSExport JavaScript com o ASP.NET Core Blazor.

Para scripts ou módulos fornecidos por uma biblioteca de classes (RCL) Razor, usando interop JS baseada emIJSRuntime, o seguinte caminho é usado:

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

• O segmento de caminho para o diretório atual (./) é necessário para criar o caminho de ativo estático correto para o arquivo JS.
• O espaço reservado {PACKAGE ID} é o identificador do pacote da RCL (ou nome da biblioteca para uma biblioteca de classes referenciada pelo aplicativo).
• 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 placeholder {EXTENSION} corresponde à extensão do componente, seja razor ou cshtml.

No seguinte exemplo de aplicativo Blazor:

• O identificador do 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 do ASP.NET Core Razor de uma Razor biblioteca de classes (RCL).

Injetar um script antes ou depois que Blazor iniciar

Para garantir que os scripts carreguem antes ou após o início de Blazor, use um inicializador JavaScript. Para obter mais informações e exemplos, veja Inicialização de Blazor no ASP.NET Core.

Injetar um script após o início de Blazor

Para injetar um script após a inicialização de Blazor, encadeie para o Promise que resulta de um início manual de Blazor. Para obter mais informações e um exemplo, veja Inicialização de Blazor no ASP.NET Core.