Modelos no microsoft graph ToolkitTemplates in the Microsoft Graph Toolkit

A maioria dos Toolkit do Microsoft Graph suporta o uso de modelos personalizados para modificar o conteúdo de um componente.Most Microsoft Graph Toolkit components support the use of custom templates to modify the content of a component.

Todos os componentes da Web suportam modelos com base no <template> elemento.All web components support templates based on the <template> element. Por exemplo, para substituir o modelo de um componente, adicione um <template> elemento dentro de um componente.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>

Se você estiver usando os componentes do Microsoft Graph Toolkit React, poderá usar o React para modelos de autoria.If you're using the Microsoft Graph Toolkit React components, you can use React for authoring templates. Para obter detalhes, consulte Use the toolkit with React.For details, see Use the toolkit with React.

Tipo de dadosData-type

Cada componente pode ter várias partes que podem ser modelos.Each component can have multiple parts that can be templated. Por exemplo, no componente, você pode modelo eventos individuais, headers de seção mgt-agenda individuais, exibição de carregamento, sem exibição de dados e muito mais.For example, in the mgt-agenda component, you can template individual events, individual section headers, loading view, no data view, and more. Para indicar o modelo, use o data-type atributo em um modelo.To indicate the template, use the data-type attribute on a template. Por exemplo, para modelo de cada evento no mgt-agenda , use o tipo de event dados, conforme mostrado.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>

Se não data-type for especificado, todo o componente será substituído pelo modelo.If no data-type is specified, the entire component will be replaced with the template. Você também pode data-type="default" usar para a mesma finalidade.You can also use data-type="default" for the same purpose.

Dados de associaçãoBinding data

Muitos modelos permitem a associação de dados que são passados para o modelo como contexto de dados.Many templates allow binding of data that is passed to the template as data context. Por exemplo, o event modelo no componente passa um objeto que pode ser usado diretamente no mgt-agenda {event} modelo.For example, the event template in the mgt-agenda component passes an {event} object that can be used directly in the template. Para expandir uma expressão, como event.subject , use os colchetes curvados duplos.To expand an expression, such as event.subject, use the double curly brackets.

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

Esse formato também pode ser usado dentro de atributos:This format can also be used inside attributes:

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

Observação: Você também pode expandir objetos como {{event}} ou {{this}} e eles renderizarão como cadeias de caracteres JSON.Note: You can also expand objects such as {{event}} or {{this}} and they will render as JSON strings. Isso pode ser útil quando você estiver desenvolvendo os modelos.This can be useful when you're developing the templates.

Alterar sintaxe de associaçãoChange binding syntax

Por padrão, para expandir uma expressão, você usa colchetes curvados duplos ( {{expression}} ).By default, to expand an expression, you use double curly brackets ( {{expression}} ). No entanto, você pode alterar essa sintaxe para ambientes em que a sintaxe de colchete dupla curva já é usada.However, you can change this syntax for environments where the double curly bracket syntax is already used. Por exemplo, o exemplo a seguir usa colchetes duplos ( [[expression]] ).For example, the following example uses double square brackets ( [[expression]] ).

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

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

Propriedades auxiliares de contexto de dadosData context helper properties

As propriedades a seguir também podem ser usadas com o objeto de contexto de dados em seus modelos.The following properties can also be used with the data context object in your templates.

PropriedadeProperty DescriçãoDescription
$index$index Índice numérico do item que está sendo renderizado durante o loop com data-for .Numerical index of item being rendered while being looped with data-for.
$parent$parent Se um modelo for renderizado dentro de outro modelo, essa propriedade permitirá que você acesse o contexto de dados pai.If a template is rendered inside another template, this property allows you to access the parent data context.

O exemplo a seguir mostra como usar $index a propriedade em um loop 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>

{{this}}{{this}}

Para ajudar a depurar o contexto de dados, você pode usar this em suas expressões de associação.To help debug the data context, you can use this in your binding expressions. O formulário mais simples é adicionar em {{this}} qualquer lugar do seu modelo.The simplest form is to add {{this}} anywhere in your template.

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

