Fermer

février 26, 2020

Apprentissage des composants Blazor: le guide définitif


Dans ce guide, découvrez les principes fondamentaux de la construction d'un composant Blazor et découvrez comment créer un exemple d'application Blazor qui le regroupe.

Dans cet article, nous allons découvrir le modèle de composant Blazor, Razor Components. À l'aide des composants de rasoir, nous allons créer un composant pour afficher les prévisions météorologiques hebdomadaires. Grâce à ce processus, nous apprendrons les principes fondamentaux de la construction des composants, y compris les directives les paramètres le contenu / modèles pour enfants le routage et gestion des événements . Pour plus de simplicité, nous utiliserons les ressources que nous offre le nouveau modèle d'application Blazor Server.

Directives

Les directives du compilateur sont utilisées pour donner des instructions à Razor qui modifient généralement la façon dont un composant est analysé ou permettent différentes fonctionnalités. Créons une nouvelle page pour afficher les prévisions météo hebdomadaires. Dans le framework Blazor, les pages contiennent des composants décorés de la directive @page . La directive @page est suivie d'une valeur de chaîne qui définit l'itinéraire de page du composant, lui donnant une URL qui peut être parcourue dans le navigateur, par exemple: @page «/ my-url». Même si la directive @page permet le routage, elle ne supprime pas notre capacité à utiliser le composant comme bloc de construction de base pour d'autres composants ou «pages».

Commençons par ajouter un nouveau composant Razor à notre application appelé WeeklyForecast. Dans le projet, choisissez le dossier Pages et cliquez avec le bouton droit de la souris, choisissez Ajouter> Nouvel élément, puis sélectionnez Composant Razor comme illustré dans Figure 1 . Nommez le composant WeeklyForecast.razor puis cliquez sur créer pour terminer.

 Création d'un nouveau composant de rasoir avec la boîte de dialogue Ajouter un nouvel élément.
Figure 1: Création d'un nouveau rasoir Composant avec la boîte de dialogue Ajouter un nouvel élément

Notre composant est créé avec un passe-partout très basique. Nous allons laisser ce passe-partout en place et ajouter notre directive @page avec la valeur "/ hebdomadaireforecast" en haut du fichier. Il est recommandé de placer toutes les directives en haut du fichier, sauf s'il existe un cas d'utilisation particulier où elles doivent être placées ailleurs. Par exemple, le bloc @code est une directive qui est normalement située au bas du composant, mais le déplacer ne provoquera pas d'erreur.

 @page "/ hebdomadaireforecast"

WeeklyForecast

@code { }

Routage

Nous pouvons exécuter notre application et afficher les modifications dans le navigateur. Une fois l'application exécutée, ajoutez / hebdomadaireforecast pour accéder à la page nouvellement créée. Les résultats devraient ressembler à Figure 2 .

 Le composant WeeklyForecast utilisant la directive @page pour spécifier le routage.
Figure 2: Le composant WeeklyForecast utilisant la directive @page pour spécifier

Utilisons cette page pour construire un prototype de ce à quoi devrait ressembler notre produit final. Cela nous aidera à décider où les composants peuvent être extraits en bits réutilisables. Nous afficherons les informations météorologiques à l'utilisateur à l'aide des classes HTML et CSS de Bootstrap et Iconic.

À l'intérieur de la page WeeklyForecast, nous ajouterons notre premier élément d'interface utilisateur prototype, un jour de données de prévisions météorologiques. Nous utiliserons des valeurs codées en dur, qui seront éventuellement remplacées par des données. Le balisage est contenu dans un élément div qui utilise la classe de carte Bootstrap pour lui donner une belle apparence. À l'intérieur du corps de la carte, nous utilisons un élément span avec les classes Open Iconic io io-rain qui affichera une icône représentant l'état du temps.

 @page "/ hebdomadaireforecast"

WeeklyForecast

17 C & deg;

Temps pluvieux prévu lundi        

Nous allons enregistrer ces modifications et recharger la page WeeklyForecast qui affiche maintenant la carte météo. La page rendue doit ressembler à Figure 3 .

 Un prototype de la page de prévisions hebdomadaires affichant une seule prévision météorologique.
Figure 3 : Un prototype de la page de prévisions hebdomadaires affichant une seule prévision météorologique.

