Interoperabilidade do JavaScript [JSImport]/[JSExport] com o ASP.NET Core Blazor

Este artigo explica como interagir com JavaScript (JS) em componentes do lado do cliente usando a API de interoperabilidade JavaScript (). JS[JSImport]/[JSExport] Para informações adicionais e exemplos, consulte a interoperabilidade JavaScript '[JSImport]'/'[JSExport]' em .NET WebAssembly.

Para obter orientações adicionais, consulte a orientação Configurando e hospedando aplicativos .NET WebAssembly no repositório GitHub do .NET Runtime (dotnet/runtime).

Blazor fornece o seu próprio JS mecanismo de interoperabilidade baseado na IJSRuntime interface. BlazorA interoperabilidade de JS é suportada de forma uniforme em todos os modos de renderização Blazor e para apps Blazor Hybrid. IJSRuntime Também permite que os autores de bibliotecas construam JS bibliotecas interop para partilha em todo o Blazor ecossistema e continua a ser a abordagem recomendada para JS interoperabilidade em Blazor. Consulte os seguintes artigos:

• Chamar funções JavaScript a partir de métodos .NET no ASP.NET Core Blazor
• Chamar métodos .NET a partir de funções JavaScript no ASP.NET Core Blazor

Este artigo descreve uma abordagem alternativa JS de interoperabilidade específica para componentes do lado do cliente executada em WebAssembly. Estas abordagens são adequadas quando apenas se espera executar no WebAssembly do lado do cliente. Os autores das bibliotecas podem usar estas abordagens para otimizar JS a interoperabilidade, verificando durante a execução do código se a aplicação está a correr no WebAssembly num navegador (OperatingSystem.IsBrowser). As abordagens descritas neste artigo devem ser usadas para substituir a obsoleta API de interoperabilidade não-marshalled JS ao migrar para o .NET 7 ou versões posteriores.

Observação

Este artigo centra-se na JS interoperabilidade em componentes do lado do cliente. Para orientações sobre como chamar .NET em aplicações JavaScript, consulte a interoperabilidade JavaScript '[JSImport]'/'[JSExport]' com um projeto de aplicação WebAssembly Browser.

API de interoperabilidade JavaScript obsoleta

A interoperabilidade sem marshalling JS usando IJSUnmarshalledRuntime API é obsoleta no ASP.NET Core em .NET 7 ou posteriores. Siga as orientações deste artigo para substituir a API obsoleta.

Pré-requisitos

Visual Studio com a carga de trabalho de ASP.NET e desenvolvimento web .

Não são necessárias mais ferramentas se planeias implementar [JSImport]/[JSExport] interoperabilidade numa Blazor WebAssembly aplicação gerada a partir do Blazor WebAssembly modelo do projeto.

Se planeia usar os modelos de projeto da aplicação WebAssembly Browser ou WebAssembly Console, instale o Microsoft.NET.Runtime.WebAssembly.Templates pacote NuGet com o seguinte comando:

dotnet new install Microsoft.NET.Runtime.WebAssembly.Templates

Para mais informações, consulte a interoperabilidade JavaScript '[JSImport]'/'[JSExport]' com um projeto de aplicação de navegador WebAssembly.

Namespace

A JS API de interoperabilidade (JSHost.ImportAsync) descrita neste artigo é controlada por atributos no System.Runtime.InteropServices.JavaScript namespace.

Ativar blocos inseguros

Ative a AllowUnsafeBlocks propriedade no ficheiro de projeto da aplicação, que permite que o gerador de código no compilador Roslyn utilize ponteiros para JS interoperação:

<PropertyGroup>
  <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
</PropertyGroup>

Advertência

A JS API de interoperabilidade requer a ativação do AllowUnsafeBlocks. Tenha cuidado ao implementar seu próprio código não seguro em aplicativos .NET, o que pode introduzir riscos de segurança e estabilidade. Para obter mais informações, consulte Código não seguro, tipos de ponteiro e ponteiros de função.

Razor a biblioteca de classes (RCL) colocada JS não é suportada

De um modo geral, o JS suporte de localização para interoperabilidade baseada em IJSRuntimeJS (localização de JavaScript em aplicações ASP.NET CoreBlazor) também está presente para a interoperabilidade [JSImport]/[JSExport] descrita neste artigo. A única funcionalidade de localização não suportada JS é para co-localizações JS numa Razor biblioteca de classes (RCL).