Como você pode usar JavaScript em suas expressões de associação, você também tem acesso ao objeto que permite que você use (ou qualquer outra console console.log(this) console API) em seus modelos.Because you can use JavaScript in your binding expressions, you also have access to the console object which allows you to use console.log(this) (or any other console API) in your templates.

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

Renderização condicionalConditional rendering

Você só pode querer renderizar elementos quando uma condição for verdadeira ou false com base no contexto de dados.You might only want to render elements when a condition is true or false based on the data context. Os data-if atributos e podem avaliar uma expressão e data-else renderizar somente se for verdadeiro ou falso.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>

LoopingLooping

Haverá casos em que o objeto de contexto de dados contém loop e você precisará fazer um loop sobre os dados.There will be cases where the data context object contains loop and you will need to loop over the data. Para esse cenário, use o data-for atributo.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>

Contexto do modeloTemplate context

Em cenários em que você precisa converter dados em suas vinculações, vincular a eventos ou apenas usar dados externos em suas vinculações de modelos, os modelos suportam a associação ao contexto de dados externos.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. Você pode adicionar contexto de modelo adicional de duas maneiras:You can add additional template context in two ways:

  1. Diretamente no componente.Directly on the component.

    Cada componente define a templateContext propriedade, que você pode usar para passar dados adicionais para qualquer modelo no componente.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 */  }
    
    }
    

    As propriedades no objeto agora estarão disponíveis para serem templateContext usadas nas expressões de associação no modelo.The properties in the templateContext object will now be available to be used in the binding expressions in the template.

  2. Globalmente para todos os componentes.Globally for all components.

    A classe expõe o objeto para adicionar dados ou funções que TemplateHelper globalContext devem estar disponíveis globalmente para todos os componentes.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 */  }
    

ConversoresConverters

Em muitos casos, talvez você queira transformar os dados antes de apresentá-los no modelo.In many cases, you might want to transform the data before presenting it in the template. Por exemplo, talvez você queira formatar corretamente uma data antes de ser renderizada.For example, you might want to properly format a date before it is rendered. Nesses casos, talvez você queira usar um conversor de modelo.In these cases, you might want to use a template converter.

Para usar um conversor de modelo, primeiro você precisa definir uma função que fará a conversão.To use a template converter, you first need to define a function that will do the conversion. Por exemplo, você pode definir uma função para converter um objeto de evento em um intervalo de tempo formatado.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;
  }

}

Para usar o conversor em seu modelo, use-o como se você usaria uma função em 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>

Associação de eventos ou propriedadesEvent or property binding

O atributo permite adicionar um ouvinte de eventos ou definir um valor data-props de propriedade diretamente em seus modelos.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>

Os data-props aceitam uma cadeia de caracteres delimitada por vírgula para cada propriedade ou manipulador de eventos que você talvez queira definir.The data-props accepts a comma delimited string for each property or event handler you might want to set.

Para adicionar um manipulador de eventos, prefixe o nome do evento com @ .To add an event handler, prefix the name of the event with @. O manipulador de eventos precisará estar disponível no templateContext elemento.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>

Os args de evento, o contexto de dados e o elemento raiz do modelo são passados para o manipulador de eventos como parâmetros.The event args, data context, and the root element of the template are passed to the event handler as parameters.

Evento renderizado de modeloTemplate rendered event

Em determinados casos, talvez você queira obter uma referência ao elemento renderizado.In certain cases, you might want to get a reference to the rendered element. Isso pode ser útil se você quiser manipular a renderização do conteúdo por conta própria ou se quiser modificar o elemento renderizado.This can be useful if you want to handle the rendering of the content yourself, or you want to modify the rendered element.

Nesse cenário, você pode usar o templateRendered evento, que é a disparar depois que o modelo é renderizado.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) => { });

Os detalhes do evento conterão uma referência ao elemento que está sendo renderizado, ao objeto de contexto de dados e ao tipo do modelo.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', () => {});
  }
});

EstiloStyling

Os modelos podem ser estilizados normalmente via CSS à medida que são renderizados fora do dom de sombra.The templates can be styled normally via CSS as they are rendered outside of the shadow dom.