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

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

@@ -0,0 +1,370 @@
+---
+id: "g2-mark-cell-heatmap"
+title: "G2 热力图（Cell Mark）"
+description: |
+  使用 Cell Mark 创建矩阵热力图，通过颜色深浅表示两个分类维度交叉点的数值大小，
+  常用于相关性分析、时间-类别分布等场景。本文采用 Spec 模式。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+subcategory: "cell"
+tags:
+  - "热力图"
+  - "Cell"
+  - "heatmap"
+  - "矩阵"
+  - "相关性"
+  - "颜色映射"
+  - "spec"
+
+related:
+  - "g2-core-encode-channel"
+  - "g2-scale-sequential"
+  - "g2-comp-legend-config"
+
+use_cases:
+  - "展示两个分类维度的交叉数值（如相关矩阵）"
+  - "时间热力图（如每周各天的活跃度）"
+  - "用户行为矩阵分析"
+
+anti_patterns:
+  - "数据为连续型 x/y 时改用密度图或等值线图"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/heatmap/basic"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'cell',
+  data: [
+    { week: 'Mon', hour: '6AM',  value: 10 },
+    { week: 'Mon', hour: '12PM', value: 80 },
+    { week: 'Mon', hour: '6PM',  value: 60 },
+    { week: 'Tue', hour: '6AM',  value: 5  },
+    { week: 'Tue', hour: '12PM', value: 95 },
+    { week: 'Tue', hour: '6PM',  value: 70 },
+    { week: 'Wed', hour: '6AM',  value: 20 },
+    { week: 'Wed', hour: '12PM', value: 75 },
+    { week: 'Wed', hour: '6PM',  value: 55 },
+  ],
+  encode: {
+    x: 'week',
+    y: 'hour',
+    color: 'value',    // 颜色深浅表示数值大小
+  },
+  scale: {
+    color: { 
+      type: 'sequential',   // 明确指定为顺序色阶
+      palette: 'YlOrRd'     // 连续色阶：YlOrRd | Blues | Viridis 等
+    },
+  },
+  style: {
+    inset: 1,    // 格子间距（px）
+  },
+});
+
+chart.render();
+```
+
+## 带数值标签的热力图
+
+```javascript
+chart.options({
+  type: 'cell',
+  data,
+  encode: { x: 'week', y: 'hour', color: 'value' },
+  scale: {
+    color: { type: 'sequential', palette: 'Blues' },
+  },
+  labels: [
+    {
+      text: 'value',
+      style: {
+        fontSize: 11,
+        fill: (d) => d.value > 60 ? 'white' : '#333',  // 深色背景用白字
+      },
+    },
+  ],
+  style: { inset: 2 },
+});
+```
+
+## 相关系数矩阵
+
+```javascript
+// 相关性分析热力图（-1 到 1 的发散色阶）
+chart.options({
+  type: 'cell',
+  data: correlationData,  // [{ x: '变量A', y: '变量B', corr: 0.75 }, ...]
+  encode: {
+    x: 'x',
+    y: 'y',
+    color: 'corr',
+  },
+  scale: {
+    color: {
+      type: 'sequential',  // 明确指定为顺序色阶
+      palette: 'RdBu',     // 发散色阶：红-白-蓝
+      domain: [-1, 1],     // 固定数值范围
+    },
+  },
+  labels: [
+    {
+      text: (d) => d.corr.toFixed(2),
+      style: { fontSize: 10 },
+    },
+  ],
+});
+```
+
+## 日历热力图（GitHub 风格）
+
+```javascript
+// 每天活跃度的日历视图
+chart.options({
+  type: 'cell',
+  data: dailyData,   // [{ date: '2024-01-01', weekday: 'Mon', week: 1, value: 5 }, ...]
+  encode: {
+    x: 'week',      // 第几周（1-53）
+    y: 'weekday',   // 周几
+    color: 'value',
+  },
+  scale: {
+    color: { type: 'sequential', palette: 'Greens', domain: [0, 20] },
+    y: {
+      domain: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
+    },
+  },
+  style: { inset: 2, radius: 2 },
+  axis: {
+    y: { title: null },
+    x: { title: null, tickCount: 4 },
+  },
+});
+```
+
+## 地形高程热力图
+
+```javascript
+// 模拟地形高程数据
+const terrainData = [];
+for (let x = 0; x <= 50; x += 2) {
+  for (let y = 0; y <= 50; y += 2) {
+    // 模拟山峰地形：两个山峰的高程分布
+    const elevation1 = 100 * Math.exp(-((x - 15) ** 2 + (y - 15) ** 2) / 200);
+    const elevation2 = 80 * Math.exp(-((x - 35) ** 2 + (y - 35) ** 2) / 150);
+    const elevation = elevation1 + elevation2 + 10; // 基础海拔
+    terrainData.push({ x, y, elevation });
+  }
+}
+
+const chart = new Chart({
+  container: 'container',
+  autoFit: true,
+});
+
+chart.options({
+  type: 'cell',
+  data: terrainData,
+  encode: {
+    x: 'x',
+    y: 'y',
+    color: 'elevation',
+  },
+  style: {
+    stroke: '#333',
+    lineWidth: 0.5,
+    inset: 0.5,
+  },
+  scale: {
+    color: {
+      type: 'sequential',
+      palette: 'viridis',
+    },
+  },
+  legend: {
+    color: {
+      length: 300,
+      layout: { justifyContent: 'center' },
+      labelFormatter: (value) => `${Math.round(value)}m`,
+    },
+  },
+  tooltip: {
+    title: '海拔信息',
+    items: [
+      { field: 'x', name: '经度' },
+      { field: 'y', name: '纬度' },
+      {
+        field: 'elevation',
+        name: '海拔',
+        valueFormatter: (value) => `${Math.round(value)}m`,
+      },
+    ],
+  },
+});
+
+chart.render();
+```
+
+## 常见错误与修正
+
+### 错误 1：color 通道缺少 scale 配置导致离散色
+```javascript
+// ❌ 问题：color 默认使用离散色阶，不适合连续数值
+chart.options({ type: 'cell', encode: { x: 'a', y: 'b', color: 'value' } });
+// value 是连续数值，却被映射到离散颜色
+
+// ✅ 正确：指定连续色阶 palette 并明确类型为 sequential
+chart.options({
+  type: 'cell',
+  encode: { x: 'a', y: 'b', color: 'value' },
+  scale: { 
+    color: { 
+      type: 'sequential',   // 明确指定为顺序色阶
+      palette: 'Blues'      // 或 'YlOrRd'、'Viridis' 等
+    } 
+  },
+});
+```
+
+### 错误 2：格子大小不均匀
+```javascript
+// ❌ 问题：x/y 轴类别数量差异大时格子变形
+// ✅ 解决：设置 Chart 的宽高比接近 x/y 分类数量之比
+const chart = new Chart({
+  container: 'container',
+  width: xCategories.length * 40,    // 每格 40px
+  height: yCategories.length * 40,
+});
+```
+
+### 错误 3：未正确使用 transform.group 导致数据重复或缺失
+```javascript
+// ❌ 问题：当 x/y 通道存在重复组合时，未使用 group 聚合会导致多个格子重叠或数据丢失
+chart.options({
+  type: 'cell',
+  data: [
+    { day: 1, month: 0, temp: 10 },
+    { day: 1, month: 0, temp: 15 }, // 同一天同一月有两个温度记录
+  ],
+  encode: {
+    x: 'day',
+    y: 'month',
+    color: 'temp'
+  }
+});
+// 上述代码可能只显示其中一个值，或出现多个重叠格子
+
+// ✅ 正确：使用 transform.group 对重复数据进行聚合（如取最大值、平均值等）
+chart.options({
+  type: 'cell',
+  data: [
+    { day: 1, month: 0, temp: 10 },
+    { day: 1, month: 0, temp: 15 },
+  ],
+  encode: {
+    x: 'day',
+    y: 'month',
+    color: 'temp'
+  },
+  transform: [{
+    type: 'group',
+    color: 'max'  // 对相同 x/y 组合的数据，取 temp 的最大值
+  }]
+});
+```
+
+### 错误 4：未正确设置 scale.type 为 sequential 导致颜色映射异常
+```javascript
+// ❌ 问题：color 通道未显式设置 scale.type 为 'sequential'，可能导致颜色映射不符合预期
+chart.options({
+  type: 'cell',
+  encode: { x: 'a', y: 'b', color: 'value' },
+  scale: { color: { palette: 'Blues' } } // 仅设置 palette，未设置 type
+});
+
+// ✅ 正确：明确指定 scale.type 为 'sequential'
+chart.options({
+  type: 'cell',
+  encode: { x: 'a', y: 'b', color: 'value' },
+  scale: { 
+    color: { 
+      type: 'sequential',  // 明确指定为顺序色阶
+      palette: 'Blues' 
+    } 
+  }
+});
+```
+
+### 错误 5：调色板名称大小写敏感导致找不到调色板
+```javascript
+// ❌ 问题：调色板名称大小写不匹配，如 'gnBu' 实际应为 'GnBu'
+chart.options({
+  type: 'cell',
+  data,
+  encode: { x: 'day', y: 'month', color: 'temp' },
+  scale: {
+    color: { type: 'sequential', palette: 'gnBu' } // 小写 g 不符合实际命名
+  }
+});
+
+// ✅ 正确：使用正确的调色板名称（注意大小写）
+chart.options({
+  type: 'cell',
+  data,
+  encode: { x: 'day', y: 'month', color: 'temp' },
+  scale: {
+    color: { type: 'sequential', palette: 'GnBu' } // 正确的大写 G
+  }
+});
+```
+
+### 错误 6：数据未定义或引用错误
+```javascript
+// ❌ 问题：使用了未定义的变量 'data'
+const processedData = data.map(...);
+
+// ✅ 正确：确保使用的数据变量已正确定义
+const rawData = [...];
+const processedData = rawData.map(...);
+```
+
+### 错误 7：动画配置语法错误
+```javascript
+// ❌ 问题：animate.enter 应为对象而非字符串或其他类型
+chart.options({
+  type: 'cell',
+  data,
+  encode: { x: 'x', y: 'y', color: 'value' },
+  animate: 'fadeIn' // 错误的配置方式
+});
+
+// ✅ 正确：使用标准的动画配置对象
+chart.options({
+  type: 'cell',
+  data,
+  encode: { x: 'x', y: 'y', color: 'value' },
+  animate: {
+    enter: {
+      type: 'fadeIn',
+      duration: 1000
+    }
+  }
+});
+```

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

@@ -0,0 +1,341 @@
+---
+id: "g2-mark-chord"
+title: "G2 和弦图（Chord Mark）"
+description: |
+  使用 Chord Mark 创建和弦图。和弦图用于展示节点之间的流向关系，
+  常见于贸易流向、迁移数据、资金流动等场景。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "和弦图"
+  - "Chord"
+  - "关系图"
+  - "流向图"
+  - "矩阵可视化"
+
+related:
+  - "g2-mark-sankey"
+  - "g2-mark-link"
+  - "g2-coord-polar"
+
+use_cases:
+  - "展示国家/地区间的贸易流向"
+  - "可视化人口迁移数据"
+  - "分析资金流动关系"
+  - "展示部门间的协作关系"
+
+anti_patterns:
+  - "节点过多（>20个）时可视化效果差"
+  - "不适合展示单向简单关系（改用 Sankey）"
+  - "不适合展示层级结构数据"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/relationship/chord"
+---
+
+## 核心概念
+
+Chord Mark 是 G2 v5 中用于绘制和弦图的复合标记：
+- **节点（Node）**：圆弧上的多边形，表示实体
+- **连线（Link）**：连接节点的带状区域，表示流向关系
+- **布局**：自动计算节点位置和连线形状
+
+**关键配置：**
+- `encode.source`：边的起始节点字段
+- `encode.target`：边的目标节点字段
+- `encode.value`：边的权重字段
+- `layout`：布局配置（节点宽度、间距等）
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+// 和弦图数据：节点 + 边
+const data = {
+  nodes: [
+    { key: 'A', name: '产品A' },
+    { key: 'B', name: '产品B' },
+    { key: 'C', name: '产品C' },
+  ],
+  links: [
+    { source: 'A', target: 'B', value: 100 },
+    { source: 'B', target: 'C', value: 80 },
+    { source: 'C', target: 'A', value: 60 },
+  ],
+};
+
+chart.options({
+  type: 'chord',
+  data: {
+    value: data
+  },
+  encode: {
+    source: 'source',
+    target: 'target',
+    value: 'value',
+  },
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 带节点标签
+
+```javascript
+chart.options({
+  type: 'chord',
+  data: {
+    value: data
+  },
+  encode: {
+    source: 'source',
+    target: 'target',
+    value: 'value',
+    nodeKey: 'key',  // 节点标识字段
+  },
+  nodeLabels: [
+    { text: 'name', position: 'outside', fontSize: 12 },
+  ],
+});
+```
+
+### 自定义布局
+
+```javascript
+chart.options({
+  type: 'chord',
+  data: {
+    value: data
+  },
+  encode: {
+    source: 'source',
+    target: 'target',
+    value: 'value',
+  },
+  layout: {
+    nodeWidthRatio: 0.05,    // 节点宽度比例 (0, 1)
+    nodePaddingRatio: 0.1,   // 节点间距比例 [0, 1)
+    sortBy: 'weight',        // 排序方式: 'id' | 'weight' | 'frequency' | null
+  },
+});
+```
+
+### 自定义样式
+
+```javascript
+chart.options({
+  type: 'chord',
+  data: {
+    value: data
+  },
+  encode: {
+    source: 'source',
+    target: 'target',
+    value: 'value',
+    nodeColor: 'key',        // 节点颜色映射
+    linkColor: 'source',     // 连线颜色映射
+  },
+  style: {
+    node: {
+      opacity: 1,
+      lineWidth: 1,
+    },
+    link: {
+      opacity: 0.5,
+      lineWidth: 1,
+    },
+  },
+});
+```
+
+### 带 Tooltip
+
+```javascript
+chart.options({
+  type: 'chord',
+  data: {
+    value: data
+  },
+  encode: {
+    source: 'source',
+    target: 'target',
+    value: 'value',
+  },
+  tooltip: {
+    node: {
+      title: '',
+      items: [(d) => ({ name: d.key, value: d.value })],
+    },
+    link: {
+      title: '',
+      items: [(d) => ({ name: `${d.source} → ${d.target}`, value: d.value })],
+    },
+  },
+});
+```
+
+## Spec 完整结构速查
+
+```javascript
+chart.options({
+  type: 'chord',
+  data: {
+    // 数据（nodes + links 结构）
+    value: {
+      nodes: [...],
+      links: [...],
+    },
+  },
+  // 通道映射
+  encode: {
+    source: 'source',        // 边的起始节点
+    target: 'target',        // 边的目标节点
+    value: 'value',          // 边的权重
+    nodeKey: 'key',          // 节点标识字段
+    nodeColor: 'key',        // 节点颜色
+    linkColor: 'source',     // 连线颜色
+  },
+
+  // 布局配置
+  layout: {
+    nodeWidthRatio: 0.05,
+    nodePaddingRatio: 0.1,
+    sortBy: null,            // 'id' | 'weight' | 'frequency' | function
+  },
+
+  // 样式
+  style: {
+    node: { opacity: 1, lineWidth: 1 },
+    link: { opacity: 0.5, lineWidth: 1 },
+    label: { fontSize: 10 },
+  },
+
+  // 标签
+  nodeLabels: [{ text: 'name', position: 'outside' }],
+  linkLabels: [],
+
+  // Tooltip
+  tooltip: { ... },
+
+  // 动画
+  animate: {
+    node: { enter: { type: 'fadeIn' } },
+    link: { enter: { type: 'fadeIn' } },
+  },
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface ChordSpec {
+  type: 'chord';
+  data: {
+    value: {
+      nodes: Array<{ key: string; [key: string]: any }>;
+      links: Array<{ source: string; target: string; value: number; [key: string]: any }>;
+    };
+  }
+  encode?: {
+    source?: string;
+    target?: string;
+    value?: string;
+    nodeKey?: string;
+    nodeColor?: string;
+    linkColor?: string;
+  };
+  layout?: {
+    nodeWidthRatio?: number;   // (0, 1), default: 0.05
+    nodePaddingRatio?: number; // [0, 1), default: 0.1
+    sortBy?: 'id' | 'weight' | 'frequency' | ((data: any) => any) | null;
+  };
+  style?: {
+    node?: { opacity?: number; lineWidth?: number; fill?: string };
+    link?: { opacity?: number; lineWidth?: number; fill?: string };
+    label?: { fontSize?: number; fill?: string };
+  };
+  nodeLabels?: LabelOption[];
+  linkLabels?: LabelOption[];
+  tooltip?: TooltipOption;
+  animate?: AnimateOption;
+}
+```
+
+## 常见错误与修正
+
+### 错误 1：数据格式不正确
+
+```javascript
+// ❌ 错误：使用扁平数组
+chart.options({
+  type: 'chord',
+  data: [
+    { source: 'A', target: 'B', value: 100 },
+  ],
+});
+
+// ✅ 正确：使用 nodes + links 结构
+chart.options({
+  type: 'chord',
+  data: {
+    value: {
+      nodes: [{ key: 'A' }, { key: 'B' }],
+      links: [{ source: 'A', target: 'B', value: 100 }],
+    }
+  },
+  encode: { source: 'source', target: 'target', value: 'value' },
+});
+```
+
+### 错误 2：节点 key 不匹配
+
+```javascript
+// ❌ 错误：links 中的 source/target 与 nodes 的 key 不匹配
+const data = {
+  nodes: [{ key: 'ProductA' }],
+  links: [{ source: 'A', target: 'B', value: 100 }],  // 'A' ≠ 'ProductA'
+};
+
+// ✅ 正确：确保 key 一致
+const data = {
+  nodes: [{ key: 'A' }, { key: 'B' }],
+  links: [{ source: 'A', target: 'B', value: 100 }],
+};
+```
+
+### 错误 3：缺少 value 编码
+
+```javascript
+// ❌ 错误：没有指定权重字段
+chart.options({
+  type: 'chord',
+  data: {
+    value: data
+  },
+  encode: { source: 'source', target: 'target' },
+});
+
+// ✅ 正确：指定 value 字段
+chart.options({
+  type: 'chord',
+  data: {
+    value: data
+  },
+  encode: { source: 'source', target: 'target', value: 'value' },
+});
+```