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

package/builtin-skills/antv-g2-chart/references/marks/g2-mark-spiral.md

@@ -0,0 +1,257 @@
+---
+id: "g2-mark-spiral"
+title: "G2 螺旋图（spiral）"
+description: |
+  螺旋图使用 helix 坐标系（coordinate.type: 'helix'）将时间序列数据绘制成螺旋形状，
+  从中心向外延伸。适合展示大量时间序列数据的周期性规律和变化趋势（通常 100+ 数据点）。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "螺旋图"
+  - "spiral"
+  - "helix"
+  - "时间序列"
+  - "周期性"
+  - "大数据量"
+
+related:
+  - "g2-mark-line-basic"
+  - "g2-mark-interval-basic"
+
+use_cases:
+  - "大量时间序列数据的趋势展示（100+ 数据点）"
+  - "周期性数据规律识别（如年度季节性）"
+  - "基因表达时间序列"
+
+anti_patterns:
+  - "少量数据（< 30 条）不适合，改用折线图"
+  - "需要精确数值对比不适合，螺旋非线性坐标难以精确读值"
+  - "animate.enter 不能使用 growInX/growInY，会导致螺旋渲染残缺，必须用 fadeIn"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-04-01"
+updated: "2025-04-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/general/spiral"
+---
+
+## 核心概念
+
+**螺旋图 = interval/line mark + `coordinate: { type: 'helix', startAngle, endAngle }`**
+
+- `coordinate.type: 'helix'`：阿基米德螺旋坐标系
+- `startAngle`：螺旋起始角（弧度），`Math.PI / 2` ≈ 从顶部开始
+- `endAngle`：螺旋结束角，值越大螺旋圈数越多
+- **数据量要求**：通常需要 100 条以上才能形成完整螺旋
+
+**角度与圈数关系**：`圈数 = (endAngle - startAngle) / (2 * Math.PI)`
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  autoFit: true,
+  height: 500,
+});
+
+chart.options({
+  type: 'interval',
+  data: {
+    value: [
+      { time: '2025.07.11', value: 35 },
+      { time: '2025.07.12', value: 30 },
+      { time: '2025.07.13', value: 55 },
+      // ... 更多数据（100+ 条）
+    ],
+  },
+  encode: { x: 'time', y: 'value', color: 'value' },
+  scale: {
+    color: { type: 'linear', range: ['#ffffff', '#1890FF'] },
+  },
+  coordinate: {
+    type: 'helix',
+    startAngle: Math.PI / 2,              // 从顶部开始
+    endAngle: Math.PI / 2 + 6 * Math.PI, // 转3圈（每圈 2π）
+  },
+  animate: { enter: { type: 'fadeIn' } },
+  tooltip: { title: 'time' },
+});
+
+chart.render();
+```
+
+## 常用角度配置
+
+```javascript
+// 标准螺旋（约6圈，适合一年每周数据）
+coordinate: {
+  type: 'helix',
+  startAngle: 1.5707963267948966,   // Math.PI / 2
+  endAngle: 39.269908169872416,     // Math.PI / 2 + 12 * Math.PI（6圈）
+}
+
+// 少圈数（约3圈，适合季度数据）
+coordinate: {
+  type: 'helix',
+  startAngle: Math.PI / 2,
+  endAngle: Math.PI / 2 + 6 * Math.PI,
+}
+
+// 带内半径（圆环螺旋）
+coordinate: {
+  type: 'helix',
+  startAngle: 0.2 * Math.PI,
+  endAngle: 6.5 * Math.PI,
+  innerRadius: 0.1,
+}
+```
+
+## 按类别分组螺旋图
+
+```javascript
+chart.options({
+  type: 'interval',
+  data: {
+    type: 'fetch',
+    value: 'url-to-data.json',
+  },
+  encode: {
+    x: 'time',
+    y: 'group',     // 用 Y 轴区分类别
+    color: 'value', // 用颜色映射数值
+  },
+  scale: {
+    color: {
+      type: 'linear',
+      range: ['#fff', '#ec4839'],
+    },
+  },
+  coordinate: {
+    type: 'helix',
+    startAngle: 0.2 * Math.PI,
+    endAngle: 6.5 * Math.PI,
+    innerRadius: 0.1,
+  },
+  tooltip: {
+    title: 'time',
+    items: [
+      { field: 'group', name: '组别' },
+      { field: 'value', name: '数值' },
+    ],
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：数据量太少
+
+```javascript
+// ❌ 问题：5 条数据无法形成螺旋，效果极差
+chart.options({
+  type: 'interval',
+  data: {
+    value: [
+      { time: '2025-01', value: 35 },
+      { time: '2025-02', value: 50 },
+      { time: '2025-03', value: 45 },
+      { time: '2025-04', value: 60 },
+      { time: '2025-05', value: 40 },
+    ],
+  },
+  coordinate: { type: 'helix', startAngle: Math.PI / 2, endAngle: 40 },
+});
+
+// ✅ 改用折线图处理少量数据
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'time', y: 'value' },
+});
+```
+
+### 错误 2：coordinate 类型名错误
+
+```javascript
+// ❌ 错误：没有 'spiral' 类型，应该是 'helix'
+coordinate: { type: 'spiral' }   // ❌ 不存在
+
+// ✅ 正确：使用 helix
+coordinate: { type: 'helix', startAngle: Math.PI / 2, endAngle: 40 }  // ✅
+```
+
+### 错误 3：角度单位混淆
+
+```javascript
+// ❌ 错误：使用角度（度数）而非弧度
+coordinate: {
+  type: 'helix',
+  startAngle: 90,   // ❌ 90° 不是弧度，应该是 Math.PI / 2
+  endAngle: 2250,   // ❌ 应该是弧度值
+}
+
+// ✅ 正确：使用弧度
+coordinate: {
+  type: 'helix',
+  startAngle: Math.PI / 2,           // ✅ 90° = π/2 弧度
+  endAngle: Math.PI / 2 + 12 * Math.PI,  // ✅ 6圈
+}
+```
+
+### 错误 4：data 格式错误（行内数据需要 value 包裹）
+
+```javascript
+// ❌ 错误：行内数组数据需要放在 data.value 中
+chart.options({
+  data: [{ time: '2025.01', value: 35 }, ...],  // ❌ 直接数组
+  coordinate: { type: 'helix', ... },
+});
+
+// ✅ 正确：行内数据用 { value: [...] } 包裹
+chart.options({
+   {
+    value: [{ time: '2025.01', value: 35 }, ...],  // ✅
+  },
+  coordinate: { type: 'helix', ... },
+});
+```
+
+### 错误 5：animate.enter 使用 growInY/growInX 导致螺旋渲染残缺
+
+`growInX/Y` 通过沿直角坐标轴方向裁剪（clipPath）实现动画。helix 坐标系已将坐标重映射到螺旋路径，不存在"底部基线"，裁剪矩形会横穿螺旋，导致部分螺旋区域被切掉，动画结束后图表仍显示不完整。
+
+```javascript
+// ❌ 错误：growInY 在 helix 坐标系下裁剪矩形横穿螺旋 → 图表渲染残缺
+chart.options({
+  type: 'interval',
+  coordinate: { type: 'helix', startAngle: 0, endAngle: Math.PI * 6 },
+  animate: {
+    enter: { type: 'growInY', duration: 2000 },  // ❌ 螺旋被截断
+  },
+});
+
+// ✅ 正确：helix 坐标系必须用 fadeIn（或不设置动画）
+chart.options({
+  type: 'interval',
+  coordinate: { type: 'helix', startAngle: 0, endAngle: Math.PI * 6 },
+  animate: {
+    enter: { type: 'fadeIn', duration: 1000 },  // ✅
+  },
+});
+```
+
+## 与折线图的选择
+
+| 场景 | 推荐图表 |
+|------|---------|
+| 数据量 < 50 条 | 折线图 |
+| 数据量 100+ 条，观察趋势 | 螺旋图或折线图 |
+| 需要发现周期性规律 | **螺旋图**（当每圈周期对齐时效果最佳）|
+| 需要精确读取数值 | 折线图 |
+| 大屏展示视觉效果 | **螺旋图** |

package/builtin-skills/antv-g2-chart/references/marks/g2-mark-sunburst.md

@@ -0,0 +1,327 @@
+---
+id: "g2-mark-sunburst"
+title: "G2 Sunburst Chart Mark"
+description: |
+  旭日图 Mark。使用 sunburst 标记展示多层级层次化数据，通过同心圆形式展示层级关系。
+  适用于组织架构、文件系统、预算分配等场景。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "旭日图"
+  - "sunburst"
+  - "层次结构"
+  - "多层级"
+
+related:
+  - "g2-mark-treemap"
+  - "g2-mark-arc-pie"
+
+use_cases:
+  - "组织架构展示"
+  - "文件系统分析"
+  - "预算分配"
+
+anti_patterns:
+  - "层级过深（>4层）应使用矩形树图"
+  - "类别过多不适合"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/mark/sunburst"
+---
+
+## 核心概念
+
+旭日图通过同心圆展示多层级数据：
+- 每个层级用一个环表示
+- 环的内外半径表示层级深度
+- 角度大小表示数值大小
+
+**需要引入扩展：**
+```javascript
+import { plotlib } from '@antv/g2-extension-plot';
+import { Runtime, corelib, extend } from '@antv/g2';
+
+const Chart = extend(Runtime, { ...corelib(), ...plotlib() });
+```
+
+## 最小可运行示例
+
+```javascript
+import { plotlib } from '@antv/g2-extension-plot';
+import { Runtime, corelib, extend } from '@antv/g2';
+
+const Chart = extend(Runtime, { ...corelib(), ...plotlib() });
+
+const chart = new Chart({
+  container: 'container',
+  theme: 'classic',
+  autoFit: true,
+});
+
+chart.options({
+  type: 'sunburst',
+  data: {
+    type: 'fetch',
+    value: 'https://gw.alipayobjects.com/os/antvdemo/assets/data/sunburst.json',
+  },
+  encode: {
+    value: 'sum',
+  },
+});
+
+chart.render();
+```
+
+## 数据配置形式说明
+
+**为什么 sunburst 使用 ` { value: data }` 或 ` { type: 'fetch', value: 'url' }` 而不是 `data`？**
+
+层次数据是**对象**（包含 name/children），不是数组，必须使用完整形式：
+
+```javascript
+// ❌ 错误：层次数据不是数组，不能用简写
+chart.options({
+  type: 'sunburst',
+  data: hierarchyData,  // ❌ 不工作
+});
+
+// ✅ 正确：层次数据必须用完整形式
+chart.options({
+  type: 'sunburst',
+  data: { value: hierarchyData },  // ✅ 内联数据
+});
+
+// ✅ 正确：远程数据
+chart.options({
+  type: 'sunburst',
+  data: { type: 'fetch', value: 'https://example.com/data.json' },
+});
+```
+
+**简写形式仅适用于数组数据**（满足三个条件：内联、是数组、无 transform）。
+
+---
+
+## 常用变体
+
+### 带标签
+
+```javascript
+chart.options({
+  type: 'sunburst',
+  data: { value: hierarchyData },
+  encode: { value: 'sum' },
+  labels: [
+    {
+      text: 'name',
+      transform: [{ type: 'overflowHide' }],
+    },
+  ],
+});
+```
+
+### 自定义颜色
+
+```javascript
+chart.options({
+  type: 'sunburst',
+  data: { value: hierarchyData },
+  encode: {
+    value: 'sum',
+  },
+});
+```
+
+### 带下钻交互
+
+```javascript
+chart.options({
+  type: 'sunburst',
+  data: { value: hierarchyData },
+  encode: { value: 'sum' },
+  interaction: {
+    drillDown: {
+      breadCrumb: {
+        rootText: '起始',
+      },
+    },
+  },
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface SunburstOptions {
+  type: 'sunburst';
+   { value: HierarchyData } | { type: 'fetch'; value: string };
+  encode: {
+    value: string;                          // 数值字段（字符串可用，有专项处理）
+    color?: (d: HierarchyNode) => unknown;  // ⚠️ 颜色必须用回调，不能用字符串
+  };
+  labels?: Array<{
+    text: string;
+    transform?: Array<{ type: string }>;
+  }>;
+  interaction?: {
+    drillDown?: {
+      breadCrumb?: {
+        rootText?: string;
+      };
+    };
+  };
+}
+```
+
+## 旭日图 vs 矩形树图
+
+| 特性 | 旭日图 | 矩形树图 |
+|------|--------|----------|
+| 布局 | 圆形 | 矩形 |
+| 空间利用 | 较低 | 较高 |
+| 层级展示 | 同心圆 | 嵌套矩形 |
+| 适用层级 | ≤4 层 | 更深层级 |
+
+## 常见错误与修正
+
+### 错误 1：未引入扩展
+
+```javascript
+// ❌ 问题：sunburst 需要扩展库
+import { Chart } from '@antv/g2';
+
+// ✅ 正确：引入 plotlib 扩展
+import { plotlib } from '@antv/g2-extension-plot';
+import { Runtime, corelib, extend } from '@antv/g2';
+const Chart = extend(Runtime, { ...corelib(), ...plotlib() });
+```
+
+### 错误 2：层级过深
+
+```javascript
+// ⚠️ 注意：层级超过 4 层时，外层扇形过小
+// 建议使用矩形树图替代
+```
+
+### 错误 3：数据格式错误
+
+```javascript
+// ❌ 问题：层次数据不能用简写形式
+chart.options({
+  type: 'sunburst',
+   [{ name: 'A', value: 100 }],  // ❌ 数组格式，不是层次结构
+});
+
+// ✅ 正确：使用完整形式 + 层级嵌套结构
+chart.options({
+  type: 'sunburst',
+   {
+    value: {
+      name: 'Root',
+      children: [
+        { name: 'A', value: 100 },
+        { name: 'B', children: [...] }
+      ]
+    }
+  },
+  encode: { value: 'sum' },
+});
+```
+
+---
+
+## 节点数据访问规则（重要！）
+
+层次结构图中，回调函数接收到的参数 `d` **不是原始数据对象**，而是 G2 用 d3-hierarchy 包装后的层次节点，**原始数据在 `d.data` 中**。
+
+### 为什么 `encode.color: 'label'` 不起作用？
+
+**根本原因**：当 encode 是字符串时，G2 内部做的是 `datum[fieldName]`，直接访问层次节点属性。层次节点上没有 `label` 属性，返回 `undefined`，导致所有扇形显示相同颜色。
+
+```
+d['label']        → undefined  ❌（层次节点没有 label 属性）
+d.data['label']   → 'A类'      ✅（原始数据在 d.data 上）
+```
+
+**特例**：`encode.value: 'sum'` 字符串可以工作，因为 G2 对层次 mark 的 `value` 通道做了**专项处理**。其他通道（`color`、`shape` 等）无此特殊处理，必须用回调。
+
+### 回调参数 d 的结构
+
+```javascript
+// d 是 d3-hierarchy 节点，结构如下：
+{
+  value: 100,              // 节点数值（d3 计算的子树总和）
+  depth: 2,                // 层级深度（0 = 根节点）
+  height: 0,               // 子树高度（叶子节点为 0）
+   {                  // ← 原始数据在这里！
+    name: '前端',
+    sum: 120,
+    label: 'A类',
+    // ... 其它自定义字段
+  },
+  path: ['root', '技术', '前端'],
+}
+```
+
+### encode 中访问字段
+
+```javascript
+// ❌ 错误：字符串字段名对 color 通道不起作用
+encode: {
+  value: 'sum',    // ✅ value 通道有专项处理
+  color: 'label',  // ❌ d['label'] = undefined → 所有扇形颜色相同
+}
+
+// ✅ 正确：color 必须用回调函数
+encode: {
+  value: 'sum',
+  color: (d) => d.data?.label,  // ✅
+}
+```
+
+### 常用着色策略
+
+```javascript
+// 按第二层父节点着色（推荐，同门类同色）
+color: (d) => d.path?.[1] || d.data?.name
+
+// 按层级深度着色
+color: (d) => d.depth
+
+// 按自定义字段着色
+color: (d) => d.data?.label
+color: (d) => d.data?.category
+
+// 按数值着色（连续色板）
+color: (d) => d.value
+```
+
+### 错误 4：encode.color 使用字符串字段名导致所有扇形颜色相同
+
+```javascript
+// ❌ 错误：color: 'label' 等价于 d['label']，层次节点上没有此属性 → undefined
+chart.options({
+  type: 'sunburst',
+  data: { value: data },
+  encode: {
+    value: 'sum',
+    color: 'label',  // ❌ → 所有扇形相同颜色
+  },
+});
+
+// ✅ 正确：color 必须用回调，通过 d.data 访问原始字段
+chart.options({
+  type: 'sunburst',
+  data: { value: data },
+  encode: {
+    value: 'sum',
+    color: (d) => d.path?.[1] || d.data?.name,  // ✅ 按父节点着色
+  },
+});
+```