Componente de pessoa no Microsoft Graph Toolkit

  • Artigo

O componente de pessoa é usado para exibir uma pessoa ou contato usando sua foto, nome, endereço de email ou qualquer outro detalhe de pessoa.

O componente de pessoa também usa o mgt-person-cartão para exibir um cartão de sobrevoo com informações adicionais sobre o usuário. Para obter detalhes, confira a seção Cartão de Pessoa .

Exemplo

O exemplo a seguir exibe uma pessoa usando o mgt-person componente. Você pode usar o editor de código para ver como as propriedades alteram o comportamento do componente.

Definindo os detalhes da pessoa

Você pode usar três propriedades para definir os detalhes da pessoa. Use apenas uma das seguintes propriedades por instância:

  • Defina o user-id atributo ou userId a propriedade para buscar o usuário do Microsoft Graph usando sua ID.

  • Defina o person-query atributo ou personQuery a propriedade para pesquisar no Microsoft Graph uma determinada pessoa. Ele escolherá a primeira pessoa disponível e buscará os detalhes da pessoa. Um email funciona melhor para garantir que a pessoa certa seja consultada, mas um nome também funciona.

  • Defina o person-presence atributo ou personPresence a propriedade para adicionar um selo de presença ao avatar da pessoa manualmente.

  • Defina o avatar-size atributo ou avatarSize a propriedade como small ou large para determinar o tamanho do avatar. Isso ajuda a adicionar o selo de presença correto ao avatar. Você precisará escolher as propriedades personalizadas css correspondentes corretas mostradas abaixo para personalizar ainda mais o tamanho do avatar. Por padrão, o valor é definido para auto o qual decidirá automaticamente como renderizar a presença com base na view propriedade. Recomendamos usar small se o avatar for menor que 32px por 32px.

  • Use o person-details atributo ou personDetails a propriedade para definir manualmente os detalhes da pessoa, conforme mostrado no exemplo a seguir.

    let personControl = document.getElementById('myPersonControl');
personControl.personDetails = {
    displayName: 'Nikola Metulev',
    mail: 'nikola@contoso.com',
    personImage: 'url'
}

    Se nenhuma imagem for fornecida, uma será buscada (se disponível).

  • Por padrão, o componente de pessoa solicita apenas o conjunto de propriedades de usuário padrão do Microsoft Graph. Para solicitar propriedades adicionais, declare-as como qualquer parte do line(x)Property.

Propriedades

Você pode usar várias propriedades para personalizar o componente.

