可以在 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 {

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

title='Color Picker'

subText={this.props.message}

onDismiss={this.props.close}

showCloseButton={true}

>

{ this.props.submit(this._pickedColor); }} />

;

}

private _onColorChange = (ev: React.SyntheticEvent, 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(

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 框架扩展概述