Modèles dans la boîte à outils Microsoft GraphTemplates in the Microsoft Graph Toolkit

Utiliser des modèles personnalisés pour modifier le contenu d’un composant.Use custom templates to modify the content of a component.

Tous les composants Web prennent en charge les modèles basés sur l' <template> élément.All web components support templates based on the <template> element. Par exemple, pour remplacer le modèle d’un composant, ajoutez un <template> élément à l’intérieur d’un composant.For example, to override the template of a component, add a <template> element inside a component.

<mgt-agenda>
  <template data-type="event">
      <div>{{event.subject}}</div>
      <div data-for='attendee in event.attendees'>
          <mgt-person person-query="{{attendee.emailAddress.name}}">
            <template>
              <div data-if="person.image">
                <img src="{{person.image}}" />
              </div>
              <div data-else>
                {{person.displayName}}
              </div>
            </template>
          </mgt-person>
      </div>
  </template>
</mgt-agenda>

Type de donnéesData-type

Chaque composant peut avoir plusieurs parties qui peuvent être représentées par un modèle.Each component can have multiple parts that can be templated. Par exemple, dans le mgt-agenda composant, vous pouvez modèle des événements individuels, des en-têtes de section, le chargement d’un affichage, aucune vue de données, etc.For example, in the mgt-agenda component, you can template individual events, individual section headers, loading view, no data view, and more. Pour indiquer le modèle, utilisez l' data-type attribut sur un modèle.To indicate the template, use the data-type attribute on a template. Par exemple, pour modèle chaque événement dans le mgt-agenda , utilisez le event type de données, comme illustré ci-dessous.For example, to template each event in the mgt-agenda, use the event data-type, as shown.

<mgt-agenda>
  <template data-type="event"> </template>
</mgt-agenda>

Si aucun data-type élément n’est spécifié, le composant entier est remplacé par le modèle.If no data-type is specified, the entire component will be replaced with the template. Vous pouvez également utiliser data-type="default" dans le même but.You can also use data-type="default" for the same purpose.

Liaison de donnéesBinding data

De nombreux modèles permettent la liaison de données transmises au modèle en tant que contexte de données.Many templates allow binding of data that is passed to the template as data context. Par exemple, le event modèle dans le mgt-agenda composant transmet un {event} objet qui peut être utilisé directement dans le modèle.For example, the event template in the mgt-agenda component passes an {event} object that can be used directly in the template. Pour développer une expression, telle que event.subject , utilisez des accolades doubles.To expand an expression, such as event.subject, use the double curly brackets.

<template data-type="event">
  <div>{{event.subject}}</div>
</template>

Ce format peut également être utilisé dans les attributs :This format can also be used inside attributes:

<template data-type="event">
  <a href="{{ event.onlineMeetingUrl }}" />
</template>

Remarque : Vous pouvez également développer des objets tels que {{event}} et qu’ils s’affichent en tant que chaînes JSON.Note: You can also expand objects such as {{event}} and they will render as JSON strings. Cela peut être utile lorsque vous développez les modèles.This can be useful when you're developing the templates.

Modifier la syntaxe de liaisonChange binding syntax

Par défaut, pour développer une expression, vous utilisez des accolades doubles ( {{expression}} ).By default, to expand an expression, you use double curly brackets ( {{expression}} ). Toutefois, vous pouvez modifier cette syntaxe pour les environnements dans lesquels la syntaxe de la double accolade est déjà utilisée.However, you can change this syntax for environments where the double curly bracket syntax is already used. Par exemple, l’exemple suivant utilise des crochets doubles ( [[expression]] ).For example, the following example uses double square brackets ( [[expression]] ).

import { TemplateHelper } from '@microsoft/mgt';

TemplateHelper.setBindingSyntax('[[', ']]');

Propriétés du programme d’assistance de contexte de donnéesData context helper properties

Les propriétés suivantes peuvent également être utilisées avec l’objet de contexte de données dans vos modèles.The following properties can also be used with the data context object in your templates.

PropriétéProperty DescriptionDescription
$index$index Index numérique de l’élément rendu lors d’une boucle avec data-for .Numerical index of item being rendered while being looped with data-for.
$parent$parent Si un modèle est affiché à l’intérieur d’un autre modèle, cette propriété vous permet d’accéder au contexte de données parent.If a template is rendered inside another template, this property allows you to access the parent data context.

L’exemple suivant montre comment utiliser la $index propriété dans une boucle Data-for.The following example shows how to use the $index property in a data-for loop.

<mgt-person>
  <mgt-person-card>
    <template data-type="additional-details">
      <span data-for="language in languages">
        {{ language.displayName }}<span data-if="$index < languages.length - 1">, </span>
      </span>
    </template>
  </mgt-person-card>
</mgt-person>

Rendu conditionnelConditional rendering

Vous pouvez uniquement afficher des éléments lorsqu’une condition est true ou false en fonction du contexte de données.You might only want to render elements when a condition is true or false based on the data context. Les data-if data-else attributs et peuvent évaluer une expression et s’afficher uniquement si la valeur est true ou false.The data-if and data-else attributes can evaluate an expression and render only if true or false.

<mgt-person person-query="john doe">
  <template>
    <div data-if="person.image">
      <img src="{{ person.image }}" />
    </div>
    <div data-else>
      {{ person.displayName }}
    </div>
  </template>
</mgt-person>

BoucleLooping

Dans certains cas, l’objet de contexte de données contient Loop et vous devez effectuer une boucle sur les données.There will be cases where the data context object contains loop and you will need to loop over the data. Pour ce scénario, utilisez l' data-for attribut.For this scenario, use the data-for attribute.

