添加自定义项设置

2025-07-02

在 Microsoft Fabric 中，项设置是与特定项关联的信息片段。它们包括经常更新的属性和与项目相关联的资源。显示这些设置以提供必要的项元数据信息，以便用户可以轻松读取设置的值。

更改项清单

若要添加自定义项设置，首先需要在前端项清单中将getItemSettings放置到itemSettings下：

    "itemSettings": {
      "getItemSettings": {
            "action": "getItemSettings"
        },
      "schedule": {
        "itemJobType": "ScheduledJob",
        "refreshType": "Refresh"
      },
      "recentRun": {
        "useRecentRunsComponent": true
      }
    },

如前面的代码所示， getItemSettings 必须包含字符串 action 。此字符串是返回自定义项设置列表的相应作的名称。

添加自定义项选项卡

以下屏幕截图显示了添加自定义项选项卡的示例。自定义项选项卡标记为数字 1。选择此选项卡后加载的 iframe 标记为数字 2。

上图显示了两个自定义选项卡，可以使用文件中的以下代码 index.worker.ts 创建这些选项卡：

workloadClient.action.onAction(async function ({ action, data }) {
    switch (action) {
        case 'getItemSettings': {
            return [
                {
                    name: 'customItemSettings',
                    displayName: 'Custom item Settings',
                    workloadSettingLocation: {
                        workloadName: sampleWorkloadName,
                        route: 'custom-item-settings',
                    },
                    searchTokenMatchesBySection: {
                        'custom search': [
                            'key words for search',
                            'custom item'
                        ],
                    },
                },
                {
                    name: 'customItemSettings2',
                    displayName: 'Custom item Settings2',
                    workloadSettingLocation: {
                        workloadName: sampleWorkloadName,
                        route: 'custom-item-settings2',
                    },
                },
            ];
        }
        default:
            throw new Error('Unknown action received');
    }
});

该代码返回已定义自定义项的数组。每项包括：

name （字符串）：设置的唯一标识符。
displayName （字符串）：应本地化的显示的字符串。（第一项的显示名称在前面的屏幕截图中标记为数字 1。
workloadSettingLocation （对象）：
- workloadName （字符串）：工作负荷名称。
- route （对象）：工作负荷拥有的特定路由。从项设置中选择特定设置选项卡时，面板 iframe 将加载到右侧内容区域以加载路由。（iframe 在前面的屏幕截图中标记为数字 2。
searchTokenMatchesBySection （object）：一个可选对象，该对象接收节名称作为键，关键字数组作为值。只要搜索任何数组单词，就会触发该键。

以下示例显示，开始键入其中一个关键字值（1）会触发节名称作为结果选项（2）。选择此选项将打开相应的自定义选项卡（3）。此字段与本地化一致，可用于本地化。

定义 iframe 路由

若要加载 iframe，请定义组件，然后将其添加到应用路由。

组件定义

export function CustomItemSettings2() {
    return (
      <div>
        You can have additional tabs for item settings.
      </div>
    );
  }

路由器示例

export function App({ history, workloadClient }: AppProps) {
    return <Router history={history}>
        <Switch>
            ...
            <Route path="/custom-item-settings">
                <CustomItemSettings workloadClient={workloadClient}  />
            </Route>
            <Route path="/custom-item-settings2">
                <CustomItemSettings2 />
            </Route>
        </Switch>
    </Router>;
}

自定义“关于”页

以下屏幕截图显示了 “关于” 页面的自定义设置示例。设置中当前选定的选项卡是“ 关于 ”选项卡，该选项卡在黑色框架中标记。加载的选项卡显示在右侧。默认设置（名称、说明、位置和详细信息）显示在顶部。默认部分下方是自定义关于部分的iframe，该iframe用红色框标记。

“ 关于 ”页项支持使用混合视图（默认设置 About 和工作负荷的自定义 iframe）添加特定于工作负荷的内容。为此，可以添加另一个自定义项目配置。

workloadClient.action.onAction(async function ({ action, data }) {
    switch (action) {
        case 'getItemSettings': {
            return [
                {
                    name: 'about',
                    displayName: 'About',
                    workloadSettingLocation: {
                        workloadName: sampleWorkloadName,
                        route: 'custom-about',
                    },
                    workloadIframeHeight: '1000px'
                },
                ...
            ];
        }
        default:
            throw new Error('Unknown action received');
    }
});

前面的代码包括：

name ：必须定义为 about。
displayName ：必须定义为 About。
route ：需要用于加载到 iframe 中的自定义 About 组件，如下图所示。
workloadIframeHeight：以字符串的形式提供，以像素为单位。如果未设置 iframe 高度，则会将其设置为默认值 102vh。