Notre page prend forme; cependant, nous établissons une prévision hebdomadaire et nous avons actuellement une seule journée. Modifions la page pour qu'elle affiche cinq jours de données de prévision. Étant donné que nous allons répéter les cartes, nous emballerons l'affichage dans un conteneur de boîte flexible. Puisque nous utilisons Bootstrap, nous pouvons utiliser la classe pratique d-flex . À l'intérieur du conteneur d-flex, nous devons répéter notre affichage météo. Nous comptons sur Razor pour nous aider à répéter l’affichage avec une boucle foreach . Pour créer une boucle simple sans aucune donnée réelle, nous utiliserons la méthode Enumerable.Range pour générer une séquence pour nous. Avec plusieurs cartes affichées, supprimons l'attribut de style de largeur statique style = "width: 18rem;" et laissez l'élément se développer au besoin. Pour créer un espace entre chaque carte, la classe CSS m-2 ou marge 2 est ajoutée.

    @foreach (élément var dans Enumerable.Range (1, 5))     {         

17 C & deg;

Temps pluvieux prévu lundi             

}

Le résultat est une prévision sur cinq jours qui se répète sur la page, comme illustré dans Figure 4 .

 Un prototype de la page de prévisions hebdomadaires affichant une seule prévision météorologique.
Figure 4:
La ​​page météo hebdomadaire montre une carte de prévisions météorologiques répétée avec cinq éléments statiques sur la page.

À ce jour, vous pouvez probablement voir apparaître un modèle où le jour individuel de la météo est répété. Cette section répétée pourrait facilement être un composant réutilisable qui résume une journée de temps. Extrayons notre composant de la page WeeklyForecast dans son propre fichier de composant.

Dans le dossier / Shared du projet, nous allons créer un nouveau composant appelé WeatherDay. Nous allons supprimer le contenu passe-partout du composant nouvellement créé et déplacer le code HTML de l'intérieur de la boucle foreach du composant WeeklyForecast vers le composant WeatherDay. Ce travail rapide de copier / coller est tout ce dont nous avons besoin pour créer un composant Razor de base. Avec le balisage déplacé vers le composant WeatherDay, nous pouvons l'utiliser par son nom dans WeeklyForecast. Nous allons ajouter un composant WeatherDay au corps de la boucle foreach.

/ Shared / WeatherDay.razor

 
    
                 

17 C & deg;

Temps pluvieux attendu lundi        

/Pages/WeeklyForecast.razor

… html
    @foreach (élément var dans Enumerable.Range (1, 5))     {          }

Lorsque nous réexécutons l'application, elle doit être identique à la précédente, comme illustré dans Figure 4 . Le résultat n'a pas été modifié, car nous avons simplement transféré la responsabilité du rendu de la carte de WeeklyForecast à WeatherDay.

Paramètres

Remplaçons certaines des valeurs statiques par des paramètres de composant. Le moyen facile de comprendre les paramètres de composant dans le modèle de composant Razor est de les voir comme des propriétés publiques décorées avec un attribut spécial [Parameter]. Nous discuterons des attributs de paramètres supplémentaires au fur et à mesure, mais l'attribut standard [Parameter] conviendra à la plupart des scénarios.

Maintenant que le code HTML de notre composant est isolé à l'intérieur du composant WeatherDay, nous pouvons rendre notre composant plus dynamique en lui permettant d'accepter des données en utilisant des paramètres. Pour notre composante météo, nous devons afficher le résumé météo c'est-à-dire qu'il est pluvieux, ensoleillé ou nuageux avec une icône correspondante. Nous afficherons également la température et le jour de la semaine . Créons quelques paramètres pour commencer et implémentons des fonctionnalités plus détaillées au fur et à mesure de chaque défi. Nous allons commencer par un bloc @code, ajouter nos trois propriétés et les décorer à l'aide de l'attribut [Parameter].

 @code {

    [Parameter]
    chaîne publique Résumé {get; ensemble; }

    [Parameter]
    public int TemperatureC {get; ensemble; }

    [Parameter]
    public DayOfWeek DayOfWeek {get; ensemble; }

}

Liaison de données unidirectionnelle

