Microsoft Graph 工具包中的人员组件

  • 项目

人员组件用于显示人员或联系人的照片、姓名、电子邮件地址或任何其他人员详细信息。

person 组件还使用 mgt-person-卡显示浮出控件卡以及有关用户的其他信息。 有关详细信息，请参阅 人员卡片 部分。

示例

以下示例显示一个使用 mgt-person 组件的人员。 可以使用代码编辑器来查看 属性 如何更改组件的行为。

设置人员详细信息

可以使用三个属性来设置人员详细信息。 每个实例仅使用以下属性之一：

  • 设置 属性 user-id 或 userId 属性，以使用用户 ID 从 Microsoft Graph 提取用户。

  • 设置属性 person-query 或 personQuery 属性以在 Microsoft Graph 中搜索给定人员。 它将选择第一个可用人员并提取人员详细信息。 电子邮件最适用于确保查询正确的人员，但姓名也有效。

  • 设置 属性 person-presence 或 personPresence 属性以手动将状态锁屏提醒添加到个人头像。

  • 将 avatar-size 属性或 avatarSize 属性设置为 small 或 large ，以确定头像的大小。 这有助于向头像添加 正确的状态锁屏提醒 。 需要选择如下所示的正确相应 css 自定义属性，以进一步自定义头像大小。 默认情况下，值设置为 auto ，它将自动决定如何基于 view 属性呈现状态。 如果头像小于 32px x 32px，我们建议使用 small 。

  • person-details使用 属性或personDetails属性手动设置人员详细信息，如以下示例所示。

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

    如果未提供图像，则会 (提取一个映像（如果可用) ）。

  • 默认情况下，person 组件仅请求标准 Microsoft Graph 用户 的属性集。 若要请求其他属性，请将它们声明为 的任何 line(x)Property部分。

属性

可以使用多个属性来自定义组件。

属性 属性 说明
user-id userId 设置为用户 ID，以便从 Microsoft Graph 获取该用户的详细信息和图像。
person-query personQuery 设置为某人的姓名或电子邮件，以便在 Microsoft Graph 中搜索人员并提取第一个人的详细信息和图像。
person-details personDetails 设置为表示人员的 对象。 使用人员、用户、联系人或组资源中的对象。
fallback-details fallbackDetails 设置为在 Microsoft Graph 中找不到用户/人员/联系人时表示人员的 对象。
person-image personImage 设置要为人员显示的图像。
person-presence personPresence 设置人员的状态。
fetch-image fetchImage 将标志设置为基于personDetails用户提供的对象从 Microsoft Graph 自动提取personImage。
disable-image-fetch disableImageFetch 设置标志以禁用提取人员图像。 可用于避免在指定 personImage 属性时从 Microsoft Graph 提取不必要的数据。
avatar-type avatarType 设置为 initials 或 photo 以呈现其中一种显示状态 - 默认值为照片。
avatar-size avatarSize 将头像大小设置为 small、 large或 auto，有助于确定状态锁屏提醒的正确大小。 默认值为 auto。 如果属性 view 设置为 threelines 或 fourlines， avatar-size 则自动被视为 large，而不考虑其实际值。
vertical-layout verticalLayout 将组件布局设置为垂直。
view view 设置为控制人员的呈现方式。 默认值为“image”。
image - 仅显示头像
oneline - 默认显示头像和第一行 (displayName)
twolines - 显示头像和两行文本 (displayName ， jobTitle 默认情况下)
threelines - 显示头像和三行文本 (displayName， jobTitledepartment 默认情况下)
fourlines- 显示头像和四行文本 (displayName、 jobTitledepartment 和 email 默认情况下)
在 vertical-layout中，视图更改。
twolines - 显示头像和两行文本 (displayName ， email 默认情况下)
threelines - 显示头像和三行文本 (displayName ， emaildepartment 默认情况下)
line1-property line1Property 设置要用于第一行文本的 personDetails 的 属性。 默认值为“displayName”。
line2-property line2Property 设置要用于第二行文本的 personDetails 的 属性。 默认值为“jobTitle”。
line3-property line3Property 设置要用于第三行文本的 personDetails 的 属性。 默认值为“department”。
line4-property line4Property 设置要用于第四行文本的 personDetails 的 属性。 默认值为“email”。
show-presence showPresence 设置标志以显示人员状态 - 默认值为 false。
使用 使用 指定使用组件的位置，以便为其添加自定义个性化设置。 目前仅支持 people 在 people 组件中使用的 。
person-卡 personCardInteraction 设置行为以在呈现的人员组件上显示人员卡。 允许的值为 none、 hover 或 click。 默认值为“none”。

