Vorlagen im Microsoft Graph-Toolkit

Die meisten Komponenten des Microsoft Graph-Toolkits unterstützen die Verwendung benutzerdefinierter Vorlagen zum Ändern des Inhalts einer Komponente.

Alle Webkomponenten unterstützen Vorlagen, die auf dem <template> -Element basieren. Um beispielsweise die Vorlage einer Komponente zu überschreiben, fügen Sie ein <template> Element innerhalb einer Komponente hinzu.

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

Wenn Sie das Microsoft Graph-Toolkit React Komponenten verwenden, können Sie React zum Erstellen von Vorlagen verwenden. Weitere Informationen finden Sie unter Verwenden des Toolkits mit React.

Datentyp

Jede Komponente kann über mehrere Teile verfügen, die Vorlagen enthalten können. Beispielsweise können Sie in der mgt-agenda -Komponente einzelne Ereignisse, einzelne Abschnittsheader, Ladeansicht, keine Datenansicht und vieles mehr vorlagen. Verwenden Sie das -Attribut für eine Vorlage, um die data-type Vorlage anzugeben. Verwenden Sie z. B. wie gezeigt den event Datentyp, um jedes Ereignis im mgt-agendaals Vorlage zu erstellen.

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

Wenn kein data-type angegeben ist, wird die gesamte Komponente durch die Vorlage ersetzt. Sie können auch für denselben Zweck verwenden data-type="default" .

Binden von Daten

Viele Vorlagen ermöglichen die Bindung von Daten, die als Datenkontext an die Vorlage übergeben werden. Beispielsweise übergibt die event Vorlage in der mgt-agenda Komponente ein {event} Objekt, das direkt in der Vorlage verwendet werden kann. Um einen Ausdruck wie event.subjectzu erweitern, verwenden Sie die doppelten geschweiften Klammern.

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

Dieses Format kann auch innerhalb von Attributen verwendet werden:

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

Hinweis: Sie können auch Objekte wie {{event}} oder {{this}} erweitern, die als JSON-Zeichenfolgen gerendert werden. Dies kann nützlich sein, wenn Sie die Vorlagen entwickeln.

Ändern der Bindungssyntax

Zum Erweitern eines Ausdrucks verwenden Sie standardmäßig doppelte geschweifte Klammern ( {{expression}} ). Sie können diese Syntax jedoch für Umgebungen ändern, in denen die Syntax mit doppelt geschweiften Klammern bereits verwendet wird. Im folgenden Beispiel werden beispielsweise doppelte eckige Klammern ( ) [[expression]] verwendet.

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

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

Eigenschaften des Datenkontexthilfsprogramms

Die folgenden Eigenschaften können auch mit dem Datenkontextobjekt in Ihren Vorlagen verwendet werden.

Eigenschaft	Beschreibung
$index	Numerischer Index des Elements, das während der Schleife mit data-forgerendert wird.
$parent	Wenn eine Vorlage in einer anderen Vorlage gerendert wird, können Sie mit dieser Eigenschaft auf den übergeordneten Datenkontext zugreifen.

Das folgende Beispiel zeigt, wie die $index -Eigenschaft in einer Data-for-Schleife verwendet wird.

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

{{this}}

Um den Datenkontext zu debuggen, können Sie in Ihren Bindungsausdrücken verwenden this . Das einfachste Formular besteht darin, ihrer Vorlage eine beliebige Stelle hinzuzufügen {{this}} .

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

Da Sie JavaScript in Ihren Bindungsausdrücken verwenden können, haben Sie auch Zugriff auf das -Objekt, mit dem console Sie (oder eine andere console API) in Ihren Vorlagen verwenden console.log(this) können.

<template data-type="event">
  <div>
    {{console.log(this)}}
  </div>
</template>

Bedingtes Rendering

Möglicherweise möchten Sie Elemente nur rendern, wenn eine Bedingung basierend auf dem Datenkontext true oder false ist. Die data-if Attribute und data-else können einen Ausdruck auswerten und nur bei true oder false gerendert werden.

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

Schleife

Es gibt Fälle, in denen das Datenkontextobjekt eine Schleife enthält und Sie eine Schleife über die Daten ausführen müssen. Verwenden Sie für dieses Szenario das data-for -Attribut.

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

Vorlagenkontext

In Szenarien, in denen Sie Daten in Ihren Bindungen konvertieren, an Ereignisse binden oder nur externe Daten in Ihren Vorlagenbindungen verwenden müssen, unterstützen die Vorlagen die Bindung an den externen Datenkontext. Sie können zusätzlichen Vorlagenkontext auf zwei Arten hinzufügen:

1. Direkt auf der Komponente.

   Jede Komponente definiert die templateContext -Eigenschaft, die Sie verwenden können, um zusätzliche Daten an jede Vorlage in der Komponente zu übergeben.

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

   Die Eigenschaften im templateContext -Objekt sind jetzt für die Verwendung in den Bindungsausdrücken in der Vorlage verfügbar.

2. Global für alle Komponenten.

   Die TemplateHelper -Klasse macht das globalContext -Objekt verfügbar, um Daten oder Funktionen hinzuzufügen, die für alle Komponenten global verfügbar sein sollten.

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

Konverter

In vielen Fällen möchten Sie die Daten möglicherweise transformieren, bevor Sie sie in der Vorlage darstellen. Sie können z. B. ein Datum ordnungsgemäß formatieren, bevor es gerendert wird. In diesen Fällen empfiehlt es sich möglicherweise, einen Vorlagenkonverter zu verwenden.

Um einen Vorlagenkonverter zu verwenden, müssen Sie zunächst eine Funktion definieren, die die Konvertierung durchführt. Sie können beispielsweise eine Funktion definieren, um ein Ereignisobjekt in einen formatierten Zeitbereich zu konvertieren.

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

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

    return timeRange;
  }

}

Um den Konverter in Ihrer Vorlage zu verwenden, verwenden Sie ihn so, als ob Sie eine Funktion im CodeBehind verwenden würden.

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

Ereignis- oder Eigenschaftsbindung

Mit data-props dem Attribut können Sie einen Ereignislistener hinzufügen oder einen Eigenschaftswert direkt in Ihren Vorlagen festlegen.

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

Die Dateneigenschaften akzeptieren eine durch Trennzeichen getrennte Zeichenfolge für jede Eigenschaft oder jeden Ereignishandler, die Sie festlegen möchten.

Um einen Ereignishandler hinzuzufügen, stellen Sie dem Namen des Ereignisses das Präfix voran @. Der Ereignishandler muss in der templateContext des -Elements verfügbar sein.

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

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

}

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

Die Ereignisargumente, der Datenkontext und das Stammelement der Vorlage werden als Parameter an den Ereignishandler übergeben.

Vorlage gerendertes Ereignis

In bestimmten Fällen möchten Sie möglicherweise einen Verweis auf das gerenderte Element abrufen. Dies kann nützlich sein, wenn Sie das Rendern des Inhalts selbst verarbeiten oder das gerenderte Element ändern möchten.

In diesem Szenario können Sie das templateRendered -Ereignis verwenden, das ausgelöst wird, nachdem die Vorlage gerendert wurde.

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

Die Ereignisdetails enthalten einen Verweis auf das element, das gerendert wird, das Datenkontextobjekt und den Typ der Vorlage.

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', () => {});
  }
});

Styling

Die Vorlagen können normal über CSS formatiert werden, da sie außerhalb des Schattendoms gerendert werden.