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.

Remarque

Nous vous recommandons d’utiliser les scripts blazor.server.js (Blazor Server) et blazor.webassembly.js (Blazor WebAssembly) lors de l’intégration de composants Razor dans une application JavaScript existante jusqu’à ce qu’une meilleure prise en charge du script blazor.web.js (Blazor Web App) soit ajoutée à l’avenir. Pour plus d’informations, consultez RegisterCustomElement a cessé de fonctionner dans Blazor 8 (dotnet/aspnetcore #53920).

Exemples d’applications Angular

• CustomElementsBlazorSample () (Blazor Serverjaviercn/CustomElementsBlazorSample, branche : blazor-server) : Blazor Server est pris en charge dans .NET 8/9. Pour migrer cet exemple .NET 7, consultez Migrer de ASP.NET Core 7.0 vers 8.0 et migrer de ASP.NET Core dans .NET 8 vers ASP.NET Core dans .NET 9.
• CustomElementsBlazorSample (Blazor WebAssemblyjaviercn/CustomElementsBlazorSample, branche : ) : blazor-wasmpour migrer cet exemple .NET 7, consultez Migrer de ASP.NET Core 7.0 vers 8.0 et Migrer de ASP.NET Core dans .NET 8 vers ASP.NET Core dans .NET 9.

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.

Important

Ne confondez pas le paramètre javaScriptInitializer de RegisterForJavaScript avec des initialiseurs JavaScript. Le nom du paramètre et de la fonctionnalité d’initialiseurs JS est une coïncidence.

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

Remarque

rootComponents.add retourne une instance du composant. Appelez dispose de l’instance pour la libérer :

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

Remarque

Pour l’appel à rootComponents.add, utilisez le paramètre blazor (b (en) minuscules) fourni par l’événement de démarrage Blazor. Bien que l’inscription soit valide lors de l’utilisation de l’objet Blazor (B majuscule), l’approche recommandée consiste à utiliser le paramètre.

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

Remarque

Les liens de documentation vers la source de référence .NET chargent généralement la branche par défaut du référentiel, qui représente le développement actuel pour la prochaine version de .NET. Pour sélectionner une balise pour une version spécifique, utilisez la liste déroulante Échanger les branches ou les balises. Pour plus d’informations, consultez Comment sélectionner une balise de version du code source ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Éléments personnalisés Blazor

Utilisez des éléments personnalisés Blazor pour afficher dynamiquement des composants Razor à partir d’autres infrastructures SPA, telles qu’Angular ou React.

Éléments personnalisés Blazor :

• Utilisez des interfaces HTML standard pour implémenter des éléments HTML personnalisés.
• Éliminez la nécessité de gérer manuellement l’état et le cycle de vie des composants racines Razor à l’aide des API JavaScript.
• Sont utiles pour introduire progressivement des composants Razor dans des projets existants écrits dans d’autres infrastructures SPA.

Les éléments personnalisés ne prennent pas en charge le contenu enfant ou les composants basés sur un modèle.

Nom de l'élément

Conformément à la spécification HTML, les noms des balises d’éléments personnalisés doivent adopter la casse kebab :

❌Non valide : mycounter
❌Non valide : MY-COUNTER
❌Non valide : MyCounter
✔️Valide : my-counter
✔️Valide : my-cool-counter

Package

Ajoutez une référence de package pour Microsoft.AspNetCore.Components.CustomElements au fichier projet de l’application.

Remarque

Pour obtenir des conseils sur l’ajout de packages à des applications .NET, consultez les articles figurant sous Installer et gérer des packages dans Flux de travail de la consommation des packages (documentation NuGet). Vérifiez les versions du package sur NuGet.org.

Exemple de composant

Les exemples suivants sont basés sur le composant Counter du modèle de projet Blazor.

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

Inscription Blazor Server

Procédez comme suit pour inscrire un composant racine en tant qu’élément personnalisé dans une application Blazor Server.

Ajoutez l’espace de noms Microsoft.AspNetCore.Components.Web en haut du fichier Program :

using Microsoft.AspNetCore.Components.Web;

Ajoutez un espace de noms pour les composants de l’application. Dans l’exemple suivant, l’espace de noms de l’application est BlazorSample et les composants se trouvent dans le dossier Pages :

using BlazorSample.Pages;

Modifiez l’appel pour sur AddServerSideBlazor. Spécifiez l’élément personnalisé avec RegisterCustomElement sur l’option de circuit RootComponents. L’exemple suivant inscrit le composant Counter avec l’élément HTML my-counter personnalisé :

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

Inscription Blazor WebAssembly

Procédez comme suit pour inscrire un composant racine en tant qu’élément personnalisé dans une application Blazor WebAssembly.

Ajoutez l’espace de noms Microsoft.AspNetCore.Components.Web en haut du fichier Program :

using Microsoft.AspNetCore.Components.Web;

Ajoutez un espace de noms pour les composants de l’application. Dans l’exemple suivant, l’espace de noms de l’application est BlazorSample et les composants se trouvent dans le dossier Pages :

using BlazorSample.Pages;

Appelez RegisterCustomElement sur RootComponents. L’exemple suivant inscrit le composant Counter avec l’élément HTML my-counter personnalisé :

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

Utilisez l’élément personnalisé inscrit

Utilisez l’élément personnalisé avec n’importe quel framework web. Par exemple, l’élément HTML personnalisé my-counter précédent qui affiche le composant Counter de l’application est utilisé dans une application React avec la balise suivante :

<my-counter></my-counter>

Pour obtenir un exemple complet de création d’éléments personnalisés avec Blazor, consultez le CustomElementsComponentcomposant dans la source de référence.

Remarque

Les liens de documentation vers la source de référence .NET chargent généralement la branche par défaut du référentiel, qui représente le développement actuel pour la prochaine version de .NET. Pour sélectionner une balise pour une version spécifique, utilisez la liste déroulante Échanger les branches ou les balises. Pour plus d’informations, consultez Comment sélectionner une balise de version du code source ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Passer des paramètres

Transmettez les paramètres à votre composant Razor en tant qu’attributs HTML ou en tant que propriétés JavaScript sur l’élément DOM.

Le composant suivant Counter utilise un paramètre IncrementAmount pour définir l’incrémentation du bouton Click me.

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

Affichez le composant Counter avec l’élément personnalisé et transmettez une valeur au paramètre IncrementAmount en tant qu’attribut HTML. Le nom de l’attribut adopte la syntaxe de la casse kebab (increment-amountet non IncrementAmount) :

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

Vous pouvez également définir la valeur du paramètre en tant que propriété JavaScript sur l’objet élément. Le nom de propriété adopte la syntaxe de la casse chameau (incrementAmountet non IncrementAmount) :

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

Vous pouvez mettre à jour les valeurs de paramètres à tout moment à l’aide de la syntaxe d’attribut ou de propriété.

Types de paramètres pris en charge :

• À l’aide de la syntaxe de propriété JavaScript, vous pouvez transmettre des objets de n’importe quel type qui est sérialisable en JSON.
• À l’aide d’attributs HTML, vous êtes limité à la transmission d’objets de type chaîne, booléen ou numérique.

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.

Warning

Les fonctionnalités des composants Angular et React sont actuellement expérimentales, non prises en charge et susceptibles d’être modifiées ou supprimées à tout moment. Nous vous invitons à nous faire part de vos commentaires sur la façon dont cette approche particulière répond à vos besoins.