Utilizar componentes Razor em aplicações JavaScript e frameworks SPA

Este artigo aborda como renderizar Razor componentes de JavaScript, usar Blazor elementos personalizados e gerar componentes Angular e React.

Aplicações de exemplo Angular

As seguintes aplicações de exemplo demonstram como renderizar um Razor componente como elementoBlazor personalizado numa aplicação Angular:

• CustomElementsBlazorSample (Blazor Server) (javiercn/CustomElementsBlazorSample repositório GitHub, ramo: blazor-server)
• CustomElementsBlazorSample (Blazor WebAssembly) (javiercn/CustomElementsBlazorSample repositório GitHub, ramo: blazor-wasm)

Para migrar qualquer um destes exemplos de .NET 7, consulte os seguintes recursos:

• Migrar do ASP.NET Core no .NET 7 para o .NET 8
• Migrar do ASP.NET Core em .NET 8 para ASP.NET Core em .NET 9
• Migrar de ASP.NET Core em .NET 9 para ASP.NET Core em .NET 10

As principais atualizações a fazer são:

• Atualize os nomes do framework de destino (TFMs) para a versão mais recente.

• Atualize as referências dos pacotes .NET e as dependências do Angular para as suas versões mais recentes.

  Observação

  Para obter orientação sobre como adicionar pacotes a aplicativos .NET, consulte os artigos na seção Instalar e gerenciar pacotes em Workflow de utilização de pacotes (documentação do NuGet). Confirme as versões corretas do pacote em NuGet.org.

Renderizar Razor componentes a partir de JavaScript

Os Razor componentes podem ser dinamicamente renderizados a partir do JavaScript (JS) para aplicações existentes JS.

O exemplo nesta seção renderiza o componente a seguir Razor em uma página via JS.

Quote.razor:

<div class="m-5 p-5">
    <h2>Quote</h2>
    <p>@Text</p>
</div>

@code {
    [Parameter]
    public string? Text { get; set; }
}

Program No arquivo, adicione o namespace para o local do componente.

Chame RegisterForJavaScript na coleção de componentes raiz do aplicativo para registar um componente Razor como componente raiz para a renderização de JS.

RegisterForJavaScript inclui uma sobrecarga que aceita o nome de uma JS função que executa a lógica de inicialização (javaScriptInitializer). A JS função é chamada uma vez por registro de componente imediatamente após o início do Blazor aplicativo e antes que quaisquer componentes sejam renderizados. Esta função pode ser usada para integração com tecnologias JS, como elementos personalizados HTML ou uma estrutura SPA baseada em JS.

Uma ou mais funções do inicializador podem ser criadas e chamadas por diferentes registros de componentes. O caso de uso típico é reutilizar a mesma função de inicializador para vários componentes, o que é esperado se a função de inicializador estiver configurando a integração com elementos personalizados ou outra estrutura SPA baseada em JS.

O exemplo a seguir demonstra o registro dinâmico do componente anterior Quote com "quote" como identificador.

• Em uma Blazor Server aplicação, modifique a chamada para AddServerSideBlazor no arquivo Program.

  builder.Services.AddServerSideBlazor(options =>
  {
      options.RootComponents.RegisterForJavaScript<Quote>(identifier: "quote", 
          javaScriptInitializer: "initializeComponent");
  });
  

• Em uma Blazor WebAssembly aplicação, chame RegisterForJavaScript em RootComponents no ficheiro do lado do cliente Program.

  builder.RootComponents.RegisterForJavaScript<Quote>(identifier: "quote", 
      javaScriptInitializer: "initializeComponent");
  

Anexe a função de inicialização com os parâmetros de função name e parameters ao objeto window. Para fins de demonstração, a função a seguir initializeComponent registra o nome e os parâmetros do componente registrado.

wwwroot/jsComponentInitializers.js:

window.initializeComponent = (name, parameters) => {
  console.log({ name: name, parameters: parameters });
}

Renderizar o componente do JS em um elemento de contêiner usando o identificador registado, passando os parâmetros do componente conforme necessário.

No exemplo a seguir:

• O componente Quote (identificador quote) é renderizado no elemento quoteContainer quando a função showQuote é chamada.
• Uma string de citação é passada para o parâmetro do componente Text.

wwwroot/scripts.js:

window.showQuote = async () => {
  let targetElement = document.getElementById('quoteContainer');
  await Blazor.rootComponents.add(targetElement, 'quote', 
  {
    text: "Crow: I have my doubts that this movie is actually 'starring' " +
      "anybody. More like, 'camera is generally pointed at.'"
  });
}

