Componente de seletor de pessoas no Microsoft Graph Toolkit

Artigo
11/07/2024

Pode utilizar o mgt-people-picker componente Web para procurar pessoas, grupos ou ambos. Por predefinição, o componente procura todas as pessoas e utilizadores na organização, mas pode alterar o comportamento para procurar grupos ou apenas grupos. Também pode filtrar a pesquisa para um grupo específico. Também pode permitir que o utilizador introduza e selecione qualquer endereço de e-mail.

Exemplo

O exemplo seguinte mostra o mgt-people-picker componente. Comece a procurar um nome para ver a composição dos resultados e utilize o editor de código para ver como as propriedades alteram o comportamento do componente.

HTML
React

Abra este exemplo no mgt.dev.

Propriedades

Por predefinição, o mgt-people-picker componente obtém pessoas dos /me/people pontos finais e /users . Utilize os seguintes atributos para alterar este comportamento.

Atributo	Propriedade	Descrição
show-max	showMax	Um valor numérico para indicar o número máximo de pessoas a mostrar. O valor padrão é 6.
group-id	groupId	Um valor de cadeia que pertence a um grupo definido pelo Microsoft Graph para filtrar ainda mais os resultados da pesquisa.
pesquisa transitiva	pesquisa transitiva	Um valor Booleano para efetuar uma pesquisa transitiva que devolve uma lista simples de todos os membros aninhados – por predefinição, a pesquisa transitiva não é utilizada.
type	type	O tipo de entidades a procurar. As opções disponíveis são: `person`, `group`, `any`. O valor padrão é `any`. Se este atributo estiver definido como `group` e ou `group-idgroup-ids` estiver definido, `userFilters` e `peopleFilters` não tiver efeito.
tipo de utilizador	userType	O tipo de utilizador a procurar. As opções disponíveis são: `any`, `user` para utilizadores organizacionais ou `contact` para contactos. O valor padrão é `any`.
tipo de grupo	groupType	O tipo de grupo ou tipos a procurar. As opções disponíveis são: `unified`, , `securitymailenabledsecurity`, , . `anydistribution` O valor padrão é `any`. Este atributo não tem efeito se a `type` propriedade estiver definida como `person`. Este atributo aceita uma lista de valores separada por vírgulas; a propriedade aceita uma matriz ou valores.
selected-people	selectedPeople	Uma matriz de pessoas selecionadas. Defina este valor para selecionar pessoas programaticamente.
people	people	Uma matriz de pessoas encontradas e compostas no resultado da pesquisa
marcador de posição	marcador de posição	O texto predefinido que parece explicar como utilizar o componente. O valor padrão é `Start typing a name`.
default-selected-user-ids	defaultSelectedUserIds	Quando for fornecida uma cadeia de IDs de utilizador do Microsoft Graph separados por vírgulas, o componente compõe os respetivos utilizadores como selecionados após a inicialização.
default-selected-group-ids	defaultSelectedGroupIds	Semelhante a default-selected-user-ids, quando fornecida uma cadeia de IDs de grupo do Microsoft Graph separados por vírgulas, o componente compõe os respetivos grupos como selecionados após a inicialização.
modo de seleção	selectionMode	Utilizado para indicar se pretende permitir a seleção de vários itens (utilizadores ou grupos) ou apenas um único item. As opções disponíveis são: `single`, `multiple`. O valor padrão é `multiple`.
desabilitadas	desabilitadas	Define se o seletor de pessoas está desativado. Quando desativado, o utilizador não consegue procurar ou selecionar pessoas. O padrão é `false`.
desativar imagens	disableImages	Define se pretende desativar a obtenção e apresentação de imagens de pessoas. Quando definida como `true`, as iniciais do utilizador são apresentadas. O padrão é `false`.
cartão de pessoa	personCardInteraction	Define o comportamento para mostrar o cartão de pessoa de uma pessoa selecionada. Os valores permitidos são `none`, `hover` ou `click`. O padrão é `none`.
permitir-qualquer-e-mail	allowAnyEmail	Indica se o seletor de pessoas pode aceitar endereços de e-mail sem selecionar uma pessoa. O valor padrão é `false`. Quando terminar de escrever um endereço de e-mail, pode premir vírgula (`,`), ponto e vírgula (`;`), tabulação ou introduzir teclas para o adicionar.
user-ids	userIds	Uma cadeia de IDs de utilizador separados por vírgulas. Só aparecem no menu pendente ou nos resultados da pesquisa quando escreve uma consulta. Por exemplo, `48d31887-5fad-4d73-a9f5-3c356e68a038,24fcbca3-c3e2-48bf-9ffc-c7f81b81483d` apenas apresenta os dois utilizadores na lista pendente quando a entrada está focada. Quando escreve um texto de pesquisa, este devolve resultados que correspondem apenas aos utilizadores nos dois IDs de utilizador.
filtros de utilizador	userFilters	Especifica os critérios de filtro a utilizar ao consultar o ponto final dos utilizadores. Requer o `user-type` para ser definido como `user` ou `contact`. Por predefinição, o `user-type` é `any` e leva a que a consulta ocorra no `people` bloco de pontos finais. Exemplo: `user-filters="startsWith(displayName,'a')"`. Esse atributo é opcional. Saiba mais sobre o suporte para filtrar as propriedades de utilizador de objetos de diretório. Quando utiliza apenas a `User.ReadBasic.All` permissão, a lista de propriedades disponíveis é limitada e o componente adapta-se em conformidade. No âmbito User.ReadBasic.All, está limitado às seguintes propriedades: `id`, `displayName`, `givenName`, `mail`, `securityIdentifier`, e `surnameuserPrincipalName`. Por predefinição, este componente utiliza as `jobTitle` propriedades e `department` . A `mail` propriedade serve como contingência para `jobTitle` quando `User.ReadBasic.All` está em utilização e outras propriedades não são compostas. Utilize a `User.Read.All` permissão para consultar mais propriedades.
filtros de grupo	groupFilters	Especifica os critérios de filtro a utilizar ao consultar o `groups` ponto final. Requer que o `type` para ser definido como `group`. Exemplo: `group-filters="startsWith(displayName,'a')"`. Esse atributo é opcional.
filtros de pessoas	peopleFilters	Especifica os critérios de filtro a utilizar ao consultar o `people` ponto final. É utilizado como está. Exemplo: `people-filters="jobTitle eq 'Web Marketing Manager'"`. Esse atributo é opcional. Saiba mais sobre a filtragem e as capacidades suportadas no recurso de pessoas.
ids de grupo	groupIds	Uma cadeia de IDs de grupo separados por vírgulas. Os resultados disponíveis devem ser limitados aos grupos especificados. Os utilizadores que aparecem no menu pendente e através da experiência de pesquisa só devem ser provenientes dos IDs de grupo especificados. Por exemplo, `02bd9fd6-8f93-4758-87c3-1fb73740a315,06f62f70-9827-4e6e-93ef-8e0f2d9b7b23` apenas apresenta os utilizadores pertencentes a estes grupos. Quando escreve um texto de pesquisa, devolve resultados que correspondem apenas aos utilizadores nos dois IDs de grupo. Esta propriedade não é utilizada se `group-id` estiver definida. Se a propriedade estiver definida, é `group` por predefinição `type` e `transitive-search` é `true` por predefinição. Se o `group-type` estiver definido com a propriedade , pode `type` ser `any` ou `group`. Se for `typeperson`, a propriedade não é utilizada.
aria-label	ariaLabel	Uma cadeia fornecida para ajudar as tecnologias de apoio a fornecer contexto para o seletor de pessoas.