Atributo Propriedade Descrição
id do usuário userId Defina como uma ID do usuário para buscar os detalhes e a imagem desse usuário do Microsoft Graph.
consulta de pessoa personQuery Defina como um nome ou email de uma pessoa para procurar uma pessoa no Microsoft Graph e buscar os detalhes e a imagem da primeira pessoa.
detalhes da pessoa personDetails Defina como um objeto que representa uma pessoa. Funciona com objetos de pessoas, usuários, contatos ou grupo, recursos.
fallback-details fallbackDetails Defina como um objeto que representa uma pessoa quando nenhum usuário/pessoa/contato é encontrado no Microsoft Graph.
imagem de pessoa personImage Defina a imagem a ser exibida para a pessoa.
presença de pessoa personPresence Defina a presença da pessoa.
fetch-image fetchImage Defina o sinalizador para buscar personImage automaticamente do Microsoft Graph com base no personDetails objeto fornecido pelo usuário.
disable-image-fetch disableImageFetch Defina o sinalizador para desabilitar a busca de imagem de pessoa. Pode ser usado para evitar buscas desnecessárias do Microsoft Graph ao especificar personImage a propriedade.
tipo avatar avatarType Defina como initials ou photo para renderizar o estado de exibição – o padrão é a foto.
tamanho do avatar avatarSize Defina o tamanho do avatar como small, largeou auto, ajudando a determinar também o tamanho correto para o selo de presença. O valor padrão é auto. Se o view atributo for definido como threelines ou fourlines, avatar-size será tratado automaticamente como large, independentemente de seu valor real.
layout vertical verticalLayout Defina o layout do componente como vertical.
modo de exibição modo de exibição Defina para controlar como a pessoa é renderizada. O padrão é image.
image - mostrar apenas avatar
oneline - mostrar avatar e primeira linha (displayName por padrão)
twolines - mostrar avatar e duas linhas de texto (displayName e jobTitle por padrão)
threelines- mostrar avatar e três linhas de texto (displayNamee department por jobTitle padrão)
fourlines- mostrar avatar e quatro linhas de texto (displayName, jobTitlee emaildepartment por padrão)
No vertical-layout, exiba alterações.
twolines - mostrar avatar e duas linhas de texto (displayName e email por padrão)
threelines- mostrar avatar e três linhas de texto (displayName e departmentemail por padrão)
propriedade line1 line1Property Define a propriedade do personDetails a ser usada para a primeira linha de texto. O padrão é displayName.
propriedade line2 line2Property Define a propriedade do personDetails a ser usada para a segunda linha de texto. O padrão é jobTitle.
propriedade line3 line3Property Define a propriedade do personDetails a ser usada para a terceira linha de texto. O padrão é department.
propriedade line4 line4Property Define a propriedade da pessoaDetails a ser usada para a quarta linha de texto. O padrão é email.
show-presence showPresence Defina o sinalizador para exibir a presença da pessoa – o padrão é false.
Uso Uso Especifique onde o componente está sendo usado para adicionar personalização personalizada para ele. Atualmente, só dá people suporte conforme usado no componente pessoas.
person-cartão personCardInteraction Define o comportamento para mostrar a pessoa cartão no componente de pessoa renderizada. Os valores permitidos são none, hover ou click. O padrão é none.

Propriedades personalizadas do CSS

O mgt-person componente define as seguintes propriedades personalizadas do CSS.

<mgt-person class="person" person-query="me" view="fourlines" id="online" show-presence></mgt-person>

.person {
  --person-background-color: #616161;
  --person-background-border-radius: 30%;
  --person-avatar-size: 40px;
  --person-avatar-border: 3px solid yellow;
  --person-avatar-border-radius: 54%;
  --person-initials-text-color: white;
  --person-initials-background-color: blue;
  --person-line1-font-size: 32px;
  --person-line1-font-weight: 600;
  --person-line1-text-color: red;
  --person-line1-text-transform: capitalize;
  --person-line1-text-line-height: 20px;
  --person-line2-font-size: 28px;
  --person-line2-font-weight: 500;
  --person-line2-text-color: orange;
  --person-line2-text-transform: full-width;
  --person-line2-text-line-height: 16px;
  --person-line3-font-size: 24px;
  --person-line3-font-weight: 400;
  --person-line3-text-color: blue;
  --person-line3-text-transform: uppercase;
  --person-line3-text-line-height: 12px;
  --person-line4-font-size: 20px;
  --person-line4-font-weight: 300;
  --person-line4-text-color: green;
  --person-line4-text-transform: lowercase;
  --person-line4-text-line-height: 12px;
  --person-details-spacing: 30px;
}

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
line1clicked Disparada quando a linha1 é clicada O person objeto que pode ser um usuário, pessoa ou contato do Microsoft Graph com uma propriedade adicional personImage que contém a URL da foto do usuário. Não Não Sim, a menos que você substitua o modelo padrão.
line2clicked Disparada quando a linha2 é clicada O person objeto que pode ser um usuário, pessoa ou contato do Microsoft Graph com uma propriedade adicional personImage que contém a URL da foto do usuário. Não Não Sim, a menos que você substitua o modelo padrão.
line3clicked Disparada quando a linha3 é clicada O person objeto, que pode ser um usuário, pessoa ou contato do Microsoft Graph com uma propriedade adicional personImage que contém a URL da foto do usuário. Não Não Sim, a menos que você substitua o modelo padrão.
line4clicked Disparada quando a linha4 é clicada O person objeto, que pode ser um usuário, pessoa ou contato do Microsoft Graph com uma propriedade adicional personImage 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

