将自定义对话框与 SharePoint 框架扩展结合使用

项目
03/21/2023

可以在 SharePoint 框架扩展或客户端 Web 部件的上下文中使用从 @microsoft/sp-dialog 包中获取的自定义对话框。

本文介绍如何创建自定义对话框并在 ListView 命令集扩展的上下文中使用它。

可以在 sp-dev-fx-extensions 存储库中访问本文所依据的示例代码。

重要

本教程假定你已按照设置开发环境中的说明设置开发环境。

新建项目

为项目创建新的项目目录，将当前文件夹更改为该目录。
通过从你创建的新目录中运行 Yeoman SharePoint 生成器来创建新项目：
```
yo @microsoft/sharepoint
```
出现提示时，请输入以下值(为下面省略的所有提示选择默认选项):
- 要创建哪种类型的客户端组件? 扩展名
- 要创建哪种类型的客户端扩展？ 列表视图命令集
- 命令集名称是什么？ DialogDemo
此时，Yeoman 安装必需的依赖项，并为解决方案文件搭建基架。此过程可能需要几分钟时间。
完成初始基架后，输入以下内容，将 Office UI Fabric 安装到解决方案：
```
npm install office-ui-fabric-react  --save
```
在代码编辑器中，打开项目文件夹。本文的步骤和屏幕截图中使用 Visual Studio Code，但你可以使用你喜欢的任何编辑器。若要在 Visual Studio Code 中打开文件夹，请使用控制台中的以下命令：
```
code .
```

修改扩展清单

在扩展清单中，将扩展配置为只有一个按钮。在代码编辑器中，打开 ./src/extensions/dialogDemo/DialogDemoCommandSet.manifest.json 文件。将命令部分替换为以下 JSON：

{
  //...
  "items": {
    "COMMAND_1": {
      "title": { "default": "Open Custom Dialog" },
      "iconImageUrl": "icons/request.png",
      "type": "command"
    }
  }
}

创建自定义对话框

在 ./src/extensions/dialogDemo/ 文件夹中，创建一个名为 ColorPickerDialog.tsx 的新文件。

在新建的文件顶部添加下面的导入语句。正在通过使用 Office UI Fabric React 组件创建你的自定义对话框，所以是在 React 中执行。

import * as React from 'react';
import * as ReactDOM from 'react-dom';
import { BaseDialog, IDialogConfiguration } from '@microsoft/sp-dialog';
import { PrimaryButton, DefaultButton } from 'office-ui-fabric-react/lib/Button';
import { ColorPicker } from 'office-ui-fabric-react/lib/ColorPicker';
import { DialogFooter, DialogContent } from 'office-ui-fabric-react/lib/Dialog';
import { IColor } from 'office-ui-fabric-react/lib/Color';

在导入语句正下方添加下列接口定义。它用于在 ListView 命令集扩展和自定义对话框之间传递信息和功能。

interface IColorPickerDialogContentProps {
  message: string;
  close: () => void;
  submit: (color: IColor) => void;
  defaultColor?: IColor;
}

在接口定义正下方添加以下类。此 React 类负责呈现自定义对话框内的 UI 体验。请注意，你将 Office UI Fabric React 组件用于实际呈现，并且仅传递属性。

class ColorPickerDialogContent extends React.Component<IColorPickerDialogContentProps, {}> {
  private _pickedColor: IColor;

  constructor(props) {
    super(props);
    // Default Color
    this._pickedColor = props.defaultColor || { hex: 'FFFFFF', str: '', r: null, g: null, b: null, h: null, s: null, v: null };
  }

  public render(): JSX.Element {
    return <DialogContent
    title='Color Picker'
    subText={this.props.message}
    onDismiss={this.props.close}
    showCloseButton={true}
    >
    <ColorPicker color={this._pickedColor} onChange={this._onColorChange} />
    <DialogFooter>
        <DefaultButton text='Cancel' title='Cancel' onClick={this.props.close} />
        <PrimaryButton text='OK' title='OK' onClick={() => { this.props.submit(this._pickedColor); }} />
    </DialogFooter>
    </DialogContent>;
  }

  private _onColorChange = (ev: React.SyntheticEvent<HTMLElement, Event>, color: IColor) => {
    this._pickedColor = color;
  }
}

为你刚刚添加的 ColorPickerDialogContent 类下方的自定义对话框添加以下类定义。这是从 ListView 命令集按钮单击调用并从 BaseDialog 继承的实际自定义对话框。

export default class ColorPickerDialog extends BaseDialog {
  public message: string;
  public colorCode: IColor;

  public render(): void {
    ReactDOM.render(<ColorPickerDialogContent
    close={ this.close }
    message={ this.message }
    defaultColor={ this.colorCode }
    submit={ this._submit }
    />, this.domElement);
  }

