Usar componentes do Razor em aplicativos JavaScript e estruturas SPA

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

Aplicativos de exemplo angulares

• CustomElementsBlazorSample (Blazor Server) (javiercn/CustomElementsBlazorSample, branch: blazor-server): Blazor Server é suportado no .NET 8. Para migrar este exemplo do .NET 7 para o .NET 8, confira Migrar do ASP.NET Core 7.0 para 8.0.
• CustomElementsBlazorSample (Blazor WebAssembly) (javiercn/CustomElementsBlazorSample, branch: blazor-wasm): para migrar este exemplo do .NET 7 para o .NET 8, consulte Migrar do ASP.NET Core 7.0 para 8.0.

Renderizar componentes Razor de JavaScript

Os componentes Razor podem ser renderizados dinamicamente do JavaScript (JS) para aplicativos JS existentes.

O exemplo nesta seção renderiza o componente do Razor a seguir em uma página por meio de JS.

Quote.razor:

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

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

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

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

RegisterForJavaScript inclui uma sobrecarga que aceita o nome de uma função JS que executa a lógica de inicialização (javaScriptInitializer). A função JS é chamada uma vez por registro de componente imediatamente após o início do aplicativo Blazor e antes de todos os componentes serem renderizados. Essa 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 de inicializador podem ser criadas e chamadas por diferentes registros de componente. 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 o identificador.

• Em um aplicativo Blazor Server, modifique a chamada para AddServerSideBlazor no arquivo Program:

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

• Em um aplicativo Blazor WebAssembly, chame RegisterForJavaScript em RootComponents no arquivo Program do lado do cliente:

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

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

wwwroot/jsComponentInitializers.js:

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

Renderize o componente de JS em um elemento de contêiner usando o identificador registrado, passando parâmetros de componente conforme necessário.

No exemplo a seguir:

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

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 script Blazor for carregado, carregue os scripts anteriores no aplicativo JS:

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

No exemplo anterior, o espaço reservado {BLAZOR SCRIPT} é o script Blazor.

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

<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 do componente Quote (name) e (parameters) 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 armazenada em Text exibida:

Cota ©1988-1999 Satellite of Love LLC: Mystery Science Theater 3000 (Trace Beaulieu (Crow))

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

...

rootComponent.dispose();

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

O exemplo a seguir baseia-se no exemplo anterior, utilizando o componente Quote, o registro do componente raiz no arquivo Program e a inicialização de jsComponentInitializers.js. A função showQuote() (e o arquivo script.js) não é usada.

Em HTML, posicione o elemento de contêiner 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, confira o exemplo no BasicTestApp da fonte de referência do ASP.NET Core (dotnet/aspnetcore repositório GitHub):

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

Elementos personalizados de Blazor

@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 Microsoft.AspNetCore.Components.Web;

using BlazorSample.Pages;

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

<my-counter></my-counter>

@page "/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) específicos da estrutura com base em componentes Razor para estruturas da Web, como Angular ou React. Essa funcionalidade não está incluída no .NET, mas é habilitada pelo suporte para renderizar de componentes Razor de JS. O exemplo de geração de componentes JS no GitHub demonstra como gerar componentes Angular e React de componentes Razor. Consulte o arquivo README.md do aplicativo de exemplo do GitHub para obter informações adicionais.