Componente picker no Kit de Ferramentas do Microsoft Graph

Artigo
11/07/2024

O componente Picker usa mgt-get para consultar o Microsoft API do Graph então renderiza um controle suspenso que permite a seleção de um único recurso de uma matriz de recursos.

Exemplo

O exemplo a seguir mostra o uso do mgt-picker componente para selecionar uma lista de tarefas nas listas de tarefas de um usuário. Você pode usar o editor de código para ver como propriedades e atributos alteram o comportamento do componente.

HTML
React

Abra este exemplo no mgt.dev.

Propriedades e atributos

Você pode usar vários atributos para alterar o comportamento do componente. O componente tem atributos necessários, como resource - por exemplo, /users - e key-name - por exemplo, displayName.

key-name também dá suporte a valores aninhados. Por exemplo, na seguinte resposta:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications/$entity",
    "id": "03ef14b0-ca33-4840-8f4f-d6e91916010e",
    "verifiedPublisher": {
            "displayName": "publisher_contoso",
            "verifiedPublisherId": "9999999",
             "addedDateTime": "2021-04-24T17:49:44Z"
    },
    "certification": {
           "isPublisherAttested": true,
           "isCertifiedByMicrosoft": true,
           "lastCertificationDateTime": "2021-05-11T23:26:20Z",
           "certificationExpirationDateTime": "2022-05-11T23:26:20Z",
           "certificationDetailsUrl": "https://learn.microsoft.com/microsoft-365-app-certification/forward/azure/631a96bc-a705-4eda-9f99-fdaf9f54f6a2"
    },
    "tags": [],
    "tokenEncryptionKeyId": null,
    "api": {
        "requestedAccessTokenVersion": 2,
        "acceptMappedClaims": null,
        "knownClientApplications": [],
        "oauth2PermissionScopes": [],
        "preAuthorizedApplications": []
    },
    "appRoles": [],
    "web": {
        "redirectUris": [],
        "homePageUrl": null,
        "logoutUrl": null,
        "implicitGrantSettings": {
            "enableIdTokenIssuance": false,
            "enableAccessTokenIssuance": false
        }
    }
}

seu key-name valor de atributo pode ser web.homePageUrl ou verifiedPublisher.displayName.

Atributo	Propriedade	Descrição
recurso	recurso	O recurso a ser obtido do Microsoft Graph (por exemplo, `/me` ou `/users`).
Espaço	Espaço	O espaço reservado renderizado no seletor (por exemplo, `Select a user` ou `Select a task list`).
key-name	Keyname	A chave a ser renderizada no seletor (por exemplo, `displayName`).
selected-value	Selectedvalue	Opcional. O valor a ser definido como a opção selecionada no momento no seletor. Deve estar presente nas opções fornecidas na consulta do Microsoft Graph.
escopos	escopos	Matriz opcional de cadeias de caracteres se estiver usando a propriedade ou um escopo delimitado por vírgula se estiver usando o atributo. O componente e um provedor com suporte garantem que o usuário tenha consentido com pelo menos uma das permissões fornecidas.
versão	versão	Versão opcional da API a ser usada ao fazer a solicitação `GET` . O padrão é `v1.0`.
páginas máximas	maxPages	Número opcional de páginas (para recursos que dão suporte à paginação). O padrão é 3. Definir esse valor como 0 recupera todas as páginas.
Habilitado para cache	cacheEnabled	Booliano opcional. Quando definido, ele indica que a resposta do recurso é armazenada em cache. Substitua se `refresh()` for chamado ou se `pollingRate` estiver em uso. O padrão é `false`.
cache-invalidation-period	cacheInvalidationPeriod	Número opcional de milissegundos. Quando definido em combinação com `cacheEnabled`, o atraso antes que o cache atinja seu período de invalidação modifica esse valor. O padrão é `0` e usa o período de invalidação padrão.
N/D	response	Resposta somente leitura do Microsoft Graph se a solicitação tiver sido bem-sucedida.
N/D	erro	Erro somente leitura do Microsoft Graph se a solicitação não tiver sido bem-sucedida.

Propriedades personalizadas do CSS

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

<mgt-picker
  class="picker"
  resource="me/todo/lists"
  scopes="tasks.read, tasks.readwrite"
  key-name="displayName"
></mgt-picker>

.picker {
  --picker-background-color: grey;
  --picker-list-max-height: 200px;
}

Para saber mais, confira componentes de estilo.

Métodos

Método	Descrição
refresh(force?: booleano)	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 há uma alteração no recurso selecionado na lista suspensa.	`{ response: any, error: any }`. A `response` propriedade contém a resposta recuperada do Microsoft Graph. A `error` propriedade contém informações sobre o erro se ocorreu	Não	Sim	Sim

Dica

Para obter mais informações sobre os dados retornados na response propriedade, consulte a referência de API da API que você usou na resource propriedade do componente Picker.

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

Modelos

O mgt-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-picker resource="me/todo/lists" scopes="tasks.read, tasks.readwrite" key-name="displayName">
  <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-picker>

Permissões do Microsoft Graph

As permissões necessárias por esse componente dependem dos dados que você deseja recuperar com ele do Microsoft Graph. O Microsoft Graph Toolkit verifica se o usuário atual consentiu com pelo menos um dos fornecidos scopes. 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-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 a consulta especificada na `resource` propriedade de `mgt-picker`

Para obter mais informações, consulte 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 an item`

Compartilhar via