@loom-framework/core 0.1.0-alpha.84 → 0.1.0-alpha.86

package/builtin-skills/antv-g2-chart/references/interactions/g2-interaction-drilldown.md

@@ -0,0 +1,149 @@
+---
+id: "g2-interaction-drilldown"
+title: "G2 下钻交互（drillDown）"
+description: |
+  drillDown 交互用于层次数据（partition / 旭日图）的点击下钻，
+  点击某个节点后只展示该节点的子树，同时在顶部显示面包屑导航。
+  点击面包屑可以逐层向上回溯。仅适用于 partition mark。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "drillDown"
+  - "下钻"
+  - "层次数据"
+  - "旭日图"
+  - "partition"
+  - "面包屑"
+  - "interaction"
+
+related:
+  - "g2-mark-treemap"
+  - "g2-interaction-element-select"
+
+use_cases:
+  - "旭日图/矩形分区图的层次数据下钻探索"
+  - "组织架构图的逐层查看"
+  - "文件目录树的交互式浏览"
+
+difficulty: "advanced"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/interaction/drill-down"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = {
+  name: '公司',
+  children: [
+    {
+      name: '研发部',
+      children: [
+        { name: '前端组', value: 12 },
+        { name: '后端组', value: 18 },
+        { name: '算法组', value: 8 },
+      ],
+    },
+    {
+      name: '市场部',
+      children: [
+        { name: '品牌组', value: 6 },
+        { name: '运营组', value: 10 },
+      ],
+    },
+    {
+      name: '设计部',
+      children: [
+        { name: 'UX组', value: 7 },
+        { name: '视觉组', value: 5 },
+      ],
+    },
+  ],
+};
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'sunburst',   // 旭日图（partition 的极坐标形式）
+  data: { value: data },
+  encode: { value: 'value', color: 'name' },
+  interaction: {
+    drillDown: true,   // 启用下钻交互
+  },
+});
+
+chart.render();
+```
+
+## 自定义面包屑样式
+
+```javascript
+chart.options({
+  type: 'sunburst',
+  data: { value: data },
+  encode: { value: 'value', color: 'name' },
+  interaction: {
+    drillDown: {
+      breadCrumb: {
+        rootText: '全公司',         // 根节点面包屑文字，默认 'root'
+        style: {
+          fill: 'rgba(0,0,0,0.65)',
+          fontSize: 13,
+        },
+        active: {
+          fill: '#1890ff',          // 悬停时面包屑文字颜色
+        },
+        y: 8,                       // 面包屑 Y 轴偏移
+      },
+    },
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：drillDown 用于 treemap 而非 partition/sunburst
+```javascript
+// ❌ 错误：drillDown 只适用于 partition 类型（包括旭日图）
+// treemap 有专用的 treemapDrillDown 交互
+chart.options({
+  type: 'treemap',
+  interaction: { drillDown: true },  // ❌ 应该用 treemapDrillDown
+});
+
+// ✅ treemap 用 treemapDrillDown
+chart.options({
+  type: 'treemap',
+  interaction: { treemapDrillDown: true },  // ✅
+});
+
+// ✅ sunburst/partition 用 drillDown
+chart.options({
+  type: 'sunburst',
+  interaction: { drillDown: true },  // ✅
+});
+```
+
+### 错误 2：数据不是层次结构——下钻无法展示子节点
+```javascript
+// ❌ 扁平数据没有 children，下钻后没有内容
+chart.options({
+  data: [{ name: 'A', value: 10 }, { name: 'B', value: 20 }],  // ❌ 扁平
+  interaction: { drillDown: true },
+});
+
+// ✅ 必须使用带 children 的层次数据
+chart.options({
+  data: {
+    value: { name: 'root', children: [...] },  // ✅ 树形
+  },
+  interaction: { drillDown: true },
+});
+```

package/builtin-skills/antv-g2-chart/references/interactions/g2-interaction-element-highlight-by.md

@@ -0,0 +1,125 @@
+---
+id: "g2-interaction-element-highlight-by"
+title: "G2 按颜色/X轴联动高亮（elementHighlightByColor / elementHighlightByX）"
+description: |
+  elementHighlightByColor：鼠标悬停时，高亮所有与该元素颜色通道值相同的元素。
+  elementHighlightByX：鼠标悬停时，高亮所有与该元素 x 轴值相同的元素。
+  两者都是 elementHighlight 的变体，区别在于高亮的分组依据不同，
+  常用于多系列图表中同类别或同时间点的联动高亮。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "elementHighlightByColor"
+  - "elementHighlightByX"
+  - "联动高亮"
+  - "分组高亮"
+  - "interaction"
+
+related:
+  - "g2-interaction-element-highlight"
+  - "g2-interaction-element-select"
+
+use_cases:
+  - "多系列图表中悬停某柱高亮同颜色（同类别）的所有柱"
+  - "悬停某个时间点高亮同一时间点的所有系列"
+  - "热力图按行/列联动高亮"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/interaction/element-highlight"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { month: 'Jan', city: '北京', value: 83 },
+  { month: 'Feb', city: '北京', value: 60 },
+  { month: 'Jan', city: '上海', value: 71 },
+  { month: 'Feb', city: '上海', value: 55 },
+  { month: 'Jan', city: '广州', value: 95 },
+  { month: 'Feb', city: '广州', value: 88 },
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+// ── 按颜色（城市）联动高亮 ──
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'city' },
+  transform: [{ type: 'dodgeX' }],
+  interaction: {
+    elementHighlightByColor: true,   // 悬停某柱 → 高亮同城市所有柱
+  },
+});
+
+chart.render();
+```
+
+## elementHighlightByX（同 X 轴值联动高亮）
+
+```javascript
+// 悬停某个月份的任意柱 → 高亮同月份所有城市的柱
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'city' },
+  transform: [{ type: 'dodgeX' }],
+  interaction: {
+    elementHighlightByX: true,   // 高亮同一 x 值的所有元素
+  },
+});
+```
+
+## 三种高亮模式对比
+
+```javascript
+// 1. elementHighlight（默认）：只高亮鼠标悬停的单个元素
+interaction: { elementHighlight: true }
+
+// 2. elementHighlightByColor：高亮同颜色分组的所有元素（同类别）
+interaction: { elementHighlightByColor: true }
+
+// 3. elementHighlightByX：高亮同 x 值的所有元素（同时间点/类别）
+interaction: { elementHighlightByX: true }
+```
+
+## 自定义高亮样式
+
+```javascript
+chart.options({
+  interaction: {
+    elementHighlightByColor: {
+      background: true,         // 高亮时显示背景（false 则只改透明度）
+      link: false,              // 是否显示连线（仅对折线图等有效）
+      offset: 0,                // 高亮时的偏移量
+    },
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：在没有 color 通道的图表上用 elementHighlightByColor——所有元素都被高亮
+```javascript
+// ❌ 没有 color 通道时，所有元素视为同一颜色组，hover 时全部高亮
+chart.options({
+  type: 'interval',
+  encode: { x: 'month', y: 'value' },  // ❌ 没有 color
+  interaction: { elementHighlightByColor: true },
+});
+
+// ✅ 需要有 color 通道才能按颜色分组高亮
+chart.options({
+  encode: { x: 'month', y: 'value', color: 'city' },  // ✅ 有 color 分组
+  interaction: { elementHighlightByColor: true },
+});
+```

package/builtin-skills/antv-g2-chart/references/interactions/g2-interaction-element-highlight.md

@@ -0,0 +1,235 @@
+---
+id: "g2-interaction-element-highlight"
+title: "G2 元素高亮交互（elementHighlight）"
+description: |
+  elementHighlight 是 G2 v5 中最常用的交互之一，鼠标悬停时高亮当前元素、
+  同时可选择高亮同系列元素或联动其他视图。支持柱状图、折线图、散点图等所有 Mark 类型。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "elementHighlight"
+  - "高亮"
+  - "interaction"
+  - "hover"
+  - "交互"
+  - "spec"
+
+related:
+  - "g2-interaction-brush"
+  - "g2-mark-interval-basic"
+  - "g2-mark-line-basic"
+
+use_cases:
+  - "柱状图悬停高亮当前柱子"
+  - "折线图悬停高亮当前系列"
+  - "散点图悬停高亮同类数据点"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/interaction/element-highlight"
+---
+
+## 基本用法（柱状图高亮）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'interval',
+  data: [
+    { genre: 'Sports',   sold: 275 },
+    { genre: 'Strategy', sold: 115 },
+    { genre: 'Action',   sold: 120 },
+    { genre: 'Shooter',  sold: 350 },
+    { genre: 'Other',    sold: 150 },
+  ],
+  encode: { x: 'genre', y: 'sold' },
+  interaction: { elementHighlight: true },   // 悬停高亮当前柱子
+});
+
+chart.render();
+```
+
+## 高亮背景色配置
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'genre', y: 'sold', color: 'genre' },
+  interaction: {
+    elementHighlight: {
+      background: true,              // 是否显示高亮背景
+      backgroundFill: '#f0f0f0',    // 背景填充色
+    },
+  },
+});
+```
+
+## 折线图：高亮当前系列
+
+```javascript
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'month', y: 'value', color: 'series' },
+  interaction: {
+    elementHighlight: true,        // 悬停高亮当前折线
+  },
+});
+```
+
+## elementHighlightByColor：高亮同色系列
+
+```javascript
+// 悬停时高亮所有相同颜色（系列）的元素
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [{ type: 'dodgeX' }],
+  interaction: {
+    elementHighlightByColor: true,   // 高亮同系列所有柱子
+  },
+});
+```
+
+## elementHighlightByX：高亮同 x 位置的元素
+
+```javascript
+// 悬停时高亮同一 x 值的所有元素（适合分组柱状图）
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  interaction: {
+    elementHighlightByX: true,    // 高亮同组（同 x 位置）的所有元素
+  },
+});
+```
+
+## 同时启用 tooltip + 高亮
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'revenue', color: 'product' },
+  transform: [{ type: 'dodgeX' }],
+  interaction: {
+    elementHighlight: true,    // 元素高亮
+    tooltip: true,             // Tooltip 提示
+  },
+  tooltip: {
+    title: 'month',
+    items: [
+      { field: 'revenue', valueFormatter: (v) => `$${v}万` },
+    ],
+  },
+});
+```
+
+## 监听高亮事件
+
+```javascript
+chart.on('element:highlight', (event) => {
+  const datum = event.data?.data;
+  console.log('高亮元素数据：', datum);
+});
+
+chart.on('element:unhighlight', () => {
+  console.log('取消高亮');
+});
+```
+
+## 常见错误与修正
+
+### 错误：interaction 写成对象
+```javascript
+// ❌ 错误：interaction 必须是数组（旧版写法）
+chart.options({
+  interaction: { type: 'elementHighlight' },
+});
+
+// ✅ 正确（新版支持对象形式）
+chart.options({
+  interaction: { elementHighlight: true },
+});
+```
+
+### 错误：混淆 elementHighlight 与 elementHighlightByColor
+```javascript
+// ❌ 同时使用会导致重复响应
+chart.options({
+  interaction: {
+    elementHighlight: true,
+    elementHighlightByColor: true,
+  },
+});
+
+// ✅ 根据需求选择一种
+// - elementHighlight: 只高亮鼠标悬停的单个元素
+// - elementHighlightByColor: 高亮同颜色（系列）的所有元素
+// - elementHighlightByX: 高亮同 x 位置的所有元素
+```
+
+### 错误：在 view 的 children 中嵌套 view 导致白屏
+```javascript
+// ❌ 错误：在 children 中嵌套 view 会导致渲染失败
+chart.options({
+  type: 'view',
+  children: [
+    {
+      type: 'view', // 不允许嵌套 view
+      children: [...]
+    }
+  ]
+});
+
+// ✅ 正确：使用顶层容器或单一 view 结构
+chart.options({
+  type: 'view',
+  children: [
+    { type: 'interval', ... },
+    { type: 'image', ... }
+  ]
+});
+```
+
+### 错误：未正确设置 image 标记导致无法显示
+```javascript
+// ❌ 错误：缺少必要的 encode 和 style 配置
+{
+  type: 'image',
+  data: [{ url: '...' }],
+  encode: { x: () => 0, y: () => 0 } // 不适用于居中显示
+}
+
+// ✅ 正确：使用 style 设置固定位置和尺寸
+{
+  type: 'image',
+  style: {
+    x: '50%', // 居中
+    y: '50%',
+    width: 80,
+    height: 80
+  },
+  encode: {
+    src: 'url'
+  }
+}
+```
+
+</skill>

package/builtin-skills/antv-g2-chart/references/interactions/g2-interaction-element-hover-scale.md

@@ -0,0 +1,109 @@
+---
+id: "g2-interaction-element-hover-scale"
+title: "G2 悬停缩放交互（elementHoverScale）"
+description: |
+  elementHoverScale 在鼠标悬停时对元素进行缩放放大，提供立体感和视觉反馈。
+  适合饼图、点图等独立元素的交互增强，比普通高亮更有视觉冲击力。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "elementHoverScale"
+  - "悬停缩放"
+  - "hover"
+  - "缩放"
+  - "interaction"
+
+related:
+  - "g2-interaction-element-highlight"
+  - "g2-mark-arc-pie"
+
+use_cases:
+  - "饼图/环形图悬停时扇形外弹放大"
+  - "散点图悬停时数据点放大"
+  - "仪表盘卡片悬停放大效果"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/interaction/element-hover-scale"
+---
+
+## 最小可运行示例（饼图悬停放大）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 480, height: 480 });
+
+chart.options({
+  type: 'interval',
+  data: [
+    { type: '电子', value: 40 },
+    { type: '服装', value: 25 },
+    { type: '食品', value: 20 },
+    { type: '其他', value: 15 },
+  ],
+  encode: { y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  coordinate: { type: 'theta', outerRadius: 0.85 },
+  interaction: {
+    elementHoverScale: true,   // 悬停时扇形外弹放大
+  },
+});
+
+chart.render();
+```
+
+## 配置缩放比例
+
+```javascript
+chart.options({
+  interaction: {
+    elementHoverScale: {
+      scale: 1.1,    // 缩放倍数，默认约 1.1（放大 10%）
+    },
+  },
+});
+```
+
+## 与其他交互组合
+
+```javascript
+// 饼图：悬停放大 + tooltip
+chart.options({
+  type: 'interval',
+  encode: { y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  coordinate: { type: 'theta' },
+  interaction: {
+    elementHoverScale: true,   // 放大
+    tooltip: true,             // 同时显示 tooltip
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：与 elementHighlight 同时使用——视觉效果冲突
+```javascript
+// ❌ 两者同时启用，被悬停元素既放大又改透明度，效果混乱
+chart.options({
+  interaction: {
+    elementHoverScale: true,
+    elementHighlight: true,   // ❌ 与 hoverScale 冲突
+  },
+});
+
+// ✅ 只选一种悬停交互
+chart.options({
+  interaction: {
+    elementHoverScale: true,  // ✅ 缩放效果
+    // 或
+    // elementHighlight: true,  // ✅ 暗淡效果
+  },
+});
+```