Em vez de usar collocado JS num RCL, coloque o JS ficheiro na pasta do wwwroot RCL e faça referência a ele usando o caminho habitual para os ativos estáticos do RCL:

_content/{PACKAGE ID}/{PATH}/{FILE NAME}.js

• O {PACKAGE ID} marcador de lugar é o identificador de pacote do RCL (ou nome da biblioteca de uma classe).
• O {PATH} placeholder representa o caminho para o ficheiro.
• O {FILE NAME} marcador de posição é o nome do ficheiro.

Embora a colocação JS num RCL não seja suportada pelo[JSImport]/[JSExport]interop, pode manter os seus JS ficheiros organizados adotando uma ou ambas as seguintes abordagens:

• Nomeie o JS ficheiro igual ao componente onde o JS é usado. Para um componente no RCL chamado CallJavaScriptFromLib (CallJavaScriptFromLib.razor), nomeie o ficheiro CallJavaScriptFromLib.js na wwwroot pasta.
• Coloque ficheiros JS específicos do componente num diretório Components dentro do diretório wwwroot do RCL e use "Components" no caminho para o ficheiro: _content/{PACKAGE ID}/Components/CallJavaScriptFromLib.js.

Chamar JavaScript a partir de .NET

Esta secção explica como chamar JS funções a partir do .NET.

No componente seguinte CallJavaScript1:

• O CallJavaScript1 módulo é importado assíncronamente a partir do ficheiro associado JS utilizando JSHost.ImportAsync.
• A função importada getMessageJS é chamada por GetWelcomeMessage.
• A cadeia de mensagens de boas-vindas devolvidas é exibida na interface através do message campo.

CallJavaScript1.razor:

@page "/call-javascript-1"
@rendermode InteractiveWebAssembly
@using System.Runtime.InteropServices.JavaScript

<h1>
    JS <code>[JSImport]</code>/<code>[JSExport]</code> Interop 
    (Call JS Example 1)
</h1>

@(message is not null ? message : string.Empty)

@code {
    private string? message;

    protected override async Task OnInitializedAsync()
    {
        await JSHost.ImportAsync("CallJavaScript1", 
            "../Components/Pages/CallJavaScript1.razor.js");

        message = GetWelcomeMessage();
    }
}

Observação

Inclua uma verificação condicional no código com OperatingSystem.IsBrowser, para assegurar que JS interop só seja chamado por um componente renderizado no cliente. Isto é importante para bibliotecas/pacotes NuGet que visam componentes do lado do servidor, que não conseguem executar o código fornecido por esta JS API de interoperabilidade.

Para importar uma JS função para a chamar a partir de C#, use o [JSImport] atributo numa assinatura de método C# que corresponda à JS assinatura da função. O primeiro parâmetro do [JSImport] atributo é o nome da JS função a importar, e o segundo parâmetro é o nome do JS módulo.

No exemplo seguinte, getMessage é uma JS função que devolve a string para um módulo chamado CallJavaScript1. A assinatura do método C# corresponde: Nenhum parâmetro é passado para a JS função, e a JS função devolve um string. A JS função é chamada por GetWelcomeMessage em código C#.

CallJavaScript1.razor.cs:

using System.Runtime.InteropServices.JavaScript;
using System.Runtime.Versioning;

namespace BlazorSample.Components.Pages;

[SupportedOSPlatform("browser")]
public partial class CallJavaScript1
{
    [JSImport("getMessage", "CallJavaScript1")]
    internal static partial string GetWelcomeMessage();
}

O namespace da aplicação para a classe parcial anterior CallJavaScript1 é BlazorSample. O espaço de nomes do componente é BlazorSample.Components.Pages. Se estiver a usar o componente anterior numa aplicação de teste local, atualize o namespace para corresponder à aplicação. Por exemplo, o namespace é ContosoApp.Components.Pages se o namespace da aplicação for ContosoApp. Para obter mais informações, consulte componentes do ASP.NET Core Razor.