O exemplo seguinte mostra o show-max atributo .

<mgt-people-picker show-max="4"> </mgt-people-picker>

Pessoas selecionadas

A secção pessoas selecionadas do componente compõe cada pessoa escolhida pelo programador ou utilizador.

mgt-people-picker

Pode preencher dados de pessoas selecionadas com as seguintes opções:

Definir a selectedPeople propriedade diretamente, conforme mostrado no exemplo seguinte.

// personObject is the User or Person object from Microsoft Graph
document.querySelector("mgt-people-picker").selectedPeople.push(personObject);

Utilizar o selectUsersById() método , que aceita uma matriz de IDs de utilizador do Microsoft Graph para encontrar os detalhes de utilizador associados para seleção.

Nota: Se não for encontrado nenhum utilizador para um id, não serão compostos dados para esse id.
```
// id = Microsoft graph User "id"
document.querySelector("mgt-people-picker").selectUsersById(["id", "id"]);
```
Utilizar o selectGroupsById() método , que aceita uma matriz de IDs de grupo de gráficos da Microsoft para localizar os grupos com utilizadores associados.
```
// groupid = Microsoft graph group "id"
document
  .querySelector("mgt-people-picker")
  .selectGroupsById(["groupid", "groupid"]);
```

Propriedades personalizadas do CSS

