@loom-framework/core 0.1.0-alpha.84 → 0.1.0-alpha.86

package/builtin-skills/antv-g2-chart/references/scales/g2-scale-linear.md

@@ -0,0 +1,259 @@
+---
+id: "g2-scale-linear"
+title: "G2 线性比例尺（linear scale）"
+description: |
+  G2 v5 线性比例尺用于连续数值字段的映射，通过 scale.y 或 scale.color 配置，
+  支持自定义 domain（数据范围）和 range（视觉范围），
+  nice/clamp/tickCount 控制轴刻度显示。
+library: "g2"
+version: "5.x"
+category: "scales"
+tags:
+  - "线性比例尺"
+  - "linear"
+  - "连续"
+  - "数值"
+  - "domain"
+  - "range"
+  - "spec"
+
+related:
+  - "g2-core-chart-init"
+  - "g2-mark-line-basic"
+  - "g2-comp-annotation"
+
+use_cases:
+  - "控制 Y 轴的显示范围（不从 0 开始）"
+  - "设置颜色映射为连续色板"
+  - "clamp 截断超出范围的数据"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/scale"
+---
+
+## 基本用法（自定义 Y 轴 domain）
+
+折线图默认 y 轴从 0 开始。使用 `scale.y.domain` 指定精确范围，让折线细节更清晰：
+
+> **注意**：`linear` 是数值字段的默认 scale 类型，**不需要手动指定 `type: 'linear'`**。
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'line',
+  data: [
+    { month: 'Jan', value: 4200 },
+    { month: 'Feb', value: 4500 },
+    { month: 'Mar', value: 4100 },
+    { month: 'Apr', value: 4800 },
+    { month: 'May', value: 5200 },
+    { month: 'Jun', value: 4900 },
+  ],
+  encode: { x: 'month', y: 'value' },
+  scale: {
+    y: {
+      domain: [3800, 5500],   // 显式指定 y 轴范围，不从 0 开始
+      nice: true,             // 自动扩展到"好看"的整数刻度
+    },
+  },
+});
+
+chart.render();
+```
+
+## 对数比例尺（log scale）
+
+当数据跨越多个数量级时，使用 `type: 'log'` 将 y 轴压缩为对数尺度：
+
+```javascript
+chart.options({
+  type: 'line',
+  data: [
+    { year: '2018', revenue: 1200 },
+    { year: '2019', revenue: 8500 },
+    { year: '2020', revenue: 32000 },
+    { year: '2021', revenue: 210000 },
+    { year: '2022', revenue: 1500000 },
+  ],
+  encode: { x: 'year', y: 'revenue' },
+  scale: {
+    y: {
+      type: 'log',      // 对数比例尺，适合跨量级数据
+      base: 10,         // 对数底数，默认 10
+      nice: true,
+    },
+  },
+});
+```
+
+> 注意：log scale 不能包含 0 或负数，否则会导致渲染异常。
+
+## 颜色映射：连续色板（sequential color scale）
+
+将数值字段映射为连续颜色，适合热力图或气泡图着色：
+
+```javascript
+chart.options({
+  type: 'point',
+  data: [
+    { x: 10, y: 20, density: 0.1 },
+    { x: 30, y: 50, density: 0.5 },
+    { x: 60, y: 80, density: 0.9 },
+    { x: 45, y: 35, density: 0.3 },
+    { x: 75, y: 60, density: 0.7 },
+  ],
+  encode: { x: 'x', y: 'y', color: 'density', size: 12 },
+  scale: {
+    color: {
+      type: 'linear',
+      domain: [0, 1],                           // 数据范围
+      range: ['#d0e8ff', '#0050b3'],            // 从浅蓝到深蓝
+    },
+  },
+});
+```
+
+## 配置参考
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `type` | `'linear'` \| `'log'` \| `'pow'` \| `'sqrt'` | `'linear'` | 比例尺类型 |
+| `domain` | `[number, number]` | 数据的 min/max | 数据映射范围（输入域） |
+| `range` | `[number, number]` \| `string[]` | 取决于通道 | 视觉映射范围（输出域） |
+| `nice` | `boolean` | `false` | 自动将 domain 扩展到整数刻度 |
+| `clamp` | `boolean` | `false` | 超出 domain 的值截断到边界 |
+| `tickCount` | `number` | 自动 | 期望的刻度数量（近似值） |
+| `tickInterval` | `number` | 自动 | 相邻刻度的固定间隔 |
+| `tickMethod` | `function` | 内置方法 | 自定义刻度生成方法 |
+| `base` | `number` | `10` | 仅 `type: 'log'` 时有效，对数底数 |
+| `exponent` | `number` | `2` | 仅 `type: 'pow'` 时有效，指数 |
+| `zero` | `boolean` | `true` | 是否强制 domain 包含 0 |
+
+```javascript
+// 完整配置示例
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value' },
+  scale: {
+    y: {
+      // type: 'linear',  // 可省略，数值字段默认就是 linear
+      domain: [0, 1000],
+      nice: true,
+      clamp: true,
+      tickCount: 5,
+      // tickInterval: 200,  // 与 tickCount 二选一
+      zero: false,           // 不强制从 0 开始
+    },
+  },
+});
+```
+
+## tickMethod 自定义刻度
+
+`tickMethod` 用于自定义刻度生成，签名是 `(min, max, count) => number[]`：
+
+```javascript
+scale: {
+  y: {
+    tickCount: 5,
+    tickMethod: (min, max, count) => {
+      // 参数说明：
+      // min - 数据最小值
+      // max - 数据最大值
+      // count - 推荐的刻度数量
+
+      // 自定义刻度生成逻辑
+      const step = (max - min) / (count - 1);
+      const ticks = [];
+      for (let i = 0; i < count; i++) {
+        ticks.push(min + i * step);
+      }
+      return ticks;  // 返回数值数组
+    },
+  },
+}
+```
+
+**注意**：如果只需要格式化刻度标签文本，使用 `axis.labelFormatter`：
+
+```javascript
+axis: {
+  y: {
+    labelFormatter: (v) => `${v}万`,  // 格式化标签
+  },
+}
+```
+
+## 常见错误与修正
+
+### 错误：忘记设置 `nice: true` 导致刻度不整齐
+
+```javascript
+// ❌ 刻度可能出现 3827、4183 等非整数
+chart.options({
+  scale: { y: { domain: [3827, 5243] } },
+});
+
+// ✅ nice: true 自动扩展为 3800、5400 等整数刻度
+chart.options({
+  scale: { y: { domain: [3827, 5243], nice: true } },
+});
+```
+
+### 错误：domain 最小值大于最大值（反转轴）
+
+```javascript
+// ❌ domain 反转会导致轴方向翻转（通常不是预期效果）
+chart.options({
+  scale: { y: { domain: [1000, 0] } },
+});
+
+// ✅ 正确：最小值在前，最大值在后
+chart.options({
+  scale: { y: { domain: [0, 1000] } },
+});
+```
+
+### 错误：对 0 或负值使用 log scale
+
+```javascript
+// ❌ log(0) = -Infinity，图表会出现渲染异常或空白
+chart.options({
+  data: [{ x: 'A', y: 0 }, { x: 'B', y: 100 }],
+  scale: { y: { type: 'log' } },
+});
+
+// ✅ 确保所有 y 值 > 0，或对数据做预处理过滤
+chart.options({
+  data: data.filter(d => d.y > 0),
+  scale: { y: { type: 'log', domain: [1, 1000000] } },
+});
+```
+
+### 错误：tickCount 和 tickInterval 同时设置
+
+```javascript
+// ❌ 两者同时设置时 tickInterval 优先，tickCount 被忽略
+chart.options({
+  scale: { y: { tickCount: 5, tickInterval: 200 } },
+});
+
+// ✅ 根据需求二选一
+chart.options({
+  scale: { y: { tickCount: 5 } },      // 约 5 个刻度
+  // 或
+  // scale: { y: { tickInterval: 200 } },  // 每隔 200 一个刻度
+});
+```

package/builtin-skills/antv-g2-chart/references/scales/g2-scale-log.md

@@ -0,0 +1,226 @@
+---
+id: "g2-scale-log"
+title: "G2 对数比例尺（log）"
+description: |
+  对数比例尺将数值映射为对数刻度，适合数据跨越多个数量级（如 1 到 1,000,000）的场景。
+  使用 base 参数设置对数底数（默认 10），可以有效展示指数增长或数量级差异悬殊的数据。
+
+library: "g2"
+version: "5.x"
+category: "scales"
+tags:
+  - "log"
+  - "对数"
+  - "比例尺"
+  - "数量级"
+  - "scale"
+  - "指数增长"
+
+related:
+  - "g2-scale-linear"
+  - "g2-scale-pow"
+
+use_cases:
+  - "展示数量级差异悬殊的数据（如 GDP 对比：100 万到 1 万亿）"
+  - "病毒传播等指数增长数据"
+  - "频率分布的幂律特征"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/scale/log"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+// 数量级差异悬殊的数据
+const data = [
+  { country: '卢森堡',     gdp: 135000 },
+  { country: '美国',       gdp: 65000 },
+  { country: '中国',       gdp: 12000 },
+  { country: '巴西',       gdp: 7500 },
+  { country: '印度',       gdp: 2100 },
+  { country: '埃塞俄比亚', gdp: 900 },
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'country', y: 'gdp', color: 'country' },
+  scale: {
+    y: {
+      type: 'log',    // 对数比例尺
+      base: 10,       // 底数，默认 10
+      domain: [100, 200000],
+    },
+  },
+  axis: {
+    y: {
+      title: '人均 GDP（美元，对数轴）',
+      tickCount: 5,
+    },
+  },
+});
+
+chart.render();
+```
+
+## 配置项
+
+```javascript
+scale: {
+  y: {
+    type: 'log',
+    base: 10,          // 对数底数，常用 2 或 10，默认 10
+    domain: [1, 1e6],  // 数值范围（注意：不能包含 0 或负数！）
+    nice: true,        // 将刻度扩展到整数幂次
+    tickCount: 5,      // 推荐的刻度数量
+    tickMethod: (min, max, count, base) => {
+      // 自定义刻度生成方法
+      // 返回刻度值数组
+      return [1, 10, 100, 1000, 10000];
+    },
+  },
+}
+```
+
+## 刻度控制：tickMethod vs labelFormatter vs tickFormatter
+
+三者职责完全不同，不能混用：
+
+| 配置项 | 位置 | 签名 | 职责 |
+|--------|------|------|------|
+| `tickMethod` | `scale.y` 或 `axis.y` | `(min, max, count, base?) => number[]` | 决定**哪些数值**显示刻度 |
+| `labelFormatter` | `axis.y` | `(value, index, array) => string` | 决定刻度的**显示文字** ⭐ 最常用 |
+| `tickFormatter` | `axis.y` | `(datum, index, array, vector) => DisplayObject` | 自定义刻度线的**图形对象**（极少用） |
+
+### 只格式化刻度标签文字（最常见）
+
+```javascript
+// ✅ 只需改显示文字 → 用 axis.labelFormatter，不需要 tickMethod
+chart.options({
+  scale: { y: { type: 'log', base: 10 } },
+  axis: {
+    y: {
+      labelFormatter: (v) => v >= 1e6 ? `${v/1e6}M` : v >= 1e3 ? `${v/1e3}K` : String(v),
+    },
+  },
+});
+```
+
+### 同时自定义刻度位置 + 标签文字
+
+```javascript
+// ✅ tickMethod 控制"打哪些刻度"，labelFormatter 控制"显示什么文字"
+chart.options({
+  scale: {
+    y: {
+      type: 'log',
+      base: 10,
+      domain: [0.1, 1000],
+      // 签名：(min, max, count, base) => number[]，必须返回数值数组
+      tickMethod: (min, max, count, base) => [0.1, 1, 10, 100, 1000],
+    },
+  },
+  axis: {
+    y: {
+      labelFormatter: (v) => `10^${Math.log10(v)}`,
+    },
+  },
+});
+```
+
+## 折线图的对数轴（指数增长数据）
+
+```javascript
+chart.options({
+  type: 'line',
+  data: covidData,
+  encode: { x: 'date', y: 'cases', color: 'country' },
+  scale: {
+    y: { type: 'log', base: 10, nice: true },
+  },
+  axis: {
+    y: {
+      title: '累计病例数（对数轴）',
+      labelFormatter: (v) => v >= 1e6 ? `${v / 1e6}M` : v >= 1e3 ? `${v / 1e3}K` : String(v),
+    },
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：tickMethod 签名错误，且混淆了刻度位置与标签格式化
+
+`tickMethod` 有两处可配置，**签名不同，职责不同**：
+
+| 位置 | 签名 | 职责 |
+|------|------|------|
+| `scale.y.tickMethod` | `(min, max, n?, base?) => number[]` | 控制刻度的**数值位置** |
+| `axis.y.tickMethod` | `(start, end, tickCount) => number[]` | 同上，也是返回数值数组 |
+| `axis.y.labelFormatter` | `(value) => string` | 控制刻度的**显示文字** |
+
+```javascript
+// ❌ 三重错误：
+// 1. 参数写成了 scale 对象（实际是 min/max/count/base 四个数值）
+// 2. 调用了不存在的 scale.ticks() 方法
+// 3. 返回了 {value, text} 对象数组（应返回 number[]）
+scale: {
+  y: {
+    type: 'log',
+    tickMethod: (scale) => {
+      const ticks = scale.ticks();
+      return ticks.map(tick => ({ value: tick, text: `log10(${tick}) + 1` }));
+    },
+  },
+}
+
+// ✅ 正确拆分：tickMethod 控制位置，labelFormatter 控制文字
+scale: {
+  y: {
+    type: 'log',
+    base: 10,
+    domain: [0.1, 1000],
+    tickMethod: (min, max, count, base) => [0.1, 1, 10, 100, 1000],  // ✅ 返回 number[]
+  },
+},
+axis: {
+  y: {
+    labelFormatter: (v) => `${Math.log10(v) + 1}`,  // ✅ 格式化文字
+  },
+}
+```
+
+### 错误 2：数据包含 0 或负数——对数比例尺无法处理
+```javascript
+// ❌ 对数 log(0) = -∞，数据中有 0 会导致渲染异常
+const data = [{ x: 'A', y: 0 }, { x: 'B', y: 100 }];
+chart.options({
+  scale: { y: { type: 'log' } },  // ❌ y=0 无法在对数轴上显示
+});
+
+// ✅ 对数轴要求所有值 > 0，可以过滤掉 0 或加微小偏移
+const data = [{ x: 'B', y: 100 }];  // ✅ 过滤掉 0
+// 或使用 domain 强制起点 > 0
+chart.options({
+  scale: { y: { type: 'log', domain: [0.1, 1000] } },
+});
+```
+
+### 错误 3：对线性数据使用对数轴——视觉失真
+```javascript
+// ❌ 数据范围是 50~200，没有数量级差异，对数轴没有意义且会误导读者
+const data = [/* 50~200 之间的均匀分布 */];
+chart.options({ scale: { y: { type: 'log' } } });  // ❌ 不必要
+
+// ✅ 线性数据用默认线性比例尺
+chart.options({ scale: { y: { type: 'linear' } } });  // ✅ 或直接省略（默认）
+```

package/builtin-skills/antv-g2-chart/references/scales/g2-scale-ordinal.md

@@ -0,0 +1,135 @@
+---
+id: "g2-scale-ordinal"
+title: "G2 序数比例尺（ordinal）"
+description: |
+  序数比例尺将离散的分类值映射到离散的输出值（如颜色）。
+  主要用于 color 通道，将字符串类别映射到颜色数组。
+  通过 range 指定自定义颜色列表，或通过 palette 使用内置调色板。
+
+library: "g2"
+version: "5.x"
+category: "scales"
+tags:
+  - "ordinal"
+  - "序数"
+  - "比例尺"
+  - "颜色"
+  - "分类色"
+  - "scale"
+  - "palette"
+
+related:
+  - "g2-scale-linear"
+  - "g2-theme-builtin"
+
+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/scale/ordinal"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+chart.options({
+  type: 'interval',
+  data: [
+    { genre: '运动', sold: 275 },
+    { genre: '策略', sold: 115 },
+    { genre: '动作', sold: 120 },
+    { genre: 'RPG',  sold: 98 },
+  ],
+  encode: { x: 'genre', y: 'sold', color: 'genre' },
+  scale: {
+    color: {
+      type: 'ordinal',
+      // 自定义颜色列表（顺序对应 domain 中的分类）
+      range: ['#F4664A', '#FAAD14', '#5B8FF9', '#30BF78'],
+    },
+  },
+});
+
+chart.render();
+```
+
+## 指定类别到颜色的映射（domain + range）
+
+```javascript
+chart.options({
+  scale: {
+    color: {
+      type: 'ordinal',
+      domain: ['通过', '失败', '跳过'],   // 指定分类顺序
+      range: ['#52c41a', '#ff4d4f', '#faad14'],  // 对应颜色
+    },
+  },
+});
+```
+
+## 使用内置调色板
+
+```javascript
+// G2 内置调色板名称：'tableau10', 'category10', 'set2', 'pastel', 'blues', etc.
+chart.options({
+  scale: {
+    color: {
+      type: 'ordinal',
+      palette: 'tableau10',   // 使用 Tableau 10 色调色板
+    },
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：range 颜色数量少于分类数量——后面的类别颜色循环重用
+```javascript
+// ⚠️  5 个分类只有 3 个颜色，第 4/5 个类别颜色与前两个相同
+chart.options({
+  scale: {
+    color: {
+      type: 'ordinal',
+      domain: ['A', 'B', 'C', 'D', 'E'],
+      range: ['red', 'blue', 'green'],  // ⚠️  只有 3 个颜色，D/E 会循环
+    },
+  },
+});
+
+// ✅ range 颜色数量应 ≥ 分类数量
+chart.options({
+  scale: {
+    color: {
+      type: 'ordinal',
+      range: ['#F4664A', '#FAAD14', '#5B8FF9', '#30BF78', '#9254DE'],  // ✅ 5 个
+    },
+  },
+});
+```
+
+### 错误 2：连续数值通道误用 ordinal——应用 linear 或 sequential
+```javascript
+// ❌ 对数值 y 轴使用 ordinal（Y 轴会变成离散）
+chart.options({
+  scale: {
+    y: { type: 'ordinal' },  // ❌ y 是数值，应用 linear
+  },
+});
+
+// ✅ 数值比例尺用 linear
+chart.options({
+  scale: {
+    y: { type: 'linear' },  // ✅
+  },
+});
+```