mars 13, 2023

Intégrer des composants Blazor avec la prise en charge des éléments personnalisés .NET 7

Vous pouvez désormais intégrer des composants Blazor partout où vous pouvez exécuter JavaScript, y compris sur des sites qui utilisent un framework JavaScript comme React ou Angular.

Blazor est devenu un cadre productif, stable et fiable pour la création d’applications Web.

Pour les développeurs C # en particulier, cela a ouvert une nouvelle frontière, nous permettant d’apporter nos connaissances et compétences existantes au monde du « développement Web moderne ».

Jusqu’à récemment, si vous vouliez utiliser Blazor, vous deviez pratiquement l’adopter dans son intégralité, en créant un nouveau site Blazor à partir de zéro.

Mais que se passe-t-il si vous disposez d’un code JavaScript existant (et de l’expertise de vos équipes) ? Vous devrez peut-être prendre ce que vous avez déjà et l’étendre avec Blazor, peut-être en l’utilisant pour des zones distinctes de votre site, ou sur des pages spécifiques où Blazor semble être un bon choix.

Avec .NET 7, cela devient beaucoup plus facile, grâce à la prise en charge officielle des éléments personnalisés HTML.

Qu’est-ce qu’un élément personnalisé ?

Les éléments personnalisés font partie de la spécification HTML. Ils permettent à l’analyseur HTML (exécuté dans votre navigateur) de gérer des éléments « non standard ».

Par exemple, vous pouvez créer un composant Greeting, puis utiliser un peu de JavaScript pour l’enregistrer en tant que HTMLElement.

class Greeting extends HtmlElement { 
    
}

customElements.define("my-greeting", Greeting);

Avec cela, lorsque vous déclarez une instance de my-greeting sur une page, l’analyseur HTML construira une nouvelle instance de Greeting classe:

<my-greeting></my-greeting>

Alors, comment cela se rapporte-t-il à Blazor ?

Intégrer des composants Blazor n’importe où

À partir de .NET 7, les composants Blazor peuvent être enregistrés en tant qu’éléments personnalisés. Cela signifie que vous pouvez rendre certains types de composants Blazor partout où vous pouvez exécuter JavaScript.

Mais comment cela se passe-t-il en pratique ?

Prends ça simplement Greeting Composant Blazor :

Salutation.razor

<h1>
    Hello @Name
</h1>

@code {
    
    [Parameter]
    public string Name { get;set; } = "Alice";
    
}

Cela saluera le nom de la personne transmise via le Name paramètre—par exemple :

<Greeting Name="Samantha" />

Maintenant, cela fonctionnera très bien dans une application Blazor, mais que se passe-t-il si vous souhaitez l’utiliser avec un site HTML et JavaScript standard ?

Pour enregistrer votre composant en tant qu’élément personnalisé, vous devez :

Définir le composant dans votre application Blazor
Enregistrez le composant en tant qu’élément personnalisé (avec un identifiant de balise unique)
Référencer le runtime Blazor sur une page HTML
Rendre une instance de Greeting composant (utilisant son identifiant de balise personnalisée) sur ladite page HTML

Vous aurez d’abord besoin d’une application Blazor, qui contient le composant que vous souhaitez utiliser (Greeting dans ce cas).

Vous devrez également référencer le package officiel Custom Elements Nuget :

dotnet add package Microsoft.AspNetCore.Components.CustomElements

Ensuite, dans votre application Web Programme.cs vous pouvez enregistrer l’élément personnalisé.

Dans Blazor WASM :

public static async Task Main(string[] args)
{
    var builder = WebAssemblyHostBuilder.CreateDefault(args);
  
    ...

    
    builder.RootComponents.RegisterCustomElement<Greeting>("my-greeting");

    await builder.Build().RunAsync();
}

Ou Serveur Blazor :

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

Vous pouvez maintenant utiliser votre Greeting composant, via son identifiant de tag personnalisé (my-greeting) sur n’importe quelle page.

Commençons par le tester sur la page « accueil » par défaut de notre application Blazor. Si vous utilisez WASM, ce sera Index.html; pour Blazor Server, vous recherchez _Host.cshtml.