<template data-type="event">
  <ul>
    <li data-for='attendee in event.attendees'>
      {{ attendee.displayName }}
    </li>
  </ul>
</template>

Contexte de modèleTemplate context

Dans les scénarios où vous devez convertir des données dans vos liaisons, les lier à des événements ou simplement utiliser des données externes dans vos liaisons de modèles, les modèles prennent en charge la liaison au contexte de données externes.In scenarios where you need to convert data in your bindings, bind to events, or just use external data in your templates bindings, the templates support binding to external data context. Vous pouvez ajouter un contexte de modèle supplémentaire de deux manières :You can add additional template context in two ways:

  1. Directement sur le composant.Directly on the component.

    Chaque composant définit la templateContext propriété, que vous pouvez utiliser pour transmettre des données supplémentaires à n’importe quel modèle dans le composant.Each component defines the templateContext property, which you can use to pass additional data to any template in the component.

    document.querySelector('mgt-agenda').templateContext = {
    
      someObject: {},
      formatDate: (date: Date) => { /* format date and return */ },
      someEventHandler: (e) => { /* handleEvent */  }
    
    }
    

    Les propriétés de l' templateContext objet seront désormais disponibles pour être utilisées dans les expressions de liaison dans le modèle.The properties in the templateContext object will now be available to be used in the binding expressions in the template.

  2. Globalement pour tous les composants.Globally for all components.

    La TemplateHelper classe expose l' globalContext objet pour ajouter des données ou des fonctions qui doivent être globalement disponibles pour tous les composants.The TemplateHelper class exposes the globalContext object to add data or functions that should be globally available for all components.

    import { TemplateHelper } from '@microsoft/mgt';
    
    TemplateHelper.globalContext.someObject = {};
    TemplateHelper.globalContext.formatDate = (date: Date) => { /* format date and return */ };
    TemplateHelper.globalContext.someEventHandler = (e) => { /* handleEvent */  }
    

ConvertisseursConverters

Dans de nombreux cas, vous souhaiterez peut-être transformer les données avant de les présenter dans le modèle.In many cases, you might want to transform the data before presenting it in the template. Par exemple, vous pouvez mettre en forme correctement une date avant qu’elle ne soit affichée.For example, you might want to properly format a date before it is rendered. Dans ce cas, vous pouvez utiliser un convertisseur de modèle.In these cases, you might want to use a template converter.

Pour utiliser un convertisseur de modèle, vous devez d’abord définir une fonction qui effectuera la conversion.To use a template converter, you first need to define a function that will do the conversion. Par exemple, vous pouvez définir une fonction pour convertir un objet Event en une plage de temps mise en forme.For example, you might define a function to convert an event object to a formatted time range.

document.querySelector('mgt-agenda').templateContext = {

  getTimeRange: (event) => {
    // TODO: format a string from the event object as you wish
    // timeRange = ...

    return timeRange;
  }

}

Pour utiliser le convertisseur dans votre modèle, utilisez-le comme si vous utilisiez une fonction dans le code-behind.To use the converter in your template, use it as if you would use a function in code behind.

<template data-type="event">
  <div>{{ getTimeRange(event) }}</div>
</template>

Liaison d’événement ou de propriétéEvent or property binding

L' data-props attribut vous permet d’ajouter un écouteur d’événements ou de définir directement une valeur de propriété dans vos modèles.The data-props attribute allows you to add an event listener or set a property value directly in your templates.

<template>
    <button data-props="{{@click: myEvent, myProp: value}}"></button>
</template>

Les données-props acceptent une chaîne séparée par des virgules pour chaque propriété ou gestionnaire d’événements que vous pouvez définir.The data-props accepts a comma delimited string for each property or event handler you might want to set.

Pour ajouter un gestionnaire d’événements, préfixez le nom de l’événement @ .To add an event handler, prefix the name of the event with @. Le gestionnaire d’événements doit être disponible dans le templateContext de l’élément.The event handler will need to be available in the templateContext of the element.

document.querySelector('mgt-agenda').templateContext = {

  someEventHandler: (e, context, root) => { /* handleEvent */  }

}
<template>
    <button data-props="{{@click: someEventHandler}}"></button>
</template>

Les arguments d’événement, le contexte de données et l’élément racine du modèle sont transmis au gestionnaire d’événements en tant que paramètres.The event args, data context, and the root element of the template are passed to the event handler as parameters.

Modèle d’événement renduTemplate rendered event

Dans certains cas, vous souhaiterez peut-être obtenir une référence à l’élément rendu.In certain cases, you might want to get a reference to the rendered element. Cela peut être utile si vous souhaitez gérer le rendu du contenu vous-même ou si vous souhaitez modifier l’élément rendu.This can be useful if you want to handle the rendering of the content yourself, or you want to modify the rendered element.

Dans ce scénario, vous pouvez utiliser l' templateRendered événement, qui se déclenche une fois que le modèle a été rendu.In this scenario, you can use the templateRendered event, which fires after the template has been rendered.

let agenda = document.querySelector('mgt-agenda');
agenda.addEventListener('templateRendered', (e) => { });

Les détails de l’événement contiennent une référence à l’élément qui est affiché, l’objet de contexte de données et le type du modèle.The event details will contain a reference to the element that is being rendered, the data context object, and the type of the template.

agenda.addEventListener('templateRendered', (e) => {
  let templateType = e.detail.templateType;
  let dataContext = e.detail.context;
  let element = e.detail.element;

  if (templateType === 'event') {
    element.querySelector('.some-button').addEventListener('click', () => {});
  }
});

StyleStyling

Les modèles peuvent être mis en forme normalement via CSS, car ils sont affichés en dehors de l’ombre DOM.The templates can be styled normally via CSS as they are rendered outside of the shadow dom.