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

package/builtin-skills/antv-g2-chart/references/coordinates/g2-coord-radial.md

@@ -0,0 +1,214 @@
+---
+id: "g2-coord-radial"
+title: "G2 径向坐标系（radial）"
+description: |
+  radial（径向坐标系）是 G2 v5 中极坐标系的一种变体，
+  将转置后的直角坐标映射为圆形布局：x 轴映射为半径，y 轴映射为角度。
+  与 polar（极坐标）相反（polar 是 x→角度，y→半径），
+  radial 适合绘制径向柱状图（向心柱状图）、径向折线图等。
+
+library: "g2"
+version: "5.x"
+category: "coordinates"
+tags:
+  - "radial"
+  - "径向坐标"
+  - "向心柱状图"
+  - "径向图"
+  - "coordinate"
+  - "圆形布局"
+
+related:
+  - "g2-coord-polar"
+  - "g2-coord-theta"
+  - "g2-mark-interval-basic"
+
+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/coordinate/radial"
+---
+
+## 核心概念
+
+径向坐标系（radial）与极坐标系（polar）的映射关系相反：
+
+| 坐标系 | x 通道 | y 通道 | 典型图表 |
+|--------|--------|--------|----------|
+| `polar` | → 角度（圆周方向） | → 半径（距中心距离） | 玫瑰图 |
+| `radial` | → 半径（距中心距离） | → 角度（圆周方向） | 径向柱状图 |
+
+## 最小可运行示例（径向柱状图）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 500, height: 500 });
+
+chart.options({
+  type: 'interval',
+  data: [
+    { month: 'Jan', value: 83 },
+    { month: 'Feb', value: 60 },
+    { month: 'Mar', value: 95 },
+    { month: 'Apr', value: 72 },
+    { month: 'May', value: 110 },
+    { month: 'Jun', value: 85 },
+  ],
+  encode: {
+    x: 'month',    // x 通道 → 角度（圆周位置）
+    y: 'value',    // y 通道 → 半径（柱子长度）
+    color: 'month',
+  },
+  coordinate: { type: 'radial', innerRadius: 0.1, outerRadius: 0.8 },
+});
+
+chart.render();
+```
+
+## 配置项
+
+```javascript
+chart.options({
+  coordinate: {
+    type: 'radial',
+    innerRadius: 0.1,            // 内环半径（0=从中心开始），默认 0
+    outerRadius: 1,              // 外环半径比例，默认 1
+    startAngle: -Math.PI / 2,   // 起始角度，默认 -π/2（12点钟方向）
+    endAngle: (Math.PI * 3) / 2, // 结束角度，默认 3π/2（顺时针一圈）
+  },
+});
+```
+
+## 带内孔的径向柱状图（环形）
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+  coordinate: {
+    type: 'radial',
+    innerRadius: 0.3,   // 留出中心空间
+    outerRadius: 0.9,
+  },
+  style: { fillOpacity: 0.85 },
+});
+```
+
+## 与 polar 坐标系的区别
+
+```javascript
+// polar：x→角度，y→半径（玫瑰图效果）
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value' },  // x 为分类（角度），y 为数值（半径）
+  coordinate: { type: 'polar' },
+});
+
+// radial：x→半径，y→角度（径向柱状图效果）
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value' },  // x 为分类（角度），y 为数值（半径）
+  coordinate: { type: 'radial' },
+});
+```
+
+## 常见错误与修正
+
+### 错误：encode x/y 与预期方向相反
+```javascript
+// ❌ 错误：radial 中 x 应该是角度方向（类别），y 是半径方向（数值）
+chart.options({
+  type: 'interval',
+  encode: { x: 'value', y: 'month' },  // ❌ 数值作为角度，月份作为半径
+  coordinate: { type: 'radial' },
+});
+
+// ✅ 正确：将分类字段作为 x（映射为角度），数值字段作为 y（映射为半径）
+chart.options({
+  type: 'interval',
+  encode: { x: 'month', y: 'value' },  // ✅ 月份→角度，数值→半径
+  coordinate: { type: 'radial' },
+});
+```
+
+### 错误：中心图片未正确显示
+```javascript
+// ❌ 错误：使用固定坐标 (0,0) 显示图片无法保证其位于中心
+chart.options({
+  type: 'image',
+  data: [{ url: 'https://example.com/logo.png' }],
+  encode: {
+    x: () => 0,
+    y: () => 0
+  },
+  style: {
+    img: (d) => d.url,
+    width: 80,
+    height: 80
+  }
+});
+
+// ✅ 正确：使用 style.x 和 style.y 设置相对位置，确保图片居中
+chart.options({
+  type: 'image',
+  data: [{ src: 'https://example.com/logo.png' }],
+  style: {
+    x: '50%',      // 相对于容器宽度的 50%
+    y: '50%',      // 相对于容器高度的 50%
+    width: 80,
+    height: 80
+  }
+});
+```
+
+### 错误：多个视图叠加导致坐标系冲突
+```javascript
+// ❌ 错误：在 view 中重复定义 coordinate 导致渲染异常
+chart.options({
+  type: 'view',
+  children: [
+    {
+      type: 'interval',
+      coordinate: { type: 'radial' }  // 子视图中定义坐标系可能导致冲突
+    },
+    {
+      type: 'image',
+      coordinate: { type: 'radial' }  // 图片标记不需要坐标系
+    }
+  ]
+});
+
+// ✅ 正确：在顶层 view 定义 coordinate，子元素继承即可
+chart.options({
+  type: 'view',
+  coordinate: { type: 'radial', innerRadius: 0.3 },
+  children: [
+    {
+      type: 'interval',
+      data,
+      encode: { x: 'type', y: 'value' }
+    },
+    {
+      type: 'image',
+      data: [{ src: 'https://example.com/logo.png' }],
+      style: {
+        x: '50%',
+        y: '50%',
+        width: 80,
+        height: 80
+      }
+    }
+  ]
+});
+```

