Utilisez des composants Razordans les applications JavaScript et les infrastructures SPA

Cet article explique comment afficher des composants Razor à partir de JavaScript, utiliser des éléments personnalisés Blazor et générer des composants Angular et React.

Exemples d’applications Angular

• CustomElementsBlazorSample (Blazor Server) (javiercn/CustomElementsBlazorSample, branche : blazor-server) : Blazor Server est pris en charge dans .NET 8. Pour migrer cet exemple .NET 7 vers .NET 8, consultez Migrer d’ASP.NET Core 7.0 vers 8.0.
• CustomElementsBlazorSample (Blazor WebAssembly) (javiercn/CustomElementsBlazorSample, branche : blazor-wasm) : pour migrer cet exemple .NET 7 vers .NET 8, consultez Migrer d’ASP.NET Core 7.0 vers 8.0.

Générer le rendu de composants Razor à partir de JavaScript

Les composants Razor peuvent être rendus dynamiquement à partir de JavaScript (JS) pour des applications JS existantes.

L’exemple de cette section affiche le composant Razor suivant dans une page via JS.

Quote.razor :

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

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

Dans le fichier Program, ajoutez l’espace de noms pour l’emplacement du composant.

Appelez RegisterForJavaScript sur la collection de composants racine de l’application pour inscrire un composant Razor en tant que composant racine pour le rendu JS.

RegisterForJavaScript inclut une surcharge qui accepte le nom d’une fonction JS qui exécute la logique d’initialisation (javaScriptInitializer). La fonction JS est appelée une fois par inscription de composant immédiatement après le démarrage de l’application Blazor et avant le rendu des composants. Cette fonction peut être utilisée pour l’intégration à des technologies JS, telles que des éléments personnalisés HTML ou une infrastructure SPA basée sur JS.

Une ou plusieurs fonctions d’initialiseur peuvent être créées et appelées par différentes inscriptions de composants. Le cas d’usage classique consiste à réutiliser la même fonction d’initialiseur pour plusieurs composants, ce qui est attendu si la fonction d’initialiseur configure l’intégration avec des éléments personnalisés ou une autre infrastructure SPA basée sur JS.

L’exemple suivant illustre l’inscription dynamique du composant Quote précédent avec « quote » comme identificateur.

• Dans une application Blazor Server, modifiez l’appel à AddServerSideBlazor dans le fichier Program :

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

• Dans une application Blazor WebAssembly, appelez RegisterForJavaScript sur RootComponents dans le fichier Program côté client :

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

Attachez la fonction d’initialiseur avec les paramètres de fonction name et parameters à l’objet window. À des fins de démonstration, la fonction suivante initializeComponent journalise le nom et les paramètres du composant inscrit.

wwwroot/jsComponentInitializers.js :

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

Affichez le composant à partir de JS dans un élément conteneur à l’aide de l’identificateur inscrit, en passant les paramètres du composant si nécessaire.

Dans l’exemple suivant :

• Le composant Quote (identificateur quote) est affiché dans l’élément quoteContainer lorsque la fonction showQuote est appelée.
• Une chaîne de guillemets est passée au paramètre du Text composant.

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);

Une fois le script Blazor chargé, chargez les scripts précédents dans l’application JS :

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

Dans l’exemple précédent, l’espace réservé {BLAZOR SCRIPT} est le script Blazor.

En HTML, placez l’élément conteneur cible (quoteContainer). Pour la démonstration de cette section, un bouton déclenche le rendu du composant Quote en appelant la fonction showQuoteJS :

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

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

Lors de l’initialisation avant le rendu de tout composant, la console des outils du développeur du navigateur journalise l’identificateur du composant Quote (name) et les paramètres (parameters) quand initializeComponent est appelé :

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

Lorsque le bouton Show Quote est sélectionné, le composant Quote est affiché avec la citation stockée dans Text :

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

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

...

rootComponent.dispose();

L’exemple précédent affiche dynamiquement le composant racine lorsque la fonction showQuote()JS est appelée. Pour afficher un composant racine dans un élément conteneur lorsque Blazor démarre, utilisez un Initialiseur JavaScript pour afficher le composant, comme le montre l’exemple suivant.

L’exemple suivant s’appuie sur l’exemple précédent, à l’aide du composant Quote, de l’inscription du composant racine dans le fichier Programet de l’initialisation de jsComponentInitializers.js. La fonction showQuote() (et le fichier script.js) ne sont pas utilisés.

En HTML, placez l’élément conteneur cible, quoteContainer2 pour cet exemple :

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

À l’aide d’un Initialiseur JavaScript, ajoutez le composant racine à l’élément conteneur cible.

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

Pour obtenir un exemple avancé avec des fonctionnalités supplémentaires, consultez l’exemple dans le BasicTestApp de la source de référence ASP.NET Core (référentiel GitHub dotnet/aspnetcore) :

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

Éléments personnalisés 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>

Générer des composants Angular et React

Générez des composants JavaScript spécifiques au framework (JS) à partir de composants Razor pour les frameworks web, comme Angular ou React. Cette fonctionnalité n’est pas incluse avec .NET, mais elle est disponible grâce à la prise en charge du rendu des composants Razor à partir de JS. L’exemple de génération de composants JS sur GitHub montre comment générer des composants Angular et React à partir de composants Razor. Pour plus d’informations, consultez le fichier README.md de l’exemple d’application GitHub.