const btn = document.querySelector("#showQuoteBtn");
btn.addEventListener("click", showQuote);

Depois que o Blazor script for carregado, carregue os scripts precedentes na JS aplicação.

<script src="_framework/{BLAZOR SCRIPT}"></script>
<script src="jsComponentInitializers.js"></script>
<script src="scripts.js"></script>

No exemplo anterior, o placeholder {BLAZOR SCRIPT} é o Blazor script.

Em HTML, coloque o elemento container de destino (quoteContainer). Para a demonstração nesta seção, um botão aciona a renderização do Quote componente chamando a showQuoteJS função:

<button id="showQuoteBtn">Show Quote</button>

<div id="quoteContainer"></div>

Na inicialização, antes de qualquer componente ser renderizado, o console de ferramentas de desenvolvedor do navegador registra o identificador (Quote) e os name parâmetros (parameters) do componente quando initializeComponent é chamado:

Object { name: "quote", parameters: (1) […] }
  name: "quote"
  parameters: Array [ {…} ]
    0: Object { name: "Text", type: "string" }
    length: 1

Quando o botão Show Quote é selecionado, o componente Quote é renderizado com a cotação armazenada em Text exibida:

Citação ©1988-1999 Satellite of Love LLC: Mystery Science Theater 3000 (Trace Beaulieu (Corvo))

const rootComponent = await window.Blazor.rootComponents.add(...);

...

rootComponent.dispose();

O exemplo anterior renderiza dinamicamente o componente raiz quando a showQuote()JS função é chamada. Para renderizar um componente raiz em um elemento container quando Blazor é iniciado, use um inicializador JavaScript para renderizar o componente, como demonstra o exemplo a seguir.

O exemplo a seguir baseia-se no exemplo anterior, usando o componente Quote, o registo do componente raiz no arquivo Program e a inicialização do jsComponentInitializers.js. A showQuote() função (e o script.js arquivo) não são usados.

Em HTML, coloque o elemento container de destino, quoteContainer2 para este exemplo:

<div id="quoteContainer2"></div>

Usando um inicializador JavaScript, adicione o componente raiz ao elemento de contêiner de destino.

wwwroot/{PACKAGE ID/ASSEMBLY NAME}.lib.module.js:

export function afterStarted(blazor) {
  let targetElement = document.getElementById('quoteContainer2');
  blazor.rootComponents.add(targetElement, 'quote',
    {
      text: "Crow: I have my doubts that this movie is actually 'starring' " +
          "anybody. More like, 'camera is generally pointed at.'"
    });
}

Para obter um exemplo avançado com recursos adicionais, consulte o exemplo na BasicTestApp fonte de referência do ASP.NET Core (dotnet/aspnetcore repositório GitHub):

• JavaScriptRootComponents.razor
• wwwroot/js/jsRootComponentInitializers.js
• wwwroot/index.html

Blazor elementos personalizados

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

using Microsoft.AspNetCore.Components.Web;

using BlazorSample.Pages;

builder.Services.AddServerSideBlazor(options =>
{
    options.RootComponents.RegisterCustomElement<Counter>("my-counter");
});

using BlazorSample.Pages;
using Microsoft.AspNetCore.Components.Web;
using Microsoft.AspNetCore.Components.WebAssembly.Hosting;

var builder = WebAssemblyHostBuilder.CreateDefault(args);

builder.RootComponents.RegisterCustomElement<Counter>("my-counter");

await builder.Build().RunAsync();

<my-counter></my-counter>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    [Parameter]
    public int IncrementAmount { get; set; } = 1;

    private void IncrementCount()
    {
        currentCount += IncrementAmount;
    }
}

<my-counter increment-amount="10"></my-counter>

const elem = document.querySelector("my-counter");
elem.incrementAmount = 10;

<script src="/_content/Microsoft.AspNetCore.Components.CustomElements/BlazorCustomElements.js"></script>

<my-counter increment-amount={incrementAmount}></my-counter>

Gerar componentes Angular e React

Gere componentes JavaScript (JS) a partir de Razor componentes para tecnologias JavaScript, como Angular ou React. Essa funcionalidade não está incluída no .NET, mas é ativada pelo suporte para renderização de componentes Razor do JS. O JS exemplo de geração de componentes no GitHub demonstra como gerar componentes Angular e React a partir de Razor componentes. Consulte o arquivo do README.md aplicativo de exemplo GitHub para obter informações adicionais.

Recursos adicionais

Alojar e publicar ASP.NET Core Blazor