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

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

@@ -0,0 +1,426 @@
+---
+id: "g2-mark-treemap"
+title: "G2 矩形树图（treemap）"
+description: |
+  G2 v5 内置 treemap Mark，用矩形面积表示层级数据中各节点的占比，
+  数据采用嵌套的 children 树形结构，通过 encode.value 映射叶节点数值，
+  支持多种 tile 布局算法和层级钻取交互。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "矩形树图"
+  - "treemap"
+  - "层级数据"
+  - "占比"
+  - "hierarchy"
+  - "树形"
+  - "spec"
+
+related:
+  - "g2-mark-arc-pie"
+  - "g2-mark-sankey"
+  - "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/hierarchy/#treemap"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 800,
+  height: 500,
+});
+
+// 树形嵌套数据
+const data = {
+  name: 'root',
+  children: [
+    {
+      name: '技术',
+      children: [
+        { name: '前端', value: 120 },
+        { name: '后端', value: 180 },
+        { name: '算法', value: 80 },
+      ],
+    },
+    {
+      name: '产品',
+      children: [
+        { name: '移动端', value: 95 },
+        { name: 'Web', value: 60 },
+      ],
+    },
+    {
+      name: '设计',
+      children: [
+        { name: 'UI', value: 70 },
+        { name: 'UX', value: 45 },
+      ],
+    },
+  ],
+};
+
+chart.options({
+  type: 'treemap',
+  data: {
+    value: data
+  },
+  encode: {
+    value: 'value',   // 叶节点数值字段
+  },
+  layout: {
+    tile: 'treemapSquarify',    // 布局算法（默认）
+    paddingInner: 2,            // 矩形间距
+  },
+  style: {
+    labelText: (d) => d.data?.name || '',
+    labelFill: '#fff',
+    labelFontSize: 13,
+    fillOpacity: 0.85,
+  },
+  legend: false,
+});
+
+chart.render();
+```
+
+## 数据配置形式说明
+
+**为什么 treemap 使用 ` { value: data }` 而不是 `data`？**
+
+层次数据是**对象**（包含 name/children），不是数组，必须使用完整形式：
+
+```javascript
+// ❌ 错误：层次数据不是数组，不能用简写
+chart.options({
+  type: 'treemap',
+  data: hierarchyData,  // ❌ 不工作
+});
+
+// ✅ 正确：层次数据必须用完整形式
+chart.options({
+  type: 'treemap',
+  data: { value: hierarchyData },  // ✅
+});
+```
+
+**简写形式仅适用于数组数据**（满足三个条件：内联、是数组、无 transform）。
+
+---
+
+## 完整配置项
+
+```javascript
+chart.options({
+  type: 'treemap',
+  data: {
+    value: hierarchicalData
+  },
+  encode: {
+    value: 'value',   // 叶节点数值字段（决定矩形面积）
+  },
+  layout: {
+    // tile 算法选择：
+    // 'treemapSquarify'（默认，接近正方形）
+    // 'treemapBinary'（二叉分割）
+    // 'treemapDice'（横向分割）
+    // 'treemapSlice'（纵向分割）
+    // 'treemapSliceDice'（交替分割）
+    tile: 'treemapSquarify',
+    paddingInner: 2,      // 同层矩形间距（px）
+    paddingOuter: 4,      // 外边距
+    paddingTop: 20,       // 顶部留白（用于父节点标签）
+    ratio: 1.618,         // 黄金比例（treemapSquarify 专用）
+    ignoreParentValue: true,  // 忽略父节点自身 value
+  },
+  style: {
+    // 矩形标签
+    labelText: (d) => d.data?.name,
+    labelFill: '#fff',
+    labelFontSize: 12,
+    labelPosition: 'top-left',  // 标签位置
+    fillOpacity: 0.8,
+    stroke: '#fff',
+    lineWidth: 1,
+  },
+});
+```
+
+## 多层级标签（父节点 + 叶节点）
+
+```javascript
+chart.options({
+  type: 'treemap',
+  data: {
+    value: data
+  },
+  encode: { value: 'value' },
+  layout: {
+    tile: 'treemapSquarify',
+    paddingInner: 3,
+    paddingTop: 24,       // 为父节点标题留空间
+  },
+  style: {
+    // 叶节点显示名称
+    labelText: (d) => {
+      // path 是从根到当前节点的路径数组
+      return d.depth > 1 ? d.data?.name : '';
+    },
+    // 父节点（depth=1）用大标签
+    labelFontSize: (d) => d.depth === 1 ? 14 : 11,
+    labelFontWeight: (d) => d.depth === 1 ? 'bold' : 'normal',
+    labelFill: '#fff',
+    fillOpacity: (d) => d.depth === 1 ? 0.6 : 0.85,
+  },
+});
+```
+
+## 股票板块热力图（市场涨跌）
+
+```javascript
+const marketData = {
+  name: 'A股',
+  children: [
+    {
+      name: '科技',
+      children: [
+        { name: '华为', value: 1200, change: 3.5 },
+        { name: '腾讯', value: 980,  change: -1.2 },
+        { name: '阿里', value: 850,  change: 0.8 },
+      ],
+    },
+    {
+      name: '金融',
+      children: [
+        { name: '工行', value: 2100, change: 1.1 },
+        { name: '建行', value: 1800, change: -0.5 },
+      ],
+    },
+  ],
+};
+
+chart.options({
+  type: 'treemap',
+  data: {
+    value: marketData
+  },
+  encode: {
+    value: 'value',
+    // 颜色按涨跌幅映射
+    color: (d) => d.data?.change ?? 0,
+  },
+  scale: {
+    color: {
+      type: 'diverging',
+      palette: 'RdYlGn',      // 红（跌）→ 黄（平）→ 绿（涨）
+      domain: [-5, 0, 5],
+    },
+  },
+  style: {
+    labelText: (d) =>
+      d.data?.name && d.data?.change != null
+        ? `${d.data.name}\n${d.data.change > 0 ? '+' : ''}${d.data.change}%`
+        : d.data?.name || '',
+    labelFill: '#fff',
+    labelFontSize: 12,
+  },
+  legend: { color: { position: 'top' } },
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：数据格式非树形结构
+
+```javascript
+// ❌ 错误：treemap 需要树形嵌套数据，不能用平坦数组
+chart.options({
+  type: 'treemap',
+  data: [
+    { name: '前端', value: 120, parent: '技术' },   // ❌ 平坦格式
+  ],
+});
+
+// ✅ 正确：需要 children 嵌套结构
+chart.options({
+  type: 'treemap',
+  data: {
+    value: {
+      name: 'root',
+      children: [
+        {
+          name: '技术',
+          children: [
+            { name: '前端', value: 120 },   // ✅ 叶节点有 value
+          ],
+        },
+      ],
+    },
+  },
+  encode: { value: 'value' },
+});
+```
+
+### 错误 2：encode.value 字段名与数据不匹配
+
+```javascript
+// ❌ 错误：数据中叶节点字段是 size，但 encode.value 写的是 value
+const data = {
+  value: { name: 'root', children: [{ name: 'A', size: 100 }] }
+ };
+chart.options({
+  encode: { value: 'value' },   // ❌ 字段名不匹配
+});
+
+// ✅ 正确
+chart.options({
+  encode: { value: 'size' },    // ✅ 与数据字段一致
+});
+```
+
+---
+
+## 节点数据访问规则（重要！）
+
+层次结构图中，回调函数接收到的参数 `d` **不是原始数据对象**，而是 G2 用 d3-hierarchy 包装后的层次节点，**原始数据在 `d.data` 中**。
+
+### 为什么 `encode.color: 'growth'` 不起作用？
+
+**根本原因**：当 encode 是字符串时，G2 内部做的是 `datum[fieldName]`，直接访问节点对象的属性。对于层次 mark，`datum` 是层次节点（hierarchy node），不是原始数据对象：
+
+```
+d['growth']        → undefined  ❌（层次节点没有 growth 属性）
+d.data['growth']   → 3.5        ✅（原始数据在 d.data 上）
+```
+
+**特例**：`encode.value: 'value'` 看起来用字符串也能工作，是因为 G2 对层次 mark 的 `value` 通道做了**专项处理**，直接读取节点的 `value` 属性（d3-hierarchy 计算后的值）。其他通道（`color`、`shape` 等）没有这个特殊处理，字符串会直接 `datum[field]` 导致 `undefined`。
+
+```javascript
+// ❌ encode.color: 'growth' 的内部执行等价于：
+const color = datum['growth']  // datum 是层次节点，'growth' 不在节点上 → undefined
+// 结果：所有矩形使用相同颜色
+
+// ✅ 使用回调才能正确访问：
+const color = datum.data?.['growth']  // datum.data 才是原始数据对象
+```
+
+### 回调参数 d 的结构
+
+```javascript
+// d 是 d3-hierarchy 节点，结构如下：
+{
+  value: 100,              // 节点数值（d3 计算的叶子值之和）
+  depth: 2,                // 层级深度（0 = 根节点）
+  height: 0,               // 子树高度（叶子节点为 0）
+   {                  // ← 原始数据在这里！
+    name: '前端',
+    value: 120,
+    growth: 3.5,
+    // ... 其它自定义字段
+  },
+  path: ['root', '技术', '前端'],  // 从根到当前节点的路径
+}
+```
+
+### encode 中访问字段
+
+```javascript
+// ❌ 错误：字符串字段名对 color/shape 等通道不起作用，返回 undefined
+encode: {
+  value: 'value',   // ✅ value 通道有专项处理，字符串可用
+  color: 'growth',  // ❌ 等价于 d['growth'] = undefined，所有矩形颜色相同
+}
+
+// ✅ 正确：除 value 外的所有通道必须用回调函数
+encode: {
+  value: 'value',
+  color: (d) => d.data?.growth,  // ✅ 通过 d.data 访问原始字段
+}
+```
+
+### 常用着色策略
+
+```javascript
+// 按父节点着色（推荐，同门类同色，视觉分组清晰）
+color: (d) => d.path?.[1] || d.data?.name
+
+// 按层级深度着色
+color: (d) => d.depth
+
+// 按自定义字段着色
+color: (d) => d.data?.growth
+color: (d) => d.data?.category
+
+// 按数值着色（连续色板）
+color: (d) => d.value
+```
+
+### 配合 scale 自定义颜色
+
+```javascript
+encode: {
+  value: 'value',
+  color: (d) => d.data?.growth,
+},
+scale: {
+  color: {
+    type: 'diverging',
+    palette: 'RdYlGn',
+    domain: [-5, 0, 5],
+  },
+}
+```
+
+### 错误 3：encode.color 使用字符串字段名导致所有矩形颜色相同
+
+```javascript
+// ❌ 错误：color: 'growth' 等价于 d['growth']，层次节点上没有 growth 属性 → undefined
+chart.options({
+  type: 'treemap',
+  data: { value: data },
+  encode: {
+    value: 'value',
+    color: 'growth',  // ❌ d['growth'] = undefined → 所有矩形显示相同颜色
+  },
+});
+
+// ✅ 正确：color 必须用回调函数，通过 d.data 访问原始字段
+chart.options({
+  type: 'treemap',
+  data: { value: data },
+  encode: {
+    value: 'value',
+    color: (d) => d.data?.growth,  // ✅ 按涨跌幅着色
+  },
+});
+```
+
+### 错误 4：labels/style 中使用 d.name 导致 undefined
+
+```javascript
+// ❌ 错误：treemap 节点的原始字段在 d.data 中，d.name 是 undefined
+style: {
+  labelText: (d) => d.name,  // ❌ d.name 是 undefined
+}
+
+// ✅ 正确：通过 d.data 访问原始数据字段
+style: {
+  labelText: (d) => d.data?.name || '',  // ✅
+}
+```

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

@@ -0,0 +1,108 @@
+---
+id: "g2-mark-vector"
+title: "G2 向量图（vector）"
+description: |
+  vector mark 在每个数据点绘制一个有方向和大小的箭头，
+  用于展示风场、水流方向等具有方向和强度的场数据。
+  encode 中用 rotate 通道控制方向（角度），size 通道控制长度。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "vector"
+  - "向量"
+  - "方向场"
+  - "风场"
+  - "箭头"
+  - "流场"
+
+related:
+  - "g2-mark-point-scatter"
+  - "g2-core-encode-channel"
+
+use_cases:
+  - "风场可视化（风向和风速）"
+  - "流体力学模拟结果展示"
+  - "梯度场、力场可视化"
+
+difficulty: "advanced"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/general/point/#vector"
+---
+
+## 最小可运行示例（风场）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+// 模拟风场数据：每个格点有位置、风向（角度）和风速（大小）
+const data = [];
+for (let x = 0; x < 10; x++) {
+  for (let y = 0; y < 10; y++) {
+    const angle = (x * 30 + y * 15) % 360;  // 风向（度）
+    const speed = 2 + Math.random() * 8;      // 风速
+    data.push({ x, y, angle, speed });
+  }
+}
+
+const chart = new Chart({ container: 'container', width: 600, height: 600 });
+
+chart.options({
+  type: 'vector',
+  data,
+  encode: {
+    x: 'x',
+    y: 'y',
+    rotate: 'angle',   // 箭头旋转角度（度，0=向右，顺时针）
+    size: 'speed',     // 箭头长度（映射到速度）
+    color: 'speed',    // 颜色映射风速
+  },
+  scale: {
+    color: { type: 'sequential', palette: 'viridis' },
+    size: { range: [6, 24] },
+  },
+  style: {
+    arrow: true,   // 显示箭头
+  },
+  legend: { color: { title: '风速 (m/s)' } },
+});
+
+chart.render();
+```
+
+## 配置项
+
+```javascript
+chart.options({
+  type: 'vector',
+  data,
+  encode: {
+    x: 'x',
+    y: 'y',
+    rotate: 'direction',  // 方向角度字段（0°=向右，顺时针增加）
+    size: 'magnitude',    // 向量长度字段
+    color: 'intensity',   // 颜色编码字段（可选）
+  },
+  style: {
+    arrow: true,          // 是否显示箭头，默认 true
+    arrowSize: 6,         // 箭头头部大小（px）
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：rotate 是弧度而不是角度
+```javascript
+// ❌ 如果原始数据是弧度，直接用 rotate 通道会导致方向错误
+const data = [{ ..., direction: Math.PI / 4 }];  // 弧度
+chart.options({ encode: { rotate: 'direction' } });  // ❌ G2 期望角度
+
+// ✅ 将弧度转换为角度
+const data = data.map(d => ({ ...d, dirDeg: (d.direction * 180) / Math.PI }));
+chart.options({ encode: { rotate: 'dirDeg' } });  // ✅ 角度值
+```