@loom-framework/core 0.1.0-alpha.19 → 0.1.0-alpha.190

package/builtin-skills/antv-g2-chart/references/core/g2-core-chart-init.md

@@ -0,0 +1,266 @@
+---
+id: "g2-core-chart-init"
+title: "G2 Chart 初始化与基础配置"
+description: |
+  介绍 G2 v5 中 Chart 对象的创建方式、必填与可选参数、
+  自适应尺寸、主题配置及生命周期管理。
+  必须使用 Spec 声明式写法（chart.options({})），禁止使用链式 API。
+
+library: "g2"
+version: "5.x"
+category: "core"
+tags:
+  - "Chart"
+  - "初始化"
+  - "容器"
+  - "autoFit"
+  - "主题"
+  - "生命周期"
+  - "init"
+  - "spec"
+  - "options"
+
+related:
+  - "g2-core-encode-channel"
+  - "g2-core-data-binding"
+  - "g2-core-lifecycle"
+  - "g2-theme-builtin"
+
+use_cases:
+  - "开始创建任何 G2 图表"
+  - "配置图表画布尺寸和容器"
+  - "设置全局主题和内边距"
+
+anti_patterns:
+  - "不要在同一个容器上多次 new Chart（会产生多个画布）"
+  - "禁止使用链式 API（chart.interval().encode()...）"
+  - "禁止在同一图表中多次调用 chart.options({})（后者会覆盖前者，应合并为一次调用）"
+
+difficulty: "beginner"
+completeness: "partial"
+created: "2024-01-01"
+updated: "2025-03-27"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/chart"
+---
+
+## 核心概念
+
+`Chart` 是 G2 中最顶层的容器对象，负责管理画布、视图、坐标系和渲染。
+
+**必须使用 Spec 模式**：通过 `chart.options({})` 一次性传入完整描述对象，结构清晰，易于序列化和动态生成。
+
+**禁止使用链式 API**：`chart.interval().encode()` 等链式调用禁止使用。
+
+## 最小可运行示例（Spec 模式）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'line',        // Mark 类型
+  data: [
+    { x: 1, y: 10 },
+    { x: 2, y: 30 },
+    { x: 3, y: 20 },
+  ],
+  encode: { x: 'x', y: 'y' },
+});
+
+chart.render();
+```
+
+## 完整 Chart 容器配置项
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  // ── 必填 ──────────────────────────────
+  container: 'container',        // string | HTMLElement：DOM 容器
+
+  // ── 尺寸 ──────────────────────────────
+  width: 640,                    // 画布宽度（px），默认 640
+  height: 480,                   // 画布高度（px），默认 480
+  autoFit: true,                 // 自动适应容器尺寸（忽略 width/height）
+
+  // ── 内边距 ────────────────────────────
+  padding: 'auto',               // 'auto' | number | [top, right, bottom, left]
+  paddingTop: 40,
+  paddingRight: 20,
+  paddingBottom: 40,
+  paddingLeft: 60,
+  inset: 0,                      // 数据区域内缩（防止数据点紧贴边缘）
+
+  // ── 主题 ──────────────────────────────
+  theme: 'classic',              // 'classic' | 'classicDark' | 'academy'
+
+  // ── 渲染器 ────────────────────────────
+  renderer: undefined,           // 默认 Canvas，可传入 SVG 渲染器
+
+  // ── 像素比 ────────────────────────────
+  devicePixelRatio: window.devicePixelRatio,
+});
+```
+
+## Spec 模式完整结构
+
+```javascript
+chart.options({
+  // Mark 类型
+  type: 'interval',
+
+  // 数据，不同 Mark 直接存在结构上的差异，优先使用对应 mark 中的数据结构
+  data: [...],
+
+  // 视觉通道映射
+  encode: {
+    x: 'genre',
+    y: 'sold',
+    color: 'genre',
+  },
+
+  // 数据变换
+  transform: [{ type: 'stackY' }],
+
+  // 比例尺
+  scale: {
+    y: { domain: [0, 500] },
+    color: { range: ['#1890ff', '#52c41a'] },
+  },
+
+  // 坐标系
+  coordinate: { transform: [{ type: 'transpose' }] },
+
+  // 样式
+  style: { radius: 4 },
+
+  // 数据标签
+  labels: [{ text: 'sold', position: 'outside' }],
+
+  // Tooltip
+  tooltip: { title: 'genre', items: [{ field: 'sold', name: '销量' }] },
+
+  // 坐标轴
+  axis: {
+    x: { title: '游戏类型' },
+    y: { title: '销量' },
+  },
+
+  // 图例
+  legend: {
+    color: { position: 'top' },
+  },
+});
+```
+
+## Spec 模式标准写法
+
+```javascript
+// ✅ 正确：Spec 模式（唯一推荐写法）
+chart.options({
+  type: 'interval',
+  data: [...],
+  encode: { x: 'genre', y: 'sold', color: 'genre' },
+  style: { radius: 4 },
+});
+
+// ❌ 禁止：链式 API 模式
+chart.interval()
+  .data([...])
+  .encode('x', 'genre')
+  .encode('y', 'sold')
+  .encode('color', 'genre')
+  .style({ radius: 4 });
+```
+
+
+## 响应式自适应
+
+```javascript
+// autoFit：宽度跟随容器，高度可固定
+const chart = new Chart({
+  container: 'container',
+  autoFit: true,
+  height: 400,
+});
+
+chart.options({ type: 'line', data: [...], encode: { x: 'x', y: 'y' } });
+chart.render();
+```
+
+## 生命周期
+
+```javascript
+// 初次渲染
+chart.render();
+
+// 更新 Spec 后重新渲染（changeData 只更新数据）
+chart.options({ type: 'bar',  newData, encode: { x: 'x', y: 'y' } });
+chart.render();
+
+// 仅更新数据（性能更好）
+chart.changeData(newData);
+
+// 销毁
+chart.destroy();
+
+// 事件监听
+chart.on('afterrender', () => console.log('渲染完成'));
+```
+
+## 常见错误与修正
+
+### 错误 0：多次调用 chart.options({})
+```javascript
+// ❌ 错误：第二次 options() 会完全覆盖第一次，导致配置丢失
+chart.options({ type: 'interval', encode: { x: 'genre', y: 'sold' } });
+chart.options({ style: { radius: 4 } }); // 前面的 type/encode 丢失！
+
+// ✅ 正确：所有配置合并为一次 chart.options({}) 调用
+chart.options({
+  type: 'interval',
+  encode: { x: 'genre', y: 'sold' },
+  style: { radius: 4 },
+});
+```
+
+
+### 错误 1：container 指向不存在的 ID
+```javascript
+// ❌ 错误：DOM 还未加载
+const chart = new Chart({ container: 'chart' });
+
+// ✅ 正确：确保 DOM 已存在
+document.addEventListener('DOMContentLoaded', () => {
+  const chart = new Chart({ container: 'chart', width: 640, height: 400 });
+  chart.options({ type: 'line',  [...], encode: { x: 'x', y: 'y' } });
+  chart.render();
+});
+```
+
+### 错误 2：重复初始化同一容器
+```javascript
+// ❌ 错误：会创建两个画布叠加
+const chart1 = new Chart({ container: 'container' });
+const chart2 = new Chart({ container: 'container' });
+
+// ✅ 正确：先销毁旧实例
+chart1.destroy();
+const chart2 = new Chart({ container: 'container' });
+```
+
+### 错误 3：autoFit 与固定宽度混用
+```javascript
+// ❌ 错误：autoFit 会覆盖 width
+const chart = new Chart({ container: 'c', autoFit: true, width: 640 });
+
+// ✅ 正确：autoFit 时只设 height
+const chart = new Chart({ container: 'c', autoFit: true, height: 400 });
+```

