+
+
+
+
+
+
+
+
+
+
+```
diff --git a/skills/vchart-development-assistant/references/api/interaction-api.md b/skills/vchart-development-assistant/references/api/interaction-api.md
new file mode 100644
index 0000000000..6d9844c0d5
--- /dev/null
+++ b/skills/vchart-development-assistant/references/api/interaction-api.md
@@ -0,0 +1,301 @@
+# 交互控制 API
+
+## 概述
+
+交互控制 API 用于手动触发或禁用图表的交互效果，包括 Tooltip、Crosshair、Dimension 等。
+
+---
+
+## API 列表
+
+### showTooltip
+
+**手动显示 Tooltip**
+
+```typescript
+showTooltip(datum: Datum, options: IShowTooltipOption): boolean;
+```
+
+**参数**：
+- `datum`: 要显示 tooltip 的数据
+- `options`: 显示选项
+
+**返回值**：是否成功显示
+
+**使用示例**：
+
+```javascript
+// 显示指定数据的 tooltip
+vchart.showTooltip(
+ { category: 'A', value: 20 },
+ { position: { x: 100, y: 100 } }
+);
+```
+
+---
+
+### hideTooltip
+
+**隐藏 Tooltip**
+
+```typescript
+hideTooltip(): boolean;
+```
+
+**返回值**：是否成功隐藏
+
+**使用示例**：
+
+```javascript
+vchart.hideTooltip();
+```
+
+---
+
+### setDimensionIndex
+
+**手动触发 dimension 交互效果**
+
+```typescript
+setDimensionIndex(value: StringOrNumber, options?: DimensionIndexOption): void;
+```
+
+**参数**：
+- `value`: 维度值
+- `options`: 触发配置
+
+**使用示例**：
+
+```javascript
+// 触发指定维度的交互效果
+vchart.setDimensionIndex('A'); // 显示 'A' 类别的 crosshair 和 tooltip
+```
+
+---
+
+### disableTooltip
+
+**禁用/启用 Tooltip**
+
+```typescript
+disableTooltip(disabled: boolean): void;
+```
+
+**参数**：
+- `disabled`: true 禁用，false 启用
+
+**使用示例**：
+
+```javascript
+// 禁用 tooltip
+vchart.disableTooltip(true);
+
+// 重新启用
+vchart.disableTooltip(false);
+```
+
+---
+
+### disableCrossHair
+
+**禁用/启用 Crosshair**
+
+```typescript
+disableCrossHair(disabled: boolean): void;
+```
+
+**参数**：
+- `disabled`: true 禁用，false 启用
+
+**使用示例**：
+
+```javascript
+vchart.disableCrossHair(true);
+```
+
+---
+
+### disableDimensionHoverEvent
+
+**禁用/启用 dimension hover 事件**
+
+```typescript
+disableDimensionHoverEvent(disabled?: boolean): void;
+```
+
+**参数**：
+- `disabled`: true 禁用，false 启用
+
+**使用示例**：
+
+```javascript
+vchart.disableDimensionHoverEvent(true);
+```
+
+---
+
+## 使用场景
+
+### 场景 1: 外部触发 Tooltip
+
+```javascript
+// 通过外部按钮显示 tooltip
+function showTooltipForCategory(category) {
+ const data = chartData.find(d => d.category === category);
+ if (data) {
+ const position = vchart.convertDatumToPosition(data);
+ vchart.showTooltip(data, { position });
+ }
+}
+```
+
+### 场景 2: 联动 Crosshair
+
+```javascript
+// 两个图表联动 crosshair
+chart1.on('pointermove', (params) => {
+ if (params.value?.dimension) {
+ chart2.setDimensionIndex(params.value.dimension);
+ }
+});
+
+chart1.on('pointerout', () => {
+ chart2.setDimensionIndex(null);
+});
+```
+
+### 场景 3: 条件禁用交互
+
+```javascript
+// 数据加载时禁用交互
+async function reloadData() {
+ vchart.disableTooltip(true);
+ vchart.disableCrossHair(true);
+
+ await vchart.updateData('data', newData);
+
+ vchart.disableTooltip(false);
+ vchart.disableCrossHair(false);
+}
+```
+
+### 场景 4: 自定义 Tooltip 触发
+
+```javascript
+// 点击外部元素显示 tooltip
+document.getElementById('info-panel').addEventListener('mouseenter', (e) => {
+ const category = e.target.dataset.category;
+ const data = chartData.find(d => d.category === category);
+ vchart.showTooltip(data, {});
+});
+
+document.getElementById('info-panel').addEventListener('mouseleave', () => {
+ vchart.hideTooltip();
+});
+```
+
+---
+
+## TooltipHandler 自定义
+
+### setTooltipHandler
+
+**设置自定义 Tooltip 处理器**
+
+```typescript
+setTooltipHandler(tooltipHandler: ITooltipHandler): void;
+```
+
+**使用示例**：
+
+```javascript
+const customHandler = {
+ showTooltip: (activeTooltip, params) => {
+ // 自定义显示逻辑
+ console.log('显示 tooltip', activeTooltip);
+ return true;
+ },
+ hideTooltip: () => {
+ // 自定义隐藏逻辑
+ console.log('隐藏 tooltip');
+ return true;
+ },
+ release: () => {
+ // 清理资源
+ }
+};
+
+vchart.setTooltipHandler(customHandler);
+```
+
+### getTooltipHandler
+
+**获取当前 Tooltip 处理器**
+
+```typescript
+getTooltipHandler(): ITooltipHandler | undefined;
+```
+
+---
+
+## 完整示例
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
diff --git a/skills/vchart-development-assistant/references/api/layout-api.md b/skills/vchart-development-assistant/references/api/layout-api.md
new file mode 100644
index 0000000000..78916344fb
--- /dev/null
+++ b/skills/vchart-development-assistant/references/api/layout-api.md
@@ -0,0 +1,176 @@
+# 布局与尺寸 API
+
+## 概述
+
+布局与尺寸 API 用于控制图表的尺寸和布局。
+
+---
+
+## API 列表
+
+### resize
+
+**调整图表尺寸**
+
+```typescript
+resize(width: number, height: number): Promise
+
+
+
+
+
+
+
+
+
+
+
+
+```
diff --git a/skills/vchart-development-assistant/references/api/legend-api.md b/skills/vchart-development-assistant/references/api/legend-api.md
new file mode 100644
index 0000000000..0b11d77c1d
--- /dev/null
+++ b/skills/vchart-development-assistant/references/api/legend-api.md
@@ -0,0 +1,186 @@
+# 图例操作 API
+
+## 概述
+
+图例操作 API 用于获取图例数据和设置图例选中状态。
+
+---
+
+## API 列表
+
+### getLegendDataById
+
+**根据 ID 获取图例数据**
+
+```typescript
+getLegendDataById(id: string): Datum[];
+```
+
+**参数**：
+- `id`: 图例组件 ID
+
+**返回值**：图例数据数组
+
+---
+
+### getLegendDataByIndex
+
+**根据索引获取图例数据**
+
+```typescript
+getLegendDataByIndex(index?: number): Datum[];
+```
+
+**参数**：
+- `index`: 图例索引，默认 0
+
+---
+
+### getLegendSelectedDataById
+
+**根据 ID 获取图例选中项**
+
+```typescript
+getLegendSelectedDataById(id: string): StringOrNumber[];
+```
+
+**返回值**：选中的图例项值数组
+
+---
+
+### getLegendSelectedDataByIndex
+
+**根据索引获取图例选中项**
+
+```typescript
+getLegendSelectedDataByIndex(index?: number): StringOrNumber[];
+```
+
+---
+
+### setLegendSelectedDataById
+
+**根据 ID 设置图例选中项**
+
+```typescript
+setLegendSelectedDataById(id: string, selectedData: StringOrNumber[]): void;
+```
+
+**参数**：
+- `id`: 图例组件 ID
+- `selectedData`: 要选中的图例项值数组
+
+---
+
+### setLegendSelectedDataByIndex
+
+**根据索引设置图例选中项**
+
+```typescript
+setLegendSelectedDataByIndex(index: number, selectedData: StringOrNumber[]): void;
+```
+
+---
+
+## 使用场景
+
+### 场景 1: 获取当前图例选中状态
+
+```javascript
+const selected = vchart.getLegendSelectedDataByIndex(0);
+console.log('当前选中:', selected); // ['A', 'B']
+```
+
+### 场景 2: 程序控制图例选中
+
+```javascript
+// 只显示指定类别
+vchart.setLegendSelectedDataByIndex(0, ['A', 'B']);
+
+// 全选
+const allData = vchart.getLegendDataByIndex(0);
+const allValues = allData.map(d => d.value);
+vchart.setLegendSelectedDataByIndex(0, allValues);
+```
+
+### 场景 3: 图例状态保存与恢复
+
+```javascript
+// 保存图例状态
+function saveLegendState() {
+ return vchart.getLegendSelectedDataByIndex(0);
+}
+
+// 恢复图例状态
+function restoreLegendState(selected) {
+ vchart.setLegendSelectedDataByIndex(0, selected);
+}
+```
+
+### 场景 4: 多图表图例联动
+
+```javascript
+// 图表1图例变化时，同步到图表2
+chart1.on('legendItemClick', (params) => {
+ chart2.setLegendSelectedDataByIndex(0, params.value);
+});
+```
+
+---
+
+## 完整示例
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
diff --git a/skills/vchart-development-assistant/references/api/state-api.md b/skills/vchart-development-assistant/references/api/state-api.md
new file mode 100644
index 0000000000..37e1d61398
--- /dev/null
+++ b/skills/vchart-development-assistant/references/api/state-api.md
@@ -0,0 +1,376 @@
+# 状态管理 API
+
+## 概述
+
+状态管理 API 用于控制图元的高亮、选中等交互状态，支持自定义状态配置。
+
+---
+
+## API 列表
+
+### setHovered
+
+**设置图元 hover 状态**
+
+```typescript
+setHovered(
+ datum: MaybeArray
+
+
+
+
+
+
+
+
+```
diff --git a/skills/vchart-development-assistant/scripts/generate_demo_html.py b/skills/vchart-development-assistant/scripts/generate_demo_html.py
index 7194104799..2cfcf763e5 100644
--- a/skills/vchart-development-assistant/scripts/generate_demo_html.py
+++ b/skills/vchart-development-assistant/scripts/generate_demo_html.py
@@ -16,6 +16,7 @@
from pathlib import Path
import argparse
+import sys
def escape_js_string(s: str) -> str:
"""转义 JavaScript 字符串中的特殊字符"""
@@ -24,33 +25,71 @@ def escape_js_string(s: str) -> str:
s = s.replace("\n", "\\n")
return s
+def validate_spec_code(spec_code: str) -> bool:
+ """验证 spec 代码基本格式"""
+ # 检查是否包含基本的 spec 结构
+ if "const spec" not in spec_code and "let spec" not in spec_code and "var spec" not in spec_code:
+ return False
+ if "type:" not in spec_code:
+ return False
+ return True
+
def main():
- parser = argparse.ArgumentParser(description="Generate demo HTML from template/demo.html")
- parser.add_argument("--title", default="VChart 图表示例", help="页面标题")
- parser.add_argument("--desc", default="基于需求生成的可运行图表配置", help="页面描述")
- parser.add_argument("--feature", default="补充主要功能说明", help="主要功能说明")
- parser.add_argument("--tips", default="补充编辑提示", help="编辑提示")
- parser.add_argument("--spec-file", help="包含完整 spec 代码的文件路径")
- parser.add_argument("--output", default="output/demo.html", help="输出 HTML 文件路径")
- args = parser.parse_args()
-
- template_path = Path("template/demo.html")
- if not template_path.exists():
- raise FileNotFoundError(f"❌ 模板不存在: {template_path}\n💡 请确保在项目根目录运行脚本")
-
- html = template_path.read_text(encoding="utf-8")
- html = html.replace("{{REPORT_TITLE}}", args.title)
- html = html.replace("{{REPORT_DESC}}", args.desc)
- html = html.replace("{{FEATURE_DESC}}", args.feature)
- html = html.replace("{{EDIT_TIPS}}", args.tips)
-
- if args.spec_file:
- spec_path = Path(args.spec_file)
- if not spec_path.exists():
- raise FileNotFoundError(f"❌ Spec 文件不存在: {spec_path}")
- spec_code = spec_path.read_text(encoding="utf-8")
- else:
- spec_code = """const spec = {
+ try:
+ parser = argparse.ArgumentParser(
+ description="Generate demo HTML from template/demo.html",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog="""
+示例：
+ # 使用自定义 spec 文件
+ python3 scripts/generate_demo_html.py --spec-file my-spec.js --output demo.html
+
+ # 完整参数
+ python3 scripts/generate_demo_html.py \\
+ --title "柱状图示例" \\
+ --desc "基础柱状图配置" \\
+ --spec-file spec.js \\
+ --output output/demo.html
+ """
+ )
+ parser.add_argument("--title", default="VChart 图表示例", help="页面标题")
+ parser.add_argument("--desc", default="基于需求生成的可运行图表配置", help="页面描述")
+ parser.add_argument("--feature", default="补充主要功能说明", help="主要功能说明")
+ parser.add_argument("--tips", default="补充编辑提示", help="编辑提示")
+ parser.add_argument("--spec-file", help="包含完整 spec 代码的文件路径")
+ parser.add_argument("--output", default="output/demo.html", help="输出 HTML 文件路径")
+ parser.add_argument("--validate", action="store_true", help="验证 spec 代码格式")
+ args = parser.parse_args()
+
+ # 检查模板文件
+ template_path = Path("template/demo.html")
+ if not template_path.exists():
+ print(f"❌ 错误: 模板文件不存在: {template_path}", file=sys.stderr)
+ print(f"💡 提示: 请确保在 skills/vchart-development-assistant 目录运行脚本", file=sys.stderr)
+ sys.exit(1)
+
+ html = template_path.read_text(encoding="utf-8")
+ html = html.replace("{{REPORT_TITLE}}", args.title)
+ html = html.replace("{{REPORT_DESC}}", args.desc)
+ html = html.replace("{{FEATURE_DESC}}", args.feature)
+ html = html.replace("{{EDIT_TIPS}}", args.tips)
+
+ # 读取或使用默认 spec
+ if args.spec_file:
+ spec_path = Path(args.spec_file)
+ if not spec_path.exists():
+ print(f"❌ 错误: Spec 文件不存在: {spec_path}", file=sys.stderr)
+ sys.exit(1)
+
+ spec_code = spec_path.read_text(encoding="utf-8")
+
+ # 验证 spec 代码格式
+ if args.validate and not validate_spec_code(spec_code):
+ print(f"⚠️ 警告: Spec 代码格式可能不正确", file=sys.stderr)
+ print(f" 请确保包含 'const spec = {{...}}' 和 'type: \"...\"'", file=sys.stderr)
+ else:
+ # 使用内置示例
+ spec_code = """const spec = {
type: "line",
data: {
values: [
@@ -64,21 +103,37 @@ def main():
xField: "time",
yField: "value"
};"""
+ print(f"ℹ️ 使用内置示例 spec", file=sys.stderr)
+
+ # 转义 spec 代码供 JavaScript 字符串使用
+ initial_code_escaped = escape_js_string(spec_code.strip())
+
+ # 填充 spec 和 initialCode 模板变量
+ html = html.replace("{{SPEC_CODE}}", spec_code)
+ html = html.replace("{{INITIAL_CODE}}", initial_code_escaped)
- # 转义 spec 代码供 JavaScript 字符串使用
- initial_code_escaped = escape_js_string(spec_code.strip())
+ # 检查模板占位符是否都被替换
+ if "{{SPEC_CODE}}" in html or "{{INITIAL_CODE}}" in html:
+ print(f"❌ 错误: 模板占位符替换失败", file=sys.stderr)
+ print(f"💡 提示: 请检查模板文件: {template_path}", file=sys.stderr)
+ sys.exit(1)
- # 填充 spec 和 initialCode 模板变量
- html = html.replace("{{SPEC_CODE}}", spec_code)
- html = html.replace("{{INITIAL_CODE}}", initial_code_escaped)
- filled = html
+ # 创建输出目录并写入文件
+ output_path = Path(args.output)
+ output_path.parent.mkdir(parents=True, exist_ok=True)
+ output_path.write_text(html, encoding="utf-8")
- output_path = Path(args.output)
- output_path.parent.mkdir(parents=True, exist_ok=True)
- output_path.write_text(filled, encoding="utf-8")
+ print(f"✅ 示例 HTML 已生成: {output_path.resolve()}")
+ print(f"📖 请在浏览器中打开以查看交互式图表")
- print(f"✅ 示例 HTML 已生成: {output_path.resolve()}")
- print(f"📊 请在浏览器中打开以查看可运行示例")
+ except FileNotFoundError as e:
+ print(f"❌ 文件错误: {e}", file=sys.stderr)
+ sys.exit(1)
+ except Exception as e:
+ print(f"❌ 未知错误: {e}", file=sys.stderr)
+ import traceback
+ traceback.print_exc()
+ sys.exit(1)
if __name__ == "__main__":
- main()
+ main()
\ No newline at end of file