Componente do seletor de taxonomia no Kit de Ferramentas do Microsoft Graph

Artigo
11/07/2024

O seletor de taxonomia é um componente que pode consultar o microsoft API do Graph para Taxonomia e renderizar um controle suspenso com termos, permitindo a seleção de um único termo com base no conjunto id de termos especificado ou em uma combinação do conjunto id de termos especificado e do termo idespecificado.

O componente recupera os termos de primeiro nível presentes em um conjunto de termos ou termo especificado. Se apenas a ID do conjunto de termos for fornecida, ela retornará os termos de primeiro nível nesse conjunto de termos. Se a ID do conjunto de termos e a ID de termo forem fornecidas, ela retornará os termos de primeiro nível no termo especificado.

Nota Atualmente, esse recurso dá suporte a uma única seleção de termos provenientes do repositório de termos.

Exemplo

O exemplo a seguir mostra o uso do mgt-taxonomy-picker componente para selecionar um termo de um conjunto de termos.

HTML
React

Abra este exemplo no mgt.dev.

Propriedades e atributos

Você pode usar vários atributos para alterar o comportamento do componente. O atributo necessário é term-set-id.

Atributo	Propriedade	Descrição	Tipo
term-set-id	termsetId	Obrigatório. A ID do termo definido para recuperar os termos do primeiro nível.	Cadeia de caracteres
term-id	termId	Opcional. A ID do termo para recuperar termos de primeiro nível. Se não for fornecida, a função recuperará os termos de primeiro nível no conjunto de termos especificado por `term-set-id`. Observe que este termo deve ser um dos termos no termo definido com ID `term-set-id`.	Cadeia de caracteres
site-id	siteId	Opcional. A ID do site em que o termo definido está presente. Se não for especificado, o conjunto de termos será considerado no nível do locatário.	Cadeia de caracteres
versão	versão	Opcional. Versão da API a ser usada ao fazer a solicitação GET. O padrão é `beta`.	Cadeia de caracteres
Espaço	Espaço	Opcional. O espaço reservado a ser usado na caixa de combinação. O valor padrão é `Select a term`.	string
localidade	localidade	Opcional. A localidade dos termos que precisam ser exibidos. Isso só é útil quando os termos têm vários rótulos em idiomas diferentes.	Cadeia de caracteres
default-selected-term-id	defaultSelectedTermId	Opcional. A ID do termo que deve ser selecionado por padrão.	Cadeia de caracteres
position	position	Opcional. A posição da lista suspensa. Pode ser 'acima' ou 'abaixo'. O padrão é `below`	Cadeia de caracteres
desabilitadas	desabilitadas	Opcional. Define se o seletor de taxonomia está desabilitado. Quando desabilitado, o usuário não pode pesquisar ou selecionar termos.	NA
Habilitado para cache	cacheEnabled	Opcional. Quando definido, ele indica que a resposta do recurso será armazenada em cache. O padrão é `false`.	Booliano
cache-invalidation-period	cacheInvalidationPeriod	Opcional. (Número de milissegundos) Quando definido em combinação com `cacheEnabled`, o atraso antes que o cache atinja seu período de invalidação será modificado por esse valor. O padrão é `0` e usará o período de invalidação padrão.	Número

O exemplo a seguir altera o comportamento do componente para buscar termos filho de primeiro nível do conjunto de termos especificados.

<mgt-taxonomy-picker
  term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
></mgt-taxonomy-picker>

O exemplo a seguir altera o comportamento do componente para buscar termos filho de primeiro nível de termo especificado.

<mgt-taxonomy-picker
  term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
  term-id="a56caeb7-3b7d-4d22-93a9-0232e12905f6"
></mgt-taxonomy-picker>

O exemplo a seguir altera o comportamento do componente para buscar os rótulos franceses dos termos filho de primeiro nível do termo especificado.

<mgt-taxonomy-picker
  term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
  term-id="a56caeb7-3b7d-4d22-93a9-0232e12905f6"
  locale="fr-FR"
></mgt-taxonomy-picker>

O exemplo a seguir altera o comportamento do componente para buscar termos filho de primeiro nível do conjunto de termos especificado que está presente em um site especificado.

<mgt-taxonomy-picker
  term-set-id="7889007a-fb0e-449f-b629-dedf63ae53de"
  site-id="contoso.sharepoint.com,0962bcef-48f1-4460-baa8-b7286dcb249b,ba412b3c-951a-4322-ac37-0fe6307b5987"
