Usare Razor i componenti nelle app JavaScript e nei framework SPA

Questo articolo illustra come eseguire il rendering Razor dei componenti da JavaScript, usare Blazor elementi personalizzati e generare componenti Angular e React.

Nota

È consigliabile usare gli script (Blazor Server) e blazor.webassembly.js (Blazor WebAssembly) durante l'integrazione blazor.server.js Razor di componenti in un'app JavaScript esistente fino a quando non viene aggiunto un supporto migliore per lo blazor.web.js script (Blazor Web App) in futuro. Per altre informazioni, vedere RegisterCustomElement smesso di funzionare in Blazor 8 (dotnet/aspnetcore #53920).

App di esempio Angular

• CustomElementsBlazorSample () (javiercn/CustomElementsBlazorSampleBlazor Server, branch: ): Blazor Server blazor-serverè supportato in .NET 8/9. Per eseguire la migrazione di questo esempio .NET 7, vedere Eseguire la migrazione da ASP.NET Core 7.0 a 8.0 ed eseguire la migrazione da ASP.NET Core in .NET 8 a ASP.NET Core in .NET 9.
• CustomElementsBlazorSample () (javiercn/CustomElementsBlazorSampleBlazor WebAssembly, ramo: blazor-wasm): per eseguire la migrazione di questo esempio di .NET 7, vedere Eseguire la migrazione da ASP.NET Core 7.0 a 8.0 ed eseguire la migrazione da ASP.NET Core in .NET 8 a ASP.NET Core in .NET 9.

Eseguire il rendering dei componenti di Razor da JavaScript

È possibile eseguire il rendering dei componenti di Razor in modo dinamico da JavaScript (JS) per le app JS esistenti.

L'esempio in questa sezione esegue il rendering del componente seguente Razor in una pagina tramite JS.

Quote.razor:

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

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

Program Nel file aggiungere lo spazio dei nomi per il percorso del componente.

Chiamare RegisterForJavaScript la raccolta di componenti radice dell'app per registrare un Razor componente come componente radice per il JS rendering.

RegisterForJavaScript include un overload che accetta il nome di una JS funzione che esegue la logica di inizializzazione (javaScriptInitializer). La JS funzione viene chiamata una volta per ogni registrazione del componente immediatamente dopo l'avvio dell'app Blazor e prima del rendering di tutti i componenti. Questa funzione può essere usata per l'integrazione con JS tecnologie, ad esempio elementi personalizzati HTML o un JSframework SPA basato su .

È possibile creare e chiamare una o più funzioni di inizializzatore da registrazioni di componenti diverse. Il caso d'uso tipico consiste nel riutilizzare la stessa funzione di inizializzatore per più componenti, che è previsto se la funzione di inizializzatore configura l'integrazione con elementi personalizzati o un altro JSframework SPA basato su .

Importante

Non confondere il javaScriptInitializer parametro di RegisterForJavaScript con gli inizializzatori JavaScript. Il nome del parametro e la JS funzionalità degli inizializzatori è casuale.

Nell'esempio seguente viene illustrata la registrazione dinamica del componente precedente Quote con "quote" come identificatore.

• In un'app Blazor Server modificare la chiamata a AddServerSideBlazor nel Program file:

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

• In un'app Blazor WebAssembly chiamare RegisterForJavaScript RootComponents nel file sul lato Program client:

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

Collegare la funzione di inizializzatore con name i parametri di funzione e parameters all'oggetto window . A scopo dimostrativo, la funzione seguente initializeComponent registra il nome e i parametri del componente registrato.

wwwroot/jsComponentInitializers.js:

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

Eseguire il rendering del componente da JS in un elemento contenitore usando l'identificatore registrato, passando i parametri del componente in base alle esigenze.

Nell'esempio seguente :

• Il rendering del Quote componente (quote identificatore) viene eseguito nell'elemento quoteContainer quando viene chiamata la showQuote funzione .
• Una stringa di virgolette viene passata al parametro del Text 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);

Dopo aver caricato lo Blazor script , caricare gli script precedenti nell'app JS :

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

