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

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

@@ -0,0 +1,130 @@
+---
+id: "g2-interaction-legend-filter"
+title: "G2 图例过滤交互（legendFilter）"
+description: |
+  legendFilter 让用户通过点击图例项来显示/隐藏对应的数据系列。
+  在 G2 v5 中默认已启用，点击图例项即可切换对应系列的可见性。
+  可通过配置关闭或自定义样式。legendHighlight 则是鼠标悬停时高亮对应系列。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "legendFilter"
+  - "图例过滤"
+  - "图例高亮"
+  - "legendHighlight"
+  - "交互"
+  - "interaction"
+
+related:
+  - "g2-comp-legend-config"
+  - "g2-interaction-element-highlight"
+
+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/legend-filter"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { month: 'Jan', city: '北京', temp: -3 },
+  { month: 'Feb', city: '北京', temp: 0 },
+  { month: 'Jan', city: '上海', temp: 5 },
+  { month: 'Feb', city: '上海', temp: 7 },
+  { month: 'Jan', city: '广州', temp: 15 },
+  { month: 'Feb', city: '广州', temp: 16 },
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'month', y: 'temp', color: 'city' },
+  // legendFilter 默认已启用，无需显式配置
+  // 点击图例中的城市名称即可切换可见性
+});
+
+chart.render();
+```
+
+## 显式启用 legendFilter
+
+```javascript
+// 如果被禁用，可以显式重新启用
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  interaction: {
+    legendFilter: true,   // 点击图例切换显示/隐藏
+  },
+});
+```
+
+## 同时启用 legendHighlight（悬停高亮）
+
+```javascript
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  interaction: {
+    legendFilter: true,    // 点击：过滤数据
+    legendHighlight: true, // 悬停：高亮系列
+  },
+});
+```
+
+## 禁用图例交互
+
+```javascript
+// 禁用图例过滤（图例仅用于展示，不可点击）
+chart.options({
+  interaction: {
+    legendFilter: false,  // 禁用点击过滤
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：以为 legendFilter 需要手动配置——实际上 G2 v5 默认启用
+```javascript
+// ℹ️  G2 v5 默认已启用 legendFilter，无需额外配置
+// 只有以下情况才需要显式配置：
+
+// 1. 想要禁用时
+chart.options({ interaction: { legendFilter: false } });
+
+// 2. 想要自定义样式或行为时
+chart.options({ interaction: { legendFilter: { /* 自定义选项 */ } } });
+```
+
+### 错误：legend: false 时仍想要 legendFilter——图例隐藏后无法交互
+```javascript
+// ❌ 隐藏了图例但还想要图例过滤——图例不可见就无法点击
+chart.options({
+  legend: false,
+  interaction: { legendFilter: true },  // ❌ 没有图例，过滤无从触发
+});
+
+// ✅ legendFilter 需要可见图例配合
+chart.options({
+  legend: { color: { position: 'top' } },  // ✅ 保留图例
+  interaction: { legendFilter: true },
+});
+```

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

@@ -0,0 +1,130 @@
+---
+id: "g2-interaction-legend-highlight"
+title: "G2 图例高亮（legendHighlight）"
+description: |
+  legendHighlight 交互让用户悬停图例项时，图表中对应分组的元素高亮显示，
+  其他分组元素变为半透明（inactive 状态）。
+  与 legendFilter 的区别：legendHighlight 只改变视觉状态，不过滤数据；
+  legendFilter 点击后真正隐藏数据项。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "legendHighlight"
+  - "图例高亮"
+  - "交互"
+  - "highlight"
+  - "interaction"
+
+related:
+  - "g2-interaction-legend-filter"
+  - "g2-interaction-element-highlight-by"
+  - "g2-comp-legend-config"
+
+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/legend-highlight"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { month: 'Jan', city: '北京', value: 5 },
+  { month: 'Jan', city: '上海', value: 12 },
+  { month: 'Feb', city: '北京', value: 8 },
+  { month: 'Feb', city: '上海', value: 15 },
+  { month: 'Mar', city: '北京', value: 12 },
+  { month: 'Mar', city: '上海', value: 18 },
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'month', y: 'value', color: 'city' },
+  interaction: {
+    legendHighlight: true,  // 悬停图例时高亮对应系列
+  },
+});
+
+chart.render();
+```
+
+## legendHighlight vs legendFilter 对比
+
+```javascript
+// legendHighlight：悬停图例 → 高亮对应元素，其余变半透明（不隐藏数据）
+chart.options({
+  interaction: { legendHighlight: true },
+});
+
+// legendFilter：点击图例 → 切换显示/隐藏对应数据项（数据从图表中移除）
+chart.options({
+  interaction: { legendFilter: true },
+});
+
+// 同时开启两种交互：悬停高亮 + 点击过滤
+chart.options({
+  interaction: {
+    legendHighlight: true,
+    legendFilter: true,
+  },
+});
+```
+
+## 自定义高亮样式
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+  state: {
+    active: {
+      // 激活（高亮）状态样式
+      lineWidth: 2,
+      stroke: '#000',
+    },
+    inactive: {
+      // 非激活（背景）状态样式
+      fillOpacity: 0.2,
+      strokeOpacity: 0.2,
+    },
+  },
+  interaction: {
+    legendHighlight: true,
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：图例没有 color encode 时高亮无效
+```javascript
+// ❌ 没有 color encode，图例不会与元素关联，高亮无效
+chart.options({
+  type: 'interval',
+  encode: { x: 'month', y: 'value' },   // ❌ 缺少 color encode
+  interaction: { legendHighlight: true },
+});
+
+// ✅ 需要 color encode 来建立图例与元素的关联
+chart.options({
+  type: 'interval',
+  encode: { x: 'month', y: 'value', color: 'city' },  // ✅ 有 color encode
+  interaction: { legendHighlight: true },
+});
+```

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

@@ -0,0 +1,105 @@
+---
+id: "g2-interaction-poptip"
+title: "G2 文本溢出提示（poptip）"
+description: |
+  poptip 交互在文本元素文字被截断（溢出容器）时，
+  鼠标悬停自动弹出完整文本的气泡提示框。
+  适合轴标签过长被截断、标注文字显示不全等场景，无需自定义 tooltip。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "poptip"
+  - "文本提示"
+  - "溢出"
+  - "气泡"
+  - "截断"
+  - "interaction"
+
+related:
+  - "g2-comp-tooltip-config"
+  - "g2-comp-axis-config"
+
+use_cases:
+  - "X 轴分类标签过长被截断时的完整文本提示"
+  - "图表内文本标注过长时的悬停提示"
+  - "自动处理文本溢出，无需手动配置 tooltip"
+
+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/poptip"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+// 轴标签很长的数据
+const data = [
+  { category: '人工智能与机器学习算法研究', value: 85 },
+  { category: '云计算基础设施服务', value: 72 },
+  { category: '大数据分析与可视化平台', value: 68 },
+  { category: '区块链与去中心化应用', value: 45 },
+  { category: '物联网设备管理系统', value: 60 },
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+  axis: {
+    x: {
+      labelFormatter: (v) => v.length > 6 ? v.slice(0, 6) + '...' : v,  // 截断显示
+    },
+  },
+  interaction: {
+    poptip: true,   // 开启后，悬停截断标签时自动弹出完整文本
+  },
+});
+
+chart.render();
+```
+
+## 自定义 poptip 样式
+
+```javascript
+chart.options({
+  interaction: {
+    poptip: {
+      offsetX: 8,   // 气泡横向偏移（px），默认 8
+      offsetY: 8,   // 气泡纵向偏移（px），默认 8
+      // 气泡样式（CSS 属性）
+      tip: {
+        backgroundColor: 'rgba(0,0,0,0.75)',
+        color: '#fff',
+        fontSize: '12px',
+        padding: '4px 8px',
+        borderRadius: '4px',
+      },
+    },
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：文本没有溢出时 poptip 不弹出——这是正确行为
+```javascript
+// ℹ️  poptip 只在文本真正溢出（被截断）时触发，非溢出文本不会弹出
+// 如果所有标签都完整显示，hover 时不会弹出任何提示
+// 这是设计行为，不是 bug
+
+// 如果需要对所有元素都显示提示，应该用 tooltip
+chart.options({
+  tooltip: {
+    items: [{ channel: 'x' }],   // 显示 x 轴完整值
+  },
+});
+```

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

@@ -0,0 +1,144 @@
+---
+id: "g2-interaction-scrollbar-filter"
+title: "G2 ScrollbarFilter 滚动条过滤交互"
+description: |
+  scrollbarFilter 是 G2 v5 的交互，通过图表内嵌滚动条来过滤可见数据范围。
+  与 sliderFilter 类似，但使用更紧凑的滚动条控件（而非滑块），
+  适用于数据量大、需要翻页浏览的场景（如大量类别的柱状图）。
+  需配合 scrollbar 组件（scrollbar: { x: true }）一起使用。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "scrollbarFilter"
+  - "滚动条"
+  - "scrollbar"
+  - "数据过滤"
+  - "分页"
+  - "interaction"
+
+related:
+  - "g2-interaction-slider-filter"
+  - "g2-comp-scrollbar"
+  - "g2-mark-interval-basic"
+
+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/component/scrollbar"
+---
+
+## 核心概念
+
+`scrollbarFilter` 交互需要与 `scrollbar` 组件配合：
+- `scrollbar` 字段：控制滚动条的显示位置（x 轴 / y 轴）
+- `scrollbarFilter` 交互：响应滚动条拖动事件，过滤数据范围
+
+与 `sliderFilter` 的区别：
+- `sliderFilter`：双端滑块，支持任意范围选取
+- `scrollbarFilter`：固定窗口大小的滚动条，只能平移不能缩放范围
+
+## 基本用法（X 轴滚动条）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 600, height: 400 });
+
+chart.options({
+  type: 'interval',
+   manyCategories,   // 大量类别数据
+  encode: { x: 'category', y: 'value' },
+  scrollbar: {
+    x: true,   // 启用 X 轴滚动条
+  },
+  interaction: {
+    scrollbarFilter: true,   // 启用滚动条过滤
+  },
+});
+
+chart.render();
+```
+
+## Y 轴滚动条
+
+```javascript
+chart.options({
+  type: 'interval',
+  data: manyCategories,
+  encode: { x: 'value', y: 'category' },  // 条形图
+  coordinate: { transform: [{ type: 'transpose' }] },
+  scrollbar: {
+    y: true,   // 启用 Y 轴滚动条（条形图竖向滚动）
+  },
+  interaction: {
+    scrollbarFilter: true,
+  },
+});
+```
+
+## 配置项
+
+```javascript
+chart.options({
+  scrollbar: {
+    x: {
+      ratio: 0.3,    // 滚动条初始窗口比例（显示全部数据的 30%），默认根据数据量计算
+    },
+  },
+  interaction: {
+    scrollbarFilter: {
+      // 目前 scrollbarFilter 选项较少，主要通过 scrollbar 组件配置
+    },
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：忘记配置 scrollbar 组件
+```javascript
+// ❌ 只加 interaction 但没有 scrollbar 组件，不会显示滚动条
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value' },
+  interaction: { scrollbarFilter: true },  // ❌ 没有 scrollbar 组件
+});
+
+// ✅ 必须同时配置 scrollbar 组件
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value' },
+  scrollbar: { x: true },              // ✅ 启用滚动条组件
+  interaction: { scrollbarFilter: true },  // ✅ 启用过滤交互
+});
+```
+
+### 错误：与 sliderFilter 混用
+```javascript
+// ❌ scrollbar 与 slider 同时启用会冲突
+chart.options({
+  scrollbar: { x: true },
+  slider: { x: true },
+  interaction: {
+    scrollbarFilter: true,
+    sliderFilter: true,   // ❌ 不要同时启用
+  },
+});
+
+// ✅ 选择其中一种
+chart.options({
+  scrollbar: { x: true },
+  interaction: { scrollbarFilter: true },
+});
+```