Pessoas componente do seletor no Microsoft Graph Toolkit

  • Artigo

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 da organização, mas você pode alterar o comportamento para também pesquisar 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 usar 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 /me/people pontos de extremidade e /users . Use os atributos a seguir para alterar esse comportamento.

Atributo Propriedade Descrição
show-max showMax Um valor numérico para indicar o número máximo de pessoas a serem exibidas. 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 filtragem adicional dos resultados da pesquisa.
transitive-search 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 é person. Se esse atributo estiver definido como group e ou estiver group-ids definido, e peopleFiltersuserFiltersgroup-id não tiver 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 de grupo ou tipos a serem pesquisados. As opções disponíveis são: , , , , anydistribution. mailenabledsecuritysecurityunified 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 separada por vírgulas; a propriedade aceita uma matriz ou valores.
selected-people 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 Espaço O texto padrão que aparece para explicar como usar o componente. O valor padrão é Start typing a name.
padrão selecionado-usuário-ids defaultSelectedUserIds Quando fornecida uma cadeia de caracteres de IDs de usuário do Microsoft Graph separadas por vírgulas, o componente renderiza os respectivos usuários conforme selecionado após a inicialização.
default-selected-group-ids defaultSelectedGroupIds Semelhante a ids de usuário selecionadas por padrão, quando fornecida uma cadeia de caracteres de IDs de grupo do Microsoft Graph separadas por vírgulas, o componente renderiza os respectivos grupos conforme selecionado após a inicialização.
modo de seleção selectionMode Usado para indicar se deve 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 pode pesquisar ou selecionar pessoas. O padrão é false.
desabilitar imagens disableImages Define se deve desabilitar a busca e a exibição de imagens de pessoa. Em vez disso, quando definido como true, as iniciais do usuário são exibidas. O padrão é false.
person-cartão personCardInteraction Define o comportamento para mostrar a pessoa cartão de uma pessoa selecionada. Os valores permitidos são none, hover ou click. O padrão é none.
allow-any-email allowAnyEmail Indica se o seletor de pessoas pode aceitar endereços de email sem selecionar uma pessoa. O valor padrão é false. Ao terminar de digitar um endereço de email, você pode pressionar vírgula (,), ponto e vírgula (;), guia ou inserir chaves para adicioná-lo.
ids de usuário userIds Uma cadeia de caracteres de IDs de usuário separadas por vírgulas. Elas aparecem apenas 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 está focada. Quando você digita um texto de pesquisa, ele retorna resultados que correspondem apenas aos usuários 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. Ele requer que o user-type seja definido como user ou contact. Por padrão, o user-type é any e leva a consulta a ocorrer 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, mail, securityIdentifier, surnamee userPrincipalName. Por padrão, esse componente usa as jobTitle propriedades e department . A mail propriedade serve como um fallback para jobTitle quando User.ReadBasic.All está em uso e outras propriedades não são 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. Isso 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 é. Exemplo: people-filters="jobTitle eq 'Web Marketing Manager'". Esse atributo é opcional. Saiba mais sobre filtragem e os recursos com suporte no recurso de pessoas.
IDs de grupo groupIds Uma cadeia de caracteres de IDs de grupo separadas por vírgulas. 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 só devem vir das IDs de grupo especificadas. Por exemplo, 02bd9fd6-8f93-4758-87c3-1fb73740a315,06f62f70-9827-4e6e-93ef-8e0f2d9b7b23 exibe apenas usuários pertencentes a esses grupos. Quando você digita um texto de pesquisa, ele retorna resultados que correspondem apenas aos usuários nas duas IDs de grupo. Essa propriedade não será usada se group-id for definida. Se a propriedade estiver definida, a type será group por padrão e transitive-search será 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 aria ariaLabel Uma cadeia de caracteres fornecida para ajudar as 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 pessoas selecionadas do componente renderiza cada pessoa escolhida pelo desenvolvedor ou usuário.

mgt-people-picker

Você pode preencher 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 encontrar detalhes do usuário associados para seleção.

    Nota: 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 do grupo de grafos da Microsoft para localizar os grupos com usuários 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, confira componentes de estilo.

Eventos

Os eventos a seguir são disparados do componente.

