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

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

@@ -0,0 +1,147 @@
+---
+id: "g2-mark-interval-normalized"
+title: "G2 百分比堆叠柱状图"
+description: |
+  使用 Interval Mark 配合 stackY + normalizeY Transform 创建百分比堆叠柱状图。
+  每组柱体总高度归一化为 100%，聚焦展示各子类别的占比变化，
+  消除总量差异的干扰，便于跨组比较结构分布。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+subcategory: "interval"
+tags:
+  - "百分比堆叠"
+  - "normalized"
+  - "normalizeY"
+  - "占比"
+  - "结构分析"
+  - "100% stacked bar"
+  - "spec"
+
+related:
+  - "g2-mark-interval-stacked"
+  - "g2-mark-interval-grouped"
+  - "g2-transform-normalizey"
+  - "g2-transform-stacky"
+
+use_cases:
+  - "比较不同组别中各子类别的比例分布"
+  - "关注结构变化而非绝对数值时"
+  - "消除总量差异，突出占比"
+
+anti_patterns:
+  - "需要看绝对数值变化时，改用普通堆叠柱状图"
+  - "子类别只有两个时，简单折线图或面积图更直观"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/bar/normalized"
+---
+
+## 核心概念
+
+百分比堆叠 = `stackY` + `normalizeY` 两个变换顺序执行：
+1. `stackY`：先将各子类别数值堆叠为 y0/y1 区间
+2. `normalizeY`：再将每组的 y 值归一化到 [0, 1]
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'interval',
+  data: [
+    { month: 'Jan', type: 'A', value: 100 },
+    { month: 'Jan', type: 'B', value: 200 },
+    { month: 'Jan', type: 'C', value: 150 },
+    { month: 'Feb', type: 'A', value: 80  },
+    { month: 'Feb', type: 'B', value: 220 },
+    { month: 'Feb', type: 'C', value: 100 },
+    { month: 'Mar', type: 'A', value: 130 },
+    { month: 'Mar', type: 'B', value: 180 },
+    { month: 'Mar', type: 'C', value: 90  },
+  ],
+  encode: {
+    x: 'month',
+    y: 'value',
+    color: 'type',
+  },
+  transform: [
+    { type: 'stackY' },      // 1. 先堆叠
+    { type: 'normalizeY' },  // 2. 再归一化为百分比
+  ],
+  axis: {
+    y: { labelFormatter: (v) => `${(v * 100).toFixed(0)}%` },
+  },
+});
+
+chart.render();
+```
+
+## 带百分比数据标签
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }, { type: 'normalizeY' }],
+  labels: [
+    {
+      text: (d) => `${(d.value * 100).toFixed(1)}%`,  // 注意：归一化后 value 已是 0-1
+      position: 'inside',
+      style: {
+        fill: 'white',
+        fontSize: 11,
+        fontWeight: 'bold',
+      },
+      // 过滤掉占比过小的标签（避免拥挤）
+      filter: (d) => d.value > 0.05,
+    },
+  ],
+  axis: {
+    y: { labelFormatter: (v) => `${(v * 100).toFixed(0)}%` },
+  },
+});
+```
+
+## 百分比堆叠条形图（水平）
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }, { type: 'normalizeY' }],
+  coordinate: { transform: [{ type: 'transpose' }] },
+  axis: {
+    x: { labelFormatter: (v) => `${(v * 100).toFixed(0)}%` },
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：transform 顺序颠倒
+```javascript
+// ❌ 错误：先 normalizeY 再 stackY，结果不正确
+chart.options({
+  transform: [{ type: 'normalizeY' }, { type: 'stackY' }],
+});
+
+// ✅ 正确：必须先 stackY 后 normalizeY
+chart.options({
+  transform: [{ type: 'stackY' }, { type: 'normalizeY' }],
+});
+```

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

@@ -0,0 +1,183 @@
+---
+id: "g2-mark-interval-stacked"
+title: "G2 堆叠柱状图"
+description: |
+  使用 Interval Mark 配合 stackY Transform 创建堆叠柱状图。
+  在 Spec 模式中，通过 transform 数组添加 stackY 变换。
+  堆叠柱状图用于展示部分与整体的关系及各子类别在总量中的占比变化。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+subcategory: "interval"
+tags:
+  - "堆叠柱状图"
+  - "stacked bar"
+  - "StackY"
+  - "堆叠"
+  - "部分整体"
+  - "多系列"
+  - "spec"
+
+related:
+  - "g2-mark-interval-basic"
+  - "g2-mark-interval-grouped"
+  - "g2-mark-interval-normalized"
+  - "g2-transform-stacky"
+
+use_cases:
+  - "展示多个子类别在各时间点的构成"
+  - "比较不同类别中各子项的占比"
+  - "可视化总量与子项的关系"
+
+anti_patterns:
+  - "子类别超过 5-7 个时堆叠图难以阅读，考虑用分组柱状图"
+  - "不适合比较单个子类别的趋势（难以对齐基准线）"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/bar/stacked"
+---
+
+## 核心概念
+
+堆叠柱状图 = `type: 'interval'` + `transform: [{ type: 'stackY' }]`。
+`stackY` 将同一 x 位置的多个数值叠加计算 y0/y1 区间，
+使各子类别的柱体在垂直方向上依次堆叠。
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'interval',
+  data: [
+    { month: 'Jan', type: 'A', value: 100 },
+    { month: 'Jan', type: 'B', value: 200 },
+    { month: 'Jan', type: 'C', value: 150 },
+    { month: 'Feb', type: 'A', value: 120 },
+    { month: 'Feb', type: 'B', value: 180 },
+    { month: 'Feb', type: 'C', value: 160 },
+    { month: 'Mar', type: 'A', value: 90 },
+    { month: 'Mar', type: 'B', value: 220 },
+    { month: 'Mar', type: 'C', value: 130 },
+  ],
+  encode: {
+    x: 'month',
+    y: 'value',
+    color: 'type',
+  },
+  transform: [{ type: 'stackY' }],   // 关键：堆叠变换
+});
+
+chart.render();
+```
+
+## 带数据标签的堆叠柱状图
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  labels: [
+    {
+      text: 'value',
+      position: 'inside',     // 标签在柱体内部
+      style: { fontSize: 11, fill: 'white' },
+    },
+  ],
+});
+```
+
+## 堆叠条形图（水平方向）
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  coordinate: { transform: [{ type: 'transpose' }] },   // 转置为水平条形图
+});
+```
+
+## 控制堆叠顺序
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [{ type: 'stackY', orderBy: 'value' }],  // 按值大小排序堆叠
+});
+```
+
+## 百分比堆叠柱状图
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [
+    { type: 'stackY' },
+    { type: 'normalizeY' },  // 归一化到 [0, 1]，即百分比堆叠
+  ],
+  axis: {
+    y: { labelFormatter: (v) => `${(v * 100).toFixed(0)}%` },
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：忘记 transform stackY
+```javascript
+// ❌ 错误：多系列数据不会自动堆叠，柱体会在同一位置重叠
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  // 缺少 transform！
+});
+
+// ✅ 正确：必须显式声明 stackY
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],   // 必须！
+});
+```
+
+### 错误 2：同一 (x, color) 组合有重复数据行
+```javascript
+// ❌ 错误：同月份同类型出现两条数据，stackY 会重复叠加
+const badData = [
+  { month: 'Jan', type: 'A', value: 100 },
+  { month: 'Jan', type: 'A', value: 50 },  // 重复！
+];
+
+// ✅ 正确：每个 (x, color) 组合只有一条数据；如需合并请在数据层聚合
+```
+
+### 错误 3：transform 写成对象而非数组
+```javascript
+// ❌ 错误：transform 必须是数组
+chart.options({ transform: { type: 'stackY' } });
+
+// ✅ 正确：transform 是数组，支持多个变换链式执行
+chart.options({ transform: [{ type: 'stackY' }] });
+```

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

@@ -0,0 +1,237 @@
+---
+id: "g2-mark-k-chart"
+title: "G2 K-Chart (Candlestick) Mark"
+description: |
+  K线图 Mark。使用 link 和 interval 组合，展示股票等金融数据的价格走势。
+  适用于股票分析、期货交易、数字货币分析等场景。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "K线图"
+  - "蜡烛图"
+  - "candlestick"
+  - "股票"
+
+related:
+  - "g2-mark-line-basic"
+  - "g2-mark-boxplot"
+
+use_cases:
+  - "股票价格分析"
+  - "期货交易"
+  - "数字货币分析"
+
+anti_patterns:
+  - "非时间序列数据不适合"
+  - "单一数值展示应使用折线图"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/mark/candlestick"
+---
+
+## 核心概念
+
+K线图展示金融数据的价格走势：
+- 使用 `link` 标记表示影线（最高/最低价）
+- 使用 `interval` 标记表示实体（开盘/收盘价）
+- 颜色区分涨跌
+
+**四价数据：**
+- 开盘价（start）
+- 收盘价（end）
+- 最高价（max）
+- 最低价（min）
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  autoFit: true,
+});
+
+const data = [
+  { time: '2015-11-19', start: 8.18, max: 8.33, min: 7.98, end: 8.32 },
+  { time: '2015-11-18', start: 8.37, max: 8.6, min: 8.03, end: 8.09 },
+  { time: '2015-11-17', start: 8.7, max: 8.78, min: 8.32, end: 8.37 },
+  { time: '2015-11-16', start: 8.48, max: 8.85, min: 8.43, end: 8.7 },
+];
+
+chart.options({
+  type: 'view',
+  data,
+  encode: {
+    x: 'time',
+    color: (d) => (d.start > d.end ? '下跌' : '上涨'),
+  },
+  scale: {
+    color: { domain: ['下跌', '上涨'], range: ['#4daf4a', '#e41a1c'] },
+  },
+  children: [
+    // 影线（最高/最低价）
+    {
+      type: 'link',
+      encode: { y: ['min', 'max'] },
+    },
+    // 实体（开盘/收盘价）
+    {
+      type: 'interval',
+      encode: { y: ['start', 'end'] },
+      style: { fillOpacity: 1 },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 带成交量
+
+```javascript
+// K线图
+const kChart = new Chart({ container: 'kChart' });
+kChart.options({
+  type: 'view',
+  data,
+  encode: { x: 'time', color: (d) => d.start > d.end ? '下跌' : '上涨' },
+  children: [
+    { type: 'link', encode: { y: ['min', 'max'] } },
+    { type: 'interval', encode: { y: ['start', 'end'] } },
+  ],
+});
+
+// 成交量图
+const volumeChart = new Chart({ container: 'volumeChart' });
+volumeChart.options({
+  type: 'interval',
+  data,
+  encode: {
+    x: 'time',
+    y: 'volume',
+    color: (d) => d.start > d.end ? '下跌' : '上涨',
+  },
+});
+```
+
+### Spec 模式
+
+```javascript
+chart.options({
+  type: 'view',
+  data,
+  encode: {
+    x: 'time',
+    color: (d) => d.start > d.end ? '下跌' : '上涨',
+  },
+  scale: {
+    color: { domain: ['下跌', '上涨'], range: ['#4daf4a', '#e41a1c'] },
+  },
+  children: [
+    {
+      type: 'link',
+      encode: { y: ['min', 'max'] },
+    },
+    {
+      type: 'interval',
+      encode: { y: ['start', 'end'] },
+      style: { fillOpacity: 1 },
+    },
+  ],
+});
+```
+
+### 带坐标轴标题
+
+```javascript
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    { type: 'link', encode: { y: ['min', 'max'] } },
+    {
+      type: 'interval',
+      encode: { y: ['start', 'end'] },
+      axis: {
+        y: { title: '价格' },
+      },
+    },
+  ],
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface KChartData {
+  time: string;      // 时间
+  start: number;     // 开盘价
+  end: number;       // 收盘价
+  max: number;       // 最高价
+  min: number;       // 最低价
+  volume?: number;   // 成交量（可选）
+}
+
+// K线图由两个图层组成：
+// 1. link - 影线（最高/最低价）
+// 2. interval - 实体（开盘/收盘价）
+```
+
+## K线图 vs 折线图
+
+| 特性 | K线图 | 折线图 |
+|------|-------|--------|
+| 信息量 | 四价数据 | 单一价格 |
+| 用途 | 技术分析 | 趋势展示 |
+| 复杂度 | 较高 | 简单 |
+
+## 常见错误与修正
+
+### 错误 1：缺少 link 标记
+
+```javascript
+// ❌ 问题：只有实体，没有影线
+chart.options({
+  type: 'interval',
+  encode: { y: ['start', 'end'] },
+});
+
+// ✅ 正确：使用 view 组合 link 和 interval
+chart.options({
+  type: 'view',
+  children: [
+    { type: 'link', encode: { y: ['min', 'max'] } },
+    { type: 'interval', encode: { y: ['start', 'end'] } },
+  ],
+});
+```
+
+### 错误 2：颜色编码错误
+
+```javascript
+// ❌ 问题：颜色字段不正确
+encode: { color: 'time' }
+
+// ✅ 正确：根据涨跌设置颜色
+encode: { color: (d) => d.start > d.end ? '下跌' : '上涨' }
+```
+
+### 错误 3：数据顺序错误
+
+```javascript
+// ⚠️ 注意：时间数据需要正确排序
+scale: {
+  x: {
+    compare: (a, b) => new Date(a).getTime() - new Date(b).getTime(),
+  },
+}
+```