Microsoft Graph 工具包中的 Person-Card 组件

Person-Card 组件是一个响应组件,用于显示与人员相关的详细信息。 它用作组件上的 mgt-person 浮出控件。

有关组件 mgt-person 的详细信息,请参阅 mgt-person

使用 mgt-person 的示例

以下示例演示如何将 组件与 组件配合使用mgt-person-cardmgt-person。 将鼠标悬停或单击该人员以查看人员卡片。

使用 mgt-person-card 作为独立组件的示例

以下示例演示组件的用法 mgt-person-card 。 使用代码编辑器查看 属性 如何更改组件的行为。

全局组件配置

MgtPersonCardConfig 公开静态配置属性,用于在应用程序中配置所有人员卡片组件。 类配置人员卡片使用哪些部分和哪些 API 从 Microsoft Graph 中获取有关用户的详细信息。

默认情况下,所有节和 API 都处于启用状态。 以下示例演示如何使用类属性来禁用节或 API。

import { MgtPersonCardConfig } from '@microsoft/mgt-components';

MgtPersonCardConfig.useContactApis = false;
MgtPersonCardConfig.sections.profile = false;
MgtPersonCardConfig.sections.files = false;

以下属性可用。

属性 说明
useContactApis boolean - 指示人员卡片组件是否可以使用 Microsoft Graph 联系人 API 来搜索联系人详细信息和照片。 默认值为 true
sections object - 配置人员卡片中显示的部分。
isSendMessageVisible boolean - 指示发送消息按钮是否可见。 默认值为 true

人员卡片部分

人员卡片包含多个可配置部分,用于显示人员详细信息:

  • 联系人 - 联系人信息,例如电子邮件、电话、位置、位置等。
  • 组织 - 包含经理、直接下属和相关人员的组织图。
  • 邮件 - 具有当前登录用户的大多数相关电子邮件。
  • 文件 - 与当前登录用户相关的大多数共享文件。
  • 配置文件 - 配置文件信息,例如项目、技能、语言等。

默认情况下会加载节,但可以通过 对象属性全局 MgtPersonCardConfig.sections 禁用它们。 以下属性可用。

属性 说明
组织 boolean - 指示是否显示人员卡组织部分。 默认值为 true
mailMessages boolean - 指示是否显示人员卡片消息部分。 默认值为 true
files boolean - 指示是否显示人员卡片文件部分。 默认值为 true
profile boolean - 指示是否显示人员卡片配置文件部分。 默认值为 true
lock-tab-navigation boolean - 允许使用选项卡锁定导航,以便它不会流出卡片部分。 默认值为 false

若要禁用节,请在应用初始化代码中将 属性 false 设置为 :

import { MgtPersonCardConfig } from '@microsoft/mgt-components';

MgtPersonCardConfig.sections.profile = false;

Teams 集成设置

Person-Card 组件允许用户联系目标人员,包括通过 Teams 聊天。 如果在 Teams 选项卡应用中使用该组件,则可以确保组件直接深层链接到聊天,而不是通过在 中TeamsHelper设置 microsoftTeamsLib 来打开浏览器窗口。

如果 Person-Card 组件无法检测到 Teams 库,则组件将尝试改为打开 Teams Web 客户端。

import * as microsoftTeams from "@microsoft/teams-js";
import { TeamsHelper } from "@microsoft/mgt-element";

TeamsHelper.microsoftTeamsLib = microsoftTeams;

属性

默认情况下, mgt-person 组件会将人员详细信息传递给组件 mgt-person-card 。 但是,在模板化 mgt-person 组件或将组件用作独立组件时,可以使用这些属性对其进行 mgt-person-card 更改。

属性 类型 说明
person-details MicrosoftGraph.User
MicrosoftGraph.Person
MicrosoftGraph.Contact
由 Microsoft Graph 定义的 Person 对象,其中包含与用户相关的详细信息。
person-image String 与卡片中显示的人员相关的图像 URI。
inherit-details None 允许人员卡片浏览父树,以便 mgt-person 组件使用相同的 person-detailsperson-image 数据。
user-id String 允许开发人员提供用户 ID 来检索人员卡片组件上显示的数据
person-query String 允许开发人员提供人员查询来检索人员卡片组件上显示的数据
person-card String 指定在悬停或单击mgt-person组件时是否可以person-card将组件显示为弹出卡。 允许的值为 hoverclick

CSS 自定义属性

组件 mgt-person-card 定义以下 CSS 自定义属性。

