Componente seletor de People no Microsoft Graph Toolkit

Cuidado

O Microsoft Graph Toolkit foi preterido. O período de aposentadoria começa em 1º de setembro de 2025, com aposentadoria total planejada para 28 de agosto de 2026. Os desenvolvedores devem migrar para o uso dos SDKs do Microsoft Graph ou outras ferramentas do Microsoft Graph com suporte para criar experiências na Web. Para obter mais informações, consulte o anúncio de substituição.

Você pode usar o mgt-people-picker componente Web para pesquisar pessoas, grupos ou ambos. Por padrão, o componente pesquisa todas as pessoas e usuários na organização, mas você pode alterar o comportamento para pesquisar também grupos ou apenas grupos. Você também pode filtrar a pesquisa para um grupo específico. Você também pode permitir que o usuário insira e selecione qualquer endereço de email.

Exemplo

O exemplo a seguir mostra o mgt-people-picker componente. Comece a pesquisar um nome para ver os resultados renderizados e use o editor de código para ver como as propriedades alteram o comportamento do componente.

Propriedades

Por padrão, o mgt-people-picker componente busca pessoas dos pontos de /me/people extremidade e /users . Use os atributos a seguir para alterar esse comportamento.

Atributo Propriedade Descrição
Mostrar máx. Mostrar Max Um valor numérico para indicar o número máximo de pessoas a serem mostradas. O valor padrão é 6.
ID de grupo groupId Um valor de cadeia de caracteres que pertence a um grupo definido pelo Microsoft Graph para uma filtragem adicional dos resultados da pesquisa.
pesquisa transitiva transitiveSearch Um valor booliano para executar uma pesquisa transitiva retornando uma lista simples de todos os membros aninhados - por padrão, a pesquisa transitiva não é usada.
type type O tipo de entidades a serem pesquisadas. As opções disponíveis são: person, group, any. O valor padrão é any. Se esse atributo for definido como group e ou group-id for group-ids definido, então userFilters e peopleFilters não terá efeito.
tipo de usuário userType O tipo de usuário a ser pesquisado. As opções disponíveis são: any, user para usuários organizacionais ou contact para contatos. O valor padrão é any.
tipo de grupo groupType O tipo ou os tipos de grupo a serem pesquisados. As opções disponíveis são: unified, security, mailenabledsecurity, distribution, any. O valor padrão é any. Esse atributo não terá efeito se a type propriedade estiver definida como person. Esse atributo aceita uma lista de valores separados por vírgula; A propriedade aceita uma matriz ou valores.
pessoas selecionadas selectedPeople Uma matriz de pessoas selecionadas. Defina esse valor para selecionar pessoas programaticamente.
people people Uma matriz de pessoas encontradas e renderizadas no resultado da pesquisa
espaço reservado espaço reservado O texto padrão que aparece para explicar como usar o componente. O valor padrão é Start typing a name.
IDs de usuário selecionado padrão defaultSelectedUserIds Quando recebe uma cadeia de caracteres de IDs de usuário do Microsoft Graph separadas por vírgula, o componente renderiza os respectivos usuários conforme selecionado na inicialização.
IDs de grupo selecionadas por padrão defaultSelectedGroupIds Semelhante às IDs de usuário selecionadas por padrão, quando recebe uma cadeia de caracteres de IDs de grupo do Microsoft Graph separadas por vírgula, o componente renderiza os respectivos grupos conforme selecionado na inicialização.
modo de seleção selectionMode Usado para indicar se é possível permitir a seleção de vários itens (usuários 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á desabilitado. Quando desabilitado, o usuário não poderá pesquisar ou selecionar pessoas. O padrão é false.
disable-images disableImages Define se a busca e a exibição de imagens de pessoa devem ser desabilitadas. Quando definido como true, as iniciais de usuário são exibidas. O padrão é false.
person-card personCardInteraction Define o comportamento para mostrar o card de pessoa de uma pessoa selecionada. Os valores permitidos são none, hover ou click. O padrão é none.
Permitir qualquer email allowAnyEmail Indica se o seletor de pessoas pode aceitar endereços de email sem selecionar uma pessoa. O valor padrão é false. Quando terminar de digitar um endereço de email, você pode pressionar vírgula (,), ponto e vírgula (;), tab ou inserir as teclas para adicioná-lo.
IDs de usuário userIds Uma sequência de IDs de usuário separadas por vírgula. Eles só aparecem no menu suspenso ou nos resultados da pesquisa quando você digita uma consulta. Por exemplo, 48d31887-5fad-4d73-a9f5-3c356e68a038,24fcbca3-c3e2-48bf-9ffc-c7f81b81483d exibe apenas os dois usuários na lista suspensa quando a entrada é focada. Quando você digita um texto de pesquisa, ela retorna resultados que correspondem aos usuários apenas nas duas IDs de usuário.
Filtros de usuário userFilters Especifica os critérios de filtro a serem usados ao consultar o ponto de extremidade dos usuários. Requer que o user-type seja definido como user ou contact. Por padrão, o user-type é any e faz com que a consulta ocorra no bloco de people ponto de extremidade. Exemplo: user-filters="startsWith(displayName,'a')". Esse atributo é opcional. Saiba mais sobre o suporte para filtro nas propriedades do usuário de objetos de diretório.

Quando você usa apenas a User.ReadBasic.All permissão, a lista de propriedades disponíveis é limitada e o componente se adapta de acordo. No escopo User.ReadBasic.All, você está limitado às seguintes propriedades: id, displayName, givenName, surnamemailsecurityIdentifiere .userPrincipalName Por padrão, esse componente usa as jobTitle propriedades and department . A mail propriedade serve como um fallback para jobTitle quando User.ReadBasic.All estiver em uso e outras propriedades não forem renderizadas. Use a User.Read.All permissão para consultar mais propriedades.
filtros de grupo groupFilters Especifica os critérios de filtro a serem usados ao consultar o groups ponto de extremidade. Requer que o type seja definido como group. Exemplo: group-filters="startsWith(displayName,'a')". Esse atributo é opcional.
Filtros de pessoas peopleFilters Especifica os critérios de filtro a serem usados ao consultar o people ponto de extremidade. É usado como está. Exemplo: people-filters="jobTitle eq 'Web Marketing Manager'". Esse atributo é opcional. Saiba mais sobre filtragem e os recursos com suporte no recurso pessoas.
IDs de grupo groupIds Uma sequência de IDs de grupo separadas por vírgula. Os resultados disponíveis devem ser limitados aos grupos especificados. Os usuários que aparecem no menu suspenso e por meio da experiência de pesquisa devem vir apenas das IDs de grupo especificadas. Por exemplo, 02bd9fd6-8f93-4758-87c3-1fb73740a315,06f62f70-9827-4e6e-93ef-8e0f2d9b7b23 exibe apenas os usuários pertencentes a esses grupos. Quando você digita um texto de pesquisa, ela retorna resultados que correspondem apenas aos usuários nas duas IDs de grupo. Esta propriedade não será usada se group-id estiver definida. Se a propriedade estiver definida, o type é group por padrão e transitive-search é true por padrão. Se o group-type estiver definido com a propriedade, o type pode ser any ou group. Se for typeperson, a propriedade não será usada.
rótulo de aria ariaLabel Uma cadeia de caracteres fornecida para ajudar tecnologias assistivas a fornecer contexto para o seletor de pessoas.

O exemplo a seguir mostra o show-max atributo.

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

Pessoas selecionadas

A seção de pessoas selecionadas do componente renderiza cada pessoa escolhida pelo desenvolvedor ou usuário.

mgt-people-picker

Você pode preencher os dados de pessoas selecionadas com as seguintes opções:

  • Definindo a selectedPeople propriedade diretamente, conforme mostrado no exemplo a seguir.

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

  • Usando o selectUsersById() método, que aceita uma matriz de IDs de usuário do Microsoft Graph para localizar detalhes de usuário associados para seleção.

    Observação: Se nenhum usuário for encontrado para um id, nenhum dado será renderizado para esse id.

    // id = Microsoft graph User "id"
document.querySelector("mgt-people-picker").selectUsersById(["id", "id"]);

  • Usando o selectGroupsById() método, que aceita uma matriz de IDs de grupo do Microsoft Graph para localizar o(s) grupo(s) com usuários associados.

    // groupid = Microsoft graph group "id"
document
  .querySelector("mgt-people-picker")
  .selectGroupsById(["groupid", "groupid"]);

Propriedades personalizadas CSS

O mgt-people-picker componente define as seguintes propriedades personalizadas 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, consulte Componentes de estilo.

Eventos

Os eventos a seguir são disparados do componente.

Evento Quando é emitido Dados personalizados Cancelável Bolhas Funciona com modelo personalizado
selectionChanged O usuário adicionou ou removeu uma pessoa da lista de pessoas selecionadas/escolhidas Matriz de pessoas selecionadas, onde uma pessoa pode ser um usuário do Graph, pessoa ou contato com outra personImage propriedade que contém a URL da foto do usuário Não Não Sim, a menos que você substitua o modelo padrão

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

Modelos

mgt-people-picker Suporta vários modelos que podem ser usados 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. nulo: sem dados O modelo usado para substituir a renderização de todo o componente.
carregando nulo: sem dados O modelo usado para renderizar o estado do seletor enquanto a solicitação de gráfico está sendo feita.
erro nulo: sem dados O modelo usado se a pesquisa do usuário não retornar nenhum usuário.
sem dados nulo: sem dados Um modelo alternativo usado se a pesquisa do usuário não retornar nenhum usuário.
pessoa selecionada pessoa: o objeto de detalhes da pessoa O modelo para renderizar as pessoas selecionadas.
pessoa pessoa: o objeto de detalhes da pessoa O modelo para renderizar pessoas na lista suspensa.

Os exemplos a seguir mostram como usar 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

Esse componente pode fazer muitas consultas, dependendo da configuração e do estado. A tabela a seguir divide as APIs e permissões do Microsoft Graph necessárias em três seções para simplificar. Para cada API chamada, o usuário deve ter pelo menos uma das permissões listadas.

Independentemente do estado de entrada do usuário

Configuração Permissão API Opções adicionais
default-selected-user-ids conjunto User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All /users/$({userId} Quando user-filters é definido, isso é adicionado como o $filter parâmetro para a solicitação com $count=true e o ConsistencyLevel: 'eventual' cabeçalho é definido na solicitação
default-selected-group-ids conjunto GroupMember. Read. All, Group. Read. All, Directory. Read. All, Group. ReadWrite. All, Directory. ReadWrite. All /grupos Quando people-filters é definido, seu valor é adicionado como o $filter parâmetro para a solicitação
Quando uma configuração abaixo depender user-ids de ser definida, se houver uma entrada de meuser-ids User.Read, User.ReadWrite /me

Quando nenhuma entrada do usuário está presente

Configuração Permissão API Opções adicionais
group-id conjunto GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All /groups/${groupId}/members Quando type é person ou group um /microsoft.graph.user ou será /microsoft.graph.group anexado ao caminho da solicitação
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 um /microsoft.graph.user ou será /microsoft.graph.group anexado ao caminho da solicitação
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 is type NOT group GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All /groups/${groupId}/members Quando type é person então /microsoft.graph.user é anexado ao caminho da solicitação
group-idsset AND type is NOT group AND is true transitive-search GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All /groups/${groupId}/transitiveMembers Quando type é person então /microsoft.graph.user é anexado ao caminho da solicitação
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 /grupos
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, isso é adicionado como o parâmetro $filter à solicitação e $count=true o ConsistencyLevel: 'eventual' cabeçalho é definido na solicitação
typeDefinido como OU anyperson 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 /usuários Quando user-filters é definido, isso é adicionado como o parâmetro $filter à solicitação e $count=true o ConsistencyLevel: 'eventual' cabeçalho é definido na solicitação
type Defina como person OR any e user-filters não está definido ou user-type está definido como nem user nem contact People.Read, People.Read.All /eu/pessoas Quando people-filters está definido ou user-type não any é um parâmetro $filter é adicionado à solicitação. Se user-type não contact for, o X-PeopleQuery-QuerySources: 'Mailbox,Directory' cabeçalho será definido na solicitação

Quando um usuário forneceu 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 um ou /microsoft.graph.user é /microsoft.graph.group anexado ao caminho da solicitação, um $filter parâmetro é composto com o valor de entrada do usuário
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 um ou /microsoft.graph.user é /microsoft.graph.group anexado ao caminho da solicitação, um $filter parâmetro é composto com o valor de entrada do usuário
group-id não está definido e type definido como person ou any e definido user-type 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 então /microsoft.graph.user é anexado ao caminho da solicitação, um $filter parâmetro é composto com o valor de entrada do usuário
group-id não está definido e type definido como person ou any e definido user-type 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 então /microsoft.graph.user é anexado ao caminho da solicitação, um $filter parâmetro é composto com o valor de entrada do usuário
type Definido como person Ou any e user-type não 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, isso é adicionado como o parâmetro $filter à solicitação e $count=true o ConsistencyLevel: 'eventual' cabeçalho é definido na solicitação
type Defina como person ou any e user-type defina 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, isso é adicionado como o parâmetro $filter à solicitação e $count=true o ConsistencyLevel: 'eventual' cabeçalho é definido na solicitação
group-id não está definido e type é group ou type é any e menos resultados do que show-max os encontrados GroupMember. Read. All, Group. Read. All, Directory. Read. All, Group. ReadWrite. All, Directory. ReadWrite. All /grupos A $filter é composto usando a entrada do usuário fornecida, group-filters, e group-type os valores
group-id não está definido e group-ids está definido e type é group ou type é e menos any resultados do que show-max os encontrados GroupMember. Read. All, Group. Read. All, Directory. Read. All, Group. ReadWrite. All, Directory. ReadWrite. All /grupos A $filter é composto usando a entrada do usuário fornecida, user-filters, e group-type os valores

Subcomponentes

O mgt-people-picker componente consiste em um ou mais subcomponentes que podem exigir outras permissões além das listadas anteriormente. Para obter mais informações, consulte a documentação de cada subcomponente: mgt-person.

Autenticação

O controle usa o provedor de autenticação global descrito na documentação de autenticação.

Cache

Loja de objetos Dados armazenados em cache Comentários
groups Lista de grupos Usado quando está definido como typePersonType.group
people Lista de pessoas Usado quando type está definido como PersonType.person ou PersonType.any
users Lista de usuários Usado quando groupId especificado

Para obter mais informações sobre como configurar o cache, consulte Cache.

Estenda para mais controle

Para cenários mais complexos ou uma experiência de usuário verdadeiramente personalizada, esse componente expõe vários protected render* métodos de substituição em extensões de componente.

Método Descrição
renderInput Renderiza a caixa de texto de entrada.
renderSelectedPeople Renderiza as fichas de pessoas selecionadas.
renderSelectedPerson Renderiza um token de pessoa individual.
renderFlyout Renderiza o cromo do submenu.
renderFlyoutContent Renderiza o estado apropriado no submenu de resultados.
renderLoading Renderiza o estado de carregamento.
renderNoData Renderiza o estado quando nenhum resultado é encontrado para a consulta de pesquisa.
renderSearchResults Renderiza a lista de resultados da pesquisa.
renderPersonResult Renderiza o resultado de uma pesquisa de pessoa individual.

Localização

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

Nome da cadeia de caracteres 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
  • Last updated on