package/builtin-skills/antv-g2-chart/references/coordinates/g2-coord-theta.md

@@ -0,0 +1,171 @@
+---
+id: "g2-coord-theta"
+title: "G2 Theta 坐标系（饼图 / 环形图）"
+description: |
+  Theta 坐标系是 G2 v5 中制作饼图和环形图的专用坐标系。
+  本质上是 Transpose + Polar 的组合：将 y 通道（数值）映射为角度。
+  必须配合 stackY transform 使用，否则所有扇形角度从 0 开始完全重叠。
+
+library: "g2"
+version: "5.x"
+category: "coordinates"
+tags:
+  - "theta"
+  - "饼图"
+  - "环形图"
+  - "pie"
+  - "donut"
+  - "coordinate"
+
+related:
+  - "g2-transform-stacky"
+  - "g2-mark-arc-pie"
+  - "g2-mark-arc-donut"
+  - "g2-coord-polar"
+
+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/coordinate/theta"
+---
+
+## 最小可运行示例（饼图）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 480, height: 480 });
+
+chart.options({
+  type: 'interval',
+  data: [
+    { type: '电子产品', value: 40 },
+    { type: '服装',     value: 25 },
+    { type: '食品',     value: 20 },
+    { type: '其他',     value: 15 },
+  ],
+  encode: {
+    y: 'value',      // 数值映射为扇形角度大小
+    color: 'type',   // 颜色区分类别
+  },
+  transform: [{ type: 'stackY' }],       // 必须！将数值累积为角度区间
+  coordinate: { type: 'theta' },         // 必须！theta 坐标系
+});
+
+chart.render();
+```
+
+## 环形图（设置 innerRadius）
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  coordinate: {
+    type: 'theta',
+    innerRadius: 0.6,   // 内孔半径比例（0.5~0.7 是常见值）
+    outerRadius: 0.9,
+  },
+  labels: [
+    {
+      position: 'outside',
+      text: (d) => `${d.type}: ${d.value}`,
+    },
+  ],
+});
+```
+
+## 配置项
+
+```javascript
+coordinate: {
+  type: 'theta',
+  startAngle: -Math.PI / 2,    // 起始角度，默认 -π/2（12点钟方向）
+  endAngle: (Math.PI * 3) / 2, // 结束角度，默认顺时针一整圈
+  innerRadius: 0,              // 内孔大小，0 = 实心饼图，> 0 = 环形图
+  outerRadius: 1,              // 外径比例
+}
+```
+
+## 带百分比标签的饼图
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  coordinate: { type: 'theta', outerRadius: 0.8 },
+  labels: [
+    {
+      position: 'outside',
+      text: (d, i, arr) => {
+        const total = arr.reduce((sum, item) => sum + item.value, 0);
+        return `${((d.value / total) * 100).toFixed(1)}%`;
+      },
+    },
+  ],
+  legend: { color: { position: 'right' } },
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：忘记 stackY —— 所有扇形从 0 开始完全重叠
+```javascript
+// ❌ 错误：没有 stackY，所有扇区角度都从 0 开始，图形全部重叠
+chart.options({
+  type: 'interval',
+  data,
+  encode: { y: 'value', color: 'type' },
+  coordinate: { type: 'theta' },   // ❌ 缺少 transform！
+});
+
+// ✅ 正确：必须加 stackY
+chart.options({
+  transform: [{ type: 'stackY' }],  // ✅ 先累积角度
+  coordinate: { type: 'theta' },
+});
+```
+
+### 错误 2：用 polar 代替 theta 做饼图
+```javascript
+// ❌ 错误：polar 坐标系 y 通道映射半径，不会生成扇形角度
+chart.options({
+  coordinate: { type: 'polar' },  // ❌ 得到玫瑰图，不是饼图
+});
+
+// ✅ 饼图必须用 theta
+chart.options({
+  coordinate: { type: 'theta' },  // ✅
+});
+```
+
+### 错误 3：encode 中设置了 x 通道
+```javascript
+// ❌ 错误：theta 坐标系的饼图不需要 x 通道
+chart.options({
+  encode: {
+    x: 'type',    // ❌ 多余，theta 坐标中 x 通道无意义
+    y: 'value',
+    color: 'type',
+  },
+});
+
+// ✅ 正确：theta 饼图只需要 y 和 color
+chart.options({
+  encode: {
+    y: 'value',    // ✅ 数值 → 角度
+    color: 'type', // ✅ 类别 → 颜色
+  },
+});
+```

