Componente person en Microsoft Graph Toolkit

Artículo
02/14/2024

El componente de persona se usa para mostrar una persona o contacto mediante su foto, nombre, dirección de correo electrónico o cualquier otro detalle de persona.

El componente person también usa la tarjeta mgt-person-card para mostrar una tarjeta flotante con información adicional sobre el usuario. Para obtener más información, consulte la sección Tarjeta de persona .

Ejemplo

En el ejemplo siguiente se muestra una persona que usa el mgt-person componente . Puede usar el editor de código para ver cómo cambian las propiedades el comportamiento del componente.

HTML
React

Abra este ejemplo en mgt.dev.

Establecimiento de los detalles de la persona

Puede usar tres propiedades para establecer los detalles de la persona. Use solo una de las siguientes propiedades por instancia:

Establezca el user-id atributo o userId la propiedad para capturar al usuario de Microsoft Graph mediante su identificador.
Establezca el person-query atributo o personQuery la propiedad para buscar en Microsoft Graph una persona determinada. Elegirá a la primera persona disponible y capturará los detalles de la persona. Un correo electrónico funciona mejor para asegurarse de que se consulta a la persona adecuada, pero un nombre también funciona.
Establezca el person-presence atributo o personPresence la propiedad para agregar manualmente un distintivo de presencia al avatar de la persona.
Establezca el avatar-size atributo o avatarSize la propiedad en small o large para determinar el tamaño del avatar. Esto ayuda a agregar el distintivo de presencia correcto a avatar. Tendrá que elegir las propiedades personalizadas css correspondientes correctas que se muestran a continuación para personalizar aún más el tamaño del avatar. De forma predeterminada, el valor se establece auto en el que decidirá automáticamente cómo representar la presencia en función de la view propiedad . Te recomendamos que uses small si tu avatar es menor que 32 px por 32 px.
Use el person-details atributo o personDetails la propiedad para establecer manualmente los detalles de la persona, como se muestra en el ejemplo siguiente.
```
let personControl = document.getElementById('myPersonControl');
personControl.personDetails = {
    displayName: 'Nikola Metulev',
    mail: 'nikola@contoso.com',
    personImage: 'url'
}
```
Si no se proporciona ninguna imagen, se capturará una (si está disponible).
De forma predeterminada, el componente de persona solo solicita el conjunto de propiedades de usuario estándar de Microsoft Graph. Para solicitar propiedades adicionales, declárelas como parte de line(x)Property.

Propiedades

Puede usar varias propiedades para personalizar el componente.

Atributo	Propiedad	Descripción
user-id	userId	Establezca en un identificador de usuario para capturar los detalles y la imagen de ese usuario de Microsoft Graph.
person-query	personQuery	Establezca en un nombre o correo electrónico de una persona para buscar una persona en Microsoft Graph y capturar los detalles y la imagen de la primera persona.
person-details	personDetails	Se establece en un objeto que representa a una persona. Funciona con objetos de los recursos de personas, usuarios, contactos o grupos.
fallback-details	fallbackDetails	Se establece en un objeto que representa a una persona cuando no se encuentra ningún usuario, persona o contacto en Microsoft Graph.
person-image	personImage	Establezca la imagen que se va a mostrar para la persona.
presencia de persona	personPresence	Establezca la presencia de la persona.
fetch-image	fetchImage	Establezca la marca para capturar `personImage` automáticamente desde Microsoft Graph en función del `personDetails` objeto proporcionado por el usuario.
disable-image-fetch	disableImageFetch	Establezca la marca para deshabilitar la captura de la imagen de persona. Se puede usar para evitar la captura innecesaria de Microsoft Graph al especificar la `personImage` propiedad .
tipo avatar	avatarType	`initials` Establézcalo en o `photo` para representar el estado de visualización: el valor predeterminado es foto.
tamaño de avatar	avatarSize	Establezca el tamaño del avatar en `small`, `large`o `auto`, lo que también ayuda a determinar el tamaño correcto para el distintivo de presencia. El valor predeterminado es `auto`. Si el `view` atributo se establece en `threelines` o `fourlines`, `avatar-size` se trata automáticamente como `large`, independientemente de su valor real.
diseño vertical	verticalLayout	Establezca el diseño del componente en vertical.
vista	vista	Establézcalo para controlar cómo se representa la persona. El valor predeterminado es `image`. `image` - mostrar solo avatar `oneline` - mostrar avatar y primera línea (`displayName` de forma predeterminada) `twolines` - mostrar avatar y dos líneas de texto (`displayName` y `jobTitle` de forma predeterminada) `threelines`- mostrar avatar y tres líneas de texto (`displayName`y `department` de `jobTitle` forma predeterminada) `fourlines` - mostrar avatar y cuatro líneas de texto (`displayName`, `jobTitle`y `departmentemail` de forma predeterminada) En `vertical-layout`, vea los cambios. `twolines` - mostrar avatar y dos líneas de texto (`displayName` y `email` de forma predeterminada) `threelines` - mostrar avatar y tres líneas de texto (`displayName` , `email` y `department` de forma predeterminada)
line1-property	line1Property	Establece la propiedad de personDetails que se va a usar para la primera línea de texto. El valor predeterminado es `displayName`.
line2-property	line2Property	Establece la propiedad de personDetails que se va a usar para la segunda línea de texto. El valor predeterminado es `jobTitle`.
line3-property	line3Property	Establece la propiedad de personDetails que se va a usar para la tercera línea de texto. El valor predeterminado es `department`.
line4-property	line4Property	Establece la propiedad de personDetails que se va a usar para la cuarta línea de texto. El valor predeterminado es `email`.
show-presence	showPresence	Establezca la marca para mostrar la presencia de la persona: el valor predeterminado es `false`.
Uso	Uso	Especifique dónde se usa el componente para agregar personalización personalizada. Actualmente solo admite `people` como se usa en el componente de personas.
person-card	personCardInteraction	Establece el comportamiento para mostrar la tarjeta de persona en el componente de persona representado. Los valores permitidos son `none`, `hover` o `click`. El valor predeterminado es `none`.

