From 4ee29454a7b3d6e54c24c9d175e830fc9c0a5129 Mon Sep 17 00:00:00 2001
From: DaZuiZui <y51288033@outlook.com>
Date: Wed, 29 Jul 2026 10:38:18 +0800
Subject: [PATCH] docs(api): document toolbox feature extensions

---
 en/api/echarts.md              | 57 ++++++++++++++++++++++++++++++++++
 en/option/component/toolbox.md |  7 ++++-
 zh/api/echarts.md              | 53 +++++++++++++++++++++++++++++++
 zh/option/component/toolbox.md |  2 +-
 4 files changed, 117 insertions(+), 2 deletions(-)

diff --git a/en/api/echarts.md b/en/api/echarts.md
index 6676c44dc..a9d45aa62 100644
--- a/en/api/echarts.md
+++ b/en/api/echarts.md
@@ -133,6 +133,63 @@ echarts.use(
 
 See [Use ECharts with bundler and NPM](${handbookPath}basics/import) for more detailed explanation.
 
+### Registering toolbox features from extension packages
+
+An extension installer can register a first-class toolbox feature with
+`registerToolboxFeature`. The feature class and its public types are exported
+from `echarts/core`.
+
+```ts
+import * as echarts from 'echarts/core';
+import {
+    EChartsExtensionInstaller,
+    ToolboxFeature,
+    ToolboxFeatureOption
+} from 'echarts/core';
+
+interface ExportDataFeatureOption extends ToolboxFeatureOption {
+    filename?: string;
+}
+
+class ExportDataFeature extends ToolboxFeature<ExportDataFeatureOption> {
+    onclick(): void {
+        const filename = this.model.get('filename');
+        // Call the extension package's exporter here.
+        console.log(filename);
+    }
+
+    static defaultOption: ExportDataFeatureOption = {
+        show: true,
+        title: 'Export data',
+        icon: 'path://M6 2h8l4 4v16H6V2zm7 1.5V7h3.5L13 3.5z',
+        filename: 'chart-data'
+    };
+}
+
+const installExportData: EChartsExtensionInstaller = (registers) => {
+    registers.registerToolboxFeature('exportData', ExportDataFeature);
+};
+
+echarts.use(installExportData);
+```
+
+Registering a feature only makes it available; it does not add a button to
+every chart. Each chart must explicitly configure the feature. Use `show` to
+control its availability for that chart, including when permissions change:
+
+```ts
+chart.setOption({
+    toolbox: {
+        feature: {
+            exportData: {
+                show: canExport,
+                filename: 'sales'
+            }
+        }
+    }
+});
+```
+
 ## registerMap(Function)
 
 ```ts
diff --git a/en/option/component/toolbox.md b/en/option/component/toolbox.md
index a676ce3e6..8d3ad4384 100644
--- a/en/option/component/toolbox.md
+++ b/en/option/component/toolbox.md
@@ -168,7 +168,12 @@ The configuration item for each tool.
 
 Besides the tools we provide, user-defined toolbox is also supported.
 
-Notes: User-defined tool name could only start with `my`, like `myTool1` and `myTool2` in the below example:
+Notes: A user-defined tool configured only through chart options must start with
+`my`, like `myTool1` and `myTool2` in the example below. An extension package
+can register a named feature through `registerToolboxFeature`; registered
+features do not need the `my` prefix. Registration does not add the feature to
+every chart. The button is created only when the feature is explicitly listed
+here, and its `show` option controls whether it is displayed for that chart.
 
 ```javascript
 {
diff --git a/zh/api/echarts.md b/zh/api/echarts.md
index 54b449a91..35756dd0d 100644
--- a/zh/api/echarts.md
+++ b/zh/api/echarts.md
@@ -131,6 +131,59 @@ echarts.use(
 ```
 更详细的使用方式见 [在项目中引入 Apache ECharts](${handbookPath}basics/import) 一文
 
+### 在扩展包中注册工具栏功能
+
+扩展安装器可以通过 `registerToolboxFeature` 注册正式的工具栏功能。功能基类及其公开类型均从 `echarts/core` 导出。
+
+```ts
+import * as echarts from 'echarts/core';
+import {
+    EChartsExtensionInstaller,
+    ToolboxFeature,
+    ToolboxFeatureOption
+} from 'echarts/core';
+
+interface ExportDataFeatureOption extends ToolboxFeatureOption {
+    filename?: string;
+}
+
+class ExportDataFeature extends ToolboxFeature<ExportDataFeatureOption> {
+    onclick(): void {
+        const filename = this.model.get('filename');
+        // 在这里调用扩展包提供的导出器。
+        console.log(filename);
+    }
+
+    static defaultOption: ExportDataFeatureOption = {
+        show: true,
+        title: '导出数据',
+        icon: 'path://M6 2h8l4 4v16H6V2zm7 1.5V7h3.5L13 3.5z',
+        filename: 'chart-data'
+    };
+}
+
+const installExportData: EChartsExtensionInstaller = (registers) => {
+    registers.registerToolboxFeature('exportData', ExportDataFeature);
+};
+
+echarts.use(installExportData);
+```
+
+注册功能只会使该功能可用，不会自动为所有图表添加按钮。每个图表仍需显式配置该功能。可以通过 `show` 控制当前图表是否允许使用该功能，也可以在权限变化时动态更新：
+
+```ts
+chart.setOption({
+    toolbox: {
+        feature: {
+            exportData: {
+                show: canExport,
+                filename: 'sales'
+            }
+        }
+    }
+});
+```
+
 ## registerMap(Function)
 
 ```ts
diff --git a/zh/option/component/toolbox.md b/zh/option/component/toolbox.md
index 458eeaa3f..76e9afb98 100644
--- a/zh/option/component/toolbox.md
+++ b/zh/option/component/toolbox.md
@@ -242,7 +242,7 @@ option = {
 
 除了各个内置的工具按钮外，还可以自定义工具按钮。
 
-注意，自定义的工具名字，只能以 `my` 开头，例如下例中的 `myTool1`，`myTool2`：
+注意，仅通过图表配置定义的自定义工具，名字必须以 `my` 开头，例如下例中的 `myTool1`、`myTool2`。扩展包也可以通过 `registerToolboxFeature` 注册具名功能；已注册的功能不需要 `my` 前缀。注册不会自动为所有图表添加该功能，只有在这里显式配置后才会创建按钮，并可通过功能的 `show` 配置控制是否在当前图表中显示。
 
 ```javascript
 {