添加对热门操作的支持

谨慎

此版本目前作为用于测试的公共 beta 版提供。

对于生产环境，建议使用设置 SharePoint 框架开发环境上提及的 SPFx 版本。

目前，用户需要注意 Web 部件属性面板，以找出每个 Web 部件提供的其他选项。这是一个常见的反馈，用户希望在操作所在的上下文中浮出水面，而无需依赖打开某些内容来获取这些选项。因此，我们现在允许将 Web 部件的属性面板中的最常见配置直接显示在 Web 部件的工具栏上。这些常见配置称为 Web 部件的“热门操作”。

重要

此功能在 1.16 版本中仍处于预览状态，不应在生产环境中使用。我们正在考虑正式发布它们，作为即将发布的 1.17 版本的一部分。在撰写本文时，Top Actions 仅支持呈现下拉列表和按钮命令。

热门操作示例

入门

提示

这些说明假定你知道如何创建 hello world Web 部件。

定义 Top Action 配置

在下面的示例中，我们将定义回调函数，该函数将用于拉取 Top Action 命令的配置。

注意

getTopActionsConfiguration 必须在 Web 部件的类上定义为 public。

import { ITopActions } from '@microsoft/sp-top-actions';

public getTopActionsConfiguration(): ITopActions | undefined {
  return {
    topActions: [],
    onExecute: (actionName: string, newValue: any) => {}
  };
}

定义工具栏的用户界面

数组 topActions 是在 Web 部件工具栏中呈现的控件的有序列表。在下面的示例中，我们将一个顶部操作定义为按钮界面。

import { PropertyPaneFieldType } from '@microsoft/sp-property-pane';

return {
  topActions: [
    {
      targetProperty: 'reset',
      properties: {
        icon: 'Reset'
      },
      type: PropertyPaneFieldType.Button
    }
  ]
  ...
}

当用户交互时执行命令

上一步演示了如何获取按钮以显示在 Web 部件的工具栏中。现在，我们将在用户选择按钮时执行操作。请注意， actionName 在最后一步中定义为 targetProperty ，由于这是一个按钮，我们可以忽略 newValue 传入的。

return {
  ...
  onExecute: (actionName: string, newValue: any) => {
    if (actionName === 'reset') {
      // user defined logic to reset the web part
      this.reset();
    }
  }
}

提示

实现 onExecute 命令时，常见的陷阱是未将新状态与 Web 部件属性同步和/或不刷新或重新呈现 Web 部件。

代码片段

按钮命令

按钮的类型交错类似于属性面板的按钮 (IPropertyPaneButtonProps) 。

import { ITopActions } from '@microsoft/sp-top-actions';
import { PropertyPaneFieldType } from '@microsoft/sp-property-pane';
...
public getTopActionsConfiguration(): ITopActions | undefined {
  return {
    topActions: [
      {
        targetProperty: 'reset',
        type: PropertyPaneFieldType.Button,
        properties: {
          icon: 'Reset'
        }
      }
    ],
    onExecute: (actionName: string, newValue: any) => {
      if (actionName === 'reset') {
        // user defined logic to reset the web part
        this.reset();
      }
    }
  };
}

下拉命令

下拉列表的类型接口类似于属性面板的选择组 (IPropertyPaneChoiceGroupOption) 。

import { ITopActions } from '@microsoft/sp-top-actions';
import { PropertyPaneFieldType } from '@microsoft/sp-property-pane';
...
public getTopActionsConfiguration(): ITopActions | undefined {
  return {
    topActions: [{
      targetProperty: 'layout',
      type: PropertyPaneFieldType.ChoiceGroup,
      properties: {
        options: [
          {
            // key maps to newValue in onExecute
            key: 'card',
            text: 'Card Layout',
            imageSize: { width: 32, height: 32 },
            iconProps: { officeFabricIconFontName: 'ArticlesIcon' },
            checked: this.state.layout === 'card'
          },
          {
            key: 'list',
            text: 'List Layout',
            imageSize: { width: 32, height: 32 },
            // you can use iconProps, icon to define icons
            icon: 'List',
            checked: this.state.alignment === 'list'
          }
        ]
      }
    }],
    // for ChoiceGroup drop-down, the newValue tells us which option's key was selected
    onExecute: (actionName: string, newValue: any) => {
      if (actionName === 'layout') {
        this.setLayout(newValue);
        this.render();
      }
    }
  };
}

高级配置

对于顶级操作命令的高级配置，请查看和 @microsoft/sp-top-actions中的类型定义@microsoft/sp-property-pane。目前，可以使用类型和 IPropertyPaneChoiceGroupOption 的子集来定义两个受支持的顶级操作命令（按钮和 IPropertyPaneButtonProps下拉列表）。

对于 IPropertyPaneButtonProps，当前支持的属性为 icon、 text、 ariaLabel、 disabled
对于 IPropertyPaneChoiceGroupOption，当前支持的 porperty 是 options ，并且从该数组中我们支持 key、、text、iconProps.officeFabricIconFontNameimageSize、 checkedtitle

import { IPropertyPaneButtonProps, IPropertyPaneChoiceGroupOption } from '@microsoft/sp-property-pane'
import { ITopActions } from '@microsoft/sp-top-actions';

Last updated on 2023-03-21

通过