Propiedades personalizadas css

El mgt-person componente define las siguientes propiedades personalizadas 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 obtener más información, consulte Componentes de estilo.

Eventos

Los siguientes eventos se desencadenan desde el componente.

Evento	Cuándo se emite	Datos personalizados	Cancelable	Burbujas	Funciona con una plantilla personalizada
`line1clicked`	Se desencadena cuando se hace clic en la línea 1	Objeto `person` que puede ser un usuario, una persona o un contacto de Microsoft Graph con una propiedad adicional `personImage` que contiene la dirección URL de la foto del usuario.	No	No	Sí, a menos que invalide la plantilla predeterminada.
`line2clicked`	Se desencadena cuando se hace clic en la línea 2	Objeto `person` que puede ser un usuario, una persona o un contacto de Microsoft Graph con una propiedad adicional `personImage` que contiene la dirección URL de la foto del usuario.	No	No	Sí, a menos que invalide la plantilla predeterminada.
`line3clicked`	Se desencadena cuando se hace clic en la línea 3	Objeto `person` , que puede ser un usuario, una persona o un contacto de Microsoft Graph con una propiedad adicional `personImage` que contiene la dirección URL de la foto del usuario.	No	No	Sí, a menos que invalide la plantilla predeterminada.
`line4clicked`	Se desencadena cuando se hace clic en la línea 4	Objeto `person` , que puede ser un usuario, una persona o un contacto de Microsoft Graph con una propiedad adicional `personImage` que contiene la dirección URL de la foto del usuario.	No	No	Sí, a menos que invalide la plantilla predeterminada.

Para obtener más información sobre el control de eventos, vea eventos.

Plantillas

El mgt-person componente admite varias plantillas que permiten reemplazar ciertas partes del componente. Para especificar una plantilla, incluya un <template> elemento dentro de un componente y establezca en data-type uno de los siguientes valores:

Tipo de datos	Contexto de datos	Descripción
Carga	ninguno	Plantilla que se va a representar mientras el componente está en estado de carga.
sin datos	ninguno	Plantilla que se va a representar cuando no hay ninguna imagen de persona o datos disponibles.
Es el valor predeterminado.	person: objeto de detalles de la persona `personImage`: dirección URL de la imagen `personPresence`: objeto de detalles de presencia para persona.	La plantilla predeterminada reemplaza todo el componente por el suyo propio.
person-card	person: objeto de detalles de la persona `personImage`: dirección URL de la imagen.	Plantilla para actualizar la tarjeta mgt-person-card que se muestra al mantener el mouse o hacer clic.
Line1	person: objeto de detalles de la persona	Plantilla para la primera línea de metadatos de persona.
Line2	person: objeto de detalles de la persona	Plantilla de la segunda línea de metadatos de persona.
línea 3	person: objeto de detalles de la persona	Plantilla para la tercera línea de metadatos de persona.
línea 4	person: objeto de detalles de la persona	Plantilla para la cuarta línea de metadatos de persona.

En el ejemplo siguiente se define una plantilla para el componente de persona.

<!-- 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>

Tarjeta para personas

El mgt-person componente puede mostrar un mgt-person-card al mantener el puntero o hacer clic.

Agregar el control a la página HTML

<mgt-person person-query="me" person-card="hover"></mgt-person>

Atributo	Propiedad	Descripción
person-card	personCardInteraction	Enumeración para determinar la acción del usuario necesaria para activar el panel flotante o `hoverclick`. El valor predeterminado es `none`.

Para obtener más información sobre plantillas, estilos y atributos, vea Componente de tarjeta de persona.

Configuración global de componentes

La MgtPerson clase expone un objeto estático config que configura todos los componentes de persona de la aplicación.

En el ejemplo siguiente se muestra cómo usar el objeto config.

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

MgtPerson.config.useContactApis = false;

Las siguientes propiedades están disponibles en el objeto config.

Propiedad	Descripción
useContactApis	`boolean` - Indica si el componente de persona puede usar la API de contactos personales de Microsoft Graph para buscar detalles de contacto y fotos. El valor predeterminado es `true`.

