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

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

@@ -0,0 +1,152 @@
+---
+id: "g2-interaction-element-point-move"
+title: "G2 ElementPointMove 数据点拖拽编辑"
+description: |
+  elementPointMove 是 G2 v5 的交互，允许用户通过鼠标拖拽图表中的数据点来修改数值。
+  支持折线图、柱状图、饼图、面积图等，拖拽后触发 'element-point:moved' 事件回调新数据。
+  适用于可视化数据编辑、交互式预算调整、预测值手动修正等场景。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "elementPointMove"
+  - "数据编辑"
+  - "拖拽"
+  - "可交互"
+  - "数据修改"
+  - "interaction"
+
+related:
+  - "g2-mark-line-basic"
+  - "g2-mark-interval-basic"
+  - "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/element-point-move"
+---
+
+## 核心概念
+
+`elementPointMove` 在图表元素上渲染可拖拽的控制点，鼠标按下拖拽时实时更新数据并重绘图表。
+拖拽结束后触发 `element-point:moved` 事件，回调参数包含修改后的数据。
+
+支持的 Mark 类型：
+- `line`（折线图）：每个数据点均可拖拽
+- `area`（面积图）：每个顶点可拖拽
+- `interval`（柱状图/条形图/饼图）：柱顶点可拖拽
+
+## 折线图数据点拖拽
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { month: 'Jan', value: 83 },
+  { month: 'Feb', value: 60 },
+  { month: 'Mar', value: 95 },
+  { month: 'Apr', value: 72 },
+  { month: 'May', value: 110 },
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'month', y: 'value' },
+  interaction: {
+    elementPointMove: true,   // 启用数据点拖拽
+  },
+});
+
+// 监听数据变更事件
+chart.on('element-point:moved', (event) => {
+  const { changeData, data } = event.data;
+  console.log('修改后的单条数据:', changeData);
+  console.log('完整新数据:', data);
+});
+
+chart.render();
+```
+
+## 柱状图数据点拖拽
+
+```javascript
+chart.options({
+  type: 'interval',
+  data: budgetData,
+  encode: { x: 'department', y: 'budget', color: 'department' },
+  interaction: {
+    elementPointMove: {
+      precision: 0,   // 拖拽提示精度（小数位数），默认 2
+    },
+  },
+});
+```
+
+## 配置项
+
+```javascript
+chart.options({
+  interaction: {
+    elementPointMove: {
+      precision: 2,             // 实时提示标签的小数位数，默认 2
+      selection: [],            // 初始选中的数据点索引 [elementIndex, pointIndex]
+      // 控制点样式
+      pointR: 6,                // 控制点半径，默认 6
+      pointStroke: '#888',      // 控制点描边颜色
+      pointActiveStroke: '#f5f5f5',  // 激活时描边颜色
+      // 辅助线样式
+      pathStroke: '#888',
+      pathLineDash: [3, 4],
+      // 提示标签样式
+      labelFontSize: 12,
+      labelFill: '#888',
+    },
+  },
+});
+```
+
+## 监听事件
+
+```javascript
+// 拖拽结束事件（数据已更新）
+chart.on('element-point:moved', ({  { changeData, data } }) => {
+  // changeData: 被修改的单条记录 { month: 'Feb', value: 75 }
+  // data: 修改后的完整数据数组
+  syncToServer(changeData);
+});
+
+// 选中控制点事件
+chart.on('element-point:select', ({  { selection } }) => {
+  // selection: [elementIndex, pointIndex]
+  console.log('选中点索引:', selection);
+});
+```
+
+## 常见错误与修正
+
+### 错误：在 scatter 点图上使用（不支持）
+```javascript
+// ❌ point mark 不支持 elementPointMove
+chart.options({
+  type: 'point',
+  interaction: { elementPointMove: true },  // 无效
+});
+
+// ✅ 支持的类型：line、area、interval
+chart.options({
+  type: 'line',
+  interaction: { elementPointMove: true },  // ✅
+});
+```

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

@@ -0,0 +1,133 @@
+---
+id: "g2-interaction-element-select-by"
+title: "G2 分组选择（elementSelectByColor / elementSelectByX）"
+description: |
+  elementSelectByColor：点击某个元素时，选中所有相同颜色（color encode 值）的元素，
+  常用于多系列折线图中点击一条线选中整条。
+  elementSelectByX：点击某个元素时，选中所有相同 X 值的元素，
+  常用于分组柱状图中选中同一 X 分类下所有柱。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "elementSelectByColor"
+  - "elementSelectByX"
+  - "分组选择"
+  - "批量选中"
+  - "interaction"
+
+related:
+  - "g2-interaction-element-highlight-by"
+  - "g2-interaction-element-select"
+  - "g2-interaction-legend-filter"
+
+use_cases:
+  - "多系列折线图：点击一个数据点选中整条折线"
+  - "分组柱状图：点击某柱选中同 X 分类的所有柱"
+  - "散点图按颜色分组批量选中"
+
+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-select"
+---
+
+## elementSelectByColor（按颜色分组选中）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { month: 'Jan', city: '北京', value: 5 },
+  { month: 'Feb', city: '北京', value: 8 },
+  { month: 'Jan', city: '上海', value: 12 },
+  { month: 'Feb', city: '上海', value: 15 },
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'month', y: 'value', color: 'city' },
+  interaction: {
+    elementSelectByColor: true,  // 点击任意数据点，选中同色的所有点
+  },
+});
+
+chart.render();
+```
+
+## elementSelectByX（按 X 分组选中）
+
+```javascript
+// 分组柱状图：点击某柱，选中该 X 值下所有分组柱
+chart.options({
+  type: 'interval',
+  data: groupedData,
+  encode: { x: 'month', y: 'value', color: 'city' },
+  transform: [{ type: 'dodgeX' }],
+  interaction: {
+    elementSelectByX: true,  // 点击某柱，选中同月份所有分组柱
+  },
+});
+```
+
+## 多重交互组合
+
+```javascript
+// 结合高亮和选中：悬停高亮同色系列，点击选中
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value', color: 'series' },
+  interaction: {
+    elementHighlightByColor: true,  // 悬停：高亮同色系列
+    elementSelectByColor: true,     // 点击：选中同色系列
+  },
+});
+```
+
+## 获取选中事件
+
+```javascript
+chart.on('element:select', (event) => {
+  const { data } = event.detail;
+  console.log('选中的数据：', data.datum);
+});
+
+chart.on('element:unselect', (event) => {
+  console.log('取消选中');
+});
+```
+
+## 常见错误与修正
+
+### 错误：elementSelectByColor 在无 color encode 时无效
+```javascript
+// ❌ 没有 color encode，无法按颜色分组选中
+chart.options({
+  type: 'line',
+  encode: { x: 'month', y: 'value' },   // ❌ 没有 color
+  interaction: { elementSelectByColor: true },  // 无效
+});
+
+// ✅ 需要 color encode
+chart.options({
+  type: 'line',
+  encode: { x: 'month', y: 'value', color: 'city' },  // ✅
+  interaction: { elementSelectByColor: true },
+});
+```
+
+### 错误：elementSelectByColor 与 elementSelect 混淆
+```javascript
+// elementSelect：只选中点击的单个元素
+chart.options({ interaction: { elementSelect: true } });
+
+// elementSelectByColor：选中所有相同 color 值的元素（批量选中）
+chart.options({ interaction: { elementSelectByColor: true } });
+```

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

