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.

Pode utilizar a biblioteca de cliente JavaScript do Microsoft Teams, que fornece a selectPeople API para integrar o controlo de entrada Seletor de Pessoas na sua aplicação Web.

Vantagens de usar o Seletor de Pessoas

• Funciona em todas as funcionalidades do Teams, como a caixa de diálogo (referida como módulo de tarefas no TeamsJS v1.x), chat, canal, separador reunião e aplicação 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. Tem de transmitir os IDs do Microsoft Entra das pessoas para serem pré-selecionados. 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 utilizador 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 tabulação	Este exemplo mostra a funcionalidade do seletor de pessoas que utiliza o sdk de cliente js do teams dentro do separador.	View	View	Exibir

Confira também

• 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
• Componente de seletor de pessoas no Microsoft Graph Toolkit