package/builtin-skills/antv-g2-chart/references/core/g2-core-encode-channel.md

@@ -0,0 +1,197 @@
+---
+id: "g2-core-encode-channel"
+title: "G2 encode 通道系统详解"
+description: |
+  encode 是 G2 v5 的核心数据映射机制，将数据字段映射到视觉通道（位置、颜色、大小、形状等）。
+  在 Spec 模式中，encode 是 options 对象中的一个字段；在链式 API 中通过 .encode() 方法调用。
+
+library: "g2"
+version: "5.x"
+category: "core"
+tags:
+  - "encode"
+  - "通道"
+  - "channel"
+  - "数据映射"
+  - "x"
+  - "y"
+  - "color"
+  - "size"
+  - "shape"
+  - "spec"
+
+related:
+  - "g2-core-chart-init"
+  - "g2-scale-linear"
+  - "g2-scale-ordinal"
+  - "g2-core-data-binding"
+
+use_cases:
+  - "将数据字段映射到图表的视觉属性"
+  - "理解 Spec 模式中 encode 对象的结构"
+  - "配置多通道映射"
+
+difficulty: "beginner"
+completeness: "partial"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/encode"
+---
+
+## 核心概念
+
+**通道（Channel）** 是图形属性的抽象。在 Spec 模式中，`encode` 是 `options` 对象的一个字段，
+其中每个 key 是通道名，value 是数据字段名（字符串）或常量。
+
+## 通用通道列表
+
+| 通道 | 说明 | 常见 Mark |
+|------|------|-----------|
+| `x` | X 轴位置 | 所有 Mark |
+| `y` | Y 轴位置 | 所有 Mark |
+| `color` | 颜色（fill + stroke） | 所有 Mark |
+| `size` | 大小/粗细 | Point、Link、Line |
+| `shape` | 形状 | Point、Interval |
+| `opacity` | 透明度 | 所有 Mark |
+| `series` | 系列分组（不影响颜色） | Line、Area |
+| `key` | 动画时元素匹配键 | 所有 Mark |
+
+## 基本用法（Spec 模式）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'interval',
+  data: [
+    { city: '北京', gdp: 3.6 },
+    { city: '上海', gdp: 4.0 },
+    { city: '广州', gdp: 2.8 },
+  ],
+  encode: {
+    x: 'city',      // 分类轴：自动使用 Band Scale
+    y: 'gdp',       // 数值轴：自动使用 Linear Scale
+    color: 'city',  // 颜色区分
+  },
+});
+
+chart.render();
+```
+
+## 典型场景示例
+
+### 时间 x 轴（折线图）
+
+```javascript
+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 },
+  ],
+  encode: {
+    x: 'date',      // Date 对象自动使用 Time Scale
+    y: 'value',
+    color: 'series', // 多系列折线
+  },
+});
+```
+
+### 双数值轴 + 气泡图（多通道映射）
+
+```javascript
+chart.options({
+  type: 'point',
+  data: [
+    { income: 30000, lifeExpect: 72, population: 1400, country: 'China' },
+    { income: 60000, lifeExpect: 79, population: 330,  country: 'USA' },
+    { income: 45000, lifeExpect: 84, population: 125,  country: 'Japan' },
+  ],
+  encode: {
+    x: 'income',
+    y: 'lifeExpect',
+    size: 'population',    // 气泡大小
+    color: 'country',
+    shape: 'point',
+  },
+  scale: {
+    size: { range: [10, 60] },
+  },
+});
+```
+
+### 函数映射（高级）
+
+```javascript
+chart.options({
+  type: 'point',
+  data: [...],
+  encode: {
+    x: 'date',
+    y: 'value',
+    // value 是函数时：动态计算通道值
+    color: (d) => d.value > 100 ? 'red' : 'blue',
+    size: (d) => Math.sqrt(d.count),
+  },
+});
+```
+
+## encode 字段值类型说明
+
+| 值类型 | 含义 | 示例 |
+|--------|------|------|
+| `string`（字段名）| 映射数据字段 | `'genre'` |
+| `string`（颜色/形状常量）| 所有元素相同值 | `'#1890ff'`、`'circle'` |
+| `number` | 所有元素相同数值 | `10`（size 常量） |
+| `function` | 动态计算 | `(d) => d.val * 2` |
+
+> **判断规则**：`encode.color` 传入 `'genre'` → 视为字段名；传入 `'#1890ff'` → 视为颜色常量（以 `#` 开头或合法 CSS 颜色名）。`encode.size` 传入 `10`（数字）→ 常量。
+
+## G2 v4 → v5 Spec 迁移对照
+
+| G2 v4 链式 | G2 v5 Spec encode 字段 |
+|-----------|------------------------|
+| `.position('x*y')` | `encode: { x: 'x', y: 'y' }` |
+| `.color('type')` | `encode: { color: 'type' }` |
+| `.size('count')` | `encode: { size: 'count' }` |
+| `.shape('circle')` | `encode: { shape: 'circle' }` |
+| `.opacity('rate')` | `encode: { opacity: 'rate' }` |
+
+## 常见错误与修正
+
+### 错误 1：encode 写在了 style 里
+```javascript
+// ❌ 错误：style 不做数据映射
+chart.options({
+  type: 'interval',
+  data: [...],
+  style: { color: 'genre' },  // 无效！genre 是字段名，不是颜色值
+});
+
+// ✅ 正确：数据映射用 encode，固定样式用 style
+chart.options({
+  type: 'interval',
+  data: [...],
+  encode: { color: 'genre' },   // 数据驱动颜色
+  style: { fillOpacity: 0.8 },  // 固定透明度
+});
+```
+
+### 错误 2：color 与 series 通道混淆
+```javascript
+// 说明：color 既分组又改颜色；series 只分组不改颜色
+// 多系列折线图推荐用 color：
+chart.options({
+  type: 'line',
+  encode: {
+    x: 'month',
+    y: 'value',
+    color: 'type',    // ✅ 推荐：每条线不同颜色
+    // series: 'type', // 只分组，颜色相同（少用）
+  },
+});
+```