Pour afficher la valeur du paramètre, nous utiliserons la liaison de données unidirectionnelle. Cela va simplement écrire la valeur en ligne où la valeur apparaît dans le balisage. Dans Razor, nous préfixons simplement le nom des propriétés avec un symbole @, ex: @Summary. Pour chaque paramètre, nous mettrons à jour le balisage en remplaçant le texte statique par une valeur liée aux données. Lorsque Razor génère la sortie finale, toutes les valeurs sont automatiquement converties en chaîne. Il n'est pas nécessaire de convertir manuellement une valeur comme TemperatureC même s'il s'agit d'un entier, mais nous avons la possibilité de personnaliser la mise en forme si nous le souhaitons.

 
    
                 

@TemperatureC C & deg;

@Résumé du temps prévu @DayOfWeek      

Maintenant que notre composant a des paramètres qui sont liés aux données, nous pouvons revenir à la page WeeklyForecast et mettre à jour notre instance de composant pour utiliser la nouvelle fonctionnalité. Nous allons localiser le composant WeatherDay sur la page et définir des valeurs statiques pour nos paramètres.

 @foreach (élément var dans Enumerable.Range (1, 5))
{
    
    
}

Continuons en ajoutant des données dynamiques à notre page WeeklyForecast. Nous allons injecter un WeatherForecastService sur la page et l'utiliser pour générer des données. WeatherForecastService est inclus dans le nouveau modèle de projet et se trouve dans le dossier / Data du projet. Ouvrez le fichier WeatherForecastService.cs et examinez son fonctionnement. Nous pouvons voir qu'il existe une collection de résumés qui sont utilisés pour remplir la propriété Résumé. La méthode GetForecastAsync génère 5 valeurs WeatherForecast aléatoires basées sur une date de début.

Simplifions la liste des résumés pour n'inclure que les valeurs: Nuageux Rainy et Sunny Cela correspondra à trois icônes disponibles dans notre projet.

 chaîne privée statique en lecture seule [] Summaries = new []
{
 // "Freezing", "Bracing", "Chilly", "Cool", "Mild",
 // "Chaud", "Doux", "Chaud", "Étouffant", "Brûlant"
 "Nuageux", "Pluvieux", "Ensoleillé"
};

Dans WeatherDay, nous utiliserons une propriété en lecture seule pour déterminer l'icône à afficher en fonction du champ Résumé. Une instruction ternaire rapide convertit la chaîne Résumé en nom d'icône correspondant.

 string IconCssClass =>
        Résumé == "Nuageux"? "cloud":
        Résumé == "Rainy"? "pluie" :
        "Soleil";

Nous pouvons maintenant utiliser la propriété IconCssClass pour modifier la valeur CSS de l'icône du composant.

  

Injection d'un service

Le composant WeatherDay peut désormais être lié à des données dynamiques. Nous injecterons WeatherForecastService sur la page à l'aide de la directive @inject. La dépendance est disponible car le WeatherForecastService était déjà enregistré dans Startup.cs par le modèle. Nous pouvons voir comment l'injection de dépendances ( DI ) est configurée en regardant dans la méthode ConfigureServices.

 services.AddSingleton  ();

Sur la page WeeklyForecast, sous la directive @page, nous ajoutons @inject et spécifions à la fois le type (T) qui sera résolu et le nom de variable qu'une instance de ce type sera assignée, ex: @inject T myTInstance . Une directive @using étendra le WeatherForecastService.

 @page "/ hebdomadaireforecast"
@using Data;
@inject WeatherForecastService WeatherService

Méthode OnInitializedAsync Lifecycle

Avec le WeatherForecastService disponible, nous pouvons maintenant appeler la méthode GetForecastAsync qui génère un tableau d'objets WeatherForecast. Les données doivent être chargées lors de la première initialisation du composant. Les composants Razor gèrent l'initialisation via les méthodes de cycle de vie OnInitializedAsync et OnInitialized . Les méthodes de cycle de vie des composants sont automatiquement héritées de la classe ComponentBase qui compose tous les composants Razor.

Il est préférable d'utiliser du code asynchrone chaque fois que cela est possible, car cela permet une meilleure expérience utilisateur globale. De plus, notre WeatherForecastService fournit une fonctionnalité asynchrone, nous allons donc utiliser OnInitializedAsync pour récupérer les données lors de l'initialisation du composant.

