练习–使用 Web 部件属性窗格

  • 15 分钟

在本练习中，你将使用控件、组、页面操作 SharePoint 框架客户端 Web 部件的属性窗格。

先决条件

重要

在大多数情况下，安装以下工具的最新版本是最佳选择。 此模块在发布和最后测试过程中，使用了此处列出的版本。

新建 SharePoint 框架解决方案和 Web 部件

运行以下命令，以运行 SharePoint 框架 Yeoman 生成器：

yo @microsoft/sharepoint

使用以下内容完成显示的提示（如果显示多个选项，请接受默认答案）：

  • 解决方案的名称是什么？：HelloPropertyPane
  • 要创建哪种类型的客户端组件？： WebPart
  • Web 部件的名称是什么？：HelloPropertyPane
  • 要使用哪个模板？： 无框架

预配项目所需的文件夹后，生成器将通过 NPM 来安装所有依赖项包。

npm 完成下载所有依赖项后，请执行以下命令，确保已安装开发人员证书：

gulp trust-dev-cert

接下来，请确认一切正常。

在 Visual Studio Code 中打开项目。

找到并打开文件 config/serve.json

在 serve.json 文件中，找到 initialPage 设置。 它当前配置有占位符 URL。

"initialPage": "https://{tenantDomain}/_layouts/workbench.aspx",

字符串 {tenantDomain} 将自动由 gulp 服务 任务使用工作站上的环境变量替换。 将环境变量 SPFX_SERVE_TENANT_DOMAIN 设置为要用于测试的托管 SharePoint Online 网站的域。

提示

详细了解如何在所选的开发平台上设置环境变量：