Nell'esempio precedente il {BLAZOR SCRIPT} segnaposto è lo Blazor script.

In HTML posizionare l'elemento contenitore di destinazione (quoteContainer). Per la dimostrazione in questa sezione, un pulsante attiva il rendering del Quote componente chiamando la showQuoteJS funzione :

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

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

All'inizializzazione prima del rendering di tutti i componenti, la console degli strumenti di sviluppo del browser registra l'identificatore Quote () e i parametri del componente (nameparameters) quando initializeComponent viene chiamato:

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

Quando si seleziona il Show Quote pulsante, viene eseguito il rendering del Quote componente con la virgoletta archiviata in Text visualizzata:

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

Nota

rootComponents.add restituisce un'istanza del componente. Chiamare dispose sull'istanza per rilasciarla:

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

...

rootComponent.dispose();

Nell'esempio precedente viene eseguito il rendering dinamico del componente radice quando viene chiamata la showQuote()JS funzione . Per eseguire il rendering di un componente radice in un elemento contenitore all'avvio Blazor , usare un inizializzatore JavaScript per eseguire il rendering del componente, come illustrato nell'esempio seguente.

L'esempio seguente si basa sull'esempio precedente, usando il Quote componente , la registrazione del componente radice nel Program file e l'inizializzazione di jsComponentInitializers.js. La showQuote() funzione (e il script.js file) non vengono usate.

In HTML posizionare l'elemento contenitore di destinazione, quoteContainer2 per questo esempio:

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

Usando un inizializzatore JavaScript, aggiungere il componente radice all'elemento contenitore di destinazione.

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.'"
    });
}

Nota

Per la chiamata a rootComponents.add, usare il blazor parametro (minuscolo b) fornito dall'evento Blazor start. Sebbene la registrazione sia valida quando si usa l'oggetto Blazor (maiuscolo B), l'approccio preferito consiste nell'usare il parametro .

Per un esempio avanzato con funzionalità aggiuntive, vedere l'esempio nell'origine BasicTestApp di riferimento di ASP.NET Core (dotnet/aspnetcore repository GitHub):

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

Nota

I collegamenti della documentazione all'origine del riferimento .NET in genere caricano il ramo predefinito del repository, che rappresenta lo sviluppo corrente per la versione successiva di .NET. Per selezionare un tag per una versione specifica, usare l'elenco a discesa Switch branches or tags. Per altre informazioni, vedere How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Come selezionare un tag di versione del codice sorgente di ASP.NET - dotnet/AspNetCore.Docs #26205).

Elementi personalizzati di Blazor

Usare Blazor elementi personalizzati per eseguire il rendering Razor dinamico dei componenti di altri framework SPA, ad esempio Angular o React.

Blazor elementi personalizzati:

• Usare interfacce HTML standard per implementare elementi HTML personalizzati.
• Eliminare la necessità di gestire manualmente lo stato e il ciclo di vita dei componenti radice Razor usando le API JavaScript.
• Sono utili per introdurre Razor gradualmente componenti in progetti esistenti scritti in altri framework SPA.

Gli elementi personalizzati non supportano il contenuto figlio o i componenti modello.

Nome dell'elemento

In base alla specifica HTML, i nomi dei tag di elemento personalizzati devono adottare il caso kebab:

❌Non valido: mycounter
❌Non valido: MY-COUNTER
❌Non valido: MyCounter
✔️Valevole: my-counter
✔️Valevole: my-cool-counter

Pacchetto

Aggiungere un riferimento al pacchetto per Microsoft.AspNetCore.Components.CustomElements al file di progetto dell'app.

Nota

Per indicazioni sull'aggiunta di pacchetti alle app .NET, vedere gli articoli sotto Installare e gestire pacchetti in Flusso di lavoro dell'utilizzo di pacchetti (documentazione di NuGet). Confermare le versioni corrette del pacchetto all'indirizzo NuGet.org.

Componente di esempio

Gli esempi seguenti si basano sul Counter componente del modello di Blazor progetto.

Counter.razor:

@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++;
}

Blazor Server registrazione