Ajoutons un champ pour capturer les données qui seront affichées sur la page. Nous allons créer un tableau vide de prévisions WeatherForecast. Après le champ prévisions, nous allons remplacer la méthode OnInitializedAsync et remplir le champ prévisions en attendant l'appel à GetForecastAsync.

 WeatherForecast [] prévisions;

tâche prioritaire asynchrone protégée OnInitializedAsync ()
{
    prévisions = attendre WeatherService
                .GetForecastAsync (DateTime.Now);
}

Maintenant que nous utilisons les données de notre WeatherService, nous devons remplacer la boucle statique de notre vue par une boucle qui utilise le tableau de prévisions. À l'intérieur de la nouvelle boucle, nous référençons l'élément actuel et appliquons la valeur de propriété correspondante au paramètre du composant. Le compilateur .NET est intelligent, nous n'avons donc qu'à utiliser le symbole @ sur les valeurs de chaîne pour identifier les littéraux de chaîne à partir des valeurs de propriété.

 @ * foreach (élément var dans Enumerable.Range (1, 5)) * @
@foreach (var prévision dans les prévisions)
{
     
     
}

Puisque nous ne travaillons plus avec des données statiques, nous devons envisager la possibilité de valeurs nulles. Actuellement, si le composant s'affiche alors que le tableau de prévisions est nul, une exception NullReferenceException sera levée lors de l'entrée dans la boucle foreach. Pour éviter cela, nous utilisons une instruction if / then pour fournir un affichage lorsqu'aucune donnée n'est présente.

 @if (prévisions == null)
{
     Aucune donnée 
}
autre
{
    foreach (var prévision dans les prévisions)
    {
        
        
    }
}

Nous pouvons maintenant rendre les données de manière dynamique en visitant l'itinéraire de prévision hebdomadaire comme indiqué dans Figure 5 .

 La page météo hebdomadaire montre une carte de prévisions météorologiques répétée avec cinq éléments statiques sur la page.
Figure 5: La ​​page météo hebdomadaire montre une carte de prévisions météorologiques répétée avec cinq éléments statiques sur la page

Nos composants WeeklyForecast et WeatherDay commencent à se combiner. Nous sommes en mesure de remplir dynamiquement les composants en fonction d'une collection de données qui est chargée lors de l'initialisation du composant. Les données circulent du WeeklyForecast directement vers chaque composant WeatherDay via une liaison de données unidirectionnelle. C'est une façon courante d'afficher des données et fonctionne bien lorsque nous avons une interface utilisateur cohérente que nous créons.

Développons notre composant WeatherDay et permettons à son interface utilisateur d'être étendue davantage en fournissant une région de modèle.

Contenu enfant / Templates

Les composants modèles sont des composants qui acceptent un ou plusieurs modèles d'interface utilisateur en tant que paramètres. Les modèles peuvent être utilisés pour personnaliser une partie de la sortie rendue des composants. Nous allons continuer avec notre composant WeatherDay comme exemple de mise en œuvre d'un modèle.

Pour rendre notre composant WeatherDay plus flexible, nous allons ajouter une région de modèle représentée sous forme de bloc rouge dans Figure 6. Cette zone permettra aux développeurs d'insérer n'importe quel contenu HTML, Razor ou Composant en tant que contenu enfant.

 Un cadre rouge indique où la région modèle du composant sera créée.
Figure 6:
Un cadre rouge indique où la région de modèle du composant sera créée.

Pour ajouter un modèle à notre composant WeatherDay, nous utiliserons la classe RenderFragment. Un RenderFragment représente un segment de contenu d'interface utilisateur, implémenté en tant que délégué qui écrit le contenu dans un RenderTreeBuilder (le DOM virtuel Blazor). En surface, on peut supposer que le contenu enfant est écrit en HTML brut, mais le RenderFragment est conforme à l'architecture des composants de Blazor.

En surface, on peut supposer que le contenu enfant est écrit en HTML brut, mais le RenderFragment est conforme au architecture de composant de Blazor.

