练习 - 使用 Web 部件扩展 Viva Connections 桌面

13 分钟

在本练习中，你将生成一个从 SharePoint 列表获取数据的 SharePoint 框架 Web 部件。然后，将 Web 部件添加到 Viva Connections 桌面。

创建新的解决方案

若要开始，请使用 SharePoint 框架 Yeoman 生成器创建解决方案:

为项目创建名为 spfx-company-announcements-webpart 的文件夹。
在终端中，将工作目录更改为 spfx-company-announcements-webpart。
运行 yo @microsoft/sharepoint 命令以开始搭建新解决方案的基架。

回答生成器的提示：

Prompt	条目
解决方案名称是什么?	spfx-company-announcements-webpart
仅支持 SharePoint Online（最新版）。对于早期版本的 SharePoint（2016 和 2019），请使用 1.12.1 版本的生成器。	仅 SharePoint Online（最新）
要将文件存放在哪里?	使用当前文件夹
是否要允许租户管理员选择能够立即将解决方案部署到所有站点的选项，而无需运行任何站点中的部署或添加应用程序功能?	否
解决方案中的组件是否需要访问唯一且不与租户中的其他组件共享的 Web API 的权限？	否
要创建哪种类型的客户端组件?	WebPart
Web 部件名称是什么?	公司公告
Web 部件说明是什么?	显示公司公告
要使用哪种框架?	没有 JavaScript 框架

等待项目创建完成。可能需要几分钟时间。

提示

在等待时，你可能会看到一些警告。可以放心地忽略它们。

安装开发证书

SharePoint 框架使用 SharePoint Online 中托管的工作台，你可以在将代码部署到 Viva Connections 之前对其进行测试。测试代码时，使用 Gulp 启动本地 Web 服务器。然后，SharePoint 框架工作台从本地服务器加载文件，以便你可以对其进行测试。

若要让 workbench 从本地开发服务器加载文件，请使用以下过程信任 SharePoint 框架中的开发证书。

重要

在计算机上安装一次开发证书。创建新项目时，SharePoint 框架将使用以前安装的证书。如果已执行此操作，则可以跳过这些步骤。

打开终端。
将工作目录更改为项目文件夹。
运行 gulp trust-dev-cert 命令。
按照屏幕上的说明完成证书安装。

编辑 Web 部件。

创建项目后，下一步是扩展 Web 部件，以便其从列表中加载公司公告并在页面上显示:

在代码编辑器中打开项目。
在代码编辑器中，打开 ./src/webparts/companyAnnouncements/CompanyAnnouncementsWebPart.ts 文件。
在文件的顶端部分，添加 import { SPHttpClient } from '@microsoft/sp-http';。
清除 render 方法的内容。
在 render 方法中，添加以下代码块：
```
this.context.spHttpClient
  .get(`${this.context.pageContext.web.absoluteUrl}/_api/web/lists/getByTitle('Announcements')/items?$select=Title,Description,Important`,
    SPHttpClient.configurations.v1,
    {
      headers: {
        'accept': 'application/json;odata.metadata=none'
      }
    })
  .then(response => response.json())
  .then(announcements => {
    // todo: display results
  })
  .catch(error => this.context.statusRenderer.renderError(this.domElement, error));
```
使用 spHttpClient 从以前创建的公告列表中检索公告列表。 spHttpClient封装该标准fetch API，并通过身份验证来调用 SharePoint API。

在 API URL 中，使用 OData $select 参数来指定要检索的属性列表。这些属性与公告列表中的列相匹配。

在调用 SharePoint API 时，还可设置 accept 标头来抑制响应中的元数据。它允许你最大程度地减少通过网络发送的数据量。

从 API 收到响应后，检索其 JSON 响应。如果调用 API 时出错，它将通过使用 Web 部件公开的帮助程序方法将其显示在 Web 部件的内容区域中。
从列表中检索公告后，下一步是在 Web 部件中显示它们。在最后一个 then 子句中，将 // todo: display results 注释替换为以下块：
```
const announcementsHtml = announcements.value.map(announcement =>
  `<dt${announcement.Important ?
    ` class="${styles.important}"` : ''}>${announcement.Title}</dt>
  <dd>${announcement.Description}</dd>`);

this.domElement.innerHTML = `
<div class="${styles.companyAnnouncements}">
  <div class="${styles.container}">
    <div class="${styles.title}">Announcements</div>
    <dl>
      ${announcementsHtml.join('')}
    </dl>
  </div>
</div>
`;
```
announcement 变量包含持有列表中的公告数组的 value 属性。对于每个公告，都创建一个 HTML 字符串，其中带有包含公告内容的 dt 和 dd 元素。接下来，将公告合并为单个 HTML 字符串，并将其显示在 Web 部件的 DOM 元素中。

提示

如果可能，应始终使用语义 HTML，而不是泛型 div 和 span 元素。使用语义 HTML，如标题 (h1-h6) 或定义列表 (dl)，有助于使用屏幕阅读器和其他辅助功能工具的用户可以更轻松地关注页面内容。
若要保存更改，请选择文件>保存或在键盘上选择 Ctrl+S (macOS 上的 CMD+S)。

设置 Web 部件内容的样式

要在 Web 部件中显示公告，请使用标准 dl、dt 和 dd HTML 元素。还包含名为 important 的自定义 CSS 类，以突出显示重要公告。现在添加 CSS 样式来格式化公告和重要公告的显示方式:

在代码编辑器中，打开 ./src/webparts/companyAnnouncements/CompanyAnnouncementsWebPart.module.scss 文件。
将文件内容替换为以下代码：
```
@import '~@microsoft/sp-office-ui-fabric-core/dist/sass/SPFabricCore.scss';

.companyAnnouncements {
  .container {
    @include ms-Grid;
    color: var(--primaryText, #323130);
  }

  .title {
    @include ms-fontSize-18;
    @include ms-fontWeight-semibold;
  }

  dt {
    @include ms-fontWeight-bold;
    @include ms-fontSize-14;
    margin-top: 1rem;

    &.important {
      color: $ms-color-red;
    }
  }

  dd {
    margin-left: 0;
  }
}
```
首先导入 Fluent UI，以确保与 Microsoft 365 样式一致。接下来，为 Web 部件的标题添加 CSS 类。在类中，引用 Fluent UI 中的字体定义。然后，为用于显示公告的 dt 和 dd 元素定义样式。

就像你对 Web 部件的标题所做的一样，你引用 Fluent UI 样式以确保一致性。要突出显示重要公告，请定义一个名为 important 的额外类，该类使用 Fluent UI 中定义的红色文本。
若要保存更改，请选择文件>保存或在键盘上选择 Ctrl+S (macOS 上的 CMD+S)。

测试 Web 部件。

为公司公告创建和预览 Web 部分:

在终端中，运行 gulp serve --nobrowser 命令。此命令将在 https://localhost:4321 上启动本地 Web 服务器。

警告

如果在终端中看到以下警告，则表示本地 Web 服务器无法加载开发证书：

警告 - [spfx-serve] 在 HTTPS 模式下提供服务时，必须提供 PFX 证书路径或证书路径和密钥路径，或者必须生成并信任开发证书。如果未提供 SSL 证书，将使用默认的自签名证书。需要浏览器安全警告。

若要解决此问题，请通过选择 Ctrl+C 并运行 gulp trust-dev-cert 命令来停止 Web 服务器。
在 Web 浏览器中，转到位于 <Home site url>/_layouts/workbench.aspx 的工作台。主站点 URL 是在上一练习中创建公告列表的位置。

警告

在打开工作台后，如果看到以下错误，这意味着本地 Web 服务器无法加载你的开发证书:

Web 部件不会显示在工具箱中。请确保“gulp service”在 Web 部件项目中运行。运行“gulp service”后，请刷新页面。

若要解决此问题，请通过选择 Ctrl+C 并运行 gulp trust-dev-cert 命令来停止 Web 服务器。
若要将新创建的 Web 部件添加到画布，请选择 + (加号) 按钮以打开工具箱。
在搜索栏上，键入 公司公告 并选择 Web 部件。

如果已成功执行所有步骤，将在工作台中显示的公告列表中看到你的公告。

选择为重要公告的标题显示为红色。
若要停止开发 Web 服务器，请返回到终端并选择 Ctrl+C。

将 Web 部件部署到 Viva Connections

已通过使用 SharePoint 框架建立 公司公告 web 部分。现在可以将其部署到 Viva Connections。

通过使用 Gulp 将 Web 部分打包成一个应用程序:

。转到工作目录是项目根文件夹的终端。
若要在发布模式下生成解决方案，请运行 gulp bundle --ship 命令。
若要制作解决方案的发布模式程序包，请运行 gulp package-solution --ship 命令。

package-solution 任务在 ./sharepoint/solution 文件夹中创建了名为 spfx-company-announcements-webpart.sppkg 的应用包文件。此文件就是你的应用包。接下来，将此包部署到 SharePoint 应用程序目录中，其中包含所有 Viva Connections 扩展。

如果租户中没有应用目录，请立即创建:

在 Web 浏览器中，转到 Microsoft 365 管理中心。
在侧边菜单中，选择显示所有。
从 管理中心 列表中，选择 SharePoint。
在 SharePoint 管理中心，从侧边菜单中，选择" 更多功能"。
在"应用"部分中，选择"打开"按钮，转到"应用管理"页。
在应用下，选择 应用目录。
如果网站打开，则你已有一个应用目录，可以跳过进一步的步骤。

如果应用目录不存在，系统会提示你创建一个。
从选项列表中，选择 “自动创建新的应用目录网站”，然后选择“确定”。

将应用程序部署到目录，请执行以下操作:

在 Web 浏览器中，转到 SharePoint 应用程序目录。
在目录的侧边菜单中，选择 SharePoint 应用。
将 spfx-company-announcements-webpart.sppkg 文件拖入列表。
SharePoint 要求你确认并部署包。选择部署，使包可用于在 SharePoint 网站上安装。

在应用目录中成功部署应用后，需要将其安装在主站点上:

在 Web 浏览器中，转到主站点。
从顶部菜单中，选择设置（齿轮）图标。
从 SharePoint 部分中选择“添加应用”链接。
在 我的应用 页面的搜索框中，键入公司并找到spfx-company-announcements-webpart-client-side-solution 应用。
选择“添加”按钮。

现在可以将 公司公告 Web 部件添加到网站上的任何 SharePoint 页面。若要在主站点的主页上添加 web 部分:

在 Web 浏览器中，转到主站点。
为确保在主页上，请从顶部菜单中选择 “主页”。
若要编辑页面，请从页面菜单中选择 “编辑”。
在将在其中放置 Web 部件的页面内选择一个区域。
选择 + 按钮以打开工具箱。
搜索 公司公告 Web 部件。
选择网页部分，将其添加到页面。
从页面菜单中，选择 “重新发布”.。

现在，公司公告 Web 部件位于主站点的主页上。测试应用，了解此 Web 部件在 Microsoft Teams 中的 Viva Connections 中的外观：

打开 Microsoft Teams 桌面客户端，或在 Web 浏览器中转到 Teams 站点。
打开 Viva 连接应用并确认 公司公告 Web 部件在主网站的主页上显示所有公告。

继续