  public getConfig(): IDialogConfiguration {
    return { isBlocking: false };
  }

  protected onAfterClose(): void {
    super.onAfterClose();

    // Clean up the element for the next dialog
    ReactDOM.unmountComponentAtNode(this.domElement);
  }

  private _submit = (color: IColor) => {
    this.colorCode = color;
    this.close();
  }
}

将对话框与 ListView 命令集按钮单击相关联

要将自定义对话框与自定义 ListView 命令集相关联，请添加代码以启动按钮单击操作中的对话框。

在代码编辑器中，从 ./src/extensions/dialogDemo/ 文件夹中打开 DialogDemoCommandSet.ts 文件。
将以下导入语句添加到现有的字符串导入下方。这些功能用于在 ListView 命令集的上下文中使用自定义对话框，并使用 IColor 类型将颜色传递到对话框和从对话框中传递颜色。
```
import ColorPickerDialog from './ColorPickerDialog';
import { IColor } from 'office-ui-fabric-react/lib/Color';
```
在类中的 DialogDemoCommandSet 函数上方onInit添加以下_colorCode变量定义。这用于存储颜色选取器对话框结果。
```
private _colorCode: IColor;
```

onExecute按如下所示更新函数。此代码将执行以下操作：

启动自定义对话框。
传递用于标题的对话框消息。
如果尚未设置，则传递带默认值的对话框的颜色代码。
显示自定义对话框。
接收和存储来自对话框的返回值
通过使用 Dialog.alert() 函数在默认对话框中显示接收到的值。

@override
public onExecute(event: IListViewCommandSetExecuteEventParameters): void {
  switch (event.itemId) {
    case 'COMMAND_1':
      Dialog.alert(`${this.properties.sampleTextOne}`);
      const dialog: ColorPickerDialog = new ColorPickerDialog();
      dialog.message = 'Pick a color:';
      // Use 'FFFFFF' as the default color for first usage
      let defaultColor : IColor = { hex: 'FFFFFF', str: '', r: null, g: null, b: null, h: null, s: null, v: null };
      dialog.colorCode = this._colorCode|| defaultColor;
      dialog.show().then(() => {
        this._colorCode = dialog.colorCode;
        Dialog.alert(`Picked color: ${dialog.colorCode.hex}`);
      });
      break;
    default:
      throw new Error('Unknown command');
  }
}

在租户中测试对话框

在“./config/”文件夹中，打开“serve.json”文件，然后更新此文件中的当前设置。此文件用于简化 SharePoint 框架扩展的调试。可以将文件内容更新为，匹配要在其中测试扩展的租户和网站的详细信息。要更新的键值是 json 定义中的 pageUrl 属性，要更新为匹配自己的租户。

将 pageUrl 更新为指向要在其中测试对话框功能的列表 URL。

  "serveConfigurations": {
    "default": {
      "pageUrl": "https://yourtenantname.sharepoint.com/Shared%20Documents/Forms/AllItems.aspx",
      "customActions": {
        "9b98b919-fe5e-4758-ac91-6d62e582c4fe": {
          "location": "ClientSideExtension.ListViewCommandSet.CommandBar",
          "properties": {
            "sampleTextOne": "One item is selected in the list",
            "sampleTextTwo": "This command is always visible."
          }
        }
      }
    },

注意

扩展的唯一标识符会在初始基架搭建期间自动更新为此文件。如果更新了扩展使用的属性，应在开始调试前更新 serve.json。

返回到控制台，并运行以下命令：
```
gulp serve
```

这会开始捆绑解决方案，并通过 localhost 地址提供生成的清单。鉴于 serve.json 文件中的配置，它还会在浏览器中打开特定 URL，并根据解决方案配置自动设置查询参数。

出现提示时，通过选择“加载调试脚本”接受加载调试清单。

请注意，默认情况下，新按钮在工具栏中不可见，因为默认解决方案要求从列表中选择一个项目。如果列表或库中没有任何项，请创建项或上传文档。
选择列表或库中的项，并注意“打开自定义对话框”按钮在工具栏中的显示方式。
单击“打开自定义对话框”按钮，查看在列表视图中呈现的自定义对话框。
从“颜色选取器”中选择颜色，然后选择“确定”来测试代码将所选值返回到调用方的方式。接着通过使用默认警报对话框显示选择。

注意

如果发现本文档或 SharePoint 框架有问题，请使用 sp-dev-docs 存储库上的问题列表，向 SharePoint 工程团队报告问题。提前感谢读者提供反馈意见。

另请参阅

SharePoint 框架扩展概述

通过