Na assinatura de método importado, você pode usar tipos .NET para parâmetros e valores de retorno, que são empacotados automaticamente pelo tempo de execução. Use JSMarshalAsAttribute<T> para controlar como os parâmetros do método importado são empacotados. Por exemplo, você pode optar por marshal a long as System.Runtime.InteropServices.JavaScript.JSType.Number ou System.Runtime.InteropServices.JavaScript.JSType.BigInt. Você pode passar Action/Func<TResult> retornos de chamada como parâmetros, que são organizados como funções chamáveis JS . Você pode passar referências de JS objetos gerenciados e eles são empacotados como objetos proxy, mantendo o objeto vivo através do limite até que o proxy seja coletado. Você também pode importar e exportar métodos assíncronos com um Task resultado, que são empacotados como JS promessas. A maioria dos tipos organizados funciona em ambas as direções, como parâmetros e como valores de retorno, tanto nos métodos importados como nos exportados, que são abordados na secção Chamar .NET a partir do JavaScript mais adiante neste artigo.

Para informações adicionais sobre mapeamento de tipos e exemplos, consulte a interoperabilidade JavaScript '[JSImport]'/'[JSExport]' no .NET WebAssembly.

O nome do módulo no atributo [JSImport] e a chamada para carregar o módulo no componente com JSHost.ImportAsync devem corresponder e ser únicos na aplicação. Ao criar uma biblioteca para implementação num pacote NuGet, recomendamos usar o espaço de nomes do pacote NuGet como prefixo nos nomes dos módulos. No exemplo seguinte, o nome do módulo reflete o Contoso.InteropServices.JavaScript pacote e uma pasta de classes de interoperação de mensagens de utilizador (UserMessages):

[JSImport("getMessage", 
    "Contoso.InteropServices.JavaScript.UserMessages.CallJavaScript1")]

As funções acessíveis no namespace global podem ser importadas usando o prefixo globalThis no nome da função e usando o [JSImport] atributo sem fornecer um nome de módulo. No exemplo a seguir, console.log é prefixado com globalThis. A função importada é chamada pelo método C# Log , que aceita uma mensagem de cadeia de caracteres C# (message) e marshalls a cadeia de caracteres C# para um JSString para console.log:

[JSImport("globalThis.console.log")]
internal static partial void Log([JSMarshalAs<JSType.String>] string message);

Exportar scripts de um módulo JavaScript padrão colocados junto a um componente ou colocados com outros ativos estáticos JavaScript num JS ficheiro (por exemplo, wwwroot/js/{FILE NAME}.js, onde JS os ativos estáticos são mantidos numa pasta nomeada js na pasta da wwwroot aplicação e o {FILE NAME} marcador é o nome do ficheiro).

No exemplo seguinte, uma JS função nomeada getMessage é exportada a partir de um ficheiro colocado JS que devolve uma mensagem de boas-vindas, "Hello from Blazor!" em português:

CallJavaScript1.razor.js:

export function getMessage() {
  return 'Olá do Blazor!';
}

Invocar .NET a partir do JavaScript

Esta secção explica como chamar métodos .NET a partir de JS.

O seguinte componente CallDotNet1 faz chamadas JS que interage diretamente com o DOM para renderizar a mensagem de boas-vindas:

• O CallDotNetJS módulo é importado assíncronamente a partir do ficheiro colocado JS deste componente.
• A função importada setMessageJS é chamada por SetWelcomeMessage.
• A mensagem de boas-vindas devolvida é apresentada na setMessage interface através do message campo.

Importante

No exemplo desta secção, JS interop é usado para mutar um elemento DOM puramente para fins de demonstração após o componente ser renderizado em OnAfterRender. Normalmente, só deves mutar o DOM com JS quando o objeto não interage com Blazor. A abordagem apresentada nesta secção é semelhante a casos em que uma biblioteca de terceiros JS é usada num Razor componente, onde o componente interage com a JS biblioteca via JS interop, a biblioteca de terceiros JS interage com parte do DOM e Blazor não está diretamente envolvida com as atualizações do DOM dessa parte do DOM. Para obter mais informações, consulte Interoperabilidade do JavaScript do ASP.NET Core Blazor (JS interop).

CallDotNet1.razor:

@page "/call-dotnet-1"
@rendermode InteractiveWebAssembly
@using System.Runtime.InteropServices.JavaScript

<h1>
    JS <code>[JSImport]</code>/<code>[JSExport]</code> Interop 
    (Call .NET Example 1)
</h1>

<p>
    <span id="result">.NET method not executed yet</span>
</p>

@code {
    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            await JSHost.ImportAsync("CallDotNet1", 
                "../Components/Pages/CallDotNet1.razor.js");

            SetWelcomeMessage();
        }
    }
}

Para exportar um método .NET para que possa ser chamado a partir de JS, use o [JSExport] atributo.

