Componente de seletor de pessoas no Microsoft Graph Toolkit
Artigo
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.
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.
A secção pessoas selecionadas do componente compõe cada pessoa escolhida pelo programador ou utilizador.
Pode preencher dados de pessoas selecionadas com as seguintes opções:
Definir a selectedPeople propriedade diretamente, conforme mostrado no exemplo seguinte.
JavaScript
// personObject is the User or Person object from Microsoft Graphdocument.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.
JavaScript
// 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.
JavaScript
// 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.
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.
HTML
<mgt-people-picker><templatedata-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
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
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
typedefinido como person ou any e user-filters está definido e user-type está definido como ou usercontact
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
typedefinido como person ou any e user-filters não está definido ou user-type está definido como nem usercontact
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
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
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
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
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
Um $filter é composto com a entrada de utilizador fornecida, user-filterse 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.
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.
Os componentes do Kit de ferramentas do Microsoft Graph são flexíveis para personalização. Você pode alterar o comportamento dos componentes usando atributos. Você também pode personalizar o estilo do componente usando propriedades personalizadas CSS para corresponder à identidade visual do seu aplicativo.