Quelque part dans le corps de cette page par défaut, déclarez une instance de Greeting composant à l’aide de sa balise d’élément personnalisée (my-greeting).

Index.html (ou _Host.cshtml)

...

<body>
    
    <my-greeting name="Jeff"></my-greeting>
    
    ...
    
</body>

Maintenant, avant de passer des heures à essayer de comprendre pourquoi votre élément personnalisé ne fonctionne pas, il y a un détail important concernant les éléments personnalisés…

La spécification des éléments personnalisés exige que tous les éléments personnalisés contiennent un trait d’union (-) dans le nom de la balise.

Cela m’a surpris la première fois que j’ai essayé d’utiliser le nom greeting pour cet élément personnalisé.

Plus précisément, vos noms de balises d’éléments personnalisés doivent adopter le cas kebab. Par exemple, ces noms de balises ne fonctionnera pas:

mes salutations
MES SALUTATIONS
Mes salutations

Alors que ces marchera:

mes salutations
mes-meilleures-salutations

Avec my-greeting enregistré avec succès en tant qu’élément personnalisé et une instance déclarée sur votre page index.html, vous avez maintenant un rendu de composant Blazor sur une page HTML standard.

C’est bien beau, mais jusqu’à présent, nous n’avons vraiment fait que quelque chose que nous aurions pu réaliser beaucoup plus facilement en utilisant notre Greeting composante directement dans notre Blazor application.

Comment pouvons-nous utiliser des éléments personnalisés pour rendre les composants Blazor ailleurs, sur des pages HTML standard et via JavaScript ?

La réponse à cela dépend si vous utilisez Blazor Server ou Blazor WASM.

Rendu d’éléments personnalisés via Blazor Server

Si vous utilisez Blazor Server, vous devrez continuer à utiliser une application ASP.NET Core comme hôte. Cela a du sens compte tenu de la façon dont Blazor Server conserve l’état du composant en mémoire sur le serveur lui-même.

Le moyen le plus simple d’afficher un élément personnalisé sur une page HTML autonome consiste à créer une page HTML dans le wwwroot dossier et y référencer directement l’élément personnalisé :

<!DOCTYPE html>
<html lang="en">
<head>
    <base href="/"/>
    <script src="_framework/blazor.server.js"></script>
</head>
<body>
    <my-greeting name="Indy"></my-greeting>
</body>
</html>

Le <base href="https://www.telerik.com/" est important – sans cela, votre serveur ne parviendra pas à charger les fichiers Blazor pertinents.

Nous avons référencé le fichier JavaScript principal de Blazor Server (le ciment qui le maintient ensemble, en démarrant Blazor et en activant le lien entre Blazor et le DOM du navigateur), puis rendu une instance de notre composant de salutation dans le corps principal de la page.

Pour tester cela, lancez votre application Blazor Server, puis accédez manuellement à /demo.html.

Le serveur ASP.NET Core servira la page demo.html, qui, à son tour, se connectera à Blazor Server (à l’aide du script de blazor.server.js), puis rendra le my-greeting élément personnalisé, le rendant en HTML standard.

Si vous inspectez le code source du composant rendu à l’aide des DevTools de votre navigateur, vous verrez quelque chose comme ceci :

<my-greeting name="Indy">
    <h1>
    	Hello Indy
    </h1>
</my-greeting>

Maintenant, vous remarquerez peut-être, lorsque vous inspectez votre composant dans le navigateur, qu’il manque des styles. Pour les obtenir, vous devez référencer le même CSS que vous utilisez dans votre projet Blazor Server.

<!DOCTYPE html>
<html lang="en">
<head>
    <base href="/"/>
    
    
    <link rel="stylesheet" href="Your-Project.styles.css">
    <link rel="stylesheet" href="css/bootstrap/bootstrap.min.css">
    <link rel="stylesheet" href="css/app.css">  
    
    <script src="_framework/blazor.server.js"></script>
</head>
<body>
    <my-greeting name="Indy"></my-greeting>