No exemplo a seguir:

• SetWelcomeMessage chama a uma JS função chamada setMessage. A função JS liga ao .NET para receber a mensagem de boas-vindas de GetMessageFromDotnet e apresenta a mensagem na interface.
• GetMessageFromDotnet é um método .NET com o [JSExport] atributo que devolve uma mensagem de boas-vindas, "Olá de Blazor!" em português.

CallDotNet1.razor.cs:

using System.Runtime.InteropServices.JavaScript;
using System.Runtime.Versioning;

namespace BlazorSample.Components.Pages;

[SupportedOSPlatform("browser")]
public partial class CallDotNet1
{
    [JSImport("setMessage", "CallDotNet1")]
    internal static partial void SetWelcomeMessage();

    [JSExport]
    internal static string GetMessageFromDotnet() => "Olá do Blazor!";
}

O namespace da aplicação para a classe parcial anterior CallDotNet1 é BlazorSample. O espaço de nomes do componente é BlazorSample.Components.Pages. Se usar o componente anterior numa aplicação de teste local, atualize o espaço de nomes da aplicação para corresponder à aplicação. Por exemplo, o espaço de nomes dos componentes é ContosoApp.Components.Pages se o espaço de nomes da aplicação for ContosoApp. Para obter mais informações, consulte componentes do ASP.NET Core Razor.

No exemplo seguinte, uma JS função chamada setMessage é importada de um ficheiro co-localizado JS.

O método setMessage:

• Chamada globalThis.getDotnetRuntime(0) para expor a instância de .NET runtime do WebAssembly para a execução de métodos .NET exportados.
• Obtém as exportações da montagem da aplicação JS. O nome do assembly da aplicação no exemplo seguinte é BlazorSample.
• Chama o método BlazorSample.Components.Pages.CallDotNet1.GetMessageFromDotnet das exportações (exports). O valor devolvido, que é a mensagem de boas-vindas, é atribuído ao CallDotNet1 texto do <span> componente. O espaço de nomes da aplicação é BlazorSample, e o CallDotNet1 espaço de nomes do componente é BlazorSample.Components.Pages.

CallDotNet1.razor.js:

export async function setMessage() {
  const { getAssemblyExports } = await globalThis.getDotnetRuntime(0);
  var exports = await getAssemblyExports("BlazorSample.dll");

  document.getElementById("result").innerText = 
    exports.BlazorSample.Components.Pages.CallDotNet1.GetMessageFromDotnet();
}

Observação

A chamada getAssemblyExports para obter as exportações pode ocorrer num inicializador JavaScript para disponibilidade em toda a aplicação.

Chamadas de importação múltiplas de módulos

Depois de um JS módulo ser carregado, as funções do módulo JS ficam disponíveis para os componentes e classes da aplicação desde que a aplicação esteja a correr na janela ou separador do navegador, sem que o utilizador tenha de recarregar manualmente a aplicação. JSHost.ImportAsync pode ser chamada várias vezes no mesmo módulo sem uma penalização significativa de desempenho quando:

• O utilizador visita um componente que chama JSHost.ImportAsync para importar um módulo, afasta-se do componente e depois regressa ao componente onde JSHost.ImportAsync é chamado novamente para a importação do mesmo módulo.
• O mesmo módulo é usado por diferentes componentes e carregado por JSHost.ImportAsync em cada um dos componentes.

Utilização de um único módulo JavaScript entre componentes

Antes de seguir as orientações desta secção, leia as secções Chamar JavaScript a partir do .NET e Chamar .NET a partir do JavaScript deste artigo, que fornecem orientações gerais sobre [JSImport]/[JSExport] interoperabilidade.

O exemplo nesta secção mostra como usar JS interoperabilidade a partir de um módulo partilhado JS numa aplicação cliente. As orientações desta secção não se aplicam às Razor bibliotecas de classes (RCLs).

São utilizados os seguintes componentes, classes, métodos C# e JS funções:

• Interop classe (Interop.cs): Configura a interoperabilidade de importação e exportação JS utilizando os atributos [JSImport] e [JSExport] para um módulo chamado Interop.
  • GetWelcomeMessage: método .NET que chama a função importada getMessageJS.
  • SetWelcomeMessage: método .NET que chama a função importada setMessageJS.
  • GetMessageFromDotnet: Um método C# exportado que devolve uma cadeia de mensagens de boas-vindas quando chamado a partir de JS.