package/builtin-skills/antv-g2-chart/references/core/g2-core-view-composition.md

@@ -0,0 +1,224 @@
+---
+id: "g2-core-view-composition"
+title: "G2 视图组合（view + children）"
+description: |
+  G2 v5 通过 type: 'view' 容器和 children 数组实现多 Mark 叠加、
+  共享数据、分面（facet）等复合图表。
+  这是 Spec 模式中组合多个图形层的标准方式。
+
+library: "g2"
+version: "5.x"
+category: "core"
+tags:
+  - "view"
+  - "children"
+  - "视图组合"
+  - "多Mark叠加"
+  - "layer"
+  - "复合图表"
+  - "spec"
+
+related:
+  - "g2-core-chart-init"
+  - "g2-comp-annotation"
+  - "g2-comp-facet-rect"
+
+use_cases:
+  - "在同一坐标系中叠加多种图形（折线+散点、面积+折线）"
+  - "为多个子 Mark 共享数据源"
+  - "在图表中添加标注层"
+
+anti_patterns:
+  - "只有单个 Mark 时不需要 view 容器，直接用对应 type 即可"
+  - "children 中嵌套 type: 'view'——当某个子 Mark 需要独立数据时，直接在该 Mark 上指定 data 字段，而非再套一层 view + children"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/composition/view"
+---
+
+## 核心概念
+
+```
+chart.options({
+  type: 'view',      // 容器类型
+   [...],       // 父级数据（子 Mark 可继承）
+  encode: {...},     // 父级编码（子 Mark 可继承）
+  children: [        // 子 Mark 列表（按顺序渲染，后面的在上层）
+    { type: 'area', ... },
+    { type: 'line', ... },
+    { type: 'point', ... },
+  ],
+});
+```
+
+**数据继承规则**：
+- 子 Mark 若未指定 `data`，继承父级 `data`
+- 子 Mark 若未指定 `encode`，继承父级 `encode` 中对应通道
+
+## 面积 + 折线 + 散点叠加
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 700, height: 400 });
+
+const data = [
+  { month: 'Jan', value: 33 },
+  { month: 'Feb', value: 78 },
+  { month: 'Mar', value: 56 },
+  { month: 'Apr', value: 91 },
+  { month: 'May', value: 67 },
+];
+
+chart.options({
+  type: 'view',
+  data,                                    // 父级数据，三个子 Mark 共享
+  encode: { x: 'month', y: 'value' },     // 父级编码，子 Mark 继承
+  children: [
+    {
+      type: 'area',
+      style: { fill: '#1890ff', fillOpacity: 0.15 },
+    },
+    {
+      type: 'line',
+      style: { stroke: '#1890ff', lineWidth: 2 },
+    },
+    {
+      type: 'point',
+      encode: { shape: 'circle' },
+      style: { fill: 'white', stroke: '#1890ff', r: 4, lineWidth: 2 },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 子 Mark 独立数据（不继承父级）
+
+```javascript
+chart.options({
+  type: 'view',
+  children: [
+    {
+      type: 'interval',
+       salesData,       // 独立数据
+      encode: { x: 'month', y: 'revenue' },
+    },
+    {
+      type: 'line',
+       trendData,       // 独立数据
+      encode: { x: 'month', y: 'growth' },
+      scale: { y: { key: 'right' } },   // 独立 y 轴
+    },
+  ],
+});
+```
+
+## 折线 + 参考线组合
+
+```javascript
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    {
+      type: 'line',
+      encode: { x: 'month', y: 'value' },
+    },
+    {
+      type: 'lineY',                       // 水平参考线
+       [{ threshold: 60 }],
+      encode: { y: 'threshold' },
+      style: { stroke: 'red', lineDash: [4, 4] },
+      labels: [{ text: '目标线', position: 'right', style: { fill: 'red' } }],
+    },
+  ],
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：多次调用 options() 覆盖配置
+```javascript
+// ❌ 错误：每次 options() 调用都会覆盖上一次
+chart.options({ type: 'area', ... });
+chart.options({ type: 'line', ... });   // 覆盖了面积图！
+
+// ✅ 正确：用 view + children
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    { type: 'area', ... },
+    { type: 'line', ... },
+  ],
+});
+```
+
+### 错误 2：children 中嵌套 view（为子 Mark 单独变换数据时的常见误区）
+
+```javascript
+// ❌ 错误：在 children 里再套一层 type:'view' + children
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    { type: 'line', encode: { x: 'time', y: 'value' } },
+    {
+      type: 'view',                        // ❌ 不必要的嵌套 view
+      data: data.map(d => ({              // 只是想用派生数据
+        time: d.time,
+        min: d.value - 0.1,
+        max: d.value + 0.1,
+      })),
+      children: [
+        { type: 'rangeY', encode: { x: 'time', y: 'min', y1: 'max' } },
+      ],
+    },
+  ],
+});
+
+// ✅ 正确：直接在子 Mark 上指定 data，无需嵌套 view
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    { type: 'line', encode: { x: 'time', y: 'value' } },
+    {
+      type: 'rangeY',
+      data: data.map(d => ({             // ✅ 直接在 Mark 上声明独立 data
+        time: d.time,
+        min: d.value - 0.1,
+        max: d.value + 0.1,
+      })),
+      encode: { x: 'time', y: 'min', y1: 'max' },
+      style: { fillOpacity: 0.1 },
+    },
+  ],
+});
+```
+
+**规则**：`children` 数组的每个元素必须是 Mark（`line`/`point`/`interval` 等），
+当某个 Mark 需要独立或派生数据时，在该 Mark 节点上直接写 `data`，而不是再包一层 `view`。
+G2 不支持在 `children` 内嵌套 `view`。
+
+### 错误 3：子 Mark 的 encode 字段名与数据不匹配
+```javascript
+// ❌ 错误：父级和子级 encode 的字段名应保持一致
+chart.options({
+  type: 'view',
+  data: [{ month: 'Jan', value: 33 }],
+  encode: { x: 'month', y: 'value' },
+  children: [
+    {
+      type: 'point',
+      encode: { x: 'date', y: 'amount' },  // 字段名与数据不匹配！
+    },
+  ],
+});
+```