Windows：) macOS 设置 (环境变量：在 Mac 上的终端中使用环境变量设置SharePoint 框架 Hosted Workbench 测试站点

使用提供的 gulp 服务 任务在不使用 nobrowser 切换的情况下启动本地 Web 服务器。 这将生成项目、启动本地 Web 服务器，并在 serve.json 与环境变量一起配置的 URL 处加载托管的工作台。

gulp serve

如果在托管的工作台中看到警告对话框，请切换回命令提示符，等待 reload 子任务执行完成，然后刷新托管的工作台。

gulp 服务警告的屏幕截图。

选择“添加新 Web 部件”图标：

SharePoint Workbench 的屏幕截图。

选择“HelloPropertyPane”Web 部件以将 Web 部件添加到页面：

SharePoint Workbench 中 HelloPropertyPane Web 部件的屏幕截图。

你可以通过选择 Web 部件左侧工具栏中的铅笔（编辑）图标来访问 Web 部件属性窗格：

HelloPropertyPane 的属性窗格的屏幕截图。

向 Web 部件添加新属性

有了正常运作的 web 部件，下一步是自定义属性窗格体验。 创建将在 web 部件和属性窗格中使用的两个新属性。

打开 .\src\webparts\helloPropertyPane\HelloPropertyPaneWebPart.ts 文件。 找到 import 语句后面的接口 IHelloPropertyPaneWebPartProps。 向接口添加以下两个属性：

myContinent: string;
numContinentsVisited: number;

更新 Web 部件呈现以显示这两个属性的值。 在 HelloPropertyPaneWebPart 类中，找到 render() 方法并在 HTML 输出中找到以下行：

<div>Web part property value: <strong>${escape(this.properties.description)}</strong></div>

在找到的行之后添加以下两行：

<div>Continent where I reside: <strong>${escape(this.properties.myContinent)}</strong></div>
<div>Number of continents I've visited: <strong>${this.properties.numContinentsVisited}</strong></div>

请等待几秒钟以重新生成项目，然后刷新托管的工作台。 Web 部件将为这两个属性呈现空白字符串和未定义，因为它们都未分配值：

不带值的 HelloPropertyPane 的屏幕截图。

这可以通过在将 Web 部件添加到页面时设置属性的默认值来解决。 打开 .\src\webparts\helloPropertyPane\HelloPropertyPaneWebPart.manifest.json 文件。

在文件中找到以下部分：preconfiguredEntries[0].properties.description 在 description 属性值后添加逗号，并在 description 属性后添加以下两行：

"myContinent": "North America",
"numContinentsVisited": 4

提示

在重启本地 Web 服务器之前，对清单和配置文件所做的更改不会反映在工作台中。

关闭包含托管工作台的浏览器标签页，并通过在命令提示符中按 CTRL+C 来停止本地 Web 服务器。 执行 gulp serve 命令重建并重新启动本地 Web 服务器。 加载托管的工作台时，将 Web 部件添加回页面以查看属性。

包含值的 HelloPropertyPane 的屏幕截图。

扩展属性窗格

现在 Web 部件有了两个新自定义属性，下一步便是扩展属性窗格以允许用户编辑这些值。

向属性窗格添加连接到 myContinent 属性的新文本控件。 打开 .\src\webparts\helloPropertyPane\HelloPropertyPaneWebPart.ts 文件。 找到方法 getPropertyPaneConfiguration()，并在其中找到 groupFields 数组。 在现有 PropertyPaneTextField() 之后添加逗号，并添加以下代码以添加第二个文本字段控件：

PropertyPaneTextField('myContinent', {
  label: 'Continent where I currently reside'
})

如果本地 Web 服务器未运行，请执行 gulp serve 以启动它。 SharePoint Workbench 再次运行后，将 Web 部件添加到页面并打开属性窗格。 请注意，你可以在属性窗格中看到属性和文本框。 对该字段的任何编辑都将自动更新 Web 部件：

HelloPropertyPane 的屏幕截图，其中包含新的文本字段。

接下来，向属性窗格添加连接到 numContinentsVisited 属性的滑块控件。 在 HelloPropertyPaneWebPart.ts 的文件顶部，添加对 import 包的现有 PropertyPaneSlider 语句的 @microsoft/sp-property-pane 引用。

向下滚动到方法 getPropertyPaneConfiguration() 并在其中找到 groupFields 数组。

在最后一次 PropertyPaneTextField() 调用后添加逗号，并添加以下代码：

PropertyPaneSlider('numContinentsVisited', {
  label: 'Number of continents I\'ve visited',
  min: 1, max: 7, showValue: true,
})

请注意，属性窗格现在有滑块控件来控制造访过的大陆数：

HelloPropertyPane 的屏幕截图，其中包含新的滑块字段。

添加控件控制

在上一步中，用户获得了可以在其中输入其所居住的大陆名称的属性。 现在添加验证逻辑以确保输入有效的大陆名称。

在 HelloPropertyPaneWebPart.ts 中，向 HelloPropertyPaneWebPart 类添加以下方法。 此方法将字符串作为输入并返回字符串。 这允许执行自定义验证逻辑。 如果此方法返回空字符串，则视该值有效；否则，返回的字符串将用作错误消息。

private validateContinents(textboxValue: string): string {
  const validContinentOptions: string[] = ['africa', 'antarctica', 'asia', 'australia', 'europe', 'north america', 'south america'];
  const inputToValidate: string = textboxValue.toLowerCase();

  return (validContinentOptions.indexOf(inputToValidate) === -1)
    ? 'Invalid continent entry; valid options are "Africa", "Antarctica", "Asia", "Australia", "Europe", "North America", and "South America"'
    : '';
}

现在可以将验证方法连接到先前添加的文本字段控件。 找到与 myContinent 属性关联的文本字段。

将以下代码添加到作为第二个参数传递到 PropertyPaneTextField() 调用的选项对象中：onGetErrorMessage: this.validateContinents.bind(this)。 文本字段控件现在应与以下代码相似：

PropertyPaneTextField('myContinent', {
  label: 'Continent where I currently reside',
  onGetErrorMessage: this.validateContinents.bind(this)
}),

如果本地 Web 服务器未运行，请执行 gulp serve 以启动它。 SharePoint Workbench 再次运行后，将 Web 部件添加到页面并打开属性窗格。 输入不存在的大陆名称以测试验证逻辑：

应用了验证逻辑的 HelloPropertyPane 的屏幕截图。

注意，当控件的输入无效时，属性值不会更新。

摘要

在本练习中，你已使用控件、组、页面操作 SharePoint 框架客户端 Web 部件的属性窗格。