package/builtin-skills/antv-g2-chart/references/coordinates/g2-coord-transpose.md

@@ -0,0 +1,195 @@
+---
+id: "g2-coord-transpose"
+title: "G2 转置坐标系（将柱状图转为条形图）"
+description: |
+  通过 coordinate: { transform: [{ type: 'transpose' }] } 将直角坐标系的 x/y 轴对调，
+  最常见的用途是将竖向柱状图转换为水平条形图，
+  适合分类名称较长或类别较多的场景。
+
+library: "g2"
+version: "5.x"
+category: "coordinates"
+tags:
+  - "transpose"
+  - "转置"
+  - "条形图"
+  - "horizontal"
+  - "水平"
+  - "coordinate"
+  - "spec"
+
+related:
+  - "g2-mark-interval-basic"
+  - "g2-mark-interval-grouped"
+  - "g2-mark-interval-stacked"
+
+use_cases:
+  - "分类名称较长时，水平条形图标签更清晰"
+  - "类别数量较多（> 8 个）时水平排列更美观"
+  - "排名图（横向从大到小排列）"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/coordinate/transpose"
+---
+
+## 最小可运行示例（柱状图转条形图）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'interval',
+  data: [
+    { city: '北京',   gdp: 3.6 },
+    { city: '上海',   gdp: 4.3 },
+    { city: '广州',   gdp: 2.8 },
+    { city: '深圳',   gdp: 3.2 },
+    { city: '杭州',   gdp: 1.8 },
+  ],
+  encode: {
+    x: 'city',   // 转置后，city 在 y 轴（垂直方向）
+    y: 'gdp',    // 转置后，gdp 在 x 轴（水平方向）
+  },
+  coordinate: { transform: [{ type: 'transpose' }] },   // 关键：转置坐标系
+});
+
+chart.render();
+```
+
+## 排名条形图（排序 + 转置）
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'city', y: 'gdp', color: 'city' },
+  transform: [
+    { type: 'sortX', by: 'y', reverse: true },   // 先按值降序排列
+  ],
+  coordinate: { transform: [{ type: 'transpose' }] },
+  axis: {
+    x: { title: 'GDP（万亿元）' },
+    y: { title: null },
+  },
+  labels: [
+    {
+      text: (d) => d.gdp.toFixed(1),
+      position: 'outside',
+      style: { fontSize: 12 },
+    },
+  ],
+});
+```
+
+## 水平堆叠条形图
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  coordinate: { transform: [{ type: 'transpose' }] },
+});
+```
+
+## 横向区间图（甘特图风格）
+
+```javascript
+chart.options({
+  type: 'interval',
+  autoFit: true,
+  data: [
+    { stage: 'Phase 1', task: '原型', start: 1, end: 3 },
+    { stage: 'Phase 1', task: '验证', start: 3, end: 5 },
+    { stage: 'Phase 2', task: '开发', start: 4, end: 10 },
+    { stage: 'Phase 2', task: '单元测试', start: 8, end: 11 },
+    { stage: 'Phase 3', task: '集成', start: 10, end: 13 },
+    { stage: 'Phase 3', task: '压测', start: 12, end: 15 }
+  ],
+  encode: {
+    x: (d) => `${d.stage} - ${d.task}`,  // 组合标签字段
+    y: 'start',                          // 起始时间映射到 y 轴
+    y1: 'end',                           // 结束时间映射到 y1 通道
+    color: 'stage'                       // 阶段映射到颜色
+  },
+  coordinate: { transform: [{ type: 'transpose' }] },  // 转置坐标系
+  axis: {
+    x: {
+      title: '阶段与任务',
+      labelTransform: 'rotate(30)'       // 标签倾斜防止重叠
+    },
+    y: { title: '时间（周）' }            // 时间轴标题
+  }
+});
+
+chart.render();
+```
+
+## 常见错误与修正
+
+### 错误：转置后轴标题配置未调整
+```javascript
+// ❌ 注意：转置后，原 x 配置作用于竖轴，原 y 配置作用于横轴
+// 如果需要水平轴显示数值单位，应配置 axis.x（而非 axis.y）
+chart.options({
+  coordinate: { transform: [{ type: 'transpose' }] },
+  axis: {
+    y: { title: 'GDP（万亿）' },   // ❌ 转置后 y 轴是分类轴，不是数值轴
+  },
+});
+
+// ✅ 正确：转置后的"水平轴"对应配置中的 axis.x
+chart.options({
+  coordinate: { transform: [{ type: 'transpose' }] },
+  axis: {
+    x: { title: 'GDP（万亿）' },   // ✅ 数值轴
+    y: { title: null },             // ✅ 分类轴（分类名已经在左侧，无需标题）
+  },
+});
+```
+
+### 错误：横向区间图标签处理不当
+```javascript
+// ❌ 错误示例：使用 labelFormatter 处理组合标签易出错
+chart.options({
+  encode: {
+    x: 'task',
+    y: 'start',
+    y1: 'end'
+  },
+  axis: {
+    x: {
+      labelFormatter: (task, item) => {
+        const datum = item.data;
+        return `${datum.stage}\n${task}`;
+      }
+    }
+  }
+});
+
+// ✅ 正确做法：在数据预处理阶段构造组合字段
+chart.options({
+  encode: {
+    x: (d) => `${d.stage} - ${d.task}`,  // 使用函数构造组合标签
+    y: 'start',
+    y1: 'end'
+  },
+  axis: {
+    x: {
+      title: '阶段与任务',
+      labelTransform: 'rotate(30)'        // 适当旋转标签避免重叠
+    }
+  }
+});
+```