Evento Quando ele é 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, em que uma pessoa pode ser um usuário, pessoa ou contato do Graph 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 dá suporte a vários modelos que você pode usar para substituir determinadas partes do componente. 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
Padrão. nulo: sem dados O modelo usado para substituir a renderização de todo o componente.
Carregar nulo: sem dados O modelo usado para renderizar o estado do seletor enquanto a solicitação ao grafo está sendo feito.
erro nulo: sem dados O modelo usado se a pesquisa de usuário não retornar usuários.
sem dados nulo: sem dados Um modelo alternativo usado se a pesquisa de usuários não retornar usuários.
selected-person pessoa: O objeto de detalhes da pessoa O modelo para renderizar pessoas selecionadas.
Pessoa pessoa: O objeto de detalhes da pessoa O modelo para renderizar as 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 do Microsoft Graph e as permissões 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 Definir 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 à solicitação com $count=true e o ConsistencyLevel: 'eventual' cabeçalho é definido na solicitação
default-selected-group-ids Definir 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 à solicitação
Quando uma configuração abaixo depende user-ids de ser definida, se houver uma entrada de me em user-ids User.Read, User.ReadWrite /Me

Quando nenhuma entrada de usuário está presente

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á acrescentado ao caminho da solicitação
group-id set AND transitive-search é 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á acrescentado ao caminho da solicitação
group-ids set AND type é group GroupMember. Read. All, Group. Read. All, Directory. Read. All, Group. ReadWrite. All, Directory. ReadWrite. All /groups/${id}
group-ids set AND type não é 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 acrescentado ao caminho da solicitação
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 então /microsoft.graph.user acrescentado ao caminho da solicitação
type é group e nem group-id nem group-ids sã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 é 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 com $count=true e o ConsistencyLevel: 'eventual' cabeçalho é definido na solicitação
type definido como person ou any e user-filters é definido e user-type é definido como user ou contact 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 com $count=true e o ConsistencyLevel: 'eventual' cabeçalho é definido na solicitação
typedefinido como person ou any e user-filters não é definido ou user-type é definido como nem nem usercontact People.Read, People.Read.All /me/people Quando people-filters é definido ou user-type não any é um parâmetro $filter é adicionado à solicitação. Se user-type o cabeçalho não X-PeopleQuery-QuerySources: 'Mailbox,Directory'contact estiver definido na solicitação

Quando um usuário forneceu um termo de pesquisa

Configuração Permissão API Opções adicionais
group-id é definido GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All /groups/${groupId}/members Quando type é person ou group/microsoft.graph.user ou /microsoft.graph.group é acrescentado ao caminho da solicitação, um $filter parâmetro é composto com o valor de entrada do usuário
group-id é 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/microsoft.graph.user ou /microsoft.graph.group é acrescentado ao caminho da solicitação, um $filter parâmetro é composto com o valor de entrada do usuário
group-id não é definido e type definido como person ou any e user-type definido como any e group-ids é definido GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All /groups/${groupId}/members Quando type é person acrescentado /microsoft.graph.user ao caminho da solicitação, um $filter parâmetro é composto com o valor de entrada do usuário
group-id não é definido e type definido como person ou any e user-type definido como any e group-ids é definido e transitive-search é true GroupMember.Read.All, Group.Read.All, Directory.Read.All, GroupMember.ReadWrite.All, Group.ReadWrite.All /groups/${groupId}/transitiveMembers Quando type é person acrescentado /microsoft.graph.user ao caminho da solicitação, um $filter parâmetro é composto com o valor de entrada do usuário
type definido como person ou anyuser-type não definido como any e user-ids é 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 com $count=true e o ConsistencyLevel: 'eventual' cabeçalho é definido na solicitação
type definido como person ou any e user-type definido como any e group-ids não é definido e user-ids é 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 com $count=true e o ConsistencyLevel: 'eventual' cabeçalho é definido na solicitação
group-id não é definido e type é group ou type é any e menos resultados do que show-max foram encontrados GroupMember. Read. All, Group. Read. All, Directory. Read. All, Group. ReadWrite. All, Directory. ReadWrite. All /Grupos Um $filter é composto usando a entrada de usuário fornecida, group-filterse group-type valores
group-id não é definido e group-ids é definido e type é group ou type é any e menos resultados do que show-max foram encontrados GroupMember. Read. All, Group. Read. All, Directory. Read. All, Group. ReadWrite. All, Directory. ReadWrite. All /Grupos Um $filter é composto usando a entrada de usuário fornecida, user-filterse group-type valores

Subcomponentes

O mgt-people-picker componente consiste em um ou mais subcomponentes que podem exigir outras permissões do que as listadas anteriormente. Para obter mais informações, confira 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

Repositório de objetos Dados armazenados em cache Comentários
groups Lista de grupos Usado quando type é definido como PersonType.group
people Lista de pessoas Usado quando type é 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.

Estender para obter mais controle

Para cenários mais complexos ou uma UX 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 os tokens de pessoas selecionadas.
renderSelectedPerson Renderiza um token de pessoa individual.
renderFlyout Renderiza o cromado de flyout.
renderFlyoutContent Renderiza o estado apropriado no flyout 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 um resultado de pesquisa de pessoa individual.

Localização

O controle expõe as variáveis a seguir que podem ser localizadas. Para obter detalhes sobre a 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