O mgt-people-picker componente define as seguintes propriedades personalizadas do CSS.

<mgt-people-picker class="people-picker"></mgt-people-picker>

.people-picker {
  --people-picker-selected-option-background-color: orange;
  --people-picker-selected-option-highlight-background-color: red;
  --people-picker-dropdown-background-color: blue;
  --people-picker-dropdown-result-background-color: yellow;
  --people-picker-dropdown-result-hover-background-color: gold;
  --people-picker-dropdown-result-focus-background-color: green;
  --people-picker-no-results-text-color: orange;
  --people-picker-input-background: gray;
  --people-picker-input-border-color: yellow;
  --people-picker-input-hover-background: green;
  --people-picker-input-hover-border-color: red;
  --people-picker-input-focus-background: purple;
  --people-picker-input-focus-border-color: orange;

  --people-picker-input-placeholder-focus-text-color: yellow;
  --people-picker-input-placeholder-hover-text-color: gold;
  --people-picker-input-placeholder-text-color: white;
  --people-picker-search-icon-color: yellow;
  --people-picker-remove-selected-close-icon-color: blue;

  /** Style for the avatar-size in the people-picker **/
  --people-picker-result-person-avatar-size: 50px;
  --people-picker-selected-person-avatar-size: 30px;

  /** You can also change the person tokens **/
  --person-line1-text-color: blue;
  --person-line2-text-color: red;
}

Para saber mais, veja Componentes de estilo.

Eventos

Os seguintes eventos são acionados a partir do componente.

Evento	Quando é emitido	Dados personalizados	Cancelável	Bolhas	Funciona com um modelo personalizado
`selectionChanged`	O utilizador adicionou ou removeu uma pessoa da lista de pessoas selecionadas/escolhidas	Matriz de pessoas selecionadas, onde uma pessoa pode ser um utilizador do Graph, pessoa ou contacto com outra `personImage` propriedade que contenha o URL da fotografia do utilizador	Não	Não	Sim, a menos que substitua o modelo predefinido

Para obter mais informações sobre o processamento de eventos, veja eventos.

Modelos

mgt-people-picker suporta vários modelos que pode utilizar para substituir determinadas partes do componente. Para especificar um modelo, inclua um <template> elemento dentro de um componente e defina como data-type um dos seguintes valores.

Tipo de dados	Contexto de dados	Descrição
Padrão.	null: sem dados	O modelo utilizado para substituir a composição de todo o componente.
a carregar	null: sem dados	O modelo utilizado para compor o estado do seletor enquanto o pedido ao gráfico está a ser feito.
erro	null: sem dados	O modelo utilizado se a pesquisa de utilizadores não devolver utilizadores.
sem dados	null: sem dados	Um modelo alternativo utilizado se a pesquisa de utilizadores não devolver utilizadores.
selected-person	pessoa: O objeto de detalhes da pessoa	O modelo para compor pessoas selecionadas.
pessoa	pessoa: O objeto de detalhes da pessoa	O modelo para compor pessoas na lista pendente.

Os exemplos seguintes mostram como utilizar o error modelo.

<mgt-people-picker>
  <template data-type="error">
    <p>Sorry, no people were found</p>
  </template>
</mgt-people-picker>

Permissões do Microsoft Graph

