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

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

@@ -0,0 +1,134 @@
+---
+id: "g2-mark-link"
+title: "G2 Link 连线图（两点间连线）"
+description: |
+  link mark 在两个数据点之间绘制连线，每条记录有独立的起点(x/y)和终点(x1/y1)。
+  与 line mark 不同，link 的每条记录就是一条独立的线段，不需要通过 color/series 分组。
+  适合展示迁移、比较、排名变化等场景。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "link"
+  - "连线"
+  - "坡度图"
+  - "slope chart"
+  - "迁移图"
+  - "两点连线"
+
+related:
+  - "g2-mark-line-basic"
+  - "g2-mark-point-scatter"
+
+use_cases:
+  - "坡度图（展示两个时期的排名/数值变化）"
+  - "两个分类之间的连线（迁移、关联）"
+  - "起止点数据的路径展示"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/general/link/"
+---
+
+## 最小可运行示例（坡度图 — 排名变化）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+// 每条记录代表一个城市从 2022 到 2023 年的排名变化
+const data = [
+  { city: '北京', rank2022: 1, rank2023: 2 },
+  { city: '上海', rank2022: 2, rank2023: 1 },
+  { city: '广州', rank2022: 3, rank2023: 5 },
+  { city: '深圳', rank2022: 4, rank2023: 3 },
+  { city: '成都', rank2022: 5, rank2023: 4 },
+];
+
+const chart = new Chart({ container: 'container', width: 400, height: 480 });
+
+chart.options({
+  type: 'link',
+  data,
+  encode: {
+    x: ['2022', '2023'],           // x 轴的两个位置（起点/终点）
+    y: ['rank2022', 'rank2023'],   // 两个端点的 y 值（起点/终点）
+    color: 'city',
+  },
+  scale: {
+    y: { reverse: true },  // 排名从上到下（1 在顶部）
+  },
+  style: {
+    lineWidth: 2,
+    strokeOpacity: 0.8,
+  },
+  // 显示两端散点
+  labels: [
+    { text: (d) => `${d.city} ${d.rank2022}`, position: 'left' },
+    { text: (d) => `${d.rank2023}`, position: 'right' },
+  ],
+});
+
+chart.render();
+```
+
+## 箭头连线
+
+```javascript
+chart.options({
+  type: 'link',
+  data,
+  encode: {
+    x: ['source_x', 'target_x'],
+    y: ['source_y', 'target_y'],
+    color: 'type',
+  },
+  style: {
+    lineWidth: 1.5,
+    // 末端箭头
+    endArrow: true,
+    endArrowSize: 8,
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：encode.x/y 写成单个字段名——link 需要 [起点字段, 终点字段] 数组
+```javascript
+// ❌ 错误：x 和 y 是单个字段，只绑定了一端
+chart.options({
+  type: 'link',
+  encode: {
+    x: 'x',    // ❌ 只有一个位置
+    y: 'y',    // ❌
+  },
+});
+
+// ✅ 正确：x 和 y 必须是包含两个字段名的数组
+chart.options({
+  type: 'link',
+  encode: {
+    x: ['x0', 'x1'],  // ✅ [起点字段, 终点字段]
+    y: ['y0', 'y1'],  // ✅
+  },
+});
+```
+
+### 错误：用 line mark 代替 link——多数据系列时行为不同
+```javascript
+// ❌ 如果每条记录是独立的一段连线，用 line 需要 series 分组，容易出错
+chart.options({
+  type: 'line',
+  encode: { x: 'x', y: 'y', color: 'id' },  // 需要 color 才能分线
+});
+
+// ✅ 每条记录一条线段的场景，直接用 link
+chart.options({
+  type: 'link',
+  encode: { x: ['x0', 'x1'], y: ['y0', 'y1'] },  // ✅ 更直观
+});
+```

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

@@ -0,0 +1,125 @@
+---
+id: "g2-mark-liquid"
+title: "G2 水波图（liquid）"
+description: |
+  liquid mark 用波浪填充的圆形展示单一百分比数值，
+  常用于展示完成率、健康指标、KPI 达成率等。
+  数据为 0~1 的小数（百分比），内置波浪动画效果。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "liquid"
+  - "水波图"
+  - "进度"
+  - "百分比"
+  - "KPI"
+  - "完成率"
+
+related:
+  - "g2-mark-gauge"
+  - "g2-core-chart-init"
+
+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/other/#liquid"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 300, height: 300 });
+
+chart.options({
+  type: 'liquid',
+  data: 0.72,    // 0~1 之间的百分比数值
+  style: {
+    outlineBorder: 4,       // 外框边框宽度
+    outlineDistance: 8,     // 外框与内圆的间距
+    waveLength: 128,        // 波浪长度
+  },
+});
+
+chart.render();
+```
+
+## 自定义样式
+
+```javascript
+chart.options({
+  type: 'liquid',
+  data: 0.6,
+  style: {
+    outlineBorder: 4,
+    outlineDistance: 8,
+    waveLength: 128,
+    // 波浪颜色
+    fill: '#5B8FF9',
+    fillOpacity: 0.85,
+    // 背景圆颜色
+    background: {
+      fill: '#E8F0FE',
+    },
+    // 中心文字样式
+    text: {
+      style: {
+        fontSize: 28,
+        fontWeight: 'bold',
+        fill: '#fff',
+        // 自定义文字内容（默认显示百分比）
+        formatter: (v) => `${(v * 100).toFixed(1)}%`,
+      },
+    },
+  },
+  // 不显示坐标轴和图例
+  axis: false,
+  legend: false,
+  tooltip: false,
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：数值超出 0~1 范围——波浪位置异常
+```javascript
+// ❌ 错误：液位值是 72（应该是 0.72）
+chart.options({
+  type: 'liquid',
+  data: 72,   // ❌ 应该是 0.72
+});
+
+// ✅ 正确：0~1 的小数
+chart.options({
+  data: 0.72,  // ✅
+});
+```
+
+### 错误 2：设置了坐标轴——坐标轴在水波图中无意义
+```javascript
+// ❌ 液位图默认会显示坐标轴，通常需要关闭
+chart.options({
+  type: 'liquid',
+  data: 0.7,
+  // ❌ 没有关闭 axis/legend/tooltip
+});
+
+// ✅ 推荐关闭多余组件
+chart.options({
+  type: 'liquid',
+  data: 0.7,
+  axis: false,     // ✅ 关闭坐标轴
+  legend: false,   // ✅ 关闭图例
+  tooltip: false,  // ✅ 关闭 tooltip
+});
+```

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

@@ -0,0 +1,257 @@
+---
+id: "g2-mark-mosaic"
+title: "G2 马赛克图（mosaic）"
+description: |
+  马赛克图（Mosaic Plot / Marimekko Chart）有两种形式：
+  1. 均匀马赛克图：type: 'cell'，用颜色和大小展示二维分类数据分布；
+  2. 非均匀马赛克图：type: 'interval' + flexX/stackY/normalizeY transform，
+     矩形宽度代表类别规模，高度代表内部分布比例；
+  3. 密度马赛克图：type: 'rect' + bin transform，展示二维连续数据的分布密度。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "马赛克图"
+  - "mosaic"
+  - "marimekko"
+  - "cell"
+  - "flexX"
+  - "bin"
+  - "热力图"
+
+related:
+  - "g2-mark-cell-heatmap"
+  - "g2-mark-interval-stacked"
+
+use_cases:
+  - "二维分类数据分布（均匀马赛克图）"
+  - "市场细分分析（非均匀马赛克图）"
+  - "二维连续数据密度分析（密度马赛克图）"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-04-01"
+updated: "2025-04-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/general/mosaic"
+---
+
+## 核心概念
+
+马赛克图有三种实现方式：
+
+| 类型 | mark | 特点 |
+|------|------|------|
+| 均匀马赛克图 | `cell` | 坐标轴均匀分布，用颜色/大小编码第三维 |
+| 非均匀马赛克图 | `interval` + flexX | X 轴宽度按数据比例分配 |
+| 密度马赛克图 | `rect` + bin | 连续数据分箱后展示密度 |
+
+## 均匀马赛克图（cell）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  autoFit: true,
+  height: 400,
+});
+
+chart.options({
+  type: 'cell',
+   [
+    { product: '手机', region: '华北', sales: 120, category: '高端' },
+    { product: '手机', region: '华东', sales: 180, category: '高端' },
+    { product: '手机', region: '华南', sales: 150, category: '高端' },
+    { product: '电脑', region: '华北', sales: 80, category: '中端' },
+    { product: '电脑', region: '华东', sales: 110, category: '中端' },
+    { product: '电脑', region: '华南', sales: 95, category: '中端' },
+    { product: '平板', region: '华北', sales: 60, category: '中端' },
+    { product: '平板', region: '华东', sales: 85, category: '中端' },
+    { product: '平板', region: '华南', sales: 70, category: '低端' },
+    { product: '耳机', region: '华北', sales: 40, category: '低端' },
+    { product: '耳机', region: '华东', sales: 55, category: '低端' },
+    { product: '耳机', region: '华南', sales: 45, category: '低端' },
+  ],
+  encode: {
+    x: 'product',
+    y: 'region',
+    color: 'category',
+    size: 'sales',      // 用格子大小编码数值
+  },
+  scale: {
+    color: { palette: 'category10', type: 'ordinal' },
+    size: { type: 'linear', range: [0.3, 1] },
+  },
+  style: {
+    stroke: '#fff',
+    lineWidth: 2,
+    inset: 2,
+  },
+});
+
+chart.render();
+```
+
+## 非均匀马赛克图（Marimekko Chart）
+
+矩形宽度按 X 轴字段的总量比例分配，展示市场份额类数据：
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 900,
+  height: 600,
+  paddingLeft: 0,
+  paddingRight: 0,
+});
+
+chart.options({
+  type: 'interval',
+  data: {
+    type: 'fetch',
+    value: 'https://gw.alipayobjects.com/os/bmw-prod/3041da62-1bf4-4849-aac3-01a387544bf4.csv',
+  },
+  transform: [
+    { type: 'flexX', reducer: 'sum' },  // X轴宽度按 sum 比例分配
+    { type: 'stackY' },                  // Y轴堆叠
+    { type: 'normalizeY' },              // Y轴归一化到 0-1
+  ],
+  encode: {
+    x: 'market',
+    y: 'value',
+    color: 'segment',
+  },
+  axis: {
+    y: false,
+  },
+  scale: {
+    x: { paddingOuter: 0, paddingInner: 0.01 },
+  },
+  tooltip: 'value',
+  labels: [
+    {
+      text: 'segment',
+      x: 5,
+      y: 5,
+      textAlign: 'start',
+      textBaseline: 'top',
+      fontSize: 10,
+      fill: '#fff',
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 密度马赛克图（bin transform）
+
+适合展示两个连续字段的分布密度关系：
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  autoFit: true,
+});
+
+chart.options({
+  type: 'rect',
+  data: {
+    type: 'fetch',
+    value: 'https://assets.antv.antgroup.com/g2/movies.json',
+  },
+  encode: {
+    x: 'IMDB Rating',
+    y: 'Rotten Tomatoes Rating',
+  },
+  transform: [
+    { type: 'bin', color: 'count', thresholdsX: 30, thresholdsY: 20 },
+  ],
+  scale: {
+    color: { palette: 'ylGnBu' },
+  },
+});
+
+chart.render();
+```
+
+## 常见错误与修正
+
+### 错误 1：非均匀马赛克图缺少 flexX transform
+
+```javascript
+// ❌ 错误：没有 flexX，X 轴宽度均等，不是真正的马赛克图
+chart.options({
+  type: 'interval',
+  data,
+  transform: [
+    { type: 'stackY' },
+    { type: 'normalizeY' },
+    // ❌ 缺少 flexX
+  ],
+  encode: { x: 'market', y: 'value', color: 'segment' },
+});
+
+// ✅ 正确：三个 transform 必须同时使用
+chart.options({
+  type: 'interval',
+  data,
+  transform: [
+    { type: 'flexX', reducer: 'sum' },  // ✅ X轴宽度按比例
+    { type: 'stackY' },
+    { type: 'normalizeY' },
+  ],
+  encode: { x: 'market', y: 'value', color: 'segment' },
+});
+```
+
+### 错误 2：均匀马赛克图使用 interval 而非 cell
+
+```javascript
+// ❌ 问题：interval 在均匀网格场景下不如 cell 直观
+chart.options({
+  type: 'interval',   // ❌ 均匀格子应用 cell
+  data,
+  encode: { x: 'product', y: 'region', color: 'category' },
+});
+
+// ✅ 正确：均匀二维分类用 cell
+chart.options({
+  type: 'cell',  // ✅
+  data,
+  encode: { x: 'product', y: 'region', color: 'category' },
+});
+```
+
+### 错误 3：密度马赛克图用 cell/interval 而非 rect
+
+```javascript
+// ❌ 错误：连续数据分箱应用 rect + bin transform
+chart.options({
+  type: 'cell',   // ❌ cell 适合离散数据
+  data,
+  encode: { x: 'IMDB Rating', y: 'Rotten Tomatoes Rating' },
+});
+
+// ✅ 正确：连续数据分箱用 rect
+chart.options({
+  type: 'rect',  // ✅
+  data,
+  encode: { x: 'IMDB Rating', y: 'Rotten Tomatoes Rating' },
+  transform: [{ type: 'bin', color: 'count' }],
+});
+```
+
+## 三种马赛克图对比
+
+| 类型 | 数据类型 | mark | 核心 transform |
+|------|---------|------|---------------|
+| 均匀马赛克图 | 二维离散 | `cell` | 无 |
+| 非均匀马赛克图 | 多维分类+数值 | `interval` | `flexX + stackY + normalizeY` |
+| 密度马赛克图 | 二维连续 | `rect` | `bin` |