O mgt-person componente dá suporte a vários modelos que permitem 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 seguintes valores:

Tipo de dados Contexto de dados Descrição
Carregar none O modelo a ser renderizado enquanto o componente está em um estado de carregamento.
sem dados none O modelo a ser renderizado quando nenhuma imagem ou dados de pessoa estiver disponível.
Padrão. pessoa: O objeto de detalhes da pessoa
personImage: a URL da imagem
personPresence: o objeto detalhes de presença para pessoa.		 O modelo padrão substitui todo o componente por seu próprio.
person-cartão pessoa: O objeto de detalhes da pessoa
personImage: a URL da imagem.		 O modelo para atualizar o mgt-person-cartão exibido no mouse ou clique.
line1 pessoa: O objeto de detalhes da pessoa O modelo para a primeira linha de metadados de pessoa.
line2 pessoa: O objeto de detalhes da pessoa O modelo para a segunda linha de metadados de pessoa.
line3 pessoa: O objeto de detalhes da pessoa O modelo para a terceira linha de metadados de pessoa.
line4 pessoa: O objeto de detalhes da pessoa O modelo da quarta linha de metadados de pessoa.

O exemplo a seguir define um modelo para o componente de pessoa.

<!-- Retemplate the entire person component -->
<mgt-person>
  <template>
    <div data-if="personImage">
      <img src="{{personImage}}" />
    </div>
    <div data-else>
      {{person.displayName}}
    </div>
  </template>
</mgt-person>

<!-- Retemplate the line properties -->
<mgt-person view="threeLines">
  <template data-type="line1">
    <div>
      Hello, my name is: {{person.displayName}}
    </div>
  </template>
  <template data-type="line2">
    <div>
      Super cool
    </div>
  </template>
  <template data-type="line3">
    <div>
      Loves MGT
    </div>
  </template>
</mgt-person>

<mgt-person view="fourLines">
  <template data-type="line1">
    <div>
      Hello, my name is: {{person.displayName}}
    </div>
  </template>
  <template data-type="line2">
    <div>
      Musician
    </div>
  </template>
  <template data-type="line3">
    <div>
      Calif records
    </div>
  </template>
  <template data-type="line4">
    <div>
      {{person.mail}}
    </div>
  </template>
</mgt-person>

<!-- Person-card template -->
<mgt-person person-query="me" view="twolines" person-card="hover">
	<template data-type="person-card">
		My custom person card experience
	</template>
</mgt-person>

Cartão pessoal

O mgt-person componente pode mostrar um mouse ou clique em um mgt-person-card mouse.

Adicionar o controle à página HTML

<mgt-person person-query="me" person-card="hover"></mgt-person>
Atributo Propriedade Descrição
person-cartão personCardInteraction Uma enumeração para determinar a ação do usuário necessária para ativar o painel de flyout – hover ou click. O valor padrão é none.

Para obter mais informações sobre templating, styling e atributos, consulte Componente cartão de pessoa.

Configuração de componente global

A MgtPerson classe expõe um objeto estático config que configura todos os componentes de pessoa no aplicativo.

O exemplo a seguir mostra como usar o objeto de configuração.

import { MgtPerson } from `@microsoft/mgt`;

MgtPerson.config.useContactApis = false;

As propriedades a seguir estão disponíveis no objeto config.

Propriedade Descrição
useContactApis boolean - Indica se o componente de pessoa pode usar a API de contatos pessoais do Microsoft Graph para pesquisar detalhes e fotos de contato. O valor padrão é true.

Permissões do Microsoft Graph