@@ -0,0 +1,249 @@
+---
+id: "g2-interaction-element-select"
+title: "G2 元素选中交互（elementSelect）"
+description: |
+  G2 v5 元素选中交互通过 interaction: [{ type: 'elementSelect' }] 启用，
+  点击图形元素切换 selected 状态，支持 selected/active 状态样式自定义，
+  可配合 elementSelectByX/elementSelectByColor 实现批量选中。
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "选中"
+  - "elementSelect"
+  - "交互"
+  - "状态"
+  - "click"
+  - "spec"
+
+related:
+  - "g2-interaction-element-highlight"
+  - "g2-mark-interval-basic"
+  - "g2-interaction-tooltip"
+
+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"
+---
+
+## 基本用法（柱状图点击选中）
+
+点击柱子切换 selected 状态，再次点击取消选中：
+
+```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', color: 'genre' },
+  interaction: [
+    { type: 'elementSelect' },   // 点击元素切换 selected 状态
+  ],
+});
+
+chart.render();
+```
+
+## elementSelectByX（按 x 值批量选中）
+
+适合分组柱状图或堆叠图，点击任意一组元素时选中同一 x 位置的所有元素：
+
+```javascript
+chart.options({
+  type: 'interval',
+  data: [
+    { month: 'Jan', type: 'A', value: 120 },
+    { month: 'Jan', type: 'B', value: 80 },
+    { month: 'Feb', type: 'A', value: 160 },
+    { month: 'Feb', type: 'B', value: 95 },
+    { month: 'Mar', type: 'A', value: 140 },
+    { month: 'Mar', type: 'B', value: 110 },
+  ],
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [{ type: 'dodgeX' }],
+  interaction: [
+    { type: 'elementSelectByX' },   // 点击任意柱子，选中同 x 位置的所有柱子
+  ],
+});
+```
+
+## 自定义选中状态样式
+
+通过 `state.selected` 指定选中时的视觉样式，未选中的元素样式会相应降低：
+
+```javascript
+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', color: 'genre' },
+  state: {
+    selected: {
+      fill: '#1890ff',          // 选中时填充色
+      fillOpacity: 1,           // 选中时不透明度
+      stroke: '#003a8c',        // 选中时描边色
+      lineWidth: 2,             // 选中时描边宽度
+    },
+    unselected: {
+      fillOpacity: 0.3,         // 未选中元素半透明
+    },
+  },
+  interaction: [
+    { type: 'elementSelect' },
+  ],
+});
+```
+
+## 组合使用 highlight + select
+
+鼠标悬停触发高亮，点击触发选中，两者可同时启用：
+
+```javascript
+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', color: 'genre' },
+  state: {
+    active: {
+      fill: '#69c0ff',        // 悬停高亮色（active 状态）
+      fillOpacity: 0.9,
+    },
+    selected: {
+      fill: '#1890ff',        // 点击选中色（selected 状态）
+      fillOpacity: 1,
+      stroke: '#003a8c',
+      lineWidth: 2,
+    },
+    unselected: {
+      fillOpacity: 0.3,
+    },
+  },
+  interaction: [
+    { type: 'elementHighlight' },   // 悬停高亮（active 状态）
+    { type: 'elementSelect' },      // 点击选中（selected 状态）
+    { type: 'tooltip' },
+  ],
+});
+```
+
+## 监听选中事件
+
+```javascript
+// 监听选中和取消选中事件
+chart.on('element:select', (event) => {
+  const datum = event.data?.data;
+  console.log('选中元素数据：', datum);
+  // 可在此处联动外部面板、更新状态等
+});
+
+chart.on('element:unselect', (event) => {
+  console.log('取消选中');
+});
+```
+
+## 常见错误与修正
+
+### 错误：interaction 写成对象而非数组
+
+```javascript
+// ❌ 错误：interaction 必须是数组
+chart.options({
+  interaction: { type: 'elementSelect' },
+});
+
+// ✅ 正确
+chart.options({
+  interaction: [{ type: 'elementSelect' }],
+});
+```
+
+### 错误：使用了不存在的交互名称
+
+```javascript
+// ❌ 错误：G2 中没有 'elementClick' 这个交互类型
+chart.options({
+  interaction: [{ type: 'elementClick' }],
+});
+
+// ✅ 正确的名称
+chart.options({
+  interaction: [{ type: 'elementSelect' }],         // 单个元素选中
+  // 或
+  // interaction: [{ type: 'elementSelectByX' }],   // 按 x 值批量选中
+  // interaction: [{ type: 'elementSelectByColor' }], // 按颜色批量选中
+});
+```
+
+### 错误：选中样式不生效（state 位置错误）
+
+```javascript
+// ❌ 错误：state 不能嵌套在 style 里
+chart.options({
+  style: {
+    state: { selected: { fill: '#1890ff' } },
+  },
+});
+
+// ✅ 正确：state 与 encode、style 并列，在 Mark 配置的顶层
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'genre', y: 'sold' },
+  state: {
+    selected: { fill: '#1890ff', fillOpacity: 1 },
+  },
+  interaction: [{ type: 'elementSelect' }],
+});
+```
+
+### 错误：同时使用 elementSelect 和 elementSelectByX 导致冲突
+
+```javascript
+// ❌ 两者同时启用时行为不可预期，点击会触发双重选中逻辑
+chart.options({
+  interaction: [
+    { type: 'elementSelect' },
+    { type: 'elementSelectByX' },
+  ],
+});
+
+// ✅ 根据需求选择一种
+// - elementSelect: 只选中点击的单个元素
+// - elementSelectByX: 选中同一 x 值的所有元素（适合分组/堆叠图）
+// - elementSelectByColor: 选中同一颜色（系列）的所有元素
+chart.options({
+  interaction: [{ type: 'elementSelectByX' }],
+});
+```

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