• wwwroot/js/interop.js ficheiro: Contém as JS funções.
  • getMessage: Retorna uma mensagem de boas-vindas quando chamada por código C# num componente.
  • setMessage: Chama o GetMessageFromDotnet método C# e atribui a mensagem de boas-vindas devolvida a um elemento DOM <span> .
• Program.cs chama JSHost.ImportAsync para carregar o módulo de wwwroot/js/interop.js.
• CallJavaScript2 component (CallJavaScript2.razor): Chama GetWelcomeMessage e exibe a mensagem de boas-vindas retornada na interface do componente.
• CallDotNet2 componente (CallDotNet2.razor): Chama SetWelcomeMessage.

Interop.cs:

using System.Runtime.InteropServices.JavaScript;
using System.Runtime.Versioning;

namespace BlazorSample.JavaScriptInterop;

[SupportedOSPlatform("browser")]
public partial class Interop
{
    [JSImport("getMessage", "Interop")]
    internal static partial string GetWelcomeMessage();

    [JSImport("setMessage", "Interop")]
    internal static partial void SetWelcomeMessage();

    [JSExport]
    internal static string GetMessageFromDotnet() => "Olá do Blazor!";
}

No exemplo anterior, o namespace da aplicação é BlazorSample, e o namespace completo para classes interop em C# é BlazorSample.JavaScriptInterop.

wwwroot/js/interop.js:

export function getMessage() {
  return 'Olá do Blazor!';
}

export async function setMessage() {
  const { getAssemblyExports } = await globalThis.getDotnetRuntime(0);
  var exports = await getAssemblyExports("BlazorSample.dll");

  document.getElementById("result").innerText =
    exports.BlazorSample.JavaScriptInterop.Interop.GetMessageFromDotnet();
}

Torne o System.Runtime.InteropServices.JavaScript espaço de nomes disponível na parte superior do Program.cs ficheiro:

using System.Runtime.InteropServices.JavaScript;

Carregue o módulo em Program.cs antes de WebAssemblyHost.RunAsync ser chamado.

if (OperatingSystem.IsBrowser())
{
    await JSHost.ImportAsync("Interop", "../js/interop.js");
}

CallJavaScript2.razor:

@page "/call-javascript-2"
@rendermode InteractiveWebAssembly
@using BlazorSample.JavaScriptInterop

<h1>
    JS <code>[JSImport]</code>/<code>[JSExport]</code> Interop 
    (Call JS Example 2)
</h1>

@(message is not null ? message : string.Empty)

@code {
    private string? message;

    protected override void OnInitialized()
    {
        message = Interop.GetWelcomeMessage();
    }
}

CallDotNet2.razor:

@page "/call-dotnet-2"
@rendermode InteractiveWebAssembly
@using BlazorSample.JavaScriptInterop

<h1>
    JS <code>[JSImport]</code>/<code>[JSExport]</code> Interop  
    (Call .NET Example 2)
</h1>

<p>
    <span id="result">.NET method not executed</span>
</p>

@code {
    protected override void OnAfterRender(bool firstRender)
    {
        if (firstRender)
        {
            Interop.SetWelcomeMessage();
        }
    }
}

Importante

No exemplo desta secção, JS interop é usado para mutar um elemento DOM puramente para fins de demonstração após o componente ser renderizado em OnAfterRender. Normalmente, só deves mutar o DOM com JS quando o objeto não interage com Blazor. A abordagem apresentada nesta secção é semelhante a casos em que uma biblioteca de terceiros JS é usada num Razor componente, onde o componente interage com a JS biblioteca via JS interop, a biblioteca de terceiros JS interage com parte do DOM e Blazor não está diretamente envolvida com as atualizações do DOM dessa parte do DOM. Para obter mais informações, consulte Interoperabilidade do JavaScript do ASP.NET Core Blazor (JS interop).

Recursos adicionais

• JavaScript '[JSImport]'/'[JSExport]' interop em .NET WebAssembly
• Interop JavaScript '[JSImport]'/'[JSExport]' num projeto de uma aplicação de navegador WebAssembly
• Documentação da API
  • [JSImport] atributo
  • [JSExport] atributo
• dotnet/runtime No repositório GitHub:
  • Configurando e hospedando aplicativos .NET WebAssembly
  • Tempo de execução do .NET WebAssembly
  • dotnet.d.ts arquivo (configuração de tempo de execução do .NET WebAssembly)