Per registrare un componente radice come elemento personalizzato in un'app Blazor Server , seguire questa procedura.

Aggiungere lo Microsoft.AspNetCore.Components.Web spazio dei nomi all'inizio del Program file:

using Microsoft.AspNetCore.Components.Web;

Aggiungere uno spazio dei nomi per i componenti dell'app. Nell'esempio seguente lo spazio dei nomi dell'app è BlazorSample e i componenti si trovano nella Pages cartella :

using BlazorSample.Pages;

Modificare la chiamata a AddServerSideBlazor. Specificare l'elemento personalizzato con RegisterCustomElement nell'opzione circuito RootComponents . L'esempio seguente registra il Counter componente con l'elemento my-counterHTML personalizzato :

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

Blazor WebAssembly registrazione

Per registrare un componente radice come elemento personalizzato in un'app Blazor WebAssembly , seguire questa procedura.

Aggiungere lo Microsoft.AspNetCore.Components.Web spazio dei nomi all'inizio del Program file:

using Microsoft.AspNetCore.Components.Web;

Aggiungere uno spazio dei nomi per i componenti dell'app. Nell'esempio seguente lo spazio dei nomi dell'app è BlazorSample e i componenti si trovano nella Pages cartella :

using BlazorSample.Pages;

Chiamare RegisterCustomElement su RootComponents. L'esempio seguente registra il Counter componente con l'elemento my-counterHTML personalizzato :

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

Usare l'elemento personalizzato registrato

Usare l'elemento personalizzato con qualsiasi framework Web. Ad esempio, l'elemento HTML personalizzato precedente my-counter che esegue il rendering del componente dell'app Counter viene usato in un'app React con il markup seguente:

<my-counter></my-counter>

Per un esempio completo di come creare elementi personalizzati con Blazor, vedere il CustomElementsComponent componente nell'origine di riferimento.

Nota

I collegamenti della documentazione all'origine del riferimento .NET in genere caricano il ramo predefinito del repository, che rappresenta lo sviluppo corrente per la versione successiva di .NET. Per selezionare un tag per una versione specifica, usare l'elenco a discesa Switch branches or tags. Per altre informazioni, vedere How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Come selezionare un tag di versione del codice sorgente di ASP.NET - dotnet/AspNetCore.Docs #26205).

Passare parametri

Passare i parametri al Razor componente come attributi HTML o come proprietà JavaScript nell'elemento DOM.

Il componente seguente Counter usa un IncrementAmount parametro per impostare la quantità di incremento del Click me pulsante.

Counter.razor:

@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;
    }
}

Eseguire il rendering del Counter componente con l'elemento personalizzato e passare un valore al IncrementAmount parametro come attributo HTML. Il nome dell'attributo adotta la sintassi kebab-case (increment-amount, non IncrementAmount):

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

In alternativa, è possibile impostare il valore del parametro come proprietà JavaScript nell'oggetto elemento. Il nome della proprietà adotta la sintassi del case camel (incrementAmount, non IncrementAmount):

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

È possibile aggiornare i valori dei parametri in qualsiasi momento usando la sintassi dell'attributo o della proprietà.

Tipi di parametri supportati:

• Usando la sintassi delle proprietà JavaScript, è possibile passare oggetti di qualsiasi tipo serializzabile JSON.
• Usando gli attributi HTML, è possibile passare oggetti di tipo stringa, booleano o numerico.

Generare componenti di Angular e React

Generare componenti JavaScript (JS) specifici del framework da componenti Razor per i framework Web, ad esempio Angular o React. Questa funzionalità non è inclusa in .NET, ma è abilitata dal supporto per i componenti di rendering Razor da JS. L'esempio di generazione di componenti JS in GitHub mostra come generare componenti di Angular e React da componenti di Razor. Per altre informazioni, vedere il file README.md dell'app di esempio GitHub.

Avviso

Le funzionalità dei componenti di Angular e React sono attualmente sperimentali, non supportate e soggette a modifica o rimozione in qualsiasi momento. Il feedback degli utenti su quanto questo particolare approccio soddisfi le loro esigenze sono molto apprezzati.