@@ -0,0 +1,117 @@
+---
+id: "g2-interaction-fisheye"
+title: "G2 鱼眼交互（fisheye interaction）"
+description: |
+  fisheye 交互让鱼眼效果的焦点跟随鼠标移动，实现动态的焦点+上下文放大。
+  需要配合 fisheye 坐标系使用，或独立启用（会自动在 coordinate.transform 中添加 fisheye）。
+  鼠标移出图表区域时自动恢复正常视图。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "fisheye"
+  - "鱼眼"
+  - "焦点上下文"
+  - "focus context"
+  - "interaction"
+
+related:
+  - "g2-coord-fisheye"
+  - "g2-mark-point-scatter"
+
+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/fisheye"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = Array.from({ length: 300 }, (_, i) => ({
+  x: Math.random() * 100,
+  y: Math.random() * 100,
+  group: i % 5,
+}));
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'x', y: 'y', color: 'group', shape: 'point' },
+  scale: { color: { type: 'ordinal' } },
+  coordinate: { transform: [ { type: 'fisheye' } ] },  // 配合鱼眼坐标系
+  interaction: {
+    fisheye: true,   // 焦点跟随鼠标
+  },
+});
+
+chart.render();
+```
+
+## 配置鱼眼强度
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'x', y: 'y', color: 'group' },
+  coordinate: { transform: [ { type: 'fisheye' } ] },
+  interaction: {
+    fisheye: {
+      wait: 30,       // 节流等待时间（毫秒），默认 30，值越小越灵敏
+      leading: true,  // 节流 leading edge 执行，默认 undefined
+      trailing: false, // 节流 trailing edge 执行，默认 false
+    },
+  },
+});
+```
+
+## 仅 X 方向鱼眼（折线图密集区域探索）
+
+```javascript
+chart.options({
+  type: 'line',
+  data: denseTimeData,
+  encode: { x: 'date', y: 'value', color: 'type' },
+  coordinate: {
+    transform: [
+      {
+        type: 'fisheye',
+        distortionX: 4,   // X 方向放大强度
+        distortionY: 0,   // Y 方向不变形
+      }
+    ]
+  },
+  interaction: { fisheye: true },
+});
+```
+
+## 常见错误与修正
+
+### 错误：只设置 interaction.fisheye 没有设置坐标系——鱼眼效果不生效
+```javascript
+// ⚠️  interaction.fisheye 会自动添加 fisheye coordinate.transform
+// 但如果 coordinate 有其他设置，可能需要显式配置
+chart.options({
+  coordinate: { type: 'cartesian' },  // ⚠️  明确设置了笛卡尔坐标，fisheye 会追加变换
+  interaction: { fisheye: true },     // 会自动在 coordinate.transform 中插入 fisheye
+});
+
+// ✅ 最简洁的写法：直接指定 fisheye 坐标系
+chart.options({
+  coordinate: { transform: [ { type: 'fisheye' } ] },
+  interaction: { fisheye: true },
+});
+```