@loom-framework/core 0.1.0-alpha.9 → 0.1.0-alpha.91

package/builtin-skills/antv-g2-chart/references/compositions/g2-comp-view.md

@@ -0,0 +1,309 @@
+---
+id: "g2-comp-view"
+title: "G2 View 组合"
+description: |
+  View 组合用于创建多视图图表。可以将多个 mark 组合在一起，
+  共享数据、比例尺、坐标轴等配置。
+
+library: "g2"
+version: "5.x"
+category: "compositions"
+tags:
+  - "组合"
+  - "view"
+  - "多视图"
+  - "复合图表"
+
+related:
+  - "g2-comp-space-layer"
+  - "g2-comp-space-flex"
+  - "g2-core-chart-init"
+
+use_cases:
+  - "多系列图表"
+  - "复合图表"
+  - "共享配置的多 mark 图表"
+
+anti_patterns:
+  - "单一 mark 图表不需要 View 组合"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/composition"
+---
+
+## 核心概念
+
+View 组合允许将多个 mark 组合在一起：
+- 共享数据和配置
+- 统一管理比例尺和坐标轴
+- 支持嵌套组合
+
+**特点：**
+- 子 mark 继承父级配置
+- 支持数据合并
+- 可配置坐标轴、图例等
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'view',
+  data: [
+    { month: 'Jan', value: 100, type: 'A' },
+    { month: 'Feb', value: 120, type: 'A' },
+    { month: 'Jan', value: 80, type: 'B' },
+    { month: 'Feb', value: 90, type: 'B' },
+  ],
+  children: [
+    {
+      type: 'line',
+      encode: { x: 'month', y: 'value', color: 'type' },
+    },
+    {
+      type: 'point',
+      encode: { x: 'month', y: 'value', color: 'type' },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 共享坐标轴配置
+
+```javascript
+chart.options({
+  type: 'view',
+  data,
+  axis: {
+    x: { title: 'Month' },
+    y: { title: 'Value' },
+  },
+  children: [
+    { type: 'line', encode: { x: 'month', y: 'value', color: 'type' } },
+    { type: 'point', encode: { x: 'month', y: 'value', color: 'type' } },
+  ],
+});
+```
+
+### 共享比例尺
+
+```javascript
+chart.options({
+  type: 'view',
+  data,
+  scale: {
+    color: {
+      range: ['#1890ff', '#52c41a'],
+    },
+  },
+  children: [
+    { type: 'line', encode: { x: 'month', y: 'value', color: 'type' } },
+    { type: 'point', encode: { x: 'month', y: 'value', color: 'type' } },
+  ],
+});
+```
+
+### 子 mark 独立数据
+
+```javascript
+chart.options({
+  type: 'view',
+  children: [
+    {
+      type: 'interval',
+      data: [{ category: 'A', value: 100 }],
+      encode: { x: 'category', y: 'value' },
+    },
+    {
+      type: 'line',
+      data: [{ x: 0, y: 50 }, { x: 1, y: 150 }],
+      encode: { x: 'x', y: 'y' },
+      scale: { x: { type: 'identity' }, y: { domain: [0, 200] } },
+    },
+  ],
+});
+```
+
+### 带图例配置
+
+```javascript
+chart.options({
+  type: 'view',
+  data,
+  encode: { color: 'type' },
+  legend: {
+    color: { position: 'top' },
+  },
+  children: [
+    { type: 'line', encode: { x: 'month', y: 'value', color: 'type' } },
+    { type: 'point', encode: { x: 'month', y: 'value', color: 'type' } },
+  ],
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface ViewComposition {
+  type: 'view';
+  data?: DataOption;
+  encode?: EncodeOption;
+  scale?: ScaleOption;
+  axis?: AxisOption;
+  legend?: LegendOption;
+  transform?: TransformOption[];
+  slider?: SliderOption;
+  children: MarkSpec[];  // 子 mark 数组
+}
+```
+
+## 与 SpaceLayer/SpaceFlex 的区别
+
+| 组合类型 | 用途 | 特点 |
+|---------|------|------|
+| view | 多 mark 叠加 | 共享坐标系 |
+| spaceLayer | 多图层叠加 | 独立坐标系 |
+| spaceFlex | 多视图排列 | 并排/堆叠布局 |
+
+## 常见错误与修正
+
+### 错误 1：children 格式错误
+
+```javascript
+// ❌ 错误：children 应该是数组
+chart.options({
+  type: 'view',
+  children: { type: 'line', ... },
+});
+
+// ✅ 正确
+chart.options({
+  type: 'view',
+  children: [{ type: 'line', ... }],
+});
+```
+
+### 错误 2：子 mark 未指定 type
+
+```javascript
+// ❌ 错误：子 mark 必须有 type
+chart.options({
+  type: 'view',
+  children: [{ encode: { x: 'a', y: 'b' } }],
+});
+
+// ✅ 正确
+chart.options({
+  type: 'view',
+  children: [{ type: 'line', encode: { x: 'a', y: 'b' } }],
+});
+```
+
+### 错误 3：混淆 data 和 children 的数据
+
+```javascript
+// ⚠️ 注意：View 的 data 会与子 mark 的 data 合并
+// 如果子 mark 有自己的 data，会覆盖父级的 data
+
+// 方式 1：父级提供数据
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    { type: 'line', encode: { x: 'a', y: 'b' } },
+  ],
+});
+
+// 方式 2：子 mark 独立数据
+chart.options({
+  type: 'view',
+  children: [
+    { type: 'line', data, encode: { x: 'a', y: 'b' } },
+  ],
+});
+```
+
+### 错误 4：density 和 boxplot 使用不当导致白屏
+
+```javascript
+// ❌ 错误：density 和 boxplot 的数据格式不正确
+// density 需要经过 KDE 转换后的数据，包含 y 和 size 字段
+// boxplot 需要原始数据进行内部统计计算
+chart.options({
+  type: 'view',
+  data: rawData,
+  children: [
+    {
+      type: 'density',
+      encode: { x: 'category', y: 'value', size: 'size' },
+    },
+    {
+      type: 'boxplot',
+      encode: { x: 'category', y: 'value' },
+    },
+  ],
+});
+
+// ✅ 正确：使用 transform 进行 KDE 转换，确保数据格式正确
+chart.options({
+  type: 'view',
+  data: {
+    type: 'inline',
+    value: rawData,
+  },
+  children: [
+    {
+      type: 'density',
+      data: {
+        transform: [
+          {
+            type: 'kde',
+            field: 'value',
+            groupBy: ['category'],
+            size: 50, // 控制密度曲线的精细程度
+          },
+        ],
+      },
+      encode: {
+        x: 'category',
+        y: 'value',
+        size: 'size',
+        series: 'category',
+      },
+      style: {
+        fillOpacity: 0.7,
+      },
+      tooltip: false,
+    },
+    {
+      type: 'boxplot',
+      encode: {
+        x: 'category',
+        y: 'value',
+        series: 'category',
+        shape: 'violin', // 可选，用于小提琴图
+      },
+      style: {
+        opacity: 0.8,
+        strokeOpacity: 0.6,
+        point: false, // 可选，隐藏异常点
+      },
+    },
+  ],
+});
+```

package/builtin-skills/antv-g2-chart/references/concepts/g2-concept-chart-selection.md

@@ -0,0 +1,235 @@
+---
+id: "g2-concept-chart-selection"
+title: "G2 图表类型选择指南"
+description: |
+  根据数据特征和分析目的选择合适的图表类型。
+  覆盖比较、趋势、占比、分布、关系六大场景，
+  对应 G2 的具体实现方式，帮助避免"用错图表"的常见错误。
+
+library: "g2"
+version: "5.x"
+category: "concepts"
+tags:
+  - "图表选择"
+  - "chart selection"
+  - "可视化设计"
+  - "柱状图"
+  - "折线图"
+  - "饼图"
+  - "散点图"
+  - "决策"
+
+related:
+  - "g2-concept-visual-channels"
+  - "g2-mark-interval-basic"
+  - "g2-mark-line-basic"
+  - "g2-mark-arc-pie"
+  - "g2-mark-point-scatter"
+
+use_cases:
+  - "根据用户需求选择正确的图表类型"
+  - "避免在不合适场景使用饼图或折线图"
+  - "理解何时用 G2 图表 vs G6 图分析"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+---
+
+## 核心决策树
+
+```
+你的数据和目的是什么？
+
+├── 比较类别间的大小 → 柱状图 / 条形图
+├── 展示随时间的变化趋势 → 折线图 / 面积图
+├── 展示部分与整体的占比 → 饼图 / 环形图 / 堆叠柱状图
+├── 展示两个变量的相关性 → 散点图 / 气泡图
+├── 展示数据的分布规律 → 直方图 / 箱线图 / 小提琴图
+└── 展示节点间的关系网络 → G6 图（force/dagre/tree 布局）
+```
+
+## 场景一：比较（Comparison）
+
+**目的**：比较不同类别/时间点的数值大小
+
+| 数据特征 | 推荐图表 | G2 实现 |
+|---------|---------|---------|
+| 类别 ≤ 10，竖向标签可读 | **柱状图** | `type: 'interval'` |
+| 类别名称较长 / 类别多 | **条形图**（水平） | `type: 'interval'` + `coordinate: { transform: [{ type: 'transpose' }] }` |
+| 多个系列并排比较 | **分组柱状图** | `transform: [{ type: 'dodgeX' }]` |
+| 展示子类在总量中的贡献 | **堆叠柱状图** | `transform: [{ type: 'stackY' }]` |
+
+```javascript
+// 柱状图（最常见的比较图）
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+  transform: [{ type: 'sortX', by: 'y', reverse: true }],  // 按值降序
+});
+```
+
+## 场景二：趋势（Trend）
+
+**目的**：展示数值随时间或序列的变化
+
+| 数据特征 | 推荐图表 | G2 实现 |
+|---------|---------|---------|
+| 单一指标时间趋势 | **折线图** | `type: 'line'` |
+| 多指标对比趋势 | **多系列折线图** | `type: 'line'` + `encode.color: 'series'` |
+| 强调面积/累积量 | **面积图** | `type: 'area'` |
+| 展示数量随时间增减 | **面积图**（堆叠）| `type: 'area'` + `transform: [{ type: 'stackY' }]` |
+
+```javascript
+// 多系列折线图
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value', color: 'series' },
+  scale: { x: { type: 'time' } },
+  labels: [{ text: 'series', selector: 'last', position: 'right' }],
+});
+```
+
+## 场景三：占比（Part-to-Whole）
+
+**目的**：展示部分占整体的比例
+
+| 数据特征 | 推荐图表 | G2 实现 | 注意 |
+|---------|---------|---------|------|
+| 类别 ≤ 5，强调比例 | **饼图** | `interval` + `theta` 坐标 | 类别多时难区分 |
+| 需要中心留白 | **环形图** | 饼图 + `innerRadius` | 可在中心放总数 |
+| 类别多，强调排名 | **百分比堆叠柱状图** | `stackY` + `normalizeY` | |
+| 多层级占比 | **旭日图** | 暂用 `sunburst` 插件 | |
+
+```javascript
+// 饼图（类别 ≤ 5 时）
+chart.options({
+  type: 'interval',
+  data,
+  encode: { y: 'value', color: 'category' },
+  transform: [{ type: 'stackY' }],
+  coordinate: { type: 'theta', outerRadius: 0.85 },
+  labels: [{
+    text: (d) => `${d.category}\n${d.pct}%`,
+    position: 'outside',
+    connector: true,
+  }],
+});
+```
+
+## 场景四：相关性（Correlation）
+
+**目的**：探索两个或多个变量之间的关系
+
+| 数据特征 | 推荐图表 | G2 实现 |
+|---------|---------|---------|
+| 两个数值变量 | **散点图** | `type: 'point'` |
+| 两个数值 + 第三数值维度 | **气泡图** | `point` + `encode.size` |
+| 多变量热力矩阵 | **热力图** | `type: 'cell'` |
+| 展示分布+相关 | **散点图 + 趋势线** | `view` + `point` + `line` |
+
+```javascript
+// 气泡图
+chart.options({
+  type: 'point',
+  data,
+  encode: {
+    x: 'income',
+    y: 'happiness',
+    size: 'population',  // 第三数值维度
+    color: 'region',
+  },
+  scale: { size: { range: [4, 30] } },
+});
+```
+
+## 场景五：分布（Distribution）
+
+**目的**：了解数据的分布规律
+
+| 数据特征 | 推荐图表 | G2 实现 |
+|---------|---------|---------|
+| 单变量分布 | **直方图** | `type: 'interval'` + `transform: [{ type: 'binX' }]` |
+| 多组分布比较 | **箱线图** | `type: 'boxplot'` |
+| 展示中位数/四分位 | **箱线图** | `type: 'boxplot'` |
+
+```javascript
+// 直方图
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'value', y: 'count' },
+  transform: [{ type: 'binX', y: 'count' }],
+});
+```
+
+## 场景六：关系网络（Relationship）
+
+**目的**：展示实体间的连接关系、层次结构、流向
+
+| 数据特征 | 推荐库 | G6 布局 |
+|---------|--------|---------|
+| 无层级的网络关系 | **G6** | `force`（力导向） |
+| 有方向的流程/依赖 | **G6** | `dagre`（有向无环图） |
+| 单根树形层级 | **G6** | `compactBox`（树形）|
+| 对等环状关系 | **G6** | `circular`（环形） |
+
+```javascript
+// G6 知识图谱（力导向）
+const graph = new Graph({
+  layout: { type: 'force', preventOverlap: true },
+  data: { nodes, edges },
+});
+await graph.render();
+```
+
+## 快速选择口诀
+
+```
+比较用柱状，趋势用折线，
+占比用饼图，关系用散点，
+分布用直方，层级用树形，
+网络用 G6，复杂用组合。
+```
+
+## 常见错误
+
+### 错误 1：用折线图表示无时间顺序的分类数据
+
+```javascript
+// ❌ 误用：城市名称没有顺序，不应该用折线（会误导"趋势"感知）
+chart.options({
+  type: 'line',
+   [{ city: '北京', gdp: 3.6 }, { city: '上海', gdp: 4.3 }],
+  encode: { x: 'city', y: 'gdp' },   // ❌ 城市是无序分类，不是时序
+});
+
+// ✅ 正确：分类比较用柱状图
+chart.options({
+  type: 'interval',
+  encode: { x: 'city', y: 'gdp' },
+});
+```
+
+### 错误 2：用饼图展示 8+ 个类别
+
+```javascript
+// ❌ 误用：10个类别的饼图，各扇区难以区分
+chart.options({
+  type: 'interval',
+  coordinate: { type: 'theta' },
+  // 如果有 10 个国家/地区...很难读取
+});
+
+// ✅ 正确：超过 5 类改用排序条形图
+chart.options({
+  type: 'interval',
+  encode: { x: 'country', y: 'value' },
+  coordinate: { transform: [{ type: 'transpose' }] },
+  transform: [{ type: 'sortX', by: 'y', reverse: true }],
+});
+```