Esse controle usa as seguintes APIs e permissões do Microsoft Graph. Para cada API chamada, o usuário deve ter pelo menos uma das permissões listadas. Algumas configurações podem resultar em várias chamadas para o Microsoft Graph. Quando essas chamadas podem usar permissões diferentes, cada API e conjunto de permissões está em uma linha separada.

Configuração Permissão API
personDetailsdefinido sem imagem, fetchImage definido como , avatarType definido como true, a photopessoa recuperada é um contato e useContactApis definido comotrue Contacts.Read, Contacts.ReadWrite /me/contacts/*
personDetails definido sem imagem, fetchImage definido como true, avatarType definido como photo e pessoa não é um contato ou useContactApis está definido como false User.ReadBasic.All, User.Read.All, User.ReadWrite.All /users/{id}/photo/$value
personDetails definido sem imagem, fetchImage definido como true, avatarType definido como photo e usuário especificado por email User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All /users?$search=
personDetails definido sem imagem, fetchImage definido como true, avatarType definido como photo e usuário especificado por email User.ReadBasic.All, User.Read.All, User.ReadWrite.All /users/{id}/photo/$value
personDetails set without image, fetchImage set to true, avatarType set to photo and contact specified via email and useContactApis set to true Contacts.Read, Contacts.ReadWrite /me/contacts/*
personDetailsdefinir sem imagem para um grupo, fetchImage definido como , avatarType definido como truephoto Group.Read.All, Group.ReadWrite.All' /groups/${groupId}/photo/$value
userId Definir User.ReadBasic.All /users/{id}
userId definir ou personQuery definir como me e avatarType definir como photo e disableImageFetch é false User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All /users/{id}
userId definir ou personQuery definir como me e avatarType definir como photo e disableImageFetch é false User.ReadBasic.All, User.Read.All, User.ReadWrite.All users/${userId}/photo/*
userId definido como me e avatarType definido como photo e disableImageFetch é false User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All /Me
userId definido como me e avatarType definido como photo e disableImageFetch é false User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All /me/photo/$value
personQuery definido como me e avatarType definido como outra coisa do que photo User.Read, User.ReadWrite /Me
personQuery definido como um valor diferente me e avatarType definido como outra coisa do que photo People.Read, People.Read.All /me/people
personQuery definido como um valor diferente me e avatarType definido como outra coisa que photo e /me/people não retornou nenhum dado que corresponda ao fornecido personQuery User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All /user?$search=
personQuery definido como um valor diferente me e useContactApis definido como false Pessoas. Leitura, User.ReadBasic.All /me/people/?$search=, /users?$search=
showPresencedefinido como e personQuery definido como trueme Presence.Read /me/presence
showPresence definido como true e personQuery definido como um valor diferente de me Presence.Read.All /users/{id}/presence
personCardInteraction definido como um valor diferente de PersonCardInteraction.none Consulte permissões de cartão pessoa Consulte chamadas de API cartão pessoa

Subcomponentes

O mgt-person componente consiste em um ou mais subcomponentes que podem exigir outras permissões do que as listadas anteriormente. Para obter mais informações, consulte a documentação de cada subcomponente: mgt-person-cartão.

Autenticação

O controle usa o provedor de autenticação global descrito na documentação de autenticação para buscar os dados necessários.

Cache

Repositório de objetos Dados armazenados em cache Comentários
photos Foto da pessoa Usado quando avatarType é definido como photo e fetchImage é definido como true.
presence Presença da pessoa Usado quando showPresence é definido como true.
users Informações do usuário da pessoa.

Consulte Cache para obter mais detalhes sobre como configurar o 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
renderLoading Renderiza o estado de carregamento.
renderNoData Renderiza quando nenhum dado de imagem ou pessoa está disponível.
renderAvatar Renderiza o avatar.
renderDetails Renderiza a parte de detalhes da pessoa.

Localização

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

Nome da cadeia de caracteres Valor padrão
photoFor Photo for
emailAddress Email address