<mgt-person-card class="person-card" person-query="me"></mgt-person-card>
.person-card {
  --person-card-nav-back-arrow-hover-color: green;
  --person-card-icon-color: red;
  --person-card-line1-font-size: 30px;
  --person-card-line1-font-weight: 800;
  --person-card-line1-line-height: 38px;
  --person-card-line2-font-size: 24px;
  --person-card-line2-font-weight: 600;
  --person-card-line2-line-height: 30px;
  --person-card-line3-font-size: 24px;
  --person-card-line3-font-weight: 300;
  --person-card-line3-line-height: 29px;
  --person-card-avatar-size: 85px;
  --person-card-details-left-spacing: 25px;
  --person-card-avatar-top-spacing: 25px;
  --person-card-details-bottom-spacing: 20px;
  --person-card-background-color: pink;
  --person-card-expanded-background-color-hover: blue;
  --person-card-icon-hover-color: magenta;
  --person-card-show-more-color: blue;
  --person-card-show-more-hover-color: green;
  --person-card-fluent-background-color: yellow;
  --person-card-line1-text-color: purple;
  --person-card-line2-text-color: blue;
  --person-card-line3-text-color: green;
  --person-card-fluent-background-color-hover: orange;
  --person-card-base-icons-left-spacing: 110px;

  /** person-card sections tokens */

  /** Organization */
  --organization-active-org-member-target-background-color: blue;
  --organization-title-color: green;
  --organization-sub-title-color: yellow;
  --organization-hover-color: grey;
  --organization-coworker-hover-color: grey;
  --organization-coworker-border-color: purple;
  --organization-active-org-member-border-color: red;
  --organization-coworker-person-avatar-size: 50px;
  --organization-member-person-avatar-size: 60px;
  --organization-direct-report-person-avatar-size: 80px;

  /** Style for the avatar-size in the person-card sections */
  --organization-member-person-avatar-size: 60px;
  --coworker-person-avatar-size: 50px;
  --direct-report-person-avatar-size: 40px;

  /** Files: Uses custom css properties for mgt-file-list and mgt-file */

  /** Messages */

  --message-subject-color: purple;
  --message-from-color: blue;
  --message-color: black;
  --message-hover-color: grey;
  --message-subject-font-size: 18px;
  --message-subject-font-weight: 600;
  --message-subject-line-height: 25px;
  --message-from-font-size: 40px;
  --message-from-font-weight: 800;
  --message-date-color: purple;
  --message-from-line-height: 25px;

  /** Contact */

  --contact-title-color: blue;
  --contact-value-color: green;
  --contact-link-color: red;
  --contact-link-hover-color: purple;
  --contact-background-color: grey;
  --contact-copy-icon-color: yellow;

  /** Profile */

  --profile-title-color: blue;
  --profile-background-color: grey;
  --profile-token-item-color: blue;
  --profile-token-overflow-color: purple;
  --profile-section-title-color: black;
  --profile-token-item-background-color: yellow;
}

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

模板

Person-Card 组件使用允许添加或替换组件部分的 模板 。 若要指定模板,请在组件中包含元素 <template> ,并将 设置为 data-type 以下值之一。

数据类型 数据上下文 说明
no-data 在没有可用数据时使用的模板。
违约 person:人员详细信息对象
personImage:图像的 URL
默认模板将整个组件替换为你自己的组件。
person-details person:人员详细信息对象 用于呈现人员卡片顶部的模板。
additional-details person:人员详细信息对象
personImage:图像的 URL
用于将自定义内容添加到其他详细信息容器的模板。

例如,可以使用模板自定义附加到 mgt-person 组件的组件,并使用模板向卡片添加其他详细信息。

<mgt-person person-query="me" view="twolines" person-card="hover">
  <template data-type="person-card">
    <mgt-person-card inherit-details>
      <template data-type="additional-details">
        <h3>Stuffed Animal Friends:</h3>
        <ul>
          <li>Giraffe</li>
          <li>lion</li>
          <li>Rabbit</li>
        </ul>
      </template>
    </mgt-person-card>
  </template>
</mgt-person>

事件

从 组件触发以下事件。

事件 何时发出 自定义数据 可取消 泡沫 使用自定义模板
expanded 用户打开了卡片的展开详细信息部分 None 是,除非重写默认模板

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

Microsoft Graph 权限

Person-Card 控件使用以下Microsoft Graph API 和权限。 对于每个调用的 API,用户必须至少具有列出的权限之一。

