@loom-framework/core 0.1.0-alpha.9 → 0.1.0-alpha.90

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

@@ -0,0 +1,122 @@
+---
+id: "g2-interaction-brush-filter"
+title: "G2 刷选过滤交互（brushFilter）"
+description: |
+  brushFilter 允许用户在图表上拖拽绘制矩形区域来过滤数据。
+  与 brushHighlight 不同，brushFilter 会直接过滤掉选区外的数据点，
+  只保留选中区域内的数据。支持 x/y 方向单轴过滤和二维矩形过滤。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "brush"
+  - "brushFilter"
+  - "刷选"
+  - "过滤"
+  - "交互"
+  - "interaction"
+
+related:
+  - "g2-interaction-brush"
+  - "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/brush-filter"
+---
+
+## 最小可运行示例（散点图刷选过滤）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = Array.from({ length: 300 }, () => ({
+  x: Math.random() * 100,
+  y: Math.random() * 100,
+  group: Math.floor(Math.random() * 4),
+}));
+
+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' } },
+  interaction: {
+    brushFilter: true,   // 启用刷选过滤：拖拽矩形区域过滤数据
+  },
+});
+
+chart.render();
+```
+
+## 仅 X 轴方向刷选（时间范围过滤）
+
+```javascript
+chart.options({
+  type: 'line',
+  data: timeData,
+  encode: { x: 'date', y: 'value', color: 'type' },
+  interaction: {
+    brushXFilter: true,   // 仅 X 轴方向的刷选过滤（常用于时间筛选）
+  },
+});
+```
+
+## 自定义刷选样式
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'x', y: 'y' },
+  interaction: {
+    brushFilter: {
+      maskFill: '#1890ff',
+      maskFillOpacity: 0.15,
+      maskStroke: '#1890ff',
+      maskLineWidth: 1.5,
+    },
+  },
+});
+```
+
+## 刷选高亮 vs 刷选过滤
+
+```javascript
+// brushHighlight：选区外的元素变暗（全部数据仍可见）
+chart.options({ interaction: { brushHighlight: true } });
+
+// brushFilter：选区外的元素被过滤掉（只剩选中数据）
+chart.options({ interaction: { brushFilter: true } });
+```
+
+## 常见错误与修正
+
+### 错误：brushFilter 和 brushHighlight 同时启用——行为冲突
+```javascript
+// ❌ 两者同时启用会产生冲突
+chart.options({
+  interaction: {
+    brushFilter: true,
+    brushHighlight: true,  // ❌ 与 brushFilter 冲突
+  },
+});
+
+// ✅ 只启用其中一个
+chart.options({
+  interaction: {
+    brushFilter: true,  // ✅ 过滤模式
+  },
+});
+```

package/builtin-skills/antv-g2-chart/references/interactions/g2-interaction-brush-x-y-highlight.md

@@ -0,0 +1,127 @@
+---
+id: "g2-interaction-brush-x-highlight"
+title: "G2 BrushXHighlight / BrushYHighlight 单轴框选高亮"
+description: |
+  brushXHighlight 和 brushYHighlight 是 G2 v5 的交互，
+  限制框选范围在 X 轴方向（或 Y 轴方向），高亮选中区域内的图元，非选中区域半透明淡出。
+  适用于时间序列对比、趋势局部聚焦等场景。
+  若需要过滤数据而非高亮，请使用 brushXFilter / brushYFilter。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "brushXHighlight"
+  - "brushYHighlight"
+  - "框选高亮"
+  - "X轴框选"
+  - "Y轴框选"
+  - "interaction"
+  - "highlight"
+
+related:
+  - "g2-interaction-brush"
+  - "g2-interaction-brush-filter"
+  - "g2-interaction-brush-xy"
+
+use_cases:
+  - "时间轴上圈选某段时间段，高亮对应数据点"
+  - "横向对比图表中选取某几个分类高亮"
+  - "散点图中按 Y 轴范围高亮异常值区域"
+
+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/brush-x-highlight"
+---
+
+## 核心概念
+
+- `brushXHighlight`：仅在 X 轴方向框选，选中元素高亮，其余淡出
+- `brushYHighlight`：仅在 Y 轴方向框选，选中元素高亮，其余淡出
+- 高亮效果不过滤数据，所有数据仍然可见（与 `brushXFilter` 区别）
+
+## BrushXHighlight 基本用法
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 800, height: 400 });
+
+chart.options({
+  type: 'line',
+  data: timeSeriesData,
+  encode: { x: 'date', y: 'value', color: 'type' },
+  interaction: {
+    brushXHighlight: true,   // 启用 X 轴框选高亮
+  },
+});
+
+chart.render();
+```
+
+## BrushYHighlight 基本用法
+
+```javascript
+chart.options({
+  type: 'point',
+  data: scatterData,
+  encode: { x: 'x', y: 'y', color: 'category' },
+  interaction: {
+    brushYHighlight: true,   // 启用 Y 轴框选高亮
+  },
+});
+```
+
+## 配置项
+
+```javascript
+chart.options({
+  interaction: {
+    brushXHighlight: {
+      series: true,      // 高亮同系列所有点（折线图中选中一点则整条线高亮），默认 true
+      state: {
+        // 自定义高亮/非高亮状态样式
+        selected: {
+          lineWidth: 2,
+          opacity: 1,
+        },
+        unselected: {
+          opacity: 0.2,
+        },
+      },
+    },
+  },
+});
+```
+
+## X/Y 同时框选（自由框选）
+
+```javascript
+// 如需自由框选（同时限制 X 和 Y），使用 brushHighlight
+chart.options({
+  interaction: {
+    brushHighlight: true,    // 自由矩形框选高亮
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：把高亮和过滤混淆
+```javascript
+// ❌ 以为 brushXHighlight 会过滤掉非选中数据
+// brushXHighlight 只改变透明度，数据仍然全部显示
+
+// ✅ 如果需要过滤数据（非选中区域从图表中移除），使用：
+chart.options({
+  interaction: { brushXFilter: true },   // 过滤模式，非选中数据消失
+});
+
+// ✅ 如果只需要高亮不过滤，使用：
+chart.options({
+  interaction: { brushXHighlight: true },   // 高亮模式，非选中数据淡出
+});
+```

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

@@ -0,0 +1,118 @@
+---
+id: "g2-interaction-brush-xy"
+title: "G2 单轴框选（brushXHighlight / brushYHighlight / brushXFilter / brushYFilter）"
+description: |
+  单轴框选交互限制刷选只在一个方向上生效：
+  - brushXHighlight/brushYHighlight：框选高亮，不过滤数据
+  - brushXFilter/brushYFilter：框选并过滤数据（隐藏框选范围外的元素）
+  X 方向框选适合时间序列的区间选择，Y 方向框选适合数值范围筛选。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "brushXHighlight"
+  - "brushYHighlight"
+  - "brushXFilter"
+  - "brushYFilter"
+  - "单轴框选"
+  - "刷选"
+  - "interaction"
+
+related:
+  - "g2-interaction-brush-filter"
+  - "g2-interaction-brush-axis"
+  - "g2-comp-slider"
+
+use_cases:
+  - "时间序列图表：X 方向框选时间区间高亮"
+  - "散点图：Y 方向框选数值范围筛选"
+  - "折线图区间对比标注"
+
+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/brush-highlight"
+---
+
+## brushXHighlight（X 方向框选高亮）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 800, height: 400 });
+
+chart.options({
+  type: 'line',
+  data: timeSeriesData,
+  encode: { x: 'date', y: 'value', color: 'series' },
+  interaction: {
+    brushXHighlight: true,  // 横向框选，高亮选中区间的折线
+  },
+});
+
+chart.render();
+```
+
+## brushXFilter（X 方向框选过滤）
+
+```javascript
+// 框选后只显示框选区间内的数据
+chart.options({
+  type: 'point',
+  data: scatterData,
+  encode: { x: 'date', y: 'value', color: 'category' },
+  interaction: {
+    brushXFilter: true,   // 框选 X 范围，过滤范围外的点
+  },
+});
+```
+
+## brushYFilter（Y 方向框选过滤）
+
+```javascript
+// 框选数值范围，只显示 Y 值在选中区间内的数据
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'x', y: 'y', color: 'category', size: 'value' },
+  interaction: {
+    brushYFilter: true,   // 纵向框选，过滤 Y 范围外的点
+  },
+});
+```
+
+## 四种框选交互对比
+
+```javascript
+// brushHighlight   → 二维框选，高亮（不过滤）
+// brushFilter      → 二维框选，过滤数据
+// brushXHighlight  → X 方向框选，高亮
+// brushXFilter     → X 方向框选，过滤
+// brushYHighlight  → Y 方向框选，高亮
+// brushYFilter     → Y 方向框选，过滤
+
+// 在散点图上同时支持高亮（单 X 轴框选）
+chart.options({
+  interaction: {
+    brushXHighlight: {
+      series: true,        // 是否高亮同系列其他点
+    },
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：brushXFilter 与 brushFilter 效果相同的误解
+```javascript
+// brushFilter 可以在 X/Y 两个方向同时框选一个矩形区域
+chart.options({ interaction: { brushFilter: true } });  // 二维矩形框选
+
+// brushXFilter 只能在 X 方向拖拽，形成一个竖直条带
+chart.options({ interaction: { brushXFilter: true } }); // 仅 X 轴方向
+
+// 使用场景不同：时间序列用 brushXFilter 更直观
+```

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

@@ -0,0 +1,184 @@
+---
+id: "g2-interaction-brush"
+title: "G2 框选交互（brush）"
+description: |
+  G2 v5 内置框选交互，通过 interaction: [{ type: 'brushHighlight' }] 或 brushFilter
+  实现鼠标拖拽框选、高亮/过滤数据点。常用于散点图、折线图等需要局部聚焦的场景。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "brush"
+  - "框选"
+  - "interaction"
+  - "brushHighlight"
+  - "brushFilter"
+  - "交互"
+  - "spec"
+
+related:
+  - "g2-mark-point-scatter"
+  - "g2-interaction-element-highlight"
+  - "g2-core-view-composition"
+
+use_cases:
+  - "散点图中框选关注的数据点区域"
+  - "时间序列图中框选某段时间范围并过滤"
+  - "大数据集局部聚焦分析"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/interaction/brush-highlight"
+---
+
+## 基本用法（brushHighlight：框选高亮）
+
+拖拽鼠标框选数据点，选中区域高亮，未选中区域变暗：
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'point',
+  data: [
+    { x: 1, y: 4.8, category: 'A' },
+    { x: 2, y: 3.2, category: 'B' },
+    { x: 3, y: 6.1, category: 'A' },
+    { x: 4, y: 2.5, category: 'C' },
+    { x: 5, y: 7.3, category: 'B' },
+    { x: 6, y: 5.0, category: 'A' },
+    { x: 7, y: 1.8, category: 'C' },
+  ],
+  encode: { x: 'x', y: 'y', color: 'category', size: 8 },
+  interaction: [
+    { type: 'brushHighlight' },   // 框选高亮
+  ],
+});
+
+chart.render();
+```
+
+## brushFilter：框选过滤
+
+框选后只保留选中区域内的数据点（其余被移除）：
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'x', y: 'y', color: 'category' },
+  interaction: [
+    { type: 'brushFilter' },   // 框选过滤（只显示选中区域的点）
+  ],
+});
+```
+
+## 散点图 + 框选 + 详情联动
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: {
+    x: 'income',
+    y: 'happiness',
+    color: 'region',
+    size: 'population',
+  },
+  scale: {
+    size: { range: [4, 20] },
+  },
+  interaction: [
+    { type: 'brushHighlight' },
+    { type: 'tooltip' },         // 同时保留 tooltip 交互
+  ],
+  legend: { color: { position: 'top' } },
+});
+```
+
+## 单轴框选（只横向/纵向）
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'date', y: 'price' },
+  interaction: [
+    {
+      type: 'brushXHighlight',   // 只允许横向框选（按时间范围）
+    },
+  ],
+});
+
+// 纵向框选：brushYHighlight
+chart.options({
+  interaction: [{ type: 'brushYHighlight' }],
+});
+```
+
+## 框选 + 联动其他图表
+
+通过监听事件，实现多图联动：
+
+```javascript
+const chart = new Chart({ container: 'container', width: 700, height: 400 });
+
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'x', y: 'y', color: 'type' },
+  interaction: [{ type: 'brushFilter' }],
+});
+
+chart.render();
+
+// 监听框选事件
+chart.on('brush:filter', (event) => {
+  const filteredData = event.data.items;   // 框选后的剩余数据
+  console.log('选中数据：', filteredData);
+  // 可据此更新其他图表...
+});
+```
+
+## 常见错误与修正
+
+### 错误：interaction 写成对象而非数组
+```javascript
+// ❌ 错误：interaction 必须是数组
+chart.options({
+  interaction: { type: 'brushHighlight' },
+});
+
+// ✅ 正确：数组格式
+chart.options({
+  interaction: [{ type: 'brushHighlight' }],
+});
+```
+
+### 错误：同时启用 brushHighlight 和 brushFilter
+```javascript
+// ❌ 不推荐：两者功能冲突，同时使用会产生意外行为
+chart.options({
+  interaction: [
+    { type: 'brushHighlight' },
+    { type: 'brushFilter' },
+  ],
+});
+
+// ✅ 正确：根据需求选其一
+chart.options({
+  interaction: [{ type: 'brushHighlight' }],  // 高亮但保留所有点
+  // 或
+  // interaction: [{ type: 'brushFilter' }],  // 过滤只显示选中点
+});
+```

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

@@ -0,0 +1,170 @@
+---
+id: "g2-interaction-brushx-filter"
+title: "G2 BrushXFilter Interaction"
+description: |
+  X 轴方向刷选过滤交互。用户可以通过拖拽选择 X 轴范围，
+  过滤显示该范围内的数据。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "刷选"
+  - "过滤"
+  - "brush"
+  - "X轴"
+  - "数据筛选"
+
+related:
+  - "g2-interaction-brush-filter"
+  - "g2-interaction-brushy-filter"
+  - "g2-interaction-brushx-highlight"
+
+use_cases:
+  - "时间范围筛选"
+  - "X 轴区间选择"
+  - "数据缩放查看"
+
+anti_patterns:
+  - "需要 Y 轴方向筛选时改用 BrushYFilter"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/interaction"
+---
+
+## 核心概念
+
+BrushXFilter 交互允许用户在 X 轴方向拖拽选择一个区间，图表会自动过滤并只显示该区间内的数据。
+
+**特点：**
+- 只能在 X 轴方向选择
+- 选择后自动过滤数据
+- 支持重置选择
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'line',
+  data: [
+    { date: '2024-01', value: 100 },
+    { date: '2024-02', value: 120 },
+    { date: '2024-03', value: 150 },
+    { date: '2024-04', value: 130 },
+    { date: '2024-05', value: 160 },
+  ],
+  encode: {
+    x: 'date',
+    y: 'value',
+  },
+  interaction: {
+    brushXFilter: true,
+  },
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 自定义样式
+
+```javascript
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value' },
+  interaction: {
+    brushXFilter: {
+      brushStyle: {
+        fill: '#1890ff',
+        fillOpacity: 0.2,
+        stroke: '#1890ff',
+      },
+    },
+  },
+});
+```
+
+### 设置初始选区
+
+```javascript
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value' },
+  interaction: {
+    brushXFilter: {
+      selection: [0.2, 0.8],  // 初始选区比例 [start, end]
+    },
+  },
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface BrushXFilterInteraction {
+  brushXFilter: boolean | {
+    brushStyle?: {
+      fill?: string;
+      fillOpacity?: number;
+      stroke?: string;
+      lineWidth?: number;
+    };
+    selection?: [number, number];  // [startRatio, endRatio]
+    // 其他配置继承自 BrushFilter
+  };
+}
+```
+
+## 与 BrushFilter/BrushYFilter 的对比
+
+| Interaction | 选择方向 | 常用场景 |
+|-------------|---------|---------|
+| brushFilter | 任意方向 | 通用筛选 |
+| brushXFilter | 仅 X 方向 | 时间范围筛选 |
+| brushYFilter | 仅 Y 方向 | 数值范围筛选 |
+
+## 常见错误与修正
+
+### 错误 1：与其他 brush 交互冲突
+
+```javascript
+// ❌ 错误：同时启用多个 brush 交互可能冲突
+interaction: {
+  brushXFilter: true,
+  brushYFilter: true,
+}
+
+// ✅ 正确：根据需求选择一个
+interaction: {
+  brushXFilter: true,
+}
+```
+
+### 错误 2：selection 参数格式错误
+
+```javascript
+// ❌ 错误：selection 应该是比例值 [0-1]
+interaction: {
+  brushXFilter: { selection: ['2024-01', '2024-03'] }
+}
+
+// ✅ 正确：使用比例值
+interaction: {
+  brushXFilter: { selection: [0.2, 0.6] }
+}
+```