Este componente pode fazer muitas consultas consoante a configuração e o estado. A tabela seguinte divide as APIs do Microsoft Graph e as permissões necessárias em três secções para simplificar. Para cada API chamada, o utilizador tem de ter, pelo menos, uma das permissões listadas.

Independentemente do estado de entrada do utilizador

Configuração	Permissão	API	Opções adicionais
`default-selected-user-ids` definir	User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/users/$({userId}	Quando `user-filters` é definido, isto é adicionado como o `$filter` parâmetro para o pedido com `$count=true` e o `ConsistencyLevel: 'eventual'` cabeçalho é definido no pedido
`default-selected-group-ids` definir	GroupMember. Read. All, Group. Read. All, Directory. Read. All, Group. ReadWrite. All, Directory. ReadWrite. All	/groups	Quando `people-filters` é definido, o respetivo valor é adicionado como o `$filter` parâmetro ao pedido
Quando uma configuração abaixo depende `user-ids` de ser definida, se existir uma entrada de `me` em `user-ids`	User.Read, User.ReadWrite	/me

Quando não existem entradas de utilizador

Configuração	Permissão	API	Opções adicionais
`group-id` definir	GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All	/groups/${groupId}/members	Quando `type` é `person` ou `group` ou `/microsoft.graph.user/microsoft.graph.group` será anexado ao caminho do pedido
`group-id` set AND `transitive-search` is true	GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All	/groups/${groupId}/transitiveMembers	Quando `type` é `person` ou `group` ou `/microsoft.graph.user/microsoft.graph.group` será anexado ao caminho do pedido
`group-ids` set AND `type` is `group`	GroupMember. Read. All, Group. Read. All, Directory. Read. All, Group. ReadWrite. All, Directory. ReadWrite. All	/groups/${id}
`group-ids` set AND `type` is NOT `group`	GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All	/groups/${groupId}/members	Quando `type` é `person` anexado `/microsoft.graph.user` ao caminho do pedido
`group-ids` set AND `type` is NOT `group` AND `transitive-search` is true	GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All	/groups/${groupId}/transitiveMembers	Quando `type` é `person` anexado `/microsoft.graph.user` ao caminho do pedido
`type`é `group` e nem nem `group-idsgroup-id` estão definidos	GroupMember. Read. All, Group. Read. All, Directory. Read. All, Group. ReadWrite. All, Directory. ReadWrite. All	/groups
`type` definido como `person` ou `any` e `userIds` está definido	User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/users/$({userId}	Quando `user-filters` é definido, isto é adicionado como o parâmetro $filter para o pedido com `$count=true` e o `ConsistencyLevel: 'eventual'` cabeçalho é definido no pedido
`type`definido como `person` ou `any` e `user-filters` está definido e `user-type` está definido como ou `usercontact`	User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/users	Quando `user-filters` é definido, isto é adicionado como o parâmetro $filter para o pedido com `$count=true` e o `ConsistencyLevel: 'eventual'` cabeçalho é definido no pedido
`type`definido como `person` ou `any` e `user-filters` não está definido ou `user-type` está definido como nem `usercontact`	People.Read, People.Read.All	/me/people	Quando `people-filters` é definido ou `user-type` não `any` é um parâmetro $filter é adicionado ao pedido. Se `user-type` o cabeçalho não `X-PeopleQuery-QuerySources: 'Mailbox,Directory'contact` estiver definido no pedido

Quando um utilizador tiver fornecido um termo de pesquisa

Configuração	Permissão	API	Opções adicionais
`group-id` está definido	GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All	/groups/${groupId}/members	Quando `type` é `person` ou `group` ou `/microsoft.graph.user/microsoft.graph.group` é anexado ao caminho do pedido, um `$filter` parâmetro é composto com o valor de entrada do utilizador
`group-id` está definido e `transitive-search` é verdadeiro	GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All	/groups/${groupId}/transitiveMembers	Quando `type` é `person` ou `group` ou `/microsoft.graph.user/microsoft.graph.group` é anexado ao caminho do pedido, um `$filter` parâmetro é composto com o valor de entrada do utilizador
`group-id` não está definido e `type` definido como `person` ou `any` e `user-type` definido como `any` e `group-ids` está definido	GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All	/groups/${groupId}/members	Quando `type` é `person` anexado `/microsoft.graph.user` ao caminho do pedido, é composto um `$filter` parâmetro com o valor de entrada do utilizador
`group-id` não está definido e `type` definido como `person` ou `any` e `user-type` definido como `any` e `group-ids` está definido e `transitive-search` é verdadeiro	GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All	/groups/${groupId}/transitiveMembers	Quando `type` é `person` anexado `/microsoft.graph.user` ao caminho do pedido, é composto um `$filter` parâmetro com o valor de entrada do utilizador
`type` definido como `person` ou `any` não `user-type` definido como `any` e `user-ids` está definido	User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/users/$({userId}	Quando `user-filters` é definido, isto é adicionado como o parâmetro $filter para o pedido com `$count=true` e o `ConsistencyLevel: 'eventual'` cabeçalho é definido no pedido
`type` definido como `person` ou `any` e `user-type` definido como `any` e `group-ids` não está definido e `user-ids` está definido	User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/users/$({userId}	Quando `user-filters` é definido, isto é adicionado como o parâmetro $filter para o pedido com `$count=true` e o `ConsistencyLevel: 'eventual'` cabeçalho é definido no pedido
`group-id` não está definido e `type` é `group` ou `type` é `any` e tem menos resultados do que `show-max` foram encontrados	GroupMember. Read. All, Group. Read. All, Directory. Read. All, Group. ReadWrite. All, Directory. ReadWrite. All	/groups	Um `$filter` é composto com a entrada de utilizador fornecida, `group-filters`e `group-type` os valores
`group-id` não está definido e `group-ids` está definido e `type` é `group` ou `type` é `any` e tem menos resultados do que `show-max` foram encontrados	GroupMember. Read. All, Group. Read. All, Directory. Read. All, Group. ReadWrite. All, Directory. ReadWrite. All	/groups	Um `$filter` é composto com a entrada de utilizador fornecida, `user-filters`e `group-type` os valores

Subcomponentes

O mgt-people-picker componente é composto por um ou mais subcomponentes que podem exigir outras permissões do que as listadas anteriormente. Para obter mais informações, consulte a documentação para cada subcomponente: mgt-person.

Autenticação

O controlo utiliza o fornecedor de autenticação global descrito na documentação de autenticação.

Cache

Arquivo de objetos	Dados em cache	Comentários
`groups`	Lista de grupos	Utilizado quando `type` está definido como `PersonType.group`
`people`	Lista de pessoas	Utilizado quando `type` está definido como `PersonType.person` ou `PersonType.any`
`users`	Lista de utilizadores	Utilizado quando `groupId` especificado

Para obter mais informações sobre como configurar a cache, veja Colocação em cache.

Expandir para obter mais controlo

Para cenários mais complexos ou um UX verdadeiramente personalizado, este componente expõe vários protected render* métodos de substituição em extensões de componentes.

Método	Descrição
renderInput	Compõe a caixa de texto de entrada.
renderSelectedPeople	Compõe os tokens de pessoas selecionados.
renderSelectedPerson	Compõe um token de pessoa individual.
renderFlyout	Compõe o cromado de lista de opções.
renderFlyoutContent	Compõe o estado adequado na lista de opções de resultados.
renderLoading	Compõe o estado de carregamento.
renderNoData	Compõe o estado quando não são encontrados resultados para a consulta de pesquisa.
renderSearchResults	Compõe a lista de resultados da pesquisa.
renderPersonResult	Compõe um resultado de pesquisa de uma pessoa individual.

Localização

O controlo expõe as seguintes variáveis que podem ser localizadas. Para obter detalhes sobre a localização, veja Localizar componentes.

Nome da cadeia	Valor padrão
inputPlaceholderText	`Search for a name`
maxSelectionsPlaceHolder	`Max contacts added`
maxSelectionsAriaLabel	`Maximum contact selections reached`
noResultsFound	`We didn't find any matches.`
loadingMessage	`Loading...`
selecionado	`selected`
removeSelectedUser	`Remove`
selectContact	`select a contact`
suggestionsTitle	`Suggested contacts`

Compartilhar via