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

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

@@ -0,0 +1,182 @@
+---
+id: "g2-mark-rose"
+title: "G2 Rose Chart Mark"
+description: |
+  南丁格尔玫瑰图 Mark。使用 interval 标记配合 polar 坐标系，通过扇形半径表示数值大小。
+  适用于分类数据对比、周期性数据展示等场景。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "玫瑰图"
+  - "rose"
+  - "南丁格尔图"
+  - "极坐标"
+
+related:
+  - "g2-mark-arc-pie"
+  - "g2-coord-polar"
+
+use_cases:
+  - "分类数据对比"
+  - "周期性数据展示"
+  - "多维度比较"
+
+anti_patterns:
+  - "分类过少应使用饼图"
+  - "数值差异悬殊不适合"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/mark/rose"
+---
+
+## 核心概念
+
+南丁格尔玫瑰图在极坐标系下绘制柱状图：
+- 使用 `interval` 标记
+- 配合 `polar` 坐标系
+- 扇形半径表示数值大小
+
+**与饼图的区别：**
+- 饼图：弧度表示数值
+- 玫瑰图：半径表示数值
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  theme: 'classic',
+});
+
+chart.options({
+  type: 'interval',
+  autoFit: true,
+  coordinate: { type: 'polar' },
+  data: [
+    { country: '中国', cost: 96 },
+    { country: '德国', cost: 121 },
+    { country: '美国', cost: 100 },
+    { country: '日本', cost: 111 },
+  ],
+  encode: {
+    x: 'country',
+    y: 'cost',
+    color: 'country',
+  },
+  style: {
+    stroke: 'white',
+    lineWidth: 1,
+  },
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 堆叠玫瑰图
+
+```javascript
+chart.options({
+  type: 'interval',
+  coordinate: { type: 'polar', innerRadius: 0.1 },
+  data,
+  encode: { x: 'year', y: 'count', color: 'type' },
+  transform: [{ type: 'stackY' }],
+});
+```
+
+### 扇形玫瑰图
+
+```javascript
+chart.options({
+  type: 'interval',
+  coordinate: {
+    type: 'polar',
+    startAngle: Math.PI,
+    endAngle: Math.PI * (3 / 2),
+  },
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+});
+```
+
+### 带标签
+
+```javascript
+chart.options({
+  type: 'interval',
+  coordinate: { type: 'polar' },
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+  labels: [
+    {
+      text: 'value',
+      style: { textAlign: 'center', fontSize: 10 },
+    },
+  ],
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface RoseOptions {
+  type: 'interval';
+  coordinate: {
+    type: 'polar';
+    innerRadius?: number;    // 内半径
+    startAngle?: number;     // 起始角度
+    endAngle?: number;       // 结束角度
+  };
+  encode: {
+    x: string;    // 分类字段
+    y: string;    // 数值字段
+    color?: string;
+  };
+  transform?: [{ type: 'stackY' }];  // 堆叠
+}
+```
+
+## 玫瑰图 vs 饼图
+
+| 特性 | 玫瑰图 | 饼图 |
+|------|--------|------|
+| 数值映射 | 半径 | 弧度 |
+| 分类数量 | 较多 | 较少 |
+| 对比方式 | 半径对比 | 面积对比 |
+
+## 常见错误与修正
+
+### 错误 1：使用 theta 坐标系
+
+```javascript
+// ❌ 问题：theta 是饼图坐标系
+coordinate: { type: 'theta' }
+
+// ✅ 正确：使用 polar 坐标系
+coordinate: { type: 'polar' }
+```
+
+### 错误 2：数据未排序
+
+```javascript
+// ⚠️ 注意：玫瑰图建议数据排序后使用
+// 可以使用 sortX transform
+transform: [{ type: 'sortX', by: 'y' }]
+```
+
+### 错误 3：分类过多
+
+```javascript
+// ⚠️ 注意：分类数量建议不超过 30 个
+// 过多分类会导致扇形过窄难以阅读
+```

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

@@ -0,0 +1,217 @@
+---
+id: "g2-mark-sankey"
+title: "G2 桑基图（sankey）"
+description: |
+  G2 v5 内置 sankey Mark，用于展示多阶段流量/能量分配流向，
+  数据格式为包含 source、target、value 的链接数组，
+  节点宽度自动由传入/传出流量决定。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "桑基图"
+  - "sankey"
+  - "流向图"
+  - "能量流"
+  - "转化漏斗"
+  - "spec"
+
+related:
+  - "g2-mark-funnel"
+  - "g2-recipe-funnel"
+  - "g2-core-chart-init"
+
+use_cases:
+  - "展示能源/物质流动分配"
+  - "用户转化路径分析（多步骤）"
+  - "预算/资金流向可视化"
+  - "供应链流向图"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/graph/network/#sankey"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 800,
+  height: 500,
+});
+
+// 链接数组：每条记录是一条流向
+const links = [
+  { source: '访问',   target: '注册',   value: 8000 },
+  { source: '访问',   target: '直接离开', value: 2000 },
+  { source: '注册',   target: '激活',   value: 5000 },
+  { source: '注册',   target: '流失',   value: 3000 },
+  { source: '激活',   target: '付费',   value: 2000 },
+  { source: '激活',   target: '免费使用', value: 3000 },
+];
+
+chart.options({
+  type: 'sankey',
+  data: {
+    value: {
+      links,    // 链接数组（必须）
+      // nodes 可选，不填则自动从 links 中提取节点
+    },
+  },
+  layout: {
+    nodeAlign: 'justify',   // 节点对齐：'left'|'right'|'center'|'justify'
+    nodePadding: 0.03,      // 节点上下间距（0-1）
+  },
+  style: {
+    labelSpacing: 3,
+    nodeLineWidth: 1,
+    linkFillOpacity: 0.4,
+  },
+  legend: false,
+});
+
+chart.render();
+```
+
+## 带颜色区分的桑基图
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 900,
+  height: 600,
+});
+
+const links = [
+  { source: '煤炭', target: '电力', value: 150 },
+  { source: '石油', target: '交通', value: 120 },
+  { source: '天然气', target: '供热', value: 80 },
+  { source: '电力', target: '工业', value: 90 },
+  { source: '电力', target: '居民', value: 60 },
+  { source: '交通', target: '公路', value: 80 },
+  { source: '交通', target: '航空', value: 40 },
+];
+
+chart.options({
+  type: 'sankey',
+  data: {
+    value: { links },
+  },
+  layout: {
+    nodeAlign: 'center',
+    nodePadding: 0.03,
+    nodeWidth: 0.02,       // 节点宽度（相对画布）
+  },
+  scale: {
+    color: {
+      type: 'ordinal',
+      // 颜色跟随 source 节点
+    },
+  },
+  style: {
+    labelSpacing: 4,
+    labelFontWeight: 'bold',
+    labelFontSize: 12,
+    nodeLineWidth: 1.2,
+    linkFillOpacity: 0.35,
+  },
+  legend: false,
+});
+
+chart.render();
+```
+
+## 完整配置项
+
+```javascript
+chart.options({
+  type: 'sankey',
+  data: {
+    value: {
+      links: [
+        { source: 'A', target: 'B', value: 10 },  // source/target 是节点名称
+      ],
+      nodes: [     // 可选，自动推断
+        { key: 'A' },
+        { key: 'B' },
+      ],
+    },
+  },
+
+  layout: {
+    nodeId: (d) => d.key,      // 节点 ID 提取（默认 d.key）
+    nodeAlign: 'justify',       // 'left'|'right'|'center'|'justify'
+    nodeWidth: 0.02,            // 节点宽度（相对画布宽度，0-1）
+    nodePadding: 0.02,          // 节点上下间距
+    nodeSort: null,             // 节点排序函数
+    linkSort: null,             // 链接排序函数
+    iterations: 6,              // 布局迭代次数
+  },
+
+  style: {
+    labelSpacing: 3,            // 标签与节点的间距
+    labelFontSize: 12,
+    labelFontWeight: 'normal',
+    nodeLineWidth: 1,           // 节点边框宽度
+    nodeStroke: '#fff',         // 节点边框颜色
+    linkFillOpacity: 0.4,       // 链接透明度
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：数据格式错误——直接传 links 数组
+
+```javascript
+// ❌ 错误：sankey 的 data 需要包装为 { value: { links } }
+chart.options({
+  type: 'sankey',
+  data: links,   // ❌ 直接传数组
+});
+
+// ✅ 正确
+chart.options({
+  type: 'sankey',
+  data: {
+    value: { links },   // ✅ 需要 { value: { links } } 结构
+  },
+});
+```
+
+### 错误 2：source/target 节点名称不一致导致断链
+
+```javascript
+// ❌ 错误：'电力' 和 '电力公司' 被当作两个不同节点
+const links = [
+  { source: '煤炭',   target: '电力',   value: 100 },
+  { source: '电力公司', target: '工业', value: 80 },   // ❌ 名称不一致！
+];
+
+// ✅ 正确：source 和 target 中对同一节点使用完全相同的名称
+const links = [
+  { source: '煤炭', target: '电力', value: 100 },
+  { source: '电力', target: '工业', value: 80 },   // ✅ 完全一致
+];
+```
+
+### 错误 3：图中存在环（循环引用）
+
+```javascript
+// ❌ 桑基图不支持环形流向
+const links = [
+  { source: 'A', target: 'B', value: 10 },
+  { source: 'B', target: 'A', value: 5 },   // ❌ 形成环！布局异常
+];
+
+// ✅ 桑基图只适合有向无环的流向数据
+```

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

@@ -0,0 +1,160 @@
+---
+id: "g2-mark-shape"
+title: "G2 shape 自定义图形 Mark"
+description: |
+  shape mark 是 G2 v5 中用于绘制完全自定义图形的 Mark，
+  通过注册自定义 Shape 函数来渲染任意 SVG/Canvas 图形。
+  与 image mark（使用图片）不同，shape mark 使用代码绘制矢量图形，
+  可响应状态变化（高亮、选中等）。
+  适用于需要特殊图形符号、自定义标记的可视化场景。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "shape"
+  - "自定义图形"
+  - "register"
+  - "custom shape"
+  - "矢量图形"
+
+related:
+  - "g2-mark-image"
+  - "g2-mark-point-scatter"
+  - "g2-core-chart-init"
+
+use_cases:
+  - "散点图中使用自定义图标代替默认圆形"
+  - "地图上绘制自定义地标符号"
+  - "特殊业务场景的定制化图形标记"
+
+difficulty: "advanced"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/extra-topics/custom-mark"
+---
+
+## 核心概念
+
+`shape` mark 需要先用 `register('shape.xxx', renderFn)` 注册自定义图形，
+再在 mark 的 `style.shape` 中指定图形名称。
+
+自定义 Shape 渲染函数接收 `(style, context)` 参数：
+- `style`：包含 x/y 坐标、颜色、大小等样式属性
+- `context`：G 渲染上下文，包含 document 等
+
+## 最小可运行示例
+
+```javascript
+import { Chart, register } from '@antv/g2';
+import { Circle } from '@antv/g';
+
+// 1. 注册自定义图形（绘制带十字的圆）
+register('shape.crossCircle', (style, context) => {
+  const { x, y, r = 10, fill, stroke } = style;
+  const group = new context.document.createElement('g', {});
+  const circle = new Circle({ style: { cx: x, cy: y, r, fill, stroke } });
+  group.appendChild(circle);
+  return group;
+});
+
+// 2. 使用自定义图形
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'x', y: 'y', color: 'category', size: 'value' },
+  style: {
+    shape: 'crossCircle',   // 使用注册的自定义图形名
+  },
+});
+
+chart.render();
+```
+
+## 完整自定义形状（使用 @antv/g 图形）
+
+```javascript
+import { Chart, register } from '@antv/g2';
+import { Path, Group } from '@antv/g';
+
+// 注册星形图标
+register('shape.star', (style, context) => {
+  const { x, y, r = 10, fill = '#1890ff', opacity = 1 } = style;
+
+  // 计算五角星的路径
+  const path = [];
+  for (let i = 0; i < 5; i++) {
+    const angle = (i * 4 * Math.PI) / 5 - Math.PI / 2;
+    const px = x + r * Math.cos(angle);
+    const py = y + r * Math.sin(angle);
+    path.push(i === 0 ? `M ${px} ${py}` : `L ${px} ${py}`);
+  }
+  path.push('Z');
+
+  const shape = new Path({
+    style: {
+      d: path.join(' '),
+      fill,
+      opacity,
+    },
+  });
+  return shape;
+});
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'x', y: 'y', color: 'type' },
+  style: {
+    shape: 'star',
+    r: 12,
+  },
+});
+
+chart.render();
+```
+
+## 与 image mark 的选择
+
+```javascript
+// 使用图片文件作为标记点
+chart.options({
+  type: 'image',
+  data,
+  encode: { x: 'x', y: 'y', src: 'iconUrl' },  // src 为图片 URL
+  style: { width: 24, height: 24 },
+});
+
+// 使用代码绘制矢量图形
+register('shape.myIcon', (style) => { /* ... */ });
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'x', y: 'y' },
+  style: { shape: 'myIcon' },
+});
+```
+
+## 常见错误与修正
+
+### 错误：使用自定义图形前忘记注册
+```javascript
+// ❌ 错误：未注册就使用，图形不会渲染
+chart.options({
+  type: 'point',
+  style: { shape: 'myCustomShape' },  // ❌ myCustomShape 未注册
+});
+
+// ✅ 先注册再使用
+register('shape.myCustomShape', (style) => { /* 返回 G 图形 */ });
+chart.options({
+  type: 'point',
+  style: { shape: 'myCustomShape' },  // ✅
+});
+```