Ajoutons un RenderFragment à notre composant WeatherDay. Le RenderFragment est ajouté exactement comme tout autre paramètre de composant à l'aide d'une propriété et d'un attribut [Parameter]. Pour cet exemple, nous appellerons la propriété CustomMessage.

 @code {

    [Parameter]
    public RenderFragment CustomMessage {get; ensemble; }

    [Parameter]
    chaîne publique Résumé {get; ensemble; }
…

}

Pour utiliser le paramètre, nous référençons le RenderFragment lorsque nous souhaitons qu'il apparaisse dans notre balisage de composant. Entre les éléments h1 et p de notre composant, le @CustomMessage est placé, c'est là que le modèle sera rendu.

 
    
                 

@TempératureC C & deg;

        @Message personnalisé         

        @Summary weather attendu @DayOfWeek

Lors de l'utilisation du composant WeatherDay, le modèle est appliqué en spécifiant le modèle par son nom à l'aide d'une balise HTML . À l'intérieur de cette balise, nous pouvons utiliser le balisage Razor, du HTML, d'autres composants ou toute combinaison de ces éléments. Appliquons cela à notre exemple en ajoutant une simple instruction if pour vérifier les prévisions Rainy, puis afficher une alerte spéciale sur ces éléments. À l'intérieur du CustomMessage, nous ajouterons du code Razor et un élément de base stylisé avec une classe CSS d'alerte-danger d'alerte Bootstrap.

 
    
        @if (prevision.Summary == "Rainy")
        {
            
                Avertissement de tornade!             
        }     

Lorsque nous exécutons l'application et visualisons la page weekyforecast, elle affiche désormais un "avertissement de tornade!" zone d'alerte à l'intérieur du composant WeatherDay comme illustré dans Figure 7 .

 Les prévisions hebdomadaires sont affichées avec un avertissement Tornado affiché dans la région du modèle du composant WeatherDay.
Figure 7: Les prévisions hebdomadaires sont affichées avec un avertissement Tornado affiché dans la région du modèle du composant WeatherDay.

Jusqu'à présent, les composants WeeklyForecast et WeatherDay ont la plupart des fonctionnalités que nous trouvons couramment dans l'architecture des composants. Cependant, un aspect important du développement de l'interface utilisateur n'a pas encore été discuté, l'interactivité . Ensuite, nous verrons comment gérer les événements avec Blazor en donnant aux utilisateurs la possibilité de sélectionner un élément affiché dans les prévisions hebdomadaires.

Gestion des événements

Lorsque nous pensons aux événements et aux délégués en C #, il est probable que nous considérons les mots-clés délégué: événement et ou les types de délégué Action et Func . Ce sont des options techniquement valables lorsque vous travaillez avec des assemblages C # standard. L'utilisation de l'interface utilisateur dans une application Blazor à l'aide des composants Razor introduit un modèle d'architecture différent et un délégué spécial appelé EventCallback .

EventCallback est un type délégué utilisé pour exposer les événements entre les composants. Un composant parent peut affecter une méthode de rappel à EventCallback d'un composant enfant. Lorsque vous utilisez EventCallback de cette manière, les composants parent et enfant sont automatiquement restitués lorsque des événements sont déclenchés. L'utilisation de event, delegate, Action ou Func peut entraîner la non-mise à jour de l'interface utilisateur comme prévu. Pour cette raison, EventCallback doit toujours être utilisé dans Razor Components.

EventCallback est un type délégué utilisé pour exposer les événements sur les composants.

Pour montrer comment EventCallback est utilisé, nous allons continuer avec WeeklyForecast et WeatherDay Composants. Nous ajouterons la possibilité de sélectionner un WeatherDay à partir des prévisions hebdomadaires lorsque l'utilisateur clique sur un jour donné.

Nous allons commencer par ajouter un nouveau paramètre à notre composant WeatherDay nommé OnSelected. Le paramètre OnSelected doit être un EventCallback de DayOfWeek. Cela signifie que l'événement renverra un type de DayOfWeek comme argument. Le DayOfWeek est une valeur que nous pouvons utiliser pour identifier l'élément déclenché OnSelected.

 [Parameter]
public EventCallback  OnSelected {get; ensemble; }

