Modelos no Kit de Ferramentas do Microsoft Graph

Artigo
03/26/2023

A maioria dos componentes do Microsoft Graph Toolkit dá suporte ao uso de modelos personalizados para modificar o conteúdo de um componente.

Todos os componentes da Web dão suporte a modelos com base no <template> elemento. Por exemplo, para substituir o modelo de um componente, adicione um <template> elemento dentro de um componente.

<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 React para criar modelos. Para obter detalhes, consulte Usar o kit de ferramentas com React.

Tipo de dados

Cada componente pode ter várias partes que podem ser modelos. Por exemplo, no mgt-agenda componente, você pode modelo de eventos individuais, cabeçalhos de seção individuais, exibição de carregamento, sem exibição de dados e muito mais. Para indicar o modelo, use o data-type atributo em um modelo. Por exemplo, para modelo de cada evento no mgt-agenda, use o event tipo de dados, conforme mostrado.

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

Se não data-type for especificado, todo o componente será substituído pelo modelo. Você também pode usar data-type="default" para a mesma finalidade.

Associação de dados

Muitos modelos permitem a associação de dados que são passados para o modelo como contexto de dados. Por exemplo, o event modelo no mgt-agenda componente passa um {event} objeto que pode ser usado diretamente no modelo. Para expandir uma expressão, como event.subject, use os colchetes encaracolados duplos.

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

Esse formato também pode ser usado dentro de atributos:

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

Nota: Você também pode expandir objetos como {{event}} ou {{this}} e eles serão renderizados como cadeias de caracteres JSON. Isso pode ser útil quando você está desenvolvendo os modelos.

Alterar sintaxe de associação

Por padrão, para expandir uma expressão, você usa colchetes encaracolados duplos ( {{expression}} ). No entanto, você pode alterar essa sintaxe para ambientes em que a sintaxe de colchete encaracolado duplo já é usada. Por exemplo, o exemplo a seguir usa colchetes duplos ( [[expression]] ).

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

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

Propriedades do auxiliar de contexto de dados

As propriedades a seguir também podem ser usadas com o objeto de contexto de dados em seus modelos.

Propriedade	Descrição
$index	Índice numérico do item que está sendo renderizado ao ser loop com `data-for`.
$parent	Se um modelo for renderizado dentro de outro modelo, essa propriedade permitirá que você acesse o contexto de dados pai.

O exemplo a seguir mostra como usar a $index propriedade em um loop data-for.

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

Para ajudar a depurar o contexto de dados, você pode usar this em suas expressões de associação. O formulário mais simples é adicionar {{this}} em qualquer lugar do modelo.

<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 console objeto que permite usar console.log(this) (ou qualquer outra console API) em seus modelos.

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

Renderização condicional

Talvez você só queira renderizar elementos quando uma condição for verdadeira ou falsa com base no contexto de dados. Os data-if atributos e data-else podem avaliar uma expressão e renderizar somente se true ou 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>

Looping

Haverá casos em que o objeto de contexto de dados contém loop e você precisará fazer loop sobre os dados. Para esse cenário, use o data-for atributo.

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

Contexto de modelo

Em cenários em que você precisa converter dados em suas associações, associar-se a eventos ou apenas usar dados externos em suas associações de modelos, os modelos dão suporte à associação ao contexto de dados externo. Você pode adicionar contexto de modelo adicional de duas maneiras:

Diretamente no componente.

Cada componente define a templateContext propriedade, que você pode usar para passar dados adicionais para qualquer modelo no componente.
```
document.querySelector('mgt-agenda').templateContext = {

  someObject: {},
  formatDate: (date: Date) => { /* format date and return */ },
  someEventHandler: (e) => { /* handleEvent */  }

}
```
As propriedades no templateContext objeto agora estarão disponíveis para serem usadas nas expressões de associação no modelo.

Globalmente para todos os componentes.

A TemplateHelper classe expõe o globalContext objeto para adicionar dados ou funções que devem estar disponíveis globalmente para todos os componentes.

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

TemplateHelper.globalContext.someObject = {};
TemplateHelper.globalContext.formatDate = (date: Date) => { /* format date and return */ };
TemplateHelper.globalContext.someEventHandler = (e) => { /* handleEvent */  }

Conversores

Em muitos casos, talvez você queira transformar os dados antes de apresentá-los no modelo. Por exemplo, talvez você queira formatar corretamente uma data antes que ela seja renderizada. Nesses casos, talvez você queira usar um conversor de modelo.

Para usar um conversor de modelo, primeiro você precisa definir uma função que fará a conversão. Por exemplo, você pode definir uma função para converter um objeto de evento em um intervalo de tempo formatado.

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ê usasse uma função no código atrás.

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

Associação de eventos ou propriedades

O data-props atributo permite que você adicione um ouvinte de evento ou defina um valor de propriedade diretamente em seus modelos.

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

Os adereços de dados aceitam uma cadeia de caracteres delimitada por vírgula para cada propriedade ou manipulador de eventos que talvez você queira definir.

Para adicionar um manipulador de eventos, prefixe o nome do evento com @. O manipulador de eventos precisará estar disponível no templateContext elemento.

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

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

}

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

O args de evento, o contexto de dados e o elemento raiz do modelo são passados para o manipulador de eventos como parâmetros.

Evento renderizado de modelo

Em determinados casos, talvez você queira obter uma referência ao elemento renderizado. Isso pode ser útil se você quiser manipular a renderização do conteúdo por conta própria ou quiser modificar o elemento renderizado.

Nesse cenário, você pode usar o templateRendered evento, que é disparado após a renderização do modelo.

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.

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

Estilo

Os modelos podem ser estilizados normalmente por meio do CSS, pois são renderizados fora do ponto de sombra.