配置 权限 API
在所有配置中 User.Read、User.ReadWrite /我 默认值
personDetails 使用用户 id 设置,但没有电子邮件,或 userId 设置 User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All /users/{id} 默认值
personDetails 使用用户 id 设置,但没有电子邮件,或 userId 设置 User.ReadBasic.All、User.Read.All、User.ReadWrite.All /users/{id}/photo/$value 默认值
personQuery 设置为 me User.Read、User.ReadWrite、User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All /me/users/{id}/photo/$value 默认值
personQuery 设置为 me User.Read、User.ReadWrite、User.ReadBasic.All、User.Read.All、User.ReadWrite.All /me/photo/$value 默认值
personQuery 设置为不同于 me People.Read、People.Read.All /me/people/?$search= 默认值
personQuery 设置为与 不同的 me 值,并 config.useContactApis 设置为 true (默认) Contacts.Read、Contacts.ReadWrite /me/contacts/* 默认值
personQuery 将 设置为与 不同的 me 值,并将 config.useContactApis 设置为 false User.ReadBasic.All、User.Read.All、User.ReadWrite.All /users/{id}/photo/$value 默认值
showPresence 设置为 true Presence.Read.All /users/{id}/presence 默认值
sections.organization 已启用 (默认) User.ReadBasic.All、User.Read.All、Directory.Read.All、User.ReadWrite.All、Directory.ReadWrite.All /users/{id}?$expand=manager ($levels=max) /users/${id}/directReports 组织
sections.organization.showWorksWith 设置 (默认) People.Read.All /users/{id}/people 组织
sections.mailMessages 已启用 (默认) Mail.ReadBasic、Mail.Read、Mail.ReadWrite /me/messages 消息
sections.files 已启用 (默认) Sites.Read.All、Sites.ReadWrite.All /me/insights/shared/me/insights/used 文件
sections.profile 已启用 (默认) User.Read.All、User.ReadWrite.All /users/{id}/profile 配置文件

getMgtPersonCardScopes() 函数根据全局人员卡片配置返回人员卡片正常运行所需的范围数组。

import { getMgtPersonCardScopes } from `@microsoft/mgt-components`;

const neededScopes = getMgtPersonCardScopes();

子组件

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

身份验证

Person-Card 控件使用身份验证文档中所述的全局 身份验证提供程序。

缓存

重要

组件 mgt-person-card 从父 mgt-person 组件检索基本人员数据,而无需调用 Microsoft Graph。 单独使用 时 mgt-person-card ,它会检索必要的数据本身并对其进行缓存。 卡片部分中显示的数据是单独检索的,不会缓存。

对象存储 缓存的数据 备注
people 人员信息 personQuery 指定 且其值不同于 me
photos 人员的照片
presence 人员的状态 已使用,当 showPresence 设置为 true
users 人员的用户信息 在指定 或 personQuery 设置为 时userId使用me

有关如何配置缓存的详细信息,请参阅 缓存

本地化

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

字符串名称 默认值
endOfCard End of the card
quickMessage Send a quick message
expandDetailsLabel Expand details
renderOverviewSectionLabel Render overview section
sendMessageLabel Send message
emailButtonLabel Email
callButtonLabel Call
chatButtonLabel Chat
videoButtonLabel Video
closeCardLabel Close card

还可以在人员卡片部分中本地化以下变量。

联系人

字符串名称 默认值
contactSectionTitle Contact
emailTitle Email
chatTitle Teams
businessPhoneTitle Business Phone
cellPhoneTitle Mobile Phone
departmentTitle Department
personTitle Email
officeLocationTitle Office Location
copyToClipboardButton Copy to clipboard

文件

字符串名称 默认值
showMoreSubtitle Show more items
filesSectionTitle Files
sharedTextSubtitle Shared

消息

字符串名称 默认值
emailsSectionTitle Emails

组织

字符串名称 默认值
reportsToSectionTitle Reports to
directReportsSectionTitle Direct reports
organizationSectionTitle Organization
youWorkWithSubSectionTitle You work with
userWorksWithSubSectionTitle works with

配置文件

字符串名称 默认值
SkillsAndExperienceSectionTitle Skills & Experience
AboutCompactSectionTitle About
SkillsSubSectionTitle Skills
LanguagesSubSectionTitle Languages
WorkExperienceSubSectionTitle Work Experience
EducationSubSectionTitle Education
professionalInterestsSubSectionTitle Professional Interests
personalInterestsSubSectionTitle Personal Interests
birthdaySubSectionTitle Birthday
currentYearSubtitle Current
socialMediaSubSectionTitle Social Media