</body>
</html>

Mais que se passe-t-il si vous souhaitez vous libérer entièrement d’ASP.NET Core et intégrer vos composants Blazor ailleurs, sur une page qui n’est pas hébergée via ASP.NET ?

Pour cela vous pouvez vous tourner vers Blazor WASM.

Rendre les composants Blazor n’importe où via Blazor WASM

Pour servir vos éléments personnalisés Blazor à partir de pratiquement n’importe quelle page HTML (ou application JavaScript), vous devez utiliser Blazor WASM.

Vous devez d’abord vous procurer les composants Blazor et le framework Blazor lui-même, afin de pouvoir le référencer à partir d’une page HTML standard.

Pour ce faire, vous devrez publier votre application Blazor, via votre IDE, ou le dotnet commande:

dotnet publish

Lorsque vous localisez l’application publiée (par défaut, elle sera dans le Déboguer dossier), vous trouverez deux dossiers très importants : _content et _framework.

Arborescence de répertoires montrant un .NET

_framework contient le runtime Blazor, dont vous avez besoin pour que tout cela fonctionne.
_content inclut le script JavaScript approprié du package Nuget Custom Elements de Microsoft.

Il existe d’autres dossiers, comme cssque vous souhaiterez apporter pour vous assurer que vos composants s’affichent correctement dans leur nouvelle maison.

Commencez par copier ce qui suit dans un nouveau dossier :

_contenu
_cadre
CSS
Your-Project.styles.css (BlazorExamples.WASM.styles.css dans l’exemple ci-dessus)

Une fois que vous les avez copiés, dans le même dossier, créez un « vide » index.html déposer.

Le dossier résultant devrait ressembler à ceci :

Annuaire montrant

Remplacez maintenant le contenu du index.html fichier avec ceci :

<html>
<head>
    <base href="/"/>
    <script src="_framework/blazor.webassembly.js"></script>
</head>
<body>

    <my-greeting name="Susan"></my-greeting>

</body>
</html>

Ce <base href="https://www.telerik.com/" line est important, sans quoi vos éléments personnalisés ne se chargeront pas.

À partir de là, vous devez lancer un serveur de développement Web local pour tester votre travail (il ne suffit pas d’ouvrir index.html dans le navigateur).

Si vous voulez une option rapide (et que cela ne vous dérange pas de laisser un peu de Node.js dans votre vie !), vous pouvez émettre cette commande (en supposant que Node est installé sur votre machine) :

 npm install http-server -g

Ensuite, depuis votre dossier (celui que nous venons de créer, avec index.html), lancez cette commande :

http-server

Vous devriez maintenant voir la sortie de http-server indiquant les adresses locales où votre site est accessible :

Connection Timeout: 120 seconds
Directory Listings: visible
AutoIndex: visible
Serve GZIP Files: false
Serve Brotli Files: false
Default File Extension: none

Available on:
  http://192.168.1.31:8081
  http://127.0.0.1:8081
  http://172.31.32.1:8081
Hit CTRL-C to stop the server

Appuyez sur l’une de ces adresses et vous devriez voir votre composant de salutation Blazor dans toute sa splendeur :

Une page de navigateur affichant les mots

C’est vrai que ça n’a pas l’air génial. C’est parce que nous n’avons pas (encore) dit à la page HTML d’utiliser l’un des styles de l’application Blazor d’origine.

Ajoutons des liens vers les fichiers CSS pertinents à partir du dossier que vous avez copié précédemment.

<html>
<head>
    <base href="/"/>
    <script src="_framework/blazor.webassembly.js"></script>
    
    
    <link rel="stylesheet" href="Your-Project.styles.css">
    <link rel="stylesheet" href="css/bootstrap/bootstrap.min.css">
    <link rel="stylesheet" href="css/app.css">    
</head>
<body>

    <my-greeting name="Susan"></my-greeting>

</body>
</html>

Prévisualisez ceci dans le navigateur maintenant et vous devriez voir une salutation entièrement stylée :

Une page de navigateur affichant les mots

