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

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

@@ -0,0 +1,353 @@
+---
+id: "g2-mark-line-basic"
+title: "G2 基础折线图（Line Mark）"
+description: |
+  使用 Line Mark 创建折线图，用于展示数据随时间或有序类别的变化趋势。
+  本文采用 Spec 模式（chart.options({})），支持单系列、多系列、平滑曲线等常见变体。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+subcategory: "line"
+tags:
+  - "折线图"
+  - "趋势"
+  - "时间序列"
+  - "Line"
+  - "line chart"
+  - "曲线"
+  - "多系列"
+  - "spec"
+
+related:
+  - "g2-mark-area-basic"
+  - "g2-core-encode-channel"
+  - "g2-scale-time"
+  - "g2-interaction-tooltip"
+
+use_cases:
+  - "展示数据随时间的变化趋势"
+  - "对比多个指标或维度的走势"
+  - "展示连续数值的变化"
+
+anti_patterns:
+  - "数据点较少（< 5 个）时折线图不直观，改用柱状图"
+  - "非有序数据（无序分类）不适合折线图"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/line/basic"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'line',
+  data: [
+    { month: 'Jan', value: 33 },
+    { month: 'Feb', value: 78 },
+    { month: 'Mar', value: 56 },
+    { month: 'Apr', value: 91 },
+    { month: 'May', value: 67 },
+    { month: 'Jun', value: 45 },
+  ],
+  encode: { x: 'month', y: 'value' },
+});
+
+chart.render();
+```
+
+## 时间序列折线图
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 800, 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',     // Date 类型自动使用 Time Scale
+    y: 'value',
+  },
+  axis: {
+    x: {
+      tickCount: 5,
+      labelFormatter: 'YYYY-MM',  // 日期格式化
+    },
+  },
+});
+
+chart.render();
+```
+
+## 多系列折线图
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 700, height: 400 });
+
+chart.options({
+  type: 'line',
+  data: [
+    { month: 'Jan', type: '产品A', value: 33 },
+    { month: 'Jan', type: '产品B', value: 55 },
+    { month: 'Feb', type: '产品A', value: 78 },
+    { month: 'Feb', type: '产品B', value: 62 },
+    { month: 'Mar', type: '产品A', value: 56 },
+    { month: 'Mar', type: '产品B', value: 89 },
+    { month: 'Apr', type: '产品A', value: 91 },
+    { month: 'Apr', type: '产品B', value: 74 },
+  ],
+  encode: {
+    x: 'month',
+    y: 'value',
+    color: 'type',   // color 通道自动按 type 拆分多条线
+  },
+});
+
+chart.render();
+```
+
+## 平滑曲线
+
+```javascript
+chart.options({
+  type: 'line',
+  data: [...],
+  encode: {
+    x: 'month',
+    y: 'value',
+    shape: 'smooth',    // 'line' | 'smooth' | 'hv' | 'vh' | 'hvh' | 'vhv'
+  },
+});
+```
+
+## 折线 + 数据点（Layer 组合）
+
+```javascript
+// Spec 中用 children 数组实现多 Mark 叠加
+chart.options({
+  type: 'view',               // view 容器
+   [...],
+  children: [
+    {
+      type: 'line',
+      encode: { x: 'month', y: 'value', color: 'type' },
+    },
+    {
+      type: 'point',
+      encode: {
+        x: 'month',
+        y: 'value',
+        color: 'type',
+        shape: 'circle',
+      },
+      style: { r: 4 },
+    },
+  ],
+});
+```
+
+## 折线 + 面积填充（Layer 组合）
+
+```javascript
+chart.options({
+  type: 'view',
+  data: [...],
+  children: [
+    {
+      type: 'area',
+      encode: { x: 'month', y: 'value' },
+      style: { fillOpacity: 0.2 },
+    },
+    {
+      type: 'line',
+      encode: { x: 'month', y: 'value' },
+      style: { stroke: '#1890ff', lineWidth: 2 },
+    },
+  ],
+});
+```
+
+## 带 Tooltip 和末端标签
+
+```javascript
+chart.options({
+  type: 'line',
+  data: [...],
+  encode: { x: 'month', y: 'value' },
+  tooltip: {
+    items: [{ field: 'value', name: '值' }],
+  },
+  labels: [
+    {
+      text: 'value',
+      selector: 'last',    // 只在最后一个点显示标签
+      style: { fontSize: 12, fill: '#1890ff' },
+    },
+  ],
+});
+```
+
+## 宽表数据 + fold 转长表
+
+宽表每行含多个指标列，用 `fold` transform 转为长表再绘制多系列：
+
+```javascript
+const wideData = [
+  { date: '2024-01', DAU: 12000, MAU: 45000 },
+  { date: '2024-02', DAU: 13500, MAU: 47000 },
+  { date: '2024-03', DAU: 11800, MAU: 44500 },
+];
+
+chart.options({
+  type: 'line',
+   wideData,
+  transform: [
+    {
+      type: 'fold',
+      fields: ['DAU', 'MAU'],   // 要转换的列
+      key: 'metric',             // 新增列名（存原字段名）
+      value: 'count',            // 新增列名（存原字段值）
+    },
+  ],
+  encode: {
+    x: 'date',
+    y: 'count',      // fold 后使用 value 字段名
+    color: 'metric', // fold 后使用 key 字段名
+  },
+  labels: [
+    { text: 'metric', selector: 'last', position: 'right' },
+  ],
+});
+```
+
+## 双 Y 轴（不同量级系列）
+
+```javascript
+chart.options({
+  type: 'view',
+  children: [
+    {
+      type: 'line',
+      data: revenueData,
+      encode: { x: 'date', y: 'revenue', color: () => '收入(万元)' },
+      scale: { y: { key: 'revenue' } },   // key 唯一 → 独立 y 轴
+    },
+    {
+      type: 'line',
+      data: userCountData,
+      encode: { x: 'date', y: 'count', color: () => '用户数' },
+      scale: { y: { key: 'count' } },
+      axis: { y: { position: 'right' } },  // 右侧 y 轴
+    },
+  ],
+});
+```
+
+## 多系列 Tooltip 配置
+
+```javascript
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value', color: 'series' },
+  tooltip: {
+    title: (d) => {
+      const date = new Date(d.date);
+      return `${date.getFullYear()}年${date.getMonth() + 1}月`;
+    },
+    items: [
+      { field: 'series', name: '系列' },
+      { field: 'value', name: '数值', valueFormatter: (v) => v.toLocaleString() },
+    ],
+  },
+  interaction: [{ type: 'tooltip' }],
+});
+```
+
+## Spec 字段速查
+
+| 字段 | 示例值 | 说明 |
+|------|--------|------|
+| `encode.x` | `'month'` | X 轴字段 |
+| `encode.y` | `'value'` | Y 轴字段 |
+| `encode.color` | `'type'` | 颜色/系列区分 |
+| `encode.shape` | `'smooth'` | 线型 |
+| `style.lineWidth` | `2` | 线宽 |
+| `style.stroke` | `'#f00'` | 线条颜色（固定） |
+| `labels` | `[{ text: 'value', selector: 'last' }]` | 数据标签 |
+| `tooltip` | `{ items: [{ field: 'value' }] }` | Tooltip |
+
+## 常见错误与修正
+
+### 错误 1：多系列数据缺少 color 通道
+```javascript
+// ❌ 错误：多类型数据没有 color，所有点被错误地连成一条乱线
+chart.options({
+  type: 'line',
+  data: multiSeriesData,
+  encode: { x: 'month', y: 'value' },  // 缺少 color！
+});
+
+// ✅ 正确
+chart.options({
+  type: 'line',
+  data: multiSeriesData,
+  encode: { x: 'month', y: 'value', color: 'type' },
+});
+```
+
+### 错误 2：时间字段是字符串
+```javascript
+// ❌ 不推荐：字符串时间轴排序可能不正确
+const data = [{ date: '2024-03-01', value: 100 }];
+
+// ✅ 正确：转为 Date 对象，或显式配置 scale type
+const data = [{ date: new Date('2024-03-01'), value: 100 }];
+// 或：
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value' },
+  scale: { x: { type: 'time' } },
+});
+```
+
+### 错误 3：多 Mark 叠加忘用 view 容器
+```javascript
+// ❌ 错误：直接调用 options 两次会覆盖
+chart.options({ type: 'line', ... });
+chart.options({ type: 'point', ... });  // 覆盖了上面！
+
+// ✅ 正确：用 type: 'view' + children 数组
+chart.options({
+  type: 'view',
+  data: [...],
+  children: [
+    { type: 'line', encode: { x: 'month', y: 'value' } },
+    { type: 'point', encode: { x: 'month', y: 'value' }, style: { r: 4 } },
+  ],
+});
+```

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

@@ -0,0 +1,156 @@
+---
+id: "g2-mark-line-multi"
+title: "G2 多系列折线图"
+description: |
+  通过 color 通道编码分类字段实现多系列折线图，每条线代表一个类别。
+  G2 会自动为每个 color 值生成独立的折线。
+  常用于趋势对比、多指标随时间变化的展示。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "折线图"
+  - "多系列"
+  - "line"
+  - "时间序列"
+  - "趋势对比"
+  - "多折线"
+
+related:
+  - "g2-mark-line-basic"
+  - "g2-mark-area-stacked"
+  - "g2-transform-select"
+
+use_cases:
+  - "多个产品的销售趋势对比"
+  - "多地区气温随时间变化"
+  - "多指标 KPI 折线对比"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/general/line/"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { month: 'Jan', city: '北京', temp: -3 },
+  { month: 'Feb', city: '北京', temp: 0 },
+  { month: 'Mar', city: '北京', temp: 9 },
+  { month: 'Apr', city: '北京', temp: 18 },
+  { month: 'Jan', city: '上海', temp: 5 },
+  { month: 'Feb', city: '上海', temp: 7 },
+  { month: 'Mar', city: '上海', temp: 13 },
+  { month: 'Apr', city: '上海', temp: 20 },
+  { month: 'Jan', city: '广州', temp: 15 },
+  { month: 'Feb', city: '广州', temp: 16 },
+  { month: 'Mar', city: '广州', temp: 21 },
+  { month: 'Apr', city: '广州', temp: 26 },
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+chart.options({
+  type: 'line',
+  data,
+  encode: {
+    x: 'month',
+    y: 'temp',
+    color: 'city',   // 关键：按城市分色，自动生成多条折线
+  },
+  style: { lineWidth: 2 },
+  legend: { color: { position: 'top' } },
+});
+
+chart.render();
+```
+
+## 折线 + 散点组合（突出数据点）
+
+```javascript
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    {
+      type: 'line',
+      encode: { x: 'month', y: 'value', color: 'city' },
+      style: { lineWidth: 2 },
+    },
+    {
+      type: 'point',
+      encode: { x: 'month', y: 'value', color: 'city', shape: 'circle' },
+      style: { r: 4, lineWidth: 1.5, fill: '#fff' },
+    },
+  ],
+});
+```
+
+## 折线 + 末端标签
+
+```javascript
+chart.options({
+  type: 'view',
+  children: [
+    {
+      type: 'line',
+       data,
+      encode: { x: 'month', y: 'value', color: 'city' },
+    },
+    {
+      type: 'text',
+       data,
+      encode: {
+        x: 'month',
+        y: 'value',
+        color: 'city',
+        text: 'city',
+      },
+      transform: [{ type: 'selectX', selector: 'last' }],  // 只取每条线末端
+      style: { textAnchor: 'start', dx: 6, fontSize: 12 },
+    },
+  ],
+});
+```
+
+## 平滑曲线
+
+```javascript
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  style: {
+    lineWidth: 2,
+    shape: 'smooth',   // 平滑曲线（代替折线）
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：多系列数据使用宽表格式——应使用长表格式
+```javascript
+// ❌ 错误：宽表格式，G2 无法自动按系列分色
+const wrongData = [
+  { month: 'Jan', 北京: -3, 上海: 5, 广州: 15 },
+  { month: 'Feb', 北京: 0,  上海: 7, 广州: 16 },
+];
+
+// ✅ 正确：长表格式（每条记录一个系列的一个数据点）
+const correctData = [
+  { month: 'Jan', city: '北京', value: -3 },
+  { month: 'Jan', city: '上海', value: 5 },
+  // ...
+];
+chart.options({
+  encode: { x: 'month', y: 'value', color: 'city' },  // ✅ color 绑定分类字段
+});
+```

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

@@ -0,0 +1,176 @@
+---
+id: "g2-mark-linex-liney"
+title: "G2 LineX / LineY 参考线"
+description: |
+  lineX 绘制垂直参考线（指定 x 值），lineY 绘制水平参考线（指定 y 值）。
+  常用于标注均值线、目标线、阈值线等，
+  通常与主图放在同一 view 的 children 中。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "lineX"
+  - "lineY"
+  - "参考线"
+  - "均值线"
+  - "目标线"
+  - "annotation"
+  - "标注"
+
+related:
+  - "g2-comp-annotation"
+  - "g2-mark-rangex"
+  - "g2-mark-line-basic"
+
+use_cases:
+  - "在散点图中绘制 X/Y 均值线"
+  - "添加目标值水平参考线"
+  - "标注阈值警戒线"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/annotation/line/"
+---
+
+## 最小可运行示例（均值参考线）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { month: 'Jan', value: 83 },
+  { month: 'Feb', value: 60 },
+  { month: 'Mar', value: 95 },
+  { month: 'Apr', value: 72 },
+  { month: 'May', value: 110 },
+];
+
+const avg = data.reduce((sum, d) => sum + d.value, 0) / data.length;
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    // 主柱状图
+    {
+      type: 'interval',
+      encode: { x: 'month', y: 'value', color: 'month' },
+    },
+    // 水平均值参考线
+    {
+      type: 'lineY',
+       [{ y: avg }],    // 参考线的 y 值
+      encode: { y: 'y' },
+      style: {
+        stroke: '#F4664A',
+        lineWidth: 1.5,
+        lineDash: [6, 3],   // 虚线样式
+      },
+      labels: [
+        {
+          text: `均值: ${avg.toFixed(1)}`,
+          position: 'right',
+          style: { fill: '#F4664A', fontSize: 12 },
+        },
+      ],
+    },
+  ],
+});
+
+chart.render();
+```
+
+## lineX（垂直参考线）
+
+```javascript
+// 在散点图中添加 X 轴均值线
+const meanX = data.reduce((sum, d) => sum + d.x, 0) / data.length;
+
+{
+  type: 'lineX',
+  data: [{ x: meanX }],
+  encode: { x: 'x' },
+  style: { stroke: '#5B8FF9', lineWidth: 1.5, lineDash: [4, 4] },
+  labels: [{ text: `x̄=${meanX.toFixed(1)}`, position: 'top' }],
+}
+```
+
+## 目标线（固定数值）
+
+```javascript
+{
+  type: 'lineY',
+  data: [{ y: 100 }],    // 固定目标值 100
+  encode: { y: 'y' },
+  style: {
+    stroke: '#52c41a',
+    lineWidth: 2,
+  },
+  labels: [
+    { text: '目标线 100', position: 'right', style: { fill: '#52c41a' } },
+  ],
+}
+```
+
+## 常见错误与修正
+
+### ❌ 错误：使用不存在的 ruleX / ruleY 类型
+```javascript
+// ❌ 错误：ruleX、ruleY 是 Vega-Lite 的概念，G2 中不存在
+chart.options({ type: 'ruleX', ... });
+chart.options({ type: 'ruleY', ... });
+
+// ✅ 正确：G2 中用 lineX / lineY
+chart.options({ type: 'lineX', data: [{ x: 5 }], encode: { x: 'x' } });
+chart.options({ type: 'lineY', data: [{ y: 100 }], encode: { y: 'y' } });
+```
+
+### 错误：data 中 y 字段名与 encode.y 不一致
+```javascript
+// ❌ 错误：数据中字段是 'value'，但 encode.y 写的是 'y'
+chart.options({
+  type: 'lineY',
+  data: [{ value: 100 }],
+  encode: { y: 'y' },     // ❌ 字段名不对，找不到 'y' 字段
+});
+
+// ✅ 正确：字段名与数据一致
+chart.options({
+  type: 'lineY',
+  data: [{ value: 100 }],
+  encode: { y: 'value' }, // ✅
+});
+// 或者直接用 'y' 字段名：
+chart.options({
+  type: 'lineY',
+  data: [{ y: 100 }],
+  encode: { y: 'y' },     // ✅ 字段名统一
+});
+```
+
+### 错误：lineY 放在 view 外部——与主图比例尺不共享，位置偏移
+```javascript
+// ❌ 参考线与主图不在同一 view，y 轴范围不共享
+chart.options({
+  type: 'view',
+  children: [
+    { type: 'interval', encode: { x: 'month', y: 'sales' } },
+  ],
+});
+// 单独添加 lineY（不在 children 中）——这样无法工作
+
+// ✅ 参考线必须放在同一 view 的 children 数组中
+chart.options({
+  type: 'view',
+  children: [
+    { type: 'interval', encode: { x: 'month', y: 'sales' } },
+    { type: 'lineY', data: [{ y: 100 }], encode: { y: 'y' } },  // ✅
+  ],
+});
+```