></mgt-taxonomy-picker>

O exemplo a seguir altera o comportamento do componente para buscar termos filho de primeiro nível do conjunto de termos especificados e define um termo especificado a ser selecionado por padrão.

<mgt-taxonomy-picker
  term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
  default-selected-term-id="7ab1d163-f691-4676-88b3-c2d8921b73eb"
></mgt-taxonomy-picker>

Propriedades personalizadas do CSS

O mgt-taxonomy-picker componente define as seguintes propriedades personalizadas do CSS para você fornecer substituições.

<mgt-taxonomy-picker
  class="taxonomy-picker"
  term-set-id="138a652e-7f23-46f6-b480-13da2308c235"
></mgt-taxonomy-picker>

.taxonomy-picker {
  --taxonomy-picker-background-color: grey;
  --taxonomy-picker-list-max-height: 200px;
  --taxonomy-picker-background-color: black;
  --taxonomy-picker-placeholder-color: white;
  
}

Para saber mais, confira componentes de estilo.

Métodos

Método	Descrição
refresh(force?:boolean)	Chame o método para atualizar os dados. Por padrão, a interface do usuário só será atualizada se os dados forem alterados. Passe `true` para forçar o componente a ser atualizado.

Eventos

Evento	Quando ele é emitido	Dados personalizados	Cancelável	Bolhas	Funciona com modelo personalizado
`selectionChanged`	Disparado quando o usuário faz uma alteração na seleção na lista suspensa.	O termo selecionado que será do tipo `TermStore.Term`	Não	Sim	Sim

Para obter mais informações sobre como lidar com eventos, consulte eventos.

Modelos

O mgt-taxonomy-picker componente dá suporte a vários modelos que você pode usar para definir a aparência e a aparência. Para especificar um modelo, inclua um <template> elemento dentro de um componente e defina o data-type como um dos valores a seguir.

Tipo de dados	Contexto de dados	Descrição
erro	O erro do Microsoft Graph.	Esse modelo será usado se houver um erro ao fazer a solicitação.
Carregar	N/D	Esse modelo é usado enquanto a solicitação está sendo feita.
sem dados	N/D	Esse modelo é usado quando a solicitação não retorna dados.

Uso de modelo de exemplo

<mgt-taxonomy-picker term-set-id="138a652e-7f23-46f6-b480-13da2308c235">
  <div>Loading template</div>
    <template data-type="loading">
      Loading
    </template>
    <template data-type="no-data">
      <div>No data</div>
    </template>
    <template data-type="error">
      <div>Error</div>
    </template>
  </div>
</mgt-taxonomy-picker>

Permissões do Microsoft Graph

Esse componente usa as seguintes APIs e permissões do Microsoft Graph. Para cada API chamada, o usuário deve ter pelo menos uma das permissões listadas.

Configuração	Permissão	API
Padrão.	TermStore.Read.All, TermStore.ReadWrite.All	/termStore/sets/{setId}/children
Padrão.	TermStore.Read.All, TermStore.ReadWrite.All	/termStore/sets/{setId}/terms/{termId}/children
`site-id` é definido	TermStore.Read.All, TermStore.ReadWrite.All	/sites/{site-id}/termStore/sets/{set-id}/children
`site-id` é definido	TermStore.Read.All, TermStore.ReadWrite.All	/sites/{site-id}/termStore/sets/{set-id}/terms/{term-id}/children

Para obter mais informações sobre permissões, consulte a referência de permissões do Microsoft Graph.

Autenticação

O controle usa o provedor de autenticação global descrito na documentação de autenticação para buscar os dados necessários.

Cache

Para habilitar e configurar o cache, use as cacheEnabled propriedades e cacheInvalidationPeriod . Por padrão, o mgt-taxonomy-picker componente não armazena em cache respostas.

Repositório de objetos	Dados armazenados em cache	Comentários
`response`	Resposta completa recuperada do Microsoft Graph para os termos.

Para obter detalhes, confira Cache.

Localização

O controle expõe as variáveis a seguir que podem ser localizadas. Para obter detalhes sobre como configurar a localização, confira Localizando componentes.

Nome da cadeia de caracteres	Valor padrão
comboboxPlaceholder	`Select a term`
loadingMessage	`Loading...`
noTermsFound	`No terms found`
termsetIdRequired	`The termsetId property or termset-id attribute is required`

Compartilhar via