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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Os componentes do Kit de ferramentas do Microsoft Graph são flexíveis para personalização. Você pode alterar a apresentação do Kit de ferramentas do Microsoft Graph usando modelos e aprender técnicas de solução de problemas para renderização.