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

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

@@ -0,0 +1,267 @@
+---
+id: "g2-scale-sequential"
+title: "G2 顺序比例尺（sequential）"
+description: |
+  sequential 比例尺将连续数值映射到颜色渐变，
+  专为颜色通道设计，常配合 palette（内置色板）或自定义颜色插值函数使用。
+  适合热力图、地图着色、连续数值颜色编码场景。
+  与 linear 的区别：sequential 专为颜色输出优化，linear 支持任意数值输出。
+  ⚠️ 约束：仅当 encode.color 映射的字段为连续类型（数值型）时使用。
+  分类字段（字符串/枚举）和间断字段（ordinal/band）禁止使用 sequential，
+  否则会产生错误的颜色渐变，应改用 ordinal 比例尺。
+
+library: "g2"
+version: "5.x"
+category: "scales"
+tags:
+  - "sequential"
+  - "顺序比例尺"
+  - "颜色渐变"
+  - "连续颜色"
+  - "palette"
+  - "scale"
+
+related:
+  - "g2-scale-linear"
+  - "g2-scale-quantile-quantize"
+  - "g2-scale-threshold"
+  - "g2-mark-cell-heatmap"
+
+use_cases:
+  - "热力图颜色渐变（低值→高值）"
+  - "地图按数值着色（choropleth）"
+  - "散点图气泡颜色按数值渐变"
+
+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/sequential"
+---
+
+## ⚠️ 使用约束
+
+**sequential 仅适用于 `encode.color` 字段为连续类型（数值型）的场景。**
+
+| 字段类型 | 示例 | 是否可用 sequential |
+|--------|------|------------------|
+| 连续数值（quantitative） | `temp_max`、`sales`、`score` | ✅ 允许 |
+| 分类（categorical / ordinal） | `city`、`category`、`name` | ❌ 禁止，用 `ordinal` |
+| 间断（band / point） | 离散的坐标轴字段 | ❌ 禁止，用 `ordinal` |
+
+分类或间断字段使用 sequential 会导致所有数据映射到渐变色的两端，颜色区分度极差。
+
+## 最小可运行示例（热力图）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+chart.options({
+  type: 'cell',
+  data: {
+    type: 'fetch',
+    value: 'https://assets.antv.antgroup.com/g2/seattle-weather.json',
+  },
+  encode: {
+    x: (d) => new Date(d.date).getUTCDate(),
+    y: (d) => new Date(d.date).getUTCMonth(),
+    color: 'temp_max',
+  },
+  transform: [{ type: 'group', color: 'max' }],
+  scale: {
+    color: {
+      type: 'sequential',
+      palette: 'gnBu',   // 内置色板：从浅蓝到深蓝
+    },
+  },
+  style: { inset: 0.5 },
+});
+
+chart.render();
+```
+
+## 合法 palette 完整列表
+
+G2 的 `palette` 值通过 d3-scale-chromatic 查找，**只有以下名称合法**（大小写不敏感），不在此列表中的名称（如 `'blueOrange'`、`'redGreen'`、`'heatmap'`）会导致运行时报错 `Unknown palette`。
+
+### 单色系顺序渐变（适合 sequential — 正值数据）
+
+| palette 名称 | 效果 |
+|------------|------|
+| `'blues'` | 白→蓝 |
+| `'greens'` | 白→绿 |
+| `'reds'` | 白→红 |
+| `'oranges'` | 白→橙 |
+| `'purples'` | 白→紫 |
+| `'greys'` | 白→灰 |
+| `'orRd'` | 橙→红 |
+| `'buGn'` | 蓝→绿 |
+| `'buPu'` | 蓝→紫 |
+| `'gnBu'` | 绿→蓝 |
+| `'puBu'` | 紫→蓝 |
+| `'puBuGn'` | 紫→蓝→绿 |
+| `'puRd'` | 紫→红 |
+| `'rdPu'` | 红→紫 |
+| `'ylGn'` | 黄→绿 |
+| `'ylGnBu'` | 黄→绿→蓝（sequential 默认值） |
+| `'ylOrBr'` | 黄→橙→棕 |
+| `'ylOrRd'` | 黄→橙→红 |
+
+### 多色感知均匀渐变（适合 sequential — 推荐色盲友好）
+
+| palette 名称 | 效果 |
+|------------|------|
+| `'viridis'` | 紫→蓝→绿→黄（感知均匀，色盲友好） |
+| `'plasma'` | 蓝紫→橙黄 |
+| `'magma'` | 黑→紫→橙→白 |
+| `'inferno'` | 黑→紫→红→黄 |
+| `'cividis'` | 蓝→黄（对所有色盲类型友好） |
+| `'turbo'` | 蓝→绿→黄→红（彩虹改进版） |
+| `'rainbow'` | 彩虹（不建议，感知不均匀） |
+| `'sinebow'` | 平滑彩虹 |
+| `'warm'` | 暖色（橙→红→紫） |
+| `'cool'` | 冷色（青→蓝→紫） |
+| `'cubehelixDefault'` | 螺旋渐变（黑→白） |
+
+### 发散色阶（适合 diverging — 正负值对比）
+
+| palette 名称 | 效果 |
+|------------|------|
+| `'rdBu'` | 红→白→蓝（最常用） |
+| `'rdYlBu'` | 红→黄→蓝 |
+| `'rdYlGn'` | 红→黄→绿（涨跌热力图） |
+| `'rdGy'` | 红→白→灰 |
+| `'pRGn'` | 紫→白→绿 |
+| `'piYG'` | 粉红→白→黄绿 |
+| `'puOr'` | 紫→白→橙 |
+| `'brBG'` | 棕→白→蓝绿 |
+| `'spectral'` | 红→橙→黄→绿→蓝（多色发散） |
+
+```javascript
+// ✅ 合法示例
+scale: { color: { type: 'sequential', palette: 'blues' } }
+scale: { color: { type: 'sequential', palette: 'viridis' } }
+scale: { color: { type: 'sequential', palette: 'ylOrRd' } }
+scale: { color: { type: 'diverging',  palette: 'rdBu' } }
+scale: { color: { type: 'diverging',  palette: 'rdYlGn' } }
+
+// ❌ 非法示例（不存在，会报 Unknown palette 错误）
+scale: { color: { type: 'sequential', palette: 'blueOrange' } }  // ❌ 不存在
+scale: { color: { type: 'sequential', palette: 'redGreen' } }    // ❌ 不存在
+scale: { color: { type: 'sequential', palette: 'heatmap' } }     // ❌ 不存在
+scale: { color: { type: 'sequential', palette: 'rainbow2' } }    // ❌ 不存在
+scale: { color: { type: 'sequential', palette: 'blue-orange' } } // ❌ 不存在
+```
+
+## 自定义颜色范围
+
+```javascript
+// 使用 range 指定首尾颜色（两端插值）
+chart.options({
+  scale: {
+    color: {
+      type: 'sequential',
+      range: ['#ebedf0', '#196127'],  // 从浅灰到深绿（GitHub 贡献图风格）
+    },
+  },
+});
+
+// 使用 domain 控制映射范围
+chart.options({
+  scale: {
+    color: {
+      type: 'sequential',
+      palette: 'blues',
+      domain: [0, 100],   // 明确指定数值范围
+    },
+  },
+});
+```
+
+## sequential vs 其他颜色比例尺
+
+```javascript
+// sequential：连续颜色渐变（连续数值 → 连续颜色）
+scale: { color: { type: 'sequential', palette: 'blues' } }
+
+// quantile：自动分位数分组（连续数值 → 离散颜色，等频分组）
+scale: { color: { type: 'quantile', range: ['#eee', '#aaa', '#666', '#000'] } }
+
+// quantize：等距分段（连续数值 → 离散颜色，等距分组）
+scale: { color: { type: 'quantize', domain: [0, 100], range: ['#fee', '#f99', '#f00'] } }
+
+// threshold：手动断点分级（连续数值 → 离散颜色，自定义断点）
+scale: { color: { type: 'threshold', domain: [25, 75], range: ['#0f0', '#ff0', '#f00'] } }
+```
+
+## 常见错误与修正
+
+### 错误：使用不存在的 palette 名称
+
+G2 的 palette 值来自 d3-scale-chromatic，不存在的名称会在运行时抛出 `Error: Unknown palette: XxxXxx`，图表无法渲染。
+
+```javascript
+// ❌ 这些名称看起来合理，但 G2 中不存在
+scale: { color: { type: 'sequential', palette: 'blueOrange' } }   // ❌ → Error: Unknown palette
+scale: { color: { type: 'sequential', palette: 'blueGreen' } }    // ❌ → 应用 'buGn' 或 'gnBu'
+scale: { color: { type: 'sequential', palette: 'redBlue' } }      // ❌ → 应用 'rdBu'（发散）
+scale: { color: { type: 'diverging',  palette: 'greenRed' } }     // ❌ → 应用 'rdYlGn'（注意顺序）
+scale: { color: { type: 'sequential', palette: 'hot' } }          // ❌ → 不存在，用 'ylOrRd' 代替
+scale: { color: { type: 'sequential', palette: 'jet' } }          // ❌ → 不存在，用 'turbo' 代替
+scale: { color: { type: 'sequential', palette: 'coolwarm' } }     // ❌ → 应用 'rdBu'（发散）
+
+// ✅ 不确定时，从下列可信名称选择
+// 单色顺序：'blues' | 'greens' | 'reds' | 'oranges' | 'purples' | 'ylOrRd' | 'ylGnBu'
+// 感知均匀：'viridis' | 'plasma' | 'magma' | 'inferno' | 'cividis' | 'turbo'
+// 发散：    'rdBu' | 'rdYlGn' | 'rdYlBu' | 'pRGn' | 'brBG' | 'spectral'
+```
+
+### 错误：sequential 用于分类数据
+```javascript
+// ❌ sequential 只适合连续数值，分类数据应用 ordinal
+chart.options({
+  encode: { color: 'city' },   // city 是分类字段
+  scale: { color: { type: 'sequential' } },  // ❌ 会产生奇怪的渐变
+});
+
+// ✅ 分类数据用 ordinal
+chart.options({
+  encode: { color: 'city' },
+  scale: { color: { type: 'ordinal', range: ['#5B8FF9', '#61DDAA', '#FFD666'] } },  // ✅
+});
+```
+
+### 错误：未使用 transform 导致数据聚合异常
+
+在使用 `cell` 类型图表时，若原始数据包含多个相同 `(x, y)` 坐标的记录，必须使用 `transform` 对其进行聚合，否则可能导致颜色映射不准确甚至图表渲染失败。
+
+```javascript
+// ❌ 未聚合相同坐标的 temp_max 值
+chart.options({
+  type: 'cell',
+  data: weatherData,
+  encode: {
+    x: (d) => new Date(d.date).getUTCDate(),
+    y: (d) => new Date(d.date).getUTCMonth(),
+    color: 'temp_max',
+  },
+  scale: { color: { type: 'sequential', palette: 'gnBu' } },
+});
+
+// ✅ 使用 group transform 聚合相同坐标的数据
+chart.options({
+  type: 'cell',
+  data: weatherData,
+  encode: {
+    x: (d) => new Date(d.date).getUTCDate(),
+    y: (d) => new Date(d.date).getUTCMonth(),
+    color: 'temp_max',
+  },
+  transform: [{ type: 'group', color: 'max' }],  // 对每个格子取 temp_max 的最大值
+  scale: { color: { type: 'sequential', palette: 'gnBu' } },
+});
+```
+```

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