Permisos de Microsoft Graph

Este control usa las siguientes API y permisos de Microsoft Graph. Para cada API llamada, el usuario debe tener al menos uno de los permisos enumerados. Algunas configuraciones pueden dar lugar a varias llamadas a Microsoft Graph. Cuando estas llamadas pueden usar permisos diferentes, cada API y conjunto de permisos se encuentra en una fila independiente.

Configuración	Permiso	API
`personDetails` establecido sin imagen, `fetchImage` establecido en `true`, `avatarType` establecido en `photo`, la persona recuperada es un contacto y `useContactApis` se establece en `true`	Contacts.Read, Contacts.ReadWrite	/me/contacts/*
`personDetails` establecido sin imagen, `fetchImage` establecido en `true`, `avatarType` establecido en `photo` y person no es un contacto o `useContactApis` está establecido en `false`	User.ReadBasic.All, User.Read.All, User.ReadWrite.All	/users/{id}/photo/$value
`personDetails` establecer sin imagen, `fetchImage` establecer en `true`, `avatarType` establecer en `photo` y el usuario especificado por correo electrónico	User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/users?$search=
`personDetails` establecer sin imagen, `fetchImage` establecer en `true`, `avatarType` establecer en `photo` y el usuario especificado por correo electrónico	User.ReadBasic.All, User.Read.All, User.ReadWrite.All	/users/{id}/photo/$value
`personDetails` establezca sin imagen, `fetchImage` establezca en `true`, `avatarType` establezca `photo` en y el contacto especificado por correo electrónico y `useContactApis` establezca en true.	Contacts.Read, Contacts.ReadWrite	/me/contacts/*
`personDetails` establecer sin imagen en un grupo, `fetchImage` establecer en `true`, `avatarType` establecer en `photo`	Group.Read.All, Group.ReadWrite.All'	/groups/${groupId}/photo/$value
`userId` Establecer	User.ReadBasic.All	/users/{id}
`userId` establecer o `personQuery` establecer `me` en y `avatarType` establecer en `photo` y `disableImageFetch` es `false`	User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/users/{id}
`userId` establecer o `personQuery` establecer `me` en y `avatarType` establecer en `photo` y `disableImageFetch` es `false`	User.ReadBasic.All, User.Read.All, User.ReadWrite.All	users/${userId}/photo/*
`userIdme` establecer en y `avatarType` establecer en `photo` y `disableImageFetch` es`false`	User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/me
`userIdme` establecer en y `avatarType` establecer en `photo` y `disableImageFetch` es`false`	User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All	/me/photo/$value
`personQueryme` establecer en y `avatarType` establecer en otra cosa que`photo`	User.Read, User.ReadWrite	/me
`personQuery` establecido en un valor distinto `me` de y `avatarType` establecido en otra cosa que `photo`	People.Read, People.Read.All	/me/people
`personQuery` establecido en un valor distinto `me` de y `avatarType` establecido en algo más que `photo` y `/me/people` no devolvió ningún dato que coincida con el proporcionado. `personQuery`	User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/user?$search=
`personQuery` establecido en un valor distinto `me` de y `useContactApis` establecido en `false`	Personas. Read, User.ReadBasic.All	/me/people/?$search=, /users?$search=
`showPresencetrue` establecer en y `personQuery` establecer en`me`	Presence.Read	/me/presence
`showPresencetrue` establecer en y `personQuery` establecer en un valor distinto de`me`	Presence.Read.All	/users/{id}/presence
`personCardInteraction` establecido en un valor distinto de `PersonCardInteraction.none`	Ver permisos de tarjeta de persona	Ver llamadas API de tarjeta de persona

Subcomponentes

El mgt-person componente consta de uno o varios subcomponentes que pueden requerir permisos distintos de los enumerados anteriormente. Para obtener más información, consulte la documentación de cada subcomponente: mgt-person-card.

Autenticación

El control usa el proveedor de autenticación global descrito en la documentación de autenticación para capturar los datos necesarios.

Caché

Almacén de objetos	Datos almacenados en caché	Comentarios
`photos`	Foto de la persona	Se usa cuando `avatarType` se establece en `photo` y `fetchImage` se establece en `true`.
`presence`	Presencia de la persona	Se usa cuando `showPresence` se establece en `true`.
`users`	Información de usuario de la persona.

Consulte Almacenamiento en caché para obtener más información sobre cómo configurar la memoria caché.

Ampliar para obtener más control

Para escenarios más complejos o una experiencia de usuario realmente personalizada, este componente expone varios protected render* métodos para invalidar en extensiones de componente.

Método	Descripción
renderLoading	Representa el estado de carga.
renderNoData	Se representa cuando no hay datos de imagen o de persona disponibles.
renderAvatar	Representa el avatar.
renderDetails	Representa la parte de detalles de la persona.

Localización

El control expone las siguientes variables que se pueden localizar. Para obtener más información sobre cómo configurar la localización, consulte Localización de componentes.

Nombre de cadena	Valor predeterminado
photoFor	`Photo for`
emailAddress	`Email address`