Sous le paramètre OnSelected, un gestionnaire d'événements est créé, et ce gestionnaire est chargé de lever le délégué d'événement OnSelected sur le composant parent. Pour invoquer OnSelected, nous appelons InvokeAsync et passons le DayOfWeek actuel comme argument.

 void HandleOnSelected ()
{
    OnSelected.InvokeAsync (this.DayOfWeek);
}

En poursuivant avec la logique WeatherDay, une propriété Selected est ajoutée pour indiquer si le composant est dans un état sélectionné. Nous utiliserons cette propriété non seulement pour lier la valeur sélectionnée au composant, mais également pour définir le CSS correspondant pour l'interface utilisateur. En utilisant une propriété privée SelectedCss, nous déterminons la classe CSS à appliquer en fonction de la valeur de la propriété Selected. Si l'élément est sélectionné, la classe bg-primary text-white est utilisée pour mettre en surbrillance le composant et inverser la couleur du texte, sinon la valeur par défaut sera bg-light.

 [Parameter]
public bool Selected {get; ensemble; }

chaîne privée SelectedCss => Sélectionné?
        "bg-primary text-white": "bg-light";

Dans notre balisage de composant, nous pouvons maintenant déclencher le délégué d'événement HandleOnSelected lorsque l'utilisateur clique sur l'interface utilisateur. Sur l'élément div le plus à l'extérieur, nous attacherons un gestionnaire d'événements onclick et l'affecterons à la méthode HandleOnSelected. Nous allons également modifier le div pour utiliser la valeur SelectedCss, basculant efficacement l'apparence de l'interface utilisateur.

 
    
        …     

Le composant WeatherDay peut maintenant être sélectionné et nous pouvons appliquer la nouvelle fonctionnalité avec quelques modifications à la classe WeatherForecast et au composant WeeklyForecast. Étant donné que WeatherForecast fournit les données et l'état de notre vue, nous ajouterons une propriété sélectionnée que nous pourrons ensuite lier à nos composants.

 classe publique WeatherForecast
{
    public bool Selected {get; ensemble; }
     …

Dans le composant WeeklyForecast, un gestionnaire d'événements est ajouté pour l'événement OnSelected. La méthode HandleItemSelected acceptera l'argument DayOfWeek que nous pourrons ensuite utiliser pour définir identifier l'élément sélectionné. Dans la méthode, une boucle rapide sur chaque prévision est utilisée pour effacer la valeur sélectionnée. Une fois désactivée, nous pouvons utiliser une instruction LINQ pour trouver la DayOfWeek correspondante et basculer la valeur sélectionnée sur true.

 void HandleItemSelected (DayOfWeek selectedValue)
{
    // Effacer les sélections
    foreach (var item dans les prévisions)
        item.Selected = false;

    prévisions.Premier (f =>
    f.Date.DayOfWeek == selectedValue) .Selected = true;
}

Dans le WeeklyForecast, le balisage reçoit quelques mises à jour pour tout lier ensemble. Lorsque le composant WeatherDay est utilisé, les nouvelles propriétés sont appliquées. La méthode OnSelected reçoit le délégué HandleItemSelected et la valeur Selected est liée à la propriété Selected de l'élément de prévision.

 

Une fois les mises à jour terminées, nous pouvons maintenant exécuter l'application et accéder à la page de prévision hebdomadaire et sélectionner des éléments dans la vue, comme illustré dans Figure 8 .

 Le deuxième élément de la liste est sélectionné lorsque l'utilisateur clique dessus.
Figure 8: Le deuxième élément de la liste est sélectionné lorsque l'utilisateur clique dessus.

Nous pourrions expliquer cela concept en ajoutant une logique personnalisée à la méthode HandleItemSelected. Imaginez quelles fonctionnalités vous pourriez ajouter lors de la sélection d'un élément. Quelques exemples: afficher les prévisions météorologiques horaires, répertorier les entreprises fermées ou suggérer des activités pour les prévisions données.

Conclusion

Tout au long de cet article, nous avons appris les principes de base de la construction des composants, y compris directives paramètres . ] contenu / modèles pour enfants routage et gestion des événements . Chaque exemple nous a guidés à travers le processus de création d'un composant tout en introduisant les sujets nécessaires à la compréhension de l'architecture Blazor. L'intention de cet article était de fournir des informations qui nous rendront immédiatement productifs lors de l'utilisation du framework Blazor.





Source link