@@ -0,0 +1,133 @@
+---
+id: "g2-scale-threshold"
+title: "G2 阈值比例尺（threshold）"
+description: |
+  阈值比例尺将连续数值按指定的阈值切分为若干区间，每个区间映射到一个离散输出（如颜色）。
+  常用于热力图、地图分级着色等场景，用几个关键阈值划分数据等级。
+  与 quantize（等分）不同，threshold 支持自定义不均匀的分割点。
+
+library: "g2"
+version: "5.x"
+category: "scales"
+tags:
+  - "threshold"
+  - "阈值"
+  - "比例尺"
+  - "分级"
+  - "choropleth"
+  - "热力"
+  - "scale"
+
+related:
+  - "g2-scale-linear"
+  - "g2-scale-ordinal"
+  - "g2-mark-cell-heatmap"
+
+use_cases:
+  - "地图分级着色（choropleth map）"
+  - "热力图数据分级（低/中/高/极高）"
+  - "自定义区间的颜色映射"
+
+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/threshold"
+---
+
+## 最小可运行示例（热力图分级着色）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { week: 'Mon', hour: '08:00', count: 5 },
+  { week: 'Mon', hour: '09:00', count: 45 },
+  { week: 'Mon', hour: '12:00', count: 120 },
+  { week: 'Tue', hour: '09:00', count: 85 },
+  { week: 'Wed', hour: '12:00', count: 200 },
+  // ...
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 300 });
+
+chart.options({
+  type: 'cell',
+  data,
+  encode: {
+    x: 'hour',
+    y: 'week',
+    color: 'count',
+  },
+  scale: {
+    color: {
+      type: 'threshold',
+      domain: [30, 80, 150],          // 3 个阈值，划分为 4 个区间
+      range: ['#ebedf0', '#c6e48b', '#7bc96f', '#196127'],  // 对应 4 个颜色
+    },
+  },
+  style: { lineWidth: 2, stroke: '#fff' },
+});
+
+chart.render();
+```
+
+## 配置项
+
+```javascript
+scale: {
+  color: {
+    type: 'threshold',
+    domain: [30, 80, 150],    // N 个阈值，产生 N+1 个区间
+    range: ['#low', '#mid-low', '#mid-high', '#high'],  // N+1 个输出值
+  },
+}
+```
+
+## 风险等级着色示例
+
+```javascript
+// 将连续风险分数映射到 4 个风险等级颜色
+chart.options({
+  scale: {
+    color: {
+      type: 'threshold',
+      domain: [25, 50, 75],     // 低/中/高/极高 分界线
+      range: [
+        '#52c41a',  // 0~25：低风险（绿）
+        '#faad14',  // 25~50：中风险（黄）
+        '#ff7a45',  // 50~75：高风险（橙）
+        '#ff4d4f',  // 75+：极高风险（红）
+      ],
+    },
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：domain 和 range 数量不匹配
+```javascript
+// ❌ 错误：2 个 domain 阈值产生 3 个区间，但只有 2 个 range 颜色
+chart.options({
+  scale: {
+    color: {
+      type: 'threshold',
+      domain: [50, 100],     // 2 个阈值 → 3 个区间
+      range: ['#green', '#red'],  // ❌ 只有 2 个颜色，应该是 3 个
+    },
+  },
+});
+
+// ✅ 正确：domain N 个阈值 → range 需要 N+1 个颜色
+chart.options({
+  scale: {
+    color: {
+      type: 'threshold',
+      domain: [50, 100],
+      range: ['#52c41a', '#faad14', '#ff4d4f'],  // ✅ 3 个颜色
+    },
+  },
+});
+```

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

@@ -0,0 +1,159 @@
+---
+id: "g2-scale-time"
+title: "G2 Time 时间比例尺"
+description: |
+  Time 比例尺将时间数据（Date 对象或时间戳）映射到连续坐标轴，
+  自动处理时间刻度间隔、格式化和排序。当 encode.x 映射 Date 类型数据时自动启用。
+
+library: "g2"
+version: "5.x"
+category: "scales"
+tags:
+  - "time"
+  - "时间比例尺"
+  - "时间轴"
+  - "Date"
+  - "时间序列"
+  - "scale"
+  - "spec"
+
+related:
+  - "g2-mark-line-basic"
+  - "g2-comp-axis-config"
+  - "g2-scale-linear"
+
+use_cases:
+  - "绘制时间序列折线图、面积图"
+  - "控制时间轴的刻度粒度和标签格式"
+  - "设置时间轴的显示范围"
+
+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/time"
+---
+
+## 自动识别（推荐）
+
+当数据字段为 `Date` 对象时，G2 自动使用 Time Scale，无需显式配置：
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 700, height: 400 });
+
+chart.options({
+  type: 'line',
+  data: [
+    { date: new Date('2024-01-01'), value: 100 },
+    { date: new Date('2024-02-01'), value: 130 },
+    { date: new Date('2024-03-01'), value: 110 },
+    { date: new Date('2024-04-01'), value: 160 },
+    { date: new Date('2024-05-01'), value: 145 },
+  ],
+  encode: { x: 'date', y: 'value' },   // Date 对象自动用 Time Scale
+});
+
+chart.render();
+```
+
+## 显式配置 Time Scale
+
+```javascript
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value' },
+  scale: {
+    x: {
+      type: 'time',               // 显式指定（字符串日期时需要）
+      domain: [                   // 限制显示范围
+        new Date('2024-01-01'),
+        new Date('2024-12-31'),
+      ],
+      nice: true,                  // 将域扩展到整洁的时间边界
+    },
+  },
+});
+```
+
+## 格式化时间轴标签
+
+```javascript
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value' },
+  axis: {
+    x: {
+      // 使用 dayjs 格式字符串
+      labelFormatter: 'YYYY-MM',           // 年-月：2024-01
+      // labelFormatter: 'MM/DD',          // 月/日：01/15
+      // labelFormatter: 'YYYY年MM月',     // 中文格式
+      // labelFormatter: (d) => `Q${Math.ceil((d.getMonth()+1)/3)}`,  // 自定义
+      tickCount: 6,
+    },
+  },
+});
+```
+
+## 字符串日期（推荐转为 Date 对象）
+
+G2 v5 对 `YYYY-MM-DD` 格式的字符串有一定自动识别能力，但行为依赖内部推断，**不稳定**。
+推荐在数据预处理阶段统一转为 `Date` 对象，避免歧义：
+
+```javascript
+// ✅ 推荐：预处理时转为 Date 对象
+const rawData = [
+  { date: '2024-01-01', value: 100 },
+  { date: '2024-02-01', value: 130 },
+];
+const data = rawData.map(d => ({ ...d, date: new Date(d.date) }));
+
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value' },
+  // 无需 scale.x.type，G2 自动识别 Date 对象为 Time Scale
+});
+```
+
+**不要**在字符串日期上显式写 `scale: { x: { type: 'time' } }`，这是多余的配置，
+且在某些场景（如 fold 后数据类型变化）会引发渲染异常。
+
+## 常见错误与修正
+
+### 错误 1：显式声明 type: 'time'（不必要且有风险）
+```javascript
+// ❌ 不推荐：在字符串日期上显式写 type: 'time'
+chart.options({
+  type: 'line',
+  data: [{ date: '2024-01-01', value: 100 }],
+  encode: { x: 'date', y: 'value' },
+  scale: { x: { type: 'time' } },   // ❌ 多余，可能引发异常
+});
+
+// ✅ 正确：转为 Date 对象，让 G2 自动处理
+const data = rawData.map(d => ({ ...d, date: new Date(d.date) }));
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value' },
+});
+```
+
+### 错误 2：数据乱序导致折线错乱
+```javascript
+// ❌ 错误：数据顺序混乱，折线会连错
+const data = [
+  { date: new Date('2024-03-01'), value: 110 },
+  { date: new Date('2024-01-01'), value: 100 },  // 时间倒序
+];
+
+// ✅ 正确：按时间排序后再传入
+const data = rawData
+  .map(d => ({ ...d, date: new Date(d.date) }))
+  .sort((a, b) => a.date - b.date);
+```