Interagissez avec vos éléments personnalisés Blazor via JavaScript

Nous avons vu comment déclarer une instance de my-greeting en HTML :

<my-greeting name="Alice"></my-greeting>

Vous pouvez également interagir avec un élément personnalisé via JavaScript, ce qui est utile pour mettre à jour ses paramètres en réponse à d’autres événements :

const elem = document.querySelector("my-greeting");
elem.name = "Jeff";

Cela apporte un avantage supplémentaire dans la mesure où davantage de types de paramètres sont pris en charge lorsque vous interagissez avec l’élément via JavaScript que lorsque vous transmettez des valeurs en tant qu’attributs HTML.

En utilisant JavaScript, vous pouvez transmettre n’importe quel objet sérialisable JSON.

En utilisant les attributs HTML, vous êtes limité aux chaînes, booléens ou types numériques.

Enfin, si vous choisissez d’interagir avec vos éléments personnalisés via JavaScript, vous pouvez également attacher des fonctions JavaScript aux éléments de votre composant. EventCallback paramètres.

Disons, par exemple, que vous avez étendu la Greeting composant pour élever un EventCallback lorsqu’un bouton est cliqué.

Salutation.razor

<h1>
    Hello @Name
</h1>

<button @onclick="OnClicked">Click me!</button>

@code {
    
    [Parameter]
    public string Name { get;set; } = "Alice";

    [Parameter]
    public EventCallback OnClicked { get; set; }
    
}

Vous pouvez attacher une fonction JavaScript au OnClicked paramètre de rappel.

const greeting = document.querySelector("my-greeting");

greeting.onClicked = () => {
	console.log("clicked!")
};

Une chose à surveiller ici : Blazor démarre généralement automatiquement lorsque vous faites référence au script :

<script src="_framework/blazor.webassembly.js"></script>

Pour attacher un gestionnaire JavaScript, vous devez le faire au « bon » moment, après que Blazor a terminé le chargement.

Vous pouvez y parvenir en désactivant le comportement de démarrage automatique de Blazor (par défaut) et en le démarrant vous-même à la place.

<script src="_framework/blazor.server.js" autostart="false"></script>

<script>
    const greeting = document.querySelector("my-greeting");

    Blazor.start().then(() => {
        greeting.onClicked = () => {
            console.log("clicked!")
        };
    });
</script>

Avec cela, n’importe quel bouton clique dans le my-greeting déclenchera la fonction JavaScript, qui enregistrera la chaîne « cliqué! » à la console du navigateur.

En résumé

La prise en charge officielle de Blazor pour les éléments personnalisés permet de rendre et d’interagir avec les composants Blazor partout où vous pouvez exécuter JavaScript.

Ceci est particulièrement utile si vous souhaitez utiliser Blazor dans un site HTML/JavaScript existant et/ou si vous souhaitez adopter Blazor de manière incrémentielle.

Les types de paramètres que vous pouvez envoyer via les attributs HTML sont limités aux primitives (bools, chaînes et types numériques), mais si vous interagissez avec le composant via JavaScript, vous pouvez transmettre n’importe quel objet sérialisable JavaScript.

Enfin, si vous souhaitez réagir aux événements de votre composant, vous pouvez attacher des fonctions JavaScript à EventCallback paramètres.

Blog ARC Optimizer

mars 13, 2023

Intégrer des composants Blazor avec la prise en charge des éléments personnalisés .NET 7

Qu’est-ce qu’un élément personnalisé ?

Intégrer des composants Blazor n’importe où

Rendu d’éléments personnalisés via Blazor Server

Rendre les composants Blazor n’importe où via Blazor WASM

Interagissez avec vos éléments personnalisés Blazor via JavaScript

En résumé

Articles similaires

Blog ARC Optimizer

Qu’est-ce qu’un élément personnalisé ?

Intégrer des composants Blazor n’importe où

Rendu d’éléments personnalisés via Blazor Server

Rendre les composants Blazor n’importe où via Blazor WASM

Interagissez avec vos éléments personnalisés Blazor via JavaScript

En résumé

Partager :

Articles similaires