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

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

@@ -0,0 +1,293 @@
+---
+id: "g2-mark-rangex"
+title: "G2 RangeX / RangeY 区间标注"
+description: |
+  rangeX 在 X 轴方向绘制竖向区域带（区间高亮），常用于标注特殊时间段或阈值区间。
+  rangeY 在 Y 轴方向绘制横向区域带，用于标注某个数值范围（如目标区间、警戒线）。
+  常与折线图组合使用，在背景添加时间区间标注。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "rangeX"
+  - "rangeY"
+  - "区间"
+  - "标注"
+  - "高亮区域"
+  - "参考区域"
+  - "时间区间"
+
+related:
+  - "g2-comp-annotation"
+  - "g2-mark-line-basic"
+  - "g2-comp-view"
+
+use_cases:
+  - "时间序列图中高亮特殊时间段（如历史事件、假期）"
+  - "标注正常值区间（如绿色安全区间）"
+  - "突出显示某个数据范围"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/annotation/range/"
+---
+
+## 最小可运行示例（时间段高亮）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 800, height: 400 });
+
+chart.options({
+  type: 'view',
+  children: [
+    // 主折线图
+    {
+      type: 'line',
+       [
+        { date: '2024-01', value: 100 },
+        { date: '2024-02', value: 120 },
+        { date: '2024-03', value: 150 },
+        { date: '2024-04', value: 130 },
+        { date: '2024-05', value: 160 },
+      ],
+      encode: { x: 'date', y: 'value' },
+      style: { lineWidth: 2 },
+    },
+    // 高亮特殊区域
+    {
+      type: 'rangeX',
+       [
+        { x: '2024-02', x1: '2024-03', label: '活动期' },
+      ],
+      encode: { x: 'x', x1: 'x1' },
+      style: { fill: '#FF6B35', fillOpacity: 0.15 },
+      labels: [{ text: 'label', position: 'top', style: { fontSize: 11 } }],
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 时间区间标注（折线图 + 历史事件背景）
+
+使用 Date 对象和数组格式标注历史时间段：
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  autoFit: true,
+});
+
+// 人口数据
+const populationData = [
+  { year: '1875', population: 1309 },
+  { year: '1890', population: 1558 },
+  { year: '1910', population: 4512 },
+  { year: '1925', population: 8180 },
+  { year: '1933', population: 15915 },
+  { year: '1939', population: 24824 },
+  { year: '1946', population: 28275 },
+  { year: '1950', population: 29189 },
+  { year: '1964', population: 29881 },
+  { year: '1971', population: 26007 },
+];
+
+chart.options({
+  type: 'view',
+  autoFit: true,
+  children: [
+    // 背景区间标注（历史时期）
+    {
+      type: 'rangeX',
+       [
+        { year: [new Date('1933'), new Date('1945')], event: '纳粹统治时期' },
+        { year: [new Date('1948'), new Date('1989')], event: '东德时期' },
+      ],
+      encode: { x: 'year', color: 'event' },
+      scale: {
+        color: {
+          independent: true,  // 独立颜色比例尺，每个区间不同颜色
+          range: ['#FAAD14', '#30BF78'],
+        },
+      },
+      style: { fillOpacity: 0.75 },
+      tooltip: false,
+    },
+    // 折线图
+    {
+      type: 'line',
+      data: populationData,
+      encode: {
+        x: (d) => new Date(d.year),
+        y: 'population',
+      },
+      style: { stroke: '#333', lineWidth: 2 },
+    },
+    // 数据点
+    {
+      type: 'point',
+      data: populationData,
+      encode: {
+        x: (d) => new Date(d.year),
+        y: 'population',
+      },
+      style: { fill: '#333', r: 3 },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 数据格式说明
+
+rangeX 支持两种数据格式：
+
+### 格式一：独立字段（x, x1）
+
+```javascript
+ [
+  { x: '2024-01', x1: '2024-03', label: 'Q1' },
+  { x: '2024-04', x1: '2024-06', label: 'Q2' },
+],
+encode: { x: 'x', x1: 'x1' },
+```
+
+### 格式二：数组字段
+
+```javascript
+data: [
+  { year: [new Date('1933'), new Date('1945')], event: '事件A' },
+  { year: [new Date('1948'), new Date('1989')], event: '事件B' },
+],
+encode: { x: 'year' },  // 数组自动解析为 [start, end]
+```
+
+## RangeY（水平参考区间）
+
+```javascript
+chart.options({
+  type: 'view',
+  children: [
+    {
+      type: 'line',
+       data,
+      encode: { x: 'date', y: 'temperature' },
+    },
+    // 标注正常温度区间（18~26°C）
+    {
+      type: 'rangeY',
+       [{ y: 18, y1: 26, label: '舒适区间' }],
+      encode: { y: 'y', y1: 'y1' },
+      style: { fill: '#52c41a', fillOpacity: 0.1 },
+      labels: [{ text: 'label', position: 'right', style: { fill: '#52c41a' } }],
+    },
+  ],
+});
+```
+
+## 配置项
+
+| 属性 | 说明 | 类型 |
+|------|------|------|
+| `encode.x` | 区间起点字段 | `string \| (d) => value` |
+| `encode.x1` | 区间终点字段 | `string \| (d) => value` |
+| `encode.color` | 颜色字段（区分不同区间） | `string` |
+| `style.fill` | 填充颜色 | `string` |
+| `style.fillOpacity` | 填充透明度 | `number` (0-1) |
+| `scale.color.independent` | 独立颜色比例尺 | `boolean` |
+
+## 常见错误与修正
+
+### 错误 1：encode 中 x/x1 写成数组而不是独立字段名
+
+```javascript
+// ❌ 错误：rangeX 中 x 和 x1 是独立字段，不是数组
+chart.options({
+  type: 'rangeX',
+  encode: { x: ['start', 'end'] },  // ❌ 不是这个用法
+});
+
+// ✅ 正确：x 和 x1 分别绑定起点和终点字段
+chart.options({
+  type: 'rangeX',
+   [{ start: '2024-01', end: '2024-03' }],
+  encode: {
+    x: 'start',    // ✅ 起点字段
+    x1: 'end',     // ✅ 终点字段
+  },
+});
+```
+
+### 错误 2：时间格式不一致导致区间不与主图对齐
+
+```javascript
+// ❌ 错误：折线图用 Date 对象，rangeX 用字符串，比例尺不一致
+children: [
+  { type: 'line', encode: { x: (d) => new Date(d.year) } },
+  { type: 'rangeX', encode: { x: 'year' } },  // ❌ 格式不一致
+]
+
+// ✅ 正确：统一使用 Date 对象
+children: [
+  { type: 'line', encode: { x: (d) => new Date(d.year) } },
+  { type: 'rangeX', encode: { x: 'year' }, data: [
+    { year: [new Date('1933'), new Date('1945')] }  // ✅ 也用 Date
+  ]},
+]
+```
+
+### 错误 3：多个区间颜色相同
+
+```javascript
+// ❌ 问题：多个区间默认使用连续色板，颜色可能相近
+{
+  type: 'rangeX',
+  data: [
+    { year: [start1, end1], event: '事件A' },
+    { year: [start2, end2], event: '事件B' },
+  ],
+  encode: { x: 'year', color: 'event' },
+}
+
+// ✅ 正确：使用 independent: true 让每个区间独立着色
+{
+  type: 'rangeX',
+  data: [
+    { year: [start1, end1], event: '事件A' },
+    { year: [start2, end2], event: '事件B' },
+  ],
+  encode: { x: 'year', color: 'event' },
+  scale: {
+    color: {
+      independent: true,  // ✅ 独立颜色
+      range: ['#FAAD14', '#30BF78'],
+    },
+  },
+}
+```
+
+### 错误 4：rangeX 放在折线图后面导致遮挡
+
+```javascript
+// ❌ 错误：rangeX 在后，会遮挡折线
+children: [
+  { type: 'line', ... },
+  { type: 'rangeX', ... },  // ❌ 遮挡折线
+]
+
+// ✅ 正确：rangeX 放前面，作为背景层
+children: [
+  { type: 'rangeX', ... },  // ✅ 先渲染，作为背景
+  { type: 'line', ... },
+]
+```

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

@@ -0,0 +1,115 @@
+---
+id: "g2-mark-rect"
+title: "G2 矩形标注（rect）"
+description: |
+  rect mark 在图表中绘制任意位置和大小的矩形，
+  通过 x/x1 指定左右边界，y/y1 指定上下边界（与坐标轴单位一致）。
+  常用于高亮某个数据区间、背景分区、标注区域等。
+  与 rangeX 类似但更通用（支持同时指定 x 和 y 方向边界）。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "rect"
+  - "矩形"
+  - "区域标注"
+  - "背景分区"
+  - "annotation"
+
+related:
+  - "g2-mark-rangex"
+  - "g2-comp-annotation"
+  - "g2-mark-linex-liney"
+
+use_cases:
+  - "高亮图表中特定 x/y 区间范围"
+  - "在散点图中标注某个数值区间矩形"
+  - "分区背景着色"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/annotation/range/"
+---
+
+## 最小可运行示例（二维区间标注）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const scatterData = Array.from({ length: 100 }, () => ({
+  x: Math.random() * 100,
+  y: Math.random() * 100,
+}));
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'view',
+  children: [
+    // 主散点图
+    {
+      type: 'point',
+      data: scatterData,
+      encode: { x: 'x', y: 'y' },
+      style: { r: 3, fillOpacity: 0.6 },
+    },
+    // 矩形标注：高亮 x: 30~70, y: 30~70 的区间
+    {
+      type: 'rect',
+       [{ x: 30, x1: 70, y: 30, y1: 70, label: '目标区间' }],
+      encode: { x: 'x', x1: 'x1', y: 'y', y1: 'y1' },
+      style: {
+        fill: '#52c41a',
+        fillOpacity: 0.1,
+        stroke: '#52c41a',
+        lineWidth: 1.5,
+        lineDash: [4, 4],
+      },
+      labels: [
+        { text: 'label', position: 'top-left', style: { fill: '#52c41a', fontSize: 11 } },
+      ],
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 配置项
+
+```javascript
+chart.options({
+  type: 'rect',
+  data: [{ x: 20, x1: 60, y: 0, y1: 100, label: '区间 A' }],
+  encode: {
+    x: 'x',     // 矩形左边界（与 x 轴单位相同）
+    x1: 'x1',   // 矩形右边界
+    y: 'y',     // 矩形下边界（与 y 轴单位相同）
+    y1: 'y1',   // 矩形上边界
+  },
+  style: {
+    fill: '#5B8FF9',
+    fillOpacity: 0.1,
+    stroke: '#5B8FF9',
+    lineWidth: 1,
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：rect 和 rangeX/rangeY 混淆——rect 需要同时指定 x/y 两个方向
+```javascript
+// rangeX：只指定 x 方向边界，y 方向填满整个图表高度
+chart.options({ type: 'rangeX', encode: { x: 'start', x1: 'end' } });
+
+// rangeY：只指定 y 方向边界，x 方向填满整个图表宽度
+chart.options({ type: 'rangeY', encode: { y: 'min', y1: 'max' } });
+
+// rect：同时指定 x 和 y 两个方向（完整的矩形区间）
+chart.options({ type: 'rect', encode: { x: 'x', x1: 'x1', y: 'y', y1: 'y1' } });
+```

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

@@ -0,0 +1,276 @@
+---
+id: "g2-mark-regression-curve"
+title: "G2 回归曲线图（regression curve）"
+description: |
+  回归曲线图在散点图基础上叠加回归趋势线。使用 type: 'view' 组合
+  type: 'point'（原始数据）和 type: 'line'（回归曲线），
+  回归计算通过 data.transform 中的 custom callback 接入 d3-regression 等库。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "回归曲线图"
+  - "regression"
+  - "线性回归"
+  - "趋势线"
+  - "d3-regression"
+  - "散点图"
+
+related:
+  - "g2-mark-point-scatter"
+  - "g2-mark-line-basic"
+
+use_cases:
+  - "展示两变量间的线性/非线性关系"
+  - "趋势预测"
+  - "相关性分析"
+
+anti_patterns:
+  - "数据点少于 10 条时回归不可靠"
+  - "变量间无相关关系时不适合加回归线"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-04-01"
+updated: "2025-04-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/general/regressioncurve"
+---
+
+## 核心概念
+
+**回归曲线图 = `type: 'view'` 组合 `point`（散点）+ `line`（回归线）**
+
+- 散点 (`type: 'point'`)：展示原始数据
+- 回归线 (`type: 'line'`)：通过 `data.transform` 中的 `custom` callback 调用回归函数
+- 常用回归库：`d3-regression`（`regressionLinear`, `regressionQuad`, `regressionExp`, `regressionLog`, `regressionPoly`）
+
+**回归函数输出格式**：返回一个点数组 `[[x0, y0], [x1, y1], ...]`，encode 时用 `(d) => d[0]` 和 `(d) => d[1]`
+
+## 线性回归（最小可运行示例）
+
+```javascript
+import { Chart } from '@antv/g2';
+import { regressionLinear } from 'd3-regression';
+
+const chart = new Chart({
+  container: 'container',
+  theme: 'classic',
+});
+
+chart.options({
+  type: 'view',
+  autoFit: true,
+   {
+    type: 'fetch',
+    value: 'https://assets.antv.antgroup.com/g2/linear-regression.json',
+  },
+  children: [
+    // 散点：原始数据
+    {
+      type: 'point',
+      encode: { x: (d) => d[0], y: (d) => d[1] },
+      scale: { x: { domain: [0, 1] }, y: { domain: [0, 5] } },
+      style: { fillOpacity: 0.75, fill: '#1890ff' },
+    },
+    // 折线：回归曲线
+    {
+      type: 'line',
+       {
+        transform: [
+          {
+            type: 'custom',
+            callback: regressionLinear(),  // d3-regression 回归函数
+          },
+        ],
+      },
+      encode: { x: (d) => d[0], y: (d) => d[1] },
+      style: { stroke: '#30BF78', lineWidth: 2 },
+      labels: [
+        {
+          text: 'y = 1.7x + 3.01',
+          selector: 'last',
+          position: 'right',
+          textAlign: 'end',
+          dy: -8,
+        },
+      ],
+      tooltip: false,
+    },
+  ],
+  axis: {
+    x: { title: '自变量 X' },
+    y: { title: '因变量 Y' },
+  },
+});
+
+chart.render();
+```
+
+## 多项式回归（二次回归）
+
+```javascript
+import { regressionQuad } from 'd3-regression';
+
+chart.options({
+  type: 'view',
+  autoFit: true,
+   [
+    { x: -4, y: 5.2 }, { x: -3, y: 2.8 }, { x: -2, y: 1.5 },
+    { x: -1, y: 0.8 }, { x: 0, y: 0.5 }, { x: 1, y: 0.8 },
+    { x: 2, y: 1.5 }, { x: 3, y: 2.8 }, { x: 4, y: 5.2 },
+  ],
+  children: [
+    {
+      type: 'point',
+      encode: { x: 'x', y: 'y' },
+      style: { fillOpacity: 0.75, fill: '#1890ff' },
+    },
+    {
+      type: 'line',
+       {
+        transform: [
+          {
+            type: 'custom',
+            callback: regressionQuad()
+              .x((d) => d.x)
+              .y((d) => d.y)
+              .domain([-4, 4]),
+          },
+        ],
+      },
+      encode: { x: (d) => d[0], y: (d) => d[1] },
+      style: { stroke: '#30BF78', lineWidth: 2 },
+      labels: [
+        {
+          text: 'y = 0.3x² + 0.5',
+          selector: 'last',
+          textAlign: 'end',
+          dy: -8,
+        },
+      ],
+      tooltip: false,
+    },
+  ],
+});
+```
+
+## 指数回归
+
+```javascript
+import { regressionExp } from 'd3-regression';
+
+// 在 line 子 mark 中
+{
+  type: 'line',
+  data: {
+    transform: [
+      {
+        type: 'custom',
+        callback: regressionExp(),
+      },
+    ],
+  },
+  encode: { x: (d) => d[0], y: (d) => d[1], shape: 'smooth' },
+  style: { stroke: '#30BF78', lineWidth: 2 },
+  tooltip: false,
+}
+```
+
+## d3-regression 常用函数
+
+| 函数 | 回归类型 | 适用场景 |
+|------|---------|---------|
+| `regressionLinear()` | 线性 y = ax + b | 线性相关 |
+| `regressionQuad()` | 二次 y = ax² + bx + c | 抛物线关系 |
+| `regressionPoly()` | 多项式 | 复杂弯曲 |
+| `regressionExp()` | 指数 y = ae^(bx) | 指数增长/衰减 |
+| `regressionLog()` | 对数 y = a·ln(x) + b | 增长率递减 |
+| `regressionPow()` | 幂律 y = ax^b | 幂律关系 |
+
+## 常见错误与修正
+
+### 错误 1：回归函数放在错误位置
+
+```javascript
+// ❌ 错误：custom 回归应放在 line 子 mark 的 data.transform 中
+chart.options({
+  type: 'view',
+   {
+    transform: [{ type: 'custom', callback: regressionLinear() }],  // ❌ 放在父 view 数据上
+  },
+  children: [{ type: 'point', encode: { x: 'x', y: 'y' } }],
+});
+
+// ✅ 正确：每个子 mark 有独立数据来源
+chart.options({
+  type: 'view',
+  data,  // 散点数据
+  children: [
+    { type: 'point', encode: { x: 'x', y: 'y' } },  // 散点用父数据
+    {
+      type: 'line',
+      data: {
+        transform: [{ type: 'custom', callback: regressionLinear().x(d=>d.x).y(d=>d.y) }],
+      },                                               // ✅ 回归线有独立数据
+      encode: { x: (d) => d[0], y: (d) => d[1] },
+    },
+  ],
+});
+```
+
+### 错误 2：encode 字段访问方式错误
+
+```javascript
+// ❌ 错误：d3-regression 输出 [[x,y],...] 数组，不是对象
+{
+  type: 'line',
+  encode: { x: 'x', y: 'y' },  // ❌ d[0] 不是 d.x
+}
+
+// ✅ 正确：用函数访问数组索引
+{
+  type: 'line',
+  encode: { x: (d) => d[0], y: (d) => d[1] },  // ✅
+}
+```
+
+### 错误 3：不指定 .x()/.y() 时数据格式不匹配
+
+```javascript
+// ❌ 问题：默认情况下 d3-regression 假设数据是 [x, y] 数组格式
+const data = [{ x: 1, y: 2 }, { x: 3, y: 4 }];  // 对象格式
+// regressionLinear() 默认读 d[0], d[1]，不匹配对象格式
+
+// ✅ 正确：显式指定字段读取方式
+callback: regressionLinear()
+  .x((d) => d.x)   // ✅ 指定 x 字段
+  .y((d) => d.y),  // ✅ 指定 y 字段
+```
+
+### 错误 4：data 关键字缺失
+
+```javascript
+// ❌ 错误
+children: [
+  {
+    type: 'line',
+    {
+      transform: [{ type: 'custom', callback: regressionLinear() }],
+    },                             // ❌ 孤立 {} 语法错误，缺少 data: 键
+    encode: { x: (d) => d[0], y: (d) => d[1] },
+  },
+]
+
+// ✅ 正确
+children: [
+  {
+    type: 'line',
+     {                        // ✅ 必须有 data: 键
+      transform: [{ type: 'custom', callback: regressionLinear() }],
+    },
+    encode: { x: (d) => d[0], y: (d) => d[1] },
+  },
+]
+```