Integrar o Seletor de Pessoas

O Seletor de Pessoas é um controle de entrada no Teams que permite aos usuários pesquisar e selecionar pessoas. Você pode integrar o controle de entrada do Seletor de Pessoas em um aplicativo Web, que permite que os usuários finais executem diferentes funções, tais como pesquisar e selecionar pessoas em um chat, canal ou em toda a organização dentro do Teams. O controle do Seletor de Pessoas está disponível em todos os clientes do Teams, como Web, área de trabalho e dispositivo móvel.

Você pode usar a biblioteca de clientes JavaScript do Microsoft Teams, que fornece a selectPeople API para integrar o controle de entrada Pessoas Picker em seu aplicativo Web.

Vantagens de usar o Seletor de Pessoas

• Funciona em todos os recursos do Teams, como caixa de diálogo (conhecido como módulo de tarefa no TeamsJS v1.x), chat, canal, guia de reunião e aplicativo pessoal.
• Permite que o usuário pesquise e selecione pessoas em um chat, canal ou toda a organização dentro do Teams.
• Ajuda em cenários que envolvem a atribuição de tarefas, marcação e notificação do usuário.
• Economiza tempo e esforços significativos em comparação com a construção de qualquer controle semelhante.

Para integrar o controle de entrada do Seletor de Pessoas no seu aplicativo Teams, use a API selectPeople. Para integrar e chamar a API, você deve ter uma boa compreensão do trecho de código que a acompanha. Você também precisa estar familiarizado com erros de réplica da API.

selectPeople API

A API selectPeople permite que você adicione o controle de entrada do Seletor de Pessoas do Teams para os aplicativos Web e também ajuda você com o seguinte:

• Permite que o usuário pesquise e selecione uma ou mais pessoas da lista.
• Retorna a ID, o nome e o endereço de email dos usuários selecionados para o aplicativo Web.

Em um aplicativo pessoal, o controle pesquisa por nome ou ID de email em toda a organização no Teams. Se o aplicativo for adicionado a um chat ou canal, o contexto de pesquisa será configurado com base no cenário. A pesquisar é restrita aos membros desse chat ou canal.

A API selectPeople vem com as seguintes configurações de entrada:

Parâmetro de Configuração	Tipo	Descrição	Valor padrão
title	Cadeia de caracteres	É um parâmetro opcional e define o título para o controle do Seletor de Pessoas.	selectPeople
setSelected	String	É um parâmetro opcional. Você deve passar Microsoft Entra IDs das pessoas a serem pré-selecionadas. Este parâmetro pré-seleciona as pessoas ao iniciar o controle de entrada do Seletor de Pessoas. Em uma única seleção, apenas o primeiro usuário válido é pré-preenchido, ignorando o restante.	Null
openOrgWideSearchInChatOrChannel	Boolean	É um parâmetro opcional e, quando definido como verdadeiro, inicia o Seletor de Pessoas em todo o escopo da organização, mesmo se o aplicativo for adicionado a um chat ou canal.	Falso
singleSelect	Booliano	É um parâmetro opcional e, quando definido como true, ele inicia o Seletor de Pessoas e restringe a seleção a apenas um usuário.	Falso

A imagem a seguir mostra a experiência do Seletor de Pessoas em dispositivos móveis e na área de trabalho:

Dispositivo móvel

O controle de entrada do Seletor de Pessoas permite que o usuário pesquise e adicione pessoas usando as seguintes etapas:

1. Digite o nome da pessoa obrigatória. A lista aparece com sugestões de nome.

2. Selecione o nome da pessoa obrigatória na lista.

   

Desktop

O controle do Seletor de Pessoas na Web ou na área de trabalho é iniciado em uma janela modal na parte superior do aplicativo Web e, para adicionar pessoas, siga as seguintes etapas:

1. Digite o nome da pessoa obrigatória. A lista aparece com sugestões de nome.

2. Selecione o nome da pessoa obrigatória na lista.

   

Trecho de código

O trecho de código a seguir exibe o uso das pessoas da API selectPeople de uma lista:

TeamsJS v2

people.selectPeople({ setSelected: ["aad id"], openOrgWideSearchInChatOrChannel: true, singleSelect: false, title: true}).then(people) => 
 {
    output(" People length: " + people.length + " " + JSON.stringify(people));
 }).catch((error) => { /*Unsuccessful operation*/ });

TeamsJS v1

people.selectPeople((error: microsoftTeams.SdkError, people: microsoftTeams.people.PeoplePickerResult[]) => 
 {
    if (error) 
    {
        if (error.message) 
           {
             alert(" ErrorCode: " + error.errorCode + error.message);
           }
            else 
            {
              alert(" ErrorCode: " + error.errorCode);
            }
      }
    if (people)
     {
            output(" People length: " + people.length + " " + JSON.stringify(people));
      }
  },{ setSelected: ["aad id"], openOrgWideSearchInChatOrChannel: true, singleSelect: false, title: true});

Tratamento de erros

A tabela a seguir lista os códigos de erro e suas descrições:

Código de erro	Nome do erro	Descrição
100	NÃO_SUPORTADO_NA_PLATAFORMA	A API não é compatível com a plataforma atual.
500	INTERNAL_ERROR	Erro interno encontrado ao iniciar o Seletor de Pessoas.
4000	ARGUMENTOS_INVÁLIDOS	A API foi invocada com argumentos obrigatórios incorretos ou insuficientes.
8000	ABORTAR_USUÁRIO	O usuário cancelou a operação.
9000	ANTIGA_PLATAFORMA	O usuário está em uma compilação antiga da plataforma em que a implementação da API não está disponível. Atualize para a versão mais recente da build para resolver o problema.

Exemplo de código

Nome do exemplo	Descrição	.NET	Node.js	Manifesto
Seletor de pessoas de guia	Este exemplo mostra o recurso do seletor de pessoas usando o sdk do cliente js do teams dentro da guia.	View	View	Exibir

Confira também

• Integrar aplicativos Web
• Integrar recursos de mídia
• Integrar a funcionalidade do código QR ou o verificador de código de barras no Teams
• Integrar funcionalidades de localização no Teams
• Pessoas componente do seletor no Microsoft Graph Toolkit