Interoperabilidade do JavaScript com o Blazor
- 5 minutos
O Blazor usa componentes C# em vez de JavaScript para criar páginas da Web ou seções HTML com conteúdo dinâmico. Mas você pode usar a interoperabilidade entre Blazor e JavaScript (interoperabilidade JS) para chamar bibliotecas JavaScript em aplicativos Blazor e chamar funções JavaScript do código C# por meio do .NET.
Nesta unidade, você aprende a chamar o JavaScript por meio do código C# em uma página Blazor e a invocar métodos C# de funções JavaScript. Na próxima unidade, você usa um componente de alerta de uma biblioteca JavaScript para atualizar o site de entrega de pizza Blazor.
Usar a interoperabilidade entre Blazor e JavaScript
Um componente Blazor típico usa a lógica de layout e de interface do usuário usada para gerar uma página HTML em tempo de execução. Você pode usar o código C# para manipular eventos e outros aspectos dinâmicos de uma página que interagem com o usuário e os serviços externos. Em muitos casos, você não precisa usar o código JavaScript. Em vez disso, você pode usar o Blazor, juntamente com as bibliotecas do .NET, que fornecem várias funcionalidades equivalentes.
No entanto, às vezes, você precisa usar uma biblioteca JavaScript existente. Por exemplo, algumas bibliotecas JavaScript de software livre renderizam componentes e manipulam elementos da interface do usuário de maneira especializada. Você também pode ter um código JavaScript experimentado e testado que deseja reutilizar, em vez de convertê-lo em C#.
O Blazor permite integrar bibliotecas JavaScript aos aplicativos usando a interoperabilidade entre Blazor e JavaScript ou interoperabilidade JS. Você usa a interoperabilidade JS para chamar funções JavaScript de métodos .NET e invocar métodos .NET de funções JavaScript. A interoperabilidade JS lida com o marshaling de dados e referências de objeto entre o Blazor e o JavaScript para deixar a transição entre eles o mais tranquila possível.
Carregar código JavaScript em um aplicativo Blazor
O JavaScript é adicionado a um aplicativo Blazor da mesma forma que seria adicionado a um aplicativo Web HTML padrão, usando o elemento HTML <script>. Adicione a marca <script> após a marca <script src="_framework/blazor.*.js"></script> existente no arquivo Pages/_Host.cshtml ou no arquivo wwwroot/index.html (dependendo do modelo de hospedagem Blazor). Para obter mais informações, confira Modelos de hospedagem do ASP.NET Core Blazor.
Não coloque scripts no elemento <head> da página. O Blazor só tem controle sobre o conteúdo no elemento <body> de uma página HTML, portanto, a interop JS poderá falhar se os scripts dependerem do Blazor. Além disso, a exibição da página pode ficar mais lenta devido ao tempo necessário para analisar o código JavaScript.
A marca <script> opera como em um aplicativo Web HTML. Você pode escrever código diretamente no corpo da marca ou pode referenciar um arquivo JavaScript existente. Para obter mais informações, confira Interoperabilidade do JavaScript ASP.NET Core Blazor (interoperabilidade JS): localização do JavaScript.
Importante
Coloque os arquivos JavaScript na pasta wwwroot do aplicativo Blazor.
Outra opção é injetar o elemento <script> que faz referência a um arquivo JavaScript na página Pages/_Host.cshtml dinamicamente. Essa abordagem será útil se você precisar carregar scripts diferentes, dependendo do ambiente ou outras condições que só podem ser determinadas em tempo de execução. Essa abordagem também pode acelerar o carregamento inicial do aplicativo se você disparar a lógica com um evento que é disparado depois que uma página é renderizada. Para obter mais informações, confira Inicialização do ASP.NET Core Blazor.
Chamar JavaScript a partir do código .NET
Você usa o IJSRuntime para chamar uma função JavaScript do código .NET. Para disponibilizar o tempo de execução de interoperabilidade JS, insira uma instância da abstração IJSRuntime em uma página Blazor, após a diretiva @page na parte superior do arquivo.
A interface IJSRuntime expõe os métodos InvokeAsync e InvokeVoidAsync para invocar o código JavaScript. Use InvokeAsync<TValue> para chamar uma função JavaScript que retorna um valor. Ou chame InvokeVoidAsync. Como os nomes sugerem, ambos os métodos são assíncronos, portanto, use o operador await do C# para capturar os resultados.
O parâmetro para o método InvokeAsync ou InvokeVoidAsync é o nome da função JavaScript a ser invocada, seguido pelos argumentos que a função exige. A função JavaScript precisa fazer parte do escopo de window ou de um subescopo de window. Os argumentos devem ser serializáveis em JSON.
Observação
A interoperabilidade JS só estará disponível quando o aplicativo Blazor Server estabelecer uma conexão SignalR com o navegador. Você não pode fazer chamadas de interoperabilidade até que o processamento seja concluído. Para detectar se a renderização foi concluída, use o evento OnAfterRender ou OnAfterRenderAsync no código do Blazor.
Usar um objeto ElementReference para atualizar o DOM
O Blazor mantém uma representação do DOM (Modelo de Objeto do Documento) como uma árvore de renderização virtual. Conforme a estrutura da página muda, o Blazor gera uma nova árvore de renderização que contém as diferenças. Quando as alterações são concluídas, o Blazor itera pelas diferenças para atualizar a exibição do navegador da interface do usuário e a versão do navegador do DOM que o JavaScript usa.
Muitas bibliotecas JavaScript de terceiros estão disponíveis para renderizar elementos em uma página e essas bibliotecas podem atualizar o DOM. Se o código JavaScript modificar elementos do DOM, a cópia Blazor do DOM poderá não corresponder mais ao estado atual. Essa situação pode resultar em comportamento inesperado e, possivelmente, introduzir riscos de segurança. É importante não fazer alterações que possam corromper a exibição Blazor do DOM.
A maneira mais simples de lidar com essa situação é criar um elemento de espaço reservado no componente Blazor, geralmente um elemento <div @ref="placeHolder"></div>. O código Blazor interpreta esse código como um espaço em branco e a árvore de renderização Blazor não tenta rastrear o conteúdo. Você pode adicionar elementos de código JavaScript livremente a esse <div> e o Blazor não tentará alterá-lo.
O código do aplicativo Blazor define um campo do tipo ElementReference para manter a referência ao elemento <div>. O atributo @ref no elemento <div> define o valor do campo. O objeto ElementReference é passado para uma função JavaScript, que pode usar a referência para adicionar conteúdo ao elemento <div>.
Chamar o código .NET do JavaScript
O código JavaScript pode executar um método .NET que o código Blazor define usando a classe de utilitário DotNet, parte da biblioteca de interoperabilidade JS. A classe DotNet expõe as funções auxiliares invokeMethod e invokeMethodAsync. Use invokeMethod para executar um método e aguardar o resultado e use invokeMethodAsync para chamar o método de maneira assíncrona. O método invokeMethodAsync retorna um JavaScript Promise.
Dica
Para manter a capacidade de resposta nos aplicativos, defina o método .NET como async e chame-o usando invokeMethodAsync do JavaScript.
Você precisa marcar o método .NET que está sendo chamado com o JSInvokableAttribute. O método deve ser public, e todos os parâmetros devem ser serializáveis como JSON. Além disso, para um método assíncrono, o tipo de retorno precisa ser void, Task ou um objeto genérico Task<T> em que T é um tipo serializável como JSON.
Para chamar um método static, você fornece o nome do assembly .NET que contém a classe, um identificador para o método e os parâmetros que o método aceita como argumentos para as funções invokeMethod ou invokeMethodAsync. Por padrão, o identificador de método é o mesmo que o nome do método, mas você pode especificar um valor diferente com o atributo JSInvokable.
Chamar um método de instância do .NET do JavaScript
Para executar um método de instância, o JavaScript requer uma referência de objeto que aponta para a instância. A interoperabilidade JS fornece o tipo genérico DotNetObjectReference que você pode usar para criar uma referência de objeto no código .NET. O código deve disponibilizar essa referência de objeto para o JavaScript.
O código JavaScript pode chamar invokeMethodAsync com o nome do método .NET e todos os parâmetros exigidos pelo método. Para evitar perdas de memória, o código .NET deverá descartar a referência de objeto quando ela não for mais necessária.