CSS 自定义属性

组件 mgt-person 定义以下 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;
}

若要了解详细信息，请参阅 设置组件样式。

事件

从 组件触发以下事件。

事件 何时发出 自定义数据 可取消 泡沫 使用自定义模板
line1clicked 单击 line1 时触发 对象 person ，可以是 Microsoft Graph 用户、 人员或 联系人 ，该对象具有包含用户照片 URL 的其他 personImage 属性。 否 否 是，除非重写默认模板。
line2clicked 单击 line2 时触发 对象 person ，可以是 Microsoft Graph 用户、 人员或 联系人 ，该对象具有包含用户照片 URL 的其他 personImage 属性。 否 否 是，除非重写默认模板。
line3clicked 单击 line3 时触发 对象 person ，可以是 Microsoft Graph 用户、 人员或 联系人 ，其附加 personImage 属性包含用户照片的 URL。 否 否 是，除非重写默认模板。
line4clicked 单击 line4 时触发 对象 person ，可以是 Microsoft Graph 用户、 人员或 联系人 ，其附加 personImage 属性包含用户照片的 URL。 否 否 是，除非重写默认模板。

有关处理事件的详细信息，请参阅 事件。

模板

组件 mgt-person 支持多个 模板 ，可用于替换组件的某些部分。 若要指定模板，请在组件中包含元素 <template> ，并将 设置为 data-type 以下值之一：

数据类型 数据上下文 说明
加载 无 组件处于加载状态时要呈现的模板。
no-data 无 在没有人员图像或数据可用时要呈现的模板。
默认 person：人员详细信息对象
personImage：图像的 URL
personPresence：人员的状态详细信息对象。		 默认模板将整个组件替换为你自己的组件。
person-卡 person：人员详细信息对象
personImage：图像的 URL。		 用于更新鼠标悬停或单击时显示的 mgt-person-卡的模板。
line1 person：人员详细信息对象 第一行人员元数据的模板。
line2 person：人员详细信息对象 第二行人员元数据的模板。
line3 person：人员详细信息对象 第三行人员元数据的模板。
line4 person：人员详细信息对象 第四行人员元数据的模板。

以下示例定义 person 组件的模板。

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

个人卡片

组件 mgt-person 可以在悬停或单击时显示 mgt-person-card 。

将控件添加到 HTML 页

<mgt-person person-query="me" person-card="hover"></mgt-person>
属性 属性 说明
person-卡 personCardInteraction 一个枚举，用于确定激活浮出控件面板所需的用户操作 - hover 或 click。 默认值为 none。

有关模板化、样式设置和属性的详细信息，请参阅 人员卡片组件。

全局组件配置

类 MgtPerson 公开一个静态 config 对象，该对象配置应用程序中的所有人员组件。

以下示例演示如何使用 config 对象。

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

MgtPerson.config.useContactApis = false;

以下属性可用于 config 对象。

属性 说明
useContactApis boolean - 指示人员组件是否可以使用 Microsoft Graph 个人联系人 API 搜索联系人详细信息和照片。 默认值为 true。

Microsoft Graph 权限

此控件使用以下 Microsoft Graph API 和权限。 对于每个调用的 API，用户必须至少具有列出的权限之一。 某些配置可能会导致多次调用 Microsoft Graph。 当这些调用可以使用不同的权限时，每个 API 和权限集都位于单独的行中。

配置 权限 API
personDetails 不带图像， fetchImage 设置为 true， avatarType 设置为 photo，检索到的人员是联系人，并 useContactApis 设置为 true Contacts.Read、Contacts.ReadWrite /me/contacts/*
personDetails 设置为 不带图像， fetchImage 设置为 true， avatarType 设置为 photo ，并且人员不是联系人或 useContactApis 设置为 false User.ReadBasic.All、User.Read.All、User.ReadWrite.All /users/{id}/photo/$value
personDetails 设置为 不带图像， fetchImage 设置为 true， avatarType 并 photo 通过电子邮件指定用户 User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All /users？$search=
personDetails 设置为 不带图像， fetchImage 设置为 true， avatarType 并 photo 通过电子邮件指定用户 User.ReadBasic.All、User.Read.All、User.ReadWrite.All /users/{id}/photo/$value
personDetails 不带图像， fetchImage 设置为 true， avatarType 设置为 photo 并通过电子邮件指定的联系人，并 useContactApis 设置为 true Contacts.Read、Contacts.ReadWrite /me/contacts/*
personDetails 将不带图像的设置为组， fetchImage 设置为 true， avatarType 设置为 photo Group.Read.All、Group.ReadWrite.All' /groups/${groupId}/photo/$value
userId 设置 User.ReadBasic.All /users/{id}
userId将 或 personQuery 设置为 me ，并avatarType设置为 photo 和disableImageFetchfalse User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All /users/{id}
userId将 或 personQuery 设置为 me ，并avatarType设置为 photo 和disableImageFetchfalse User.ReadBasic.All、User.Read.All、User.ReadWrite.All users/${userId}/photo/*
userIdme设置为 ，并将 avatarTypephoto 设置为 ，并且disableImageFetchfalse User.Read、User.ReadWrite、User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All /我
userIdme设置为 ，并将 avatarTypephoto 设置为 ，并且disableImageFetchfalse User.Read、User.ReadWrite、User.ReadBasic.All、User.Read.All、User.ReadWrite.All /me/photo/$value
personQuery 将 设置为 me ，并 avatarType 设置为其他内容，而不是 photo User.Read、User.ReadWrite /我
personQuery 设置为一个值，而不是 me ，并 avatarType 设置为除 photo People.Read、People.Read.All /me/people
personQuery 设置为除 me 以外的值，并 avatarType 设置为其他 photo 值，并且 /me/people 未返回与提供的 匹配的数据 personQuery User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All /user？$search=
personQuery 设置为一个值，而不是 me ，并 useContactApis 设置为 false 人员。Read、User.ReadBasic.All /me/people/？$search=， /users？$search=
showPresencetrue设置为 ，并将 personQuery 设置为me Presence.Read /me/presence
showPresence 将 设置为 true ，并 personQuery 设置为非值 me Presence.Read.All /users/{id}/presence
personCardInteraction 设置为一个值，而不是 PersonCardInteraction.none 查看人员卡权限 查看人员卡 API 调用

子组件

组件 mgt-person 由一个或多个子组件组成，这些子组件可能需要除前面列出的权限以外的其他权限。 有关详细信息，请参阅每个子组件的文档：mgt-person-卡。

身份验证

控件使用 身份验证文档中 所述的全局身份验证提供程序来提取所需的数据。

缓存

对象存储 缓存的数据 备注
photos 人员的照片 在 设置为 photo 且fetchImagetrue设置为 时avatarType使用。
presence 人员的状态 在 设置为 true时showPresence使用。
users 人员的用户信息。

有关如何配置 缓存 的更多详细信息，请参阅缓存。

扩展以获得更多控制

对于更复杂的方案或真正自定义的 UX，此组件公开了组件扩展中的多种 protected render* 替代方法。

方法 说明
renderLoading 呈现加载状态。
renderNoData 在没有图像或人员数据可用时呈现。
renderAvatar 呈现头像。
renderDetails 呈现人员详细信息部分。

本地化

控件公开以下可本地化的变量。 有关如何设置本地化的详细信息，请参阅 本地化组件。

字符串名称 默认值
photoFor Photo for
emailAddress Email address