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

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

@@ -0,0 +1,275 @@
+---
+id: "g2-mark-partition"
+title: "G2 旭日图 / 矩形分区（partition）"
+description: |
+  partition mark 用矩形分区展示层次数据，每层从父节点延伸，子节点填满父节点宽度。
+  配合极坐标可绘制旭日图（sunburst）——同心圆环形式的层次可视化。
+  支持 drillDown 交互实现层次下钻。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "partition"
+  - "旭日图"
+  - "sunburst"
+  - "层次数据"
+  - "矩形分区"
+  - "下钻"
+
+related:
+  - "g2-mark-treemap"
+  - "g2-interaction-drilldown"
+  - "g2-mark-pack"
+
+use_cases:
+  - "旭日图展示层次分类的占比（如文件目录）"
+  - "组织结构的层次可视化"
+  - "多层类别数据的占比展示"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/general/other/#sunburst"
+---
+
+## 最小可运行示例（旭日图）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = {
+  name: '总计',
+  children: [
+    {
+      name: '技术',
+      children: [
+        { name: '前端', value: 15 },
+        { name: '后端', value: 20 },
+        { name: '算法', value: 10 },
+      ],
+    },
+    {
+      name: '产品',
+      children: [
+        { name: '产品经理', value: 8 },
+        { name: '用研', value: 5 },
+      ],
+    },
+    {
+      name: '设计',
+      children: [
+        { name: 'UX', value: 7 },
+        { name: '视觉', value: 6 },
+      ],
+    },
+  ],
+};
+
+const chart = new Chart({ container: 'container', width: 600, height: 600 });
+
+chart.options({
+  type: 'sunburst',   // 旭日图 = partition + 极坐标（G2 内置别名）
+  data: { value: data },
+  encode: {
+    value: 'value',   // 叶子节点数值
+  },
+  style: {
+    fillOpacity: 0.9,
+    lineWidth: 1,
+    stroke: '#fff',
+  },
+  interaction: { drillDown: true },  // 可选：启用下钻
+});
+
+chart.render();
+```
+
+## 数据配置形式说明
+
+**为什么 partition/sunburst 使用 ` { value: data }` 而不是 `data`？**
+
+层次数据是**对象**（包含 name/children），不是数组，必须使用完整形式：
+
+```javascript
+// ❌ 错误：层次数据不是数组，不能用简写
+chart.options({
+  type: 'partition',
+   hierarchyData,  // ❌ 不工作
+});
+
+// ✅ 正确：层次数据必须用完整形式
+chart.options({
+  type: 'partition',
+  data: { value: hierarchyData },  // ✅
+});
+```
+
+**简写形式仅适用于数组数据**（满足三个条件：内联、是数组、无 transform）。
+
+---
+
+## 矩形分区图（不加极坐标）
+
+```javascript
+chart.options({
+  type: 'partition',   // 矩形分区（不是旭日图）
+  data: { value: data },
+  encode: {
+    value: 'value',   // 叶子节点数值
+  },
+  layout: {
+    valueField: 'value',   // 决定节点宽度的字段
+    sort: (a, b) => b.value - a.value,  // 按值降序排列
+  },
+  style: {
+    fillOpacity: 0.85,
+    stroke: '#fff',
+    lineWidth: 1,
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：data 直接传树形对象而不用 hierarchy 包装
+```javascript
+// ❌ 错误
+chart.options({
+  type: 'sunburst',
+  data: treeData,   // ❌ 直接传树形数据
+});
+
+// ✅ 正确：需要放到 data.value 中
+chart.options({
+  type: 'sunburst',
+  data: { value: treeData },  // ✅
+});
+```
+
+---
+
+## 节点数据访问规则（重要！）
+
+层次结构图中，回调函数接收到的参数 `d` **不是原始数据对象**，而是 G2 用 d3-hierarchy 包装后的层次节点，**原始数据在 `d.data` 中**。
+
+### 为什么 `encode.color: 'category'` 不起作用？
+
+**根本原因**：当 encode 是字符串时，G2 内部做的是 `datum[fieldName]`，直接访问层次节点属性。层次节点上没有 `category` 属性，返回 `undefined`，导致所有区域显示相同颜色。
+
+```
+d['category']        → undefined   ❌（层次节点没有 category 属性）
+d.data['category']   → '技术'      ✅（原始数据在 d.data 上）
+```
+
+**特例**：`encode.value: 'value'` 字符串可以工作，因为 G2 对层次 mark 的 `value` 通道做了**专项处理**。其他通道（`color`、`shape` 等）无此特殊处理，必须用回调。
+
+### 回调参数 d 的结构
+
+```javascript
+// d 是 d3-hierarchy 节点，结构如下：
+{
+  value: 100,              // 节点数值（d3 计算的子树总和）
+  depth: 2,                // 层级深度（0 = 根节点）
+  height: 0,               // 子树高度（叶子节点为 0）
+   {                  // ← 原始数据在这里！
+    name: '前端',
+    value: 15,
+    category: '技术',
+    // ... 其它自定义字段
+  },
+  path: ['root', '技术', '前端'],
+}
+```
+
+### encode 中访问字段
+
+```javascript
+// ❌ 错误：字符串字段名对 color 通道不起作用
+encode: {
+  value: 'value',      // ✅ value 通道有专项处理
+  color: 'category',   // ❌ d['category'] = undefined → 所有区域颜色相同
+}
+
+// ✅ 正确：color 必须用回调函数
+encode: {
+  value: 'value',
+  color: (d) => d.data?.category,  // ✅
+}
+```
+
+### 常用着色策略
+
+```javascript
+// 按第二层父节点着色（推荐，同门类同色）
+color: (d) => d.path?.[1] || d.data?.name
+
+// 按层级深度着色
+color: (d) => d.depth
+
+// 按自定义字段着色
+color: (d) => d.data?.category
+color: (d) => d.data?.type
+
+// 按数值着色（连续色板）
+color: (d) => d.value
+```
+
+### 错误 2：encode.color 使用字符串字段名导致所有区域颜色相同
+
+```javascript
+// ❌ 错误：color: 'category' 等价于 d['category']，层次节点上没有此属性 → undefined
+chart.options({
+  type: 'sunburst',
+  data: { value: data },
+  encode: {
+    value: 'value',
+    color: 'category',  // ❌ → 所有扇区相同颜色
+  },
+});
+
+// ✅ 正确：color 必须用回调，通过 d.data 访问原始字段
+chart.options({
+  type: 'sunburst',
+  data: { value: data },
+  encode: {
+    value: 'value',
+    color: (d) => d.path?.[1] || d.data?.name,  // ✅ 按父节点着色
+  },
+});
+```
+
+### 错误 3：labels 中使用 d.name 导致 undefined
+
+```javascript
+// ❌ 错误：partition 节点的原始字段在 d.data 中，d.name 是 undefined
+labels: [
+  {
+    text: (d) => d.name,  // ❌ d.name 是 undefined
+  },
+]
+
+// ✅ 正确：通过 d.data 访问原始数据字段
+labels: [
+  {
+    text: (d) => d.data?.name || '',  // ✅
+  },
+]
+```
+
+### 配合 scale 自定义颜色
+
+```javascript
+encode: {
+  value: 'value',
+  color: (d) => d.data?.category,
+},
+scale: {
+  color: {
+    type: 'sequential',
+    palette: 'blues',
+  },
+}
+```

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

@@ -0,0 +1,135 @@
+---
+id: "g2-mark-path"
+title: "G2 路径标注（path）"
+description: |
+  path mark 通过 SVG 路径字符串（d 属性）绘制任意形状，
+  适合自定义图形、地图轮廓、流程图箭头等无法用标准 mark 表达的形状。
+  与 line mark 区别：line 连接数据点坐标，path 直接使用 SVG d 路径字符串。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "path"
+  - "路径"
+  - "SVG"
+  - "自定义形状"
+  - "annotation"
+
+related:
+  - "g2-mark-polygon"
+  - "g2-mark-link"
+  - "g2-mark-connector"
+
+use_cases:
+  - "绘制自定义 SVG 路径形状"
+  - "地图轮廓（非 GeoJSON）标注"
+  - "自定义箭头和流程图元素"
+
+difficulty: "advanced"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/mark/path"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+// path mark 通过 d 字段提供 SVG 路径字符串
+const pathData = [
+  {
+    d: 'M 100 200 C 100 100 400 100 400 200 S 700 300 700 200',
+    color: '#5B8FF9',
+    label: '曲线路径',
+  },
+  {
+    d: 'M 100 350 L 250 300 L 400 350 L 550 300 L 700 350',
+    color: '#FF6B6B',
+    label: '折线路径',
+  },
+];
+
+chart.options({
+  type: 'view',
+  width: 640,
+  height: 480,
+  children: [
+    {
+      type: 'path',
+      data: pathData,
+      encode: {
+        d: 'd',          // SVG 路径字符串字段
+        color: 'color',
+      },
+      style: {
+        lineWidth: 2,
+        fillOpacity: 0,  // 路径通常只显示描边
+      },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 带填充的封闭路径
+
+```javascript
+// 封闭路径（Z 命令）可以填充颜色
+const shapes = [
+  {
+    d: 'M 200 100 L 300 300 L 100 300 Z',  // 三角形
+    category: 'triangle',
+  },
+  {
+    d: 'M 450 100 L 550 150 L 550 250 L 450 300 L 350 250 L 350 150 Z',  // 六边形
+    category: 'hexagon',
+  },
+];
+
+chart.options({
+  type: 'path',
+  data: shapes,
+  encode: {
+    d: 'd',
+    color: 'category',
+  },
+  style: {
+    fillOpacity: 0.3,
+    lineWidth: 2,
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：path mark 使用 x/y encode——path 不支持坐标编码
+```javascript
+// ❌ path mark 不使用 x/y，而是使用 d（SVG 路径字符串）
+chart.options({
+  type: 'path',
+  encode: { x: 'x', y: 'y' },  // ❌ path mark 不支持坐标编码
+});
+
+// ✅ path mark 使用 d 字段提供完整的 SVG 路径
+chart.options({
+  type: 'path',
+  encode: { d: 'd' },           // ✅ d 字段为 SVG 路径字符串
+  style: { lineWidth: 2 },
+});
+```
+
+### 错误：path 与 line 混淆——连接数据点应用 line
+```javascript
+// 连接多个数据坐标点 → 用 line mark
+chart.options({ type: 'line', encode: { x: 'date', y: 'value' } });
+
+// 自定义 SVG 路径形状 → 用 path mark
+chart.options({ type: 'path', encode: { d: 'pathString' } });
+```

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

@@ -0,0 +1,138 @@
+---
+id: "g2-mark-point-bubble"
+title: "G2 气泡图（bubble chart）"
+description: |
+  气泡图是散点图的扩展，用第三个通道 size（气泡大小）编码额外的数值维度。
+  通过 encode.size 绑定数值字段，G2 自动将数值映射为圆的面积（而非半径）。
+  适合同时展示三个数值维度的关系。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "气泡图"
+  - "bubble"
+  - "散点图"
+  - "point"
+  - "三维度"
+  - "size"
+
+related:
+  - "g2-mark-point-scatter"
+  - "g2-scale-linear"
+
+use_cases:
+  - "三维度数据关系（如 GDP、人口、预期寿命）"
+  - "用气泡大小表达第三个指标"
+  - "对比矩阵中的强度展示"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/general/point/#bubble"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { country: '中国',    gdp: 17.7, population: 14.1, life: 77 },
+  { country: '美国',    gdp: 25.5, population: 3.3,  life: 79 },
+  { country: '印度',    gdp: 3.4,  population: 14.2, life: 70 },
+  { country: '日本',    gdp: 4.2,  population: 1.26, life: 84 },
+  { country: '巴西',    gdp: 1.8,  population: 2.15, life: 76 },
+  { country: '德国',    gdp: 4.1,  population: 0.83, life: 81 },
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'point',
+  data,
+  encode: {
+    x: 'gdp',          // X 轴：GDP（万亿美元）
+    y: 'life',         // Y 轴：预期寿命（岁）
+    size: 'population', // 气泡大小：人口（亿）
+    color: 'country',  // 颜色：国家
+    shape: 'circle',
+  },
+  scale: {
+    size: {
+      range: [8, 60],   // 气泡半径范围（px），最小/最大
+    },
+  },
+  style: {
+    fillOpacity: 0.7,
+    lineWidth: 1,
+    stroke: '#fff',
+  },
+  labels: [
+    {
+      text: 'country',
+      position: 'inside',
+      style: { fontSize: 10 },
+    },
+  ],
+  tooltip: {
+    items: [
+      { channel: 'x', name: 'GDP (万亿)', valueFormatter: (v) => `$${v}T` },
+      { channel: 'y', name: '预期寿命', valueFormatter: (v) => `${v}岁` },
+      { channel: 'size', name: '人口', valueFormatter: (v) => `${v}亿` },
+    ],
+  },
+});
+
+chart.render();
+```
+
+## 配置 size 比例尺
+
+```javascript
+scale: {
+  size: {
+    type: 'linear',   // 默认：线性映射数值到大小
+    range: [5, 50],   // [最小半径, 最大半径] (px)
+    // 注意：G2 用面积而非半径映射，视觉上更准确
+  },
+}
+```
+
+## 常见错误与修正
+
+### 错误 1：size 通道绑定字符串类别而不是数值
+```javascript
+// ❌ 错误：size 通道应绑定数值字段，而不是类别
+chart.options({
+  encode: {
+    size: 'country',  // ❌ 字符串，无法映射为大小
+  },
+});
+
+// ✅ 正确：size 绑定数值字段
+chart.options({
+  encode: {
+    size: 'population',  // ✅ 数值，可映射为气泡大小
+  },
+});
+```
+
+### 错误 2：没有设置 scale.size.range——气泡太小或太大
+```javascript
+// ❌ 默认 range 可能导致气泡尺寸不合适（遮挡其他数据或几乎不可见）
+chart.options({
+  encode: { size: 'value' },
+  // ❌ 没有 scale.size.range
+});
+
+// ✅ 明确设置合适的气泡大小范围
+chart.options({
+  encode: { size: 'value' },
+  scale: {
+    size: { range: [8, 48] },  // ✅ 合适的视觉范围
+  },
+});
+```