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

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

@@ -0,0 +1,231 @@
+---
+id: "g2-interaction-slider-filter"
+title: "G2 缩略轴过滤（slider filter）"
+description: |
+  G2 v5 缩略轴通过 slider: { x: true } 或 interaction: [{ type: 'sliderFilter' }] 启用，
+  拖动滑块过滤 x/y 轴数据范围，常用于时序图的局部时间段筛选。
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "缩略轴"
+  - "slider"
+  - "过滤"
+  - "时序"
+  - "范围筛选"
+  - "spec"
+
+related:
+  - "g2-mark-line-basic"
+  - "g2-interaction-tooltip"
+  - "g2-scale-time"
+
+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/component/slider"
+---
+
+## 基本用法（时序折线图 + x 轴缩略轴）
+
+在折线图底部添加缩略轴，拖动滑块筛选时间范围：
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 720,
+  height: 480,
+});
+
+// 生成 30 天时序数据
+const data = Array.from({ length: 30 }, (_, i) => ({
+  date: new Date(2024, 0, i + 1).toISOString().slice(0, 10),
+  value: Math.round(200 + Math.random() * 300),
+}));
+
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value' },
+  slider: {
+    x: true,   // 在 x 轴下方显示缩略轴
+  },
+});
+
+chart.render();
+```
+
+## 设置初始显示范围
+
+`values` 接受 `[0, 1]` 区间的比例值，控制缩略轴初始选中范围：
+
+```javascript
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value' },
+  slider: {
+    x: {
+      values: [0.6, 1.0],   // 初始只显示后 40% 的数据
+    },
+  },
+});
+```
+
+## 双轴缩略轴（x 轴 + y 轴同时过滤）
+
+同时在 x 轴和 y 轴添加缩略轴，适合散点图等二维数据探索：
+
+```javascript
+chart.options({
+  type: 'point',
+  data: [
+    { price: 12000, score: 85, brand: 'A' },
+    { price: 8500,  score: 72, brand: 'B' },
+    { price: 23000, score: 91, brand: 'C' },
+    { price: 5000,  score: 60, brand: 'D' },
+    { price: 18000, score: 88, brand: 'E' },
+    { price: 31000, score: 95, brand: 'F' },
+    { price: 9500,  score: 78, brand: 'G' },
+  ],
+  encode: { x: 'price', y: 'score', color: 'brand' },
+  slider: {
+    x: {
+      values: [0, 0.7],   // x 轴初始显示 0-70%
+    },
+    y: {
+      values: [0.2, 1.0], // y 轴初始显示 20%-100%
+    },
+  },
+});
+```
+
+## 自定义 label 格式
+
+通过 `labelFormatter` 格式化缩略轴两端的标签显示：
+
+```javascript
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value' },
+  slider: {
+    x: {
+      values: [0.4, 1.0],
+      labelFormatter: (value) => {
+        // value 是实际数据值（经过比例换算后的原始数据）
+        const date = new Date(value);
+        return `${date.getMonth() + 1}月${date.getDate()}日`;
+      },
+    },
+  },
+});
+```
+
+## 使用 interaction 方式启用
+
+也可以通过 `interaction` 数组启用 sliderFilter，两种写法效果相同：
+
+```javascript
+// 方式一：slider 属性（推荐，更简洁）
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value' },
+  slider: { x: true },
+});
+
+// 方式二：interaction 数组
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value' },
+  interaction: [
+    { type: 'sliderFilter' },
+  ],
+});
+```
+
+## 常见错误与修正
+
+### 错误：values 超出 [0, 1] 范围
+
+```javascript
+// ❌ values 必须在 [0, 1] 区间，代表数据比例
+chart.options({
+  slider: {
+    x: { values: [10, 80] },   // 错误：不是像素或索引，是 0-1 比例
+  },
+});
+
+// ✅ 正确：使用 0-1 之间的小数
+chart.options({
+  slider: {
+    x: { values: [0.1, 0.8] },   // 显示 10% 到 80% 的数据
+  },
+});
+```
+
+### 错误：在离散分类轴上使用 sliderFilter
+
+```javascript
+// ❌ slider 主要适合连续轴（时间轴、数值轴），
+// 在纯分类 x 轴上效果不佳，过滤逻辑可能不符合预期
+chart.options({
+  type: 'interval',
+  data: [{ genre: 'Sports', sold: 275 }, { genre: 'Action', sold: 120 }],
+  encode: { x: 'genre', y: 'sold' },   // genre 是离散分类
+  slider: { x: true },
+});
+
+// ✅ sliderFilter 最适合时序数据或大量连续数值数据
+chart.options({
+  type: 'line',
+  data: timeSeriesData,
+  encode: { x: 'date', y: 'value' },   // date 是时间轴
+  slider: { x: true },
+});
+```
+
+### 错误：slider 写成数组
+
+```javascript
+// ❌ slider 是对象，不是数组
+chart.options({
+  slider: [{ x: true }],
+});
+
+// ✅ slider 是对象，x/y 是其属性
+chart.options({
+  slider: { x: true },
+  // 或同时启用双轴
+  // slider: { x: true, y: true },
+});
+```
+
+### 错误：values 顺序写反（起始值大于结束值）
+
+```javascript
+// ❌ 起始值不能大于结束值
+chart.options({
+  slider: {
+    x: { values: [0.8, 0.2] },
+  },
+});
+
+// ✅ 第一个值为起始位置，第二个值为结束位置（均为 0-1 比例）
+chart.options({
+  slider: {
+    x: { values: [0.2, 0.8] },
+  },
+});
+```

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

@@ -0,0 +1,138 @@
+---
+id: "g2-interaction-slider-wheel"
+title: "G2 SliderWheel 滚轮缩放交互"
+description: |
+  sliderWheel 是 G2 v5 的交互，通过鼠标滚轮（或触控板双指滚动）对图表的 slider 组件进行缩放操作。
+  鼠标滚轮向上缩小时间窗口（放大），向下扩大时间窗口（缩小），
+  缩放以鼠标位置为中心。需配合 slider 组件和 sliderFilter 交互使用。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "sliderWheel"
+  - "滚轮缩放"
+  - "wheel"
+  - "zoom"
+  - "缩放"
+  - "interaction"
+  - "slider"
+
+related:
+  - "g2-interaction-slider-filter"
+  - "g2-comp-slider"
+  - "g2-mark-line-basic"
+
+use_cases:
+  - "时序图表用滚轮快速缩放时间范围"
+  - "替代手动拖拽 slider 的快速缩放操作"
+  - "触控板双指捏合缩放图表时间轴"
+
+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/slider-wheel"
+---
+
+## 核心概念
+
+`sliderWheel` 监听图表容器的 `wheel` 事件，将滚轮 delta 转换为 slider 值域的缩放变化。
+- 滚轮向上（delta < 0）：缩小窗口（放大数据）
+- 滚轮向下（delta > 0）：扩大窗口（缩小数据）
+- 缩放以鼠标位置为中心，保持鼠标下的数据点不动
+
+## 基本用法
+
+```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' },
+  slider: {
+    x: { values: [0, 0.3] },   // 初始显示前 30%
+  },
+  interaction: {
+    sliderFilter: true,    // 必须先启用 sliderFilter
+    sliderWheel: true,     // 再启用 sliderWheel
+  },
+});
+
+chart.render();
+```
+
+## 配置项
+
+```javascript
+chart.options({
+  interaction: {
+    sliderWheel: {
+      x: true,               // X 轴 slider 响应滚轮，默认 true
+      y: true,               // Y 轴 slider 响应滚轮，默认 true
+      // x: 'shift',         // 仅在按住 Shift 时响应
+      // y: 'ctrl',          // 仅在按住 Ctrl 时响应
+      wheelSensitivity: 0.05,  // 滚轮灵敏度，默认 0.05
+      minRange: 0.01,          // 最小缩放范围（防止过度放大），默认 0.01
+    },
+  },
+});
+```
+
+## 修饰键控制（避免与页面滚动冲突）
+
+```javascript
+// 按住 Ctrl 时才缩放图表（避免与页面滚动冲突）
+chart.options({
+  interaction: {
+    sliderWheel: {
+      x: 'ctrl',    // 仅 Ctrl+滚轮 触发 X 轴缩放
+      y: false,     // Y 轴不响应滚轮
+    },
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：忘记同时启用 sliderFilter
+```javascript
+// ❌ 只有 sliderWheel 没有 sliderFilter，滚轮滚动无效果
+chart.options({
+  slider: { x: true },
+  interaction: {
+    sliderWheel: true,   // ❌ 缺少 sliderFilter
+  },
+});
+
+// ✅ 必须配合 sliderFilter
+chart.options({
+  slider: { x: true },
+  interaction: {
+    sliderFilter: true,   // ✅ 先启用过滤
+    sliderWheel: true,    // ✅ 再启用滚轮缩放
+  },
+});
+```
+
+### 错误：没有 slider 组件但启用了 sliderWheel
+```javascript
+// ❌ 没有 slider 组件时 sliderWheel 不起作用
+chart.options({
+  // 没有 slider 配置
+  interaction: { sliderWheel: true },  // 无效
+});
+
+// ✅ 必须有 slider 组件
+chart.options({
+  slider: { x: { values: [0, 0.5] } },
+  interaction: {
+    sliderFilter: true,
+    sliderWheel: true,
+  },
+});
+```

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

@@ -0,0 +1,192 @@
+---
+id: "g2-interaction-tooltip"
+title: "G2 Tooltip 交互配置"
+description: |
+  配置 G2 图表的 Tooltip 提示框，包括内容定制、格式化和自定义渲染。
+  在 Spec 模式中，Mark 级别的 tooltip 字段控制内容，
+  图表级别的 interaction 字段控制 Tooltip 行为。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "Tooltip"
+  - "提示框"
+  - "tooltip"
+  - "交互"
+  - "悬停"
+  - "hover"
+  - "spec"
+
+related:
+  - "g2-core-chart-init"
+  - "g2-interaction-crosshair"
+
+use_cases:
+  - "为图表添加数据悬停提示"
+  - "自定义 Tooltip 展示的字段和格式"
+  - "关闭不需要的 Tooltip"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/component/tooltip"
+---
+
+## 核心概念
+
+G2 Spec 模式中 Tooltip 有两个配置位置：
+- **Mark 级别 `tooltip` 字段**：控制该 Mark 的 Tooltip 显示内容
+- **图表级别 `interaction` 字段**：控制 Tooltip 的触发行为和自定义渲染
+
+G2 默认已启用 Tooltip，鼠标悬停时显示当前元素的数据。
+
+## 基本用法（Spec 模式）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'genre', y: 'sold' },
+  tooltip: {
+    title: 'genre',     // Tooltip 标题字段
+    items: [
+      { field: 'sold', name: '销量', valueFormatter: (v) => `${v} 万` },
+    ],
+  },
+});
+
+chart.render();
+```
+
+## tooltip 字段详细配置
+
+```javascript
+chart.options({
+  type: 'interval',
+  data: [...],
+  encode: { x: 'x', y: 'y' },
+  tooltip: {
+    // 标题：字段名字符串 | 固定字符串 | 函数
+    title: 'name',
+
+    // items：定义 Tooltip 中展示的数据行
+    items: [
+      // 写法 1：字段名字符串（快捷写法）
+      'value',
+
+      // 写法 2：对象配置
+      {
+        field: 'value',                              // 数据字段
+        name: '数值',                                // 显示名称
+        valueFormatter: (v) => `${v.toFixed(2)}%`,  // 值格式化
+        color: '#1890ff',                            // 颜色标记
+      },
+
+      // 写法 3：函数（完全自定义）
+      (data) => ({
+        name: '计算值',
+        value: data.a + data.b,
+      }),
+    ],
+  },
+});
+```
+
+## 关闭 Tooltip
+
+```javascript
+// 关闭整个图表的 Tooltip
+chart.options({
+  type: 'interval',
+  data: [...],
+  encode: { x: 'x', y: 'y' },
+  interaction: { tooltip: false },   // 图表级别关闭
+});
+
+// 或关闭特定 Mark 的 Tooltip 内容（传 false）
+chart.options({
+  type: 'interval',
+  tooltip: false,   // 该 Mark 不提供 Tooltip 内容
+});
+```
+
+## 自定义 Tooltip 渲染（HTML）
+
+```javascript
+chart.options({
+  type: 'interval',
+  data: [...],
+  encode: { x: 'genre', y: 'sold' },
+  interaction: {
+    tooltip: {
+      render: (event, { title, items }) => `
+        <div style="padding: 8px 12px; background: white; border: 1px solid #ddd; border-radius: 4px;">
+          <strong>${title}</strong>
+          ${items.map(item => `
+            <div style="display: flex; justify-content: space-between; gap: 16px; margin-top: 4px;">
+              <span style="color: ${item.color}">${item.name}</span>
+              <span>${item.value}</span>
+            </div>
+          `).join('')}
+        </div>
+      `,
+    },
+  },
+});
+```
+
+## 在 view 容器中配置 Tooltip
+
+```javascript
+// 多 Mark 叠加时，在外层 view 统一配置 Tooltip
+chart.options({
+  type: 'view',
+  data: [...],
+  interaction: { tooltip: { shared: true } },  // 共享 Tooltip（多 Mark 合并展示）
+  children: [
+    {
+      type: 'line',
+      encode: { x: 'month', y: 'value', color: 'type' },
+      tooltip: { items: [{ field: 'value', name: '数值' }] },
+    },
+    {
+      type: 'point',
+      encode: { x: 'month', y: 'value', color: 'type' },
+      tooltip: false,    // 点 Mark 不单独触发 Tooltip
+    },
+  ],
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：tooltip 写在了 style 里
+```javascript
+// ❌ 错误
+chart.options({ type: 'interval',  [...], style: { tooltip: { title: 'name' } } });
+
+// ✅ 正确：tooltip 是与 encode/style 同级的字段
+chart.options({ type: 'interval',  [...], tooltip: { title: 'name' } });
+```
+
+### 错误 2：interaction.tooltip 与 mark.tooltip 职责混淆
+```javascript
+// ❌ 错误：把内容配置写在 interaction 里
+chart.options({
+  interaction: { tooltip: { items: [{ field: 'value' }] } },  // 无效！
+});
+
+// ✅ 正确：内容配置在 mark 的 tooltip 字段；行为配置在 interaction.tooltip
+chart.options({
+  type: 'interval',
+  tooltip: { items: [{ field: 'value', name: '数值' }] },  // 内容
+  interaction: { tooltip: { shared: true } },              // 行为
+});
+```

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

@@ -0,0 +1,152 @@
+---
+id: "g2-interaction-treemap-drilldown"
+title: "G2 矩形树图下钻（treemapDrillDown）"
+description: |
+  treemapDrillDown 为矩形树图（treemap）提供层级下钻交互，
+  点击矩形块进入下一层级，顶部显示面包屑导航可返回上级。
+  与 drillDown（用于 partition/sunburst）不同，专为 treemap 布局设计。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "treemapDrillDown"
+  - "矩形树图"
+  - "下钻"
+  - "层级"
+  - "面包屑"
+  - "interaction"
+
+related:
+  - "g2-mark-treemap"
+  - "g2-interaction-drilldown"
+  - "g2-mark-partition"
+
+use_cases:
+  - "多层级目录/文件大小可视化"
+  - "产品分类层级销售分析"
+  - "组织架构矩形树图下钻"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/hierarchy/treemap/#treemap-drill-down"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+// 多层级树形数据
+const hierarchyData = {
+  name: '总销售额',
+  children: [
+    {
+      name: '电子产品',
+      children: [
+        { name: '手机', value: 400 },
+        { name: '电脑', value: 350 },
+        { name: '平板', value: 200 },
+      ],
+    },
+    {
+      name: '服装',
+      children: [
+        { name: '男装', value: 280 },
+        { name: '女装', value: 320 },
+      ],
+    },
+    {
+      name: '食品',
+      children: [
+        { name: '零食', value: 180 },
+        { name: '饮料', value: 150 },
+      ],
+    },
+  ],
+};
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'treemap',
+  data: hierarchyData,
+  encode: { value: 'value', color: 'name' },
+  style: {
+    labelText: (d) => d.data.name,
+    labelFill: '#fff',
+    stroke: '#fff',
+    lineWidth: 1,
+  },
+  interaction: {
+    treemapDrillDown: {
+      // 面包屑导航样式
+      breadCrumbFill: 'rgba(0,0,0,0.85)',
+      breadCrumbFontSize: 12,
+      activeFill: 'rgba(0,0,0,0.5)',
+    },
+  },
+});
+
+chart.render();
+```
+
+## treemapDrillDown vs drillDown 对比
+
+```javascript
+// treemapDrillDown：专为 treemap（矩形树图）设计
+chart.options({
+  type: 'treemap',
+  interaction: { treemapDrillDown: true },
+});
+
+// drillDown：用于 partition（旭日图/冰柱图）
+chart.options({
+  type: 'partition',
+  interaction: { drillDown: true },
+  coordinate: { type: 'polar' },   // 旭日图用极坐标
+});
+```
+
+## 常见错误与修正
+
+### 错误：在非 treemap mark 上使用 treemapDrillDown
+```javascript
+// ❌ treemapDrillDown 只适用于 treemap mark
+chart.options({
+  type: 'partition',   // ❌ 应用 drillDown，不是 treemapDrillDown
+  interaction: { treemapDrillDown: true },
+});
+
+// ✅ partition 使用 drillDown
+chart.options({
+  type: 'partition',
+  interaction: { drillDown: true },   // ✅
+});
+
+// ✅ treemap 使用 treemapDrillDown
+chart.options({
+  type: 'treemap',
+  interaction: { treemapDrillDown: true },  // ✅
+});
+```
+
+### 错误：数据不是嵌套层级结构
+```javascript
+// ❌ 扁平数据无法下钻
+chart.options({
+  type: 'treemap',
+  data: [{ name: 'a', value: 10 }, { name: 'b', value: 20 }],  // ❌ 无层级
+  interaction: { treemapDrillDown: true },
+});
+
+// ✅ 需要嵌套 children 结构
+chart.options({
+  type: 'treemap',
+   { name: 'root', children: [...] },  // ✅ 嵌套层级
+  interaction: { treemapDrillDown: true },
+});
+```