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

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

@@ -0,0 +1,226 @@
+---
+id: "g2-mark-radial-bar"
+title: "G2 Radial Bar Chart Mark"
+description: |
+  玉珏图/径向柱状图 Mark。使用 interval 标记配合 radial 坐标系，以环形方式展示分类数据对比。
+  适用于审美需求较高的数据展示场景。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "玉珏图"
+  - "径向柱状图"
+  - "radial bar"
+  - "环形柱状图"
+
+related:
+  - "g2-mark-interval-basic"
+  - "g2-mark-rose"
+
+use_cases:
+  - "分类数据对比"
+  - "美观展示"
+  - "大屏可视化"
+
+anti_patterns:
+  - "精确数值对比应使用柱状图"
+  - "数据必须排序"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/mark/radial-bar"
+---
+
+## 核心概念
+
+玉珏图（径向柱状图）是柱状图在极坐标系下的变换：
+- 使用 `interval` 标记
+- 配合 `radial` 坐标系
+- 以弧长表示数值大小
+
+**注意事项：**
+- 存在半径反馈效应，外圈看起来更大
+- 数据必须排序
+- 更适合审美展示而非精确对比
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  theme: 'classic',
+});
+
+chart.options({
+  type: 'interval',
+  data: [
+    { question: '台海关系', percent: 0.21 },
+    { question: '军事力量', percent: 0.47 },
+    { question: '环境影响', percent: 0.49 },
+  ],
+  coordinate: { type: 'radial', innerRadius: 0.2 },
+  encode: {
+    x: 'question',
+    y: 'percent',
+    color: 'question',
+  },
+  style: {
+    radiusTopLeft: 4,
+    radiusTopRight: 4,
+  },
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 指定角度范围
+
+```javascript
+chart.options({
+  type: 'interval',
+  coordinate: {
+    type: 'radial',
+    innerRadius: 0.3,
+    startAngle: -Math.PI,
+    endAngle: -0.25 * Math.PI,
+  },
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+});
+```
+
+### 带标签
+
+```javascript
+chart.options({
+  type: 'interval',
+  coordinate: { type: 'radial', innerRadius: 0.2 },
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+  labels: [
+    {
+      text: 'value',
+      position: 'inside',
+      style: { fontWeight: 'bold', fill: 'white' },
+    },
+  ],
+});
+```
+
+### 配合交互
+
+```javascript
+chart.options({
+  type: 'interval',
+  coordinate: { type: 'radial', innerRadius: 0.2 },
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+  interaction: [
+    { type: 'elementHighlight', background: true },
+  ],
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface RadialBarOptions {
+  type: 'interval';
+  coordinate: {
+    type: 'radial';
+    innerRadius?: number;    // 内半径
+    startAngle?: number;     // 起始角度
+    endAngle?: number;       // 结束角度
+  };
+  encode: {
+    x: string;    // 分类字段（映射到角度）
+    y: string;    // 数值字段（映射到半径）
+    color?: string;
+  };
+}
+```
+
+## 玉珏图 vs 柱状图
+
+| 特性 | 玉珏图 | 柱状图 |
+|------|--------|--------|
+| 坐标系 | 极坐标 | 直角坐标 |
+| 视觉效果 | 更美观 | 更精确 |
+| 数据对比 | 有半径效应 | 准确对比 |
+
+## 常见错误与修正
+
+### 错误 1：数据未排序
+
+```javascript
+// ❌ 问题：未排序会导致视觉误导
+data: [{ category: 'A', value: 100 }, { category: 'B', value: 50 }]
+
+// ✅ 正确：数据按值排序
+data: [{ category: 'B', value: 50 }, { category: 'A', value: 100 }]
+```
+
+### 错误 2：使用 polar 坐标系
+
+```javascript
+// ❌ 问题：polar 是玫瑰图坐标系
+coordinate: { type: 'polar' }
+
+// ✅ 正确：使用 radial 坐标系
+coordinate: { type: 'radial' }
+```
+
+### 错误 3：分类过多
+
+```javascript
+// ⚠️ 注意：分类数量建议不超过 15 个
+// 过多分类会导致环形过窄
+```
+
+### 错误 4：encode 通道映射错误
+
+```javascript
+// ❌ 问题：x 映射数值字段，y 映射分类字段，这在 radial 坐标系中是错误的
+encode: {
+  x: 'value',       // x 应该映射分类字段
+  y: 'category',    // y 应该映射数值字段
+}
+
+// ✅ 正确：x 映射分类字段，y 映射数值字段
+encode: {
+  x: 'category',    // x 映射分类字段（对应角度）
+  y: 'value',       // y 映射数值字段（对应半径）
+}
+```
+
+### 错误 5：transform 排序方式错误
+
+```javascript
+// ❌ 问题：使用了 transform 排序但方向错误
+transform: [
+  {
+    type: 'sortX',
+    by: 'value',
+    reverse: false,   // 应该为 true 才能实现由内向外递增
+  },
+],
+
+// ✅ 正确：使用正确的排序方向
+transform: [
+  {
+    type: 'sortX',
+    by: 'value',
+    reverse: true,   // 由内向外递增
+  },
+],
+// 或者更推荐的方式是在数据层面预先排序
+data: rawData.sort((a, b) => b.value - a.value)
+```

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

@@ -0,0 +1,253 @@
+---
+id: "g2-mark-range-rangey"
+title: "G2 range / rangeX / rangeY 区域标注"
+description: |
+  range、rangeX、rangeY 是 G2 v5 中用于绘制矩形区域标注的 Mark。
+  rangeX 在 X 轴方向标注区间（纵向矩形带），常用于高亮时间段；
+  rangeY 在 Y 轴方向标注区间（横向矩形带），常用于高亮数值范围；
+  range 同时在 X 和 Y 两个方向标注矩形区域。
+  常与其他 Mark 叠加使用，作为背景区域标注。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "range"
+  - "rangeX"
+  - "rangeY"
+  - "区域标注"
+  - "高亮区间"
+  - "背景带"
+  - "annotation"
+
+related:
+  - "g2-mark-linex-liney"
+  - "g2-mark-connector"
+  - "g2-comp-annotation"
+
+use_cases:
+  - "折线图上高亮特定时间段（如促销期）"
+  - "标注正常范围的上下限区间"
+  - "对比图中高亮某个参考区域"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/extra-topics/annotation#rangex"
+---
+
+## 三种 range Mark 对比
+
+| Mark | 数据格式 | encode | 用途 |
+|------|---------|--------|------|
+| `rangeX` | `[{ start: v1, end: v2 }]` | `x: 'start', x1: 'end'` | X 轴区间（纵向带）**常用** |
+| `rangeY` | `[{ min: v1, max: v2 }]` | `y: 'min', y1: 'max'` | Y 轴区间（横向带）**常用** |
+| `range` | `[{ x: [v1,v2], y: [v1,v2] }]` | `x: 'x', y: 'y'` | 二维矩形，x/y 字段为数组 **极少用** |
+
+> **选择原则**：只需高亮 X 方向时间段 → `rangeX`；只需高亮 Y 方向数值区间 → `rangeY`；需要同时限定 X 和 Y 的矩形区域 → `range`
+
+## RangeX 高亮时间段
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 800, height: 400 });
+
+chart.options({
+  type: 'view',
+  data: timeSeriesData,
+  encode: { x: 'date', y: 'value' },
+  children: [
+    // 主折线图
+    { type: 'line' },
+    // X 轴区间标注（高亮促销期）
+    {
+      type: 'rangeX',
+      data: [
+        { start: '2024-11-01', end: '2024-11-30', label: '双十一' },
+      ],
+      encode: {
+        x: 'start',    // 区间开始
+        x1: 'end',     // 区间结束
+      },
+      style: {
+        fill: '#ff4d4f',
+        fillOpacity: 0.1,
+      },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## RangeY 标注数值区间
+
+```javascript
+chart.options({
+  type: 'view',
+  data,
+  encode: { x: 'date', y: 'value' },
+  children: [
+    { type: 'line' },
+    // Y 轴区间标注（正常范围）
+    {
+      type: 'rangeY',
+      data: [{ min: 60, max: 100, label: '正常范围' }],
+      encode: {
+        y: 'min',    // 区间下限
+        y1: 'max',   // 区间上限
+      },
+      style: {
+        fill: '#52c41a',
+        fillOpacity: 0.08,
+        stroke: '#52c41a',
+        strokeOpacity: 0.3,
+        lineWidth: 1,
+        lineDash: [4, 4],
+      },
+    },
+  ],
+});
+```
+
+## Range 二维矩形区域
+
+> ⚠️ **`range` 的数据格式与 `rangeX`/`rangeY` 完全不同**：`x` 和 `y` 字段本身是 `[start, end]` 数组，encode 只需 `x` 和 `y`，**不需要** `x1`/`y1`。
+
+```javascript
+// 散点图四象限背景色（同时限定 X 和 Y 方向）
+chart.options({
+  type: 'view',
+  children: [
+    {
+      type: 'point',
+      data: scatterData,
+      encode: { x: 'changeX', y: 'changeY' },
+    },
+    {
+      type: 'range',
+      // ✅ x 和 y 字段的值是 [start, end] 数组
+      data: [
+        { x: [-25, 0], y: [-30, 0], region: 'Q3' },
+        { x: [-25, 0], y: [0, 20],  region: 'Q2' },
+        { x: [0, 5],   y: [-30, 0], region: 'Q4' },
+        { x: [0, 5],   y: [0, 20],  region: 'Q1' },
+      ],
+      encode: { x: 'x', y: 'y', color: 'region' },  // ✅ encode 只需 x 和 y
+      style: { fillOpacity: 0.15 },
+    },
+  ],
+});
+```
+
+## 与 lineX/lineY 搭配标注阈值
+
+```javascript
+// rangeY 标注背景区域 + lineY 标注具体阈值线
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    { type: 'line', encode: { x: 'date', y: 'value' } },
+    // 危险区域背景
+    {
+      type: 'rangeY',
+      data: [{ min: 80, max: 100 }],
+      encode: { y: 'min', y1: 'max' },
+      style: { fill: '#ff4d4f', fillOpacity: 0.08 },
+    },
+    // 阈值线
+    {
+      type: 'lineY',
+      data: [{ y: 80 }],
+      encode: { y: 'y' },
+      style: { stroke: '#ff4d4f', lineWidth: 1, lineDash: [4, 4] },
+    },
+  ],
+});
+```
+
+## 常见错误与修正
+
+### ❌ 错误：使用不存在的 regionX / regionY 类型
+```javascript
+// ❌ 错误：regionX、regionY 是其他库的概念，G2 中不存在
+chart.options({ type: 'regionX', ... });
+chart.options({ type: 'regionY', ... });
+
+// ✅ 正确：G2 中用 rangeX / rangeY
+chart.options({ type: 'rangeX', encode: { x: 'start', x1: 'end' } });
+chart.options({ type: 'rangeY', encode: { y: 'start', y1: 'end' } });
+```
+
+### ❌ 错误：range 使用 x1/y1 字段（混淆了 rangeX/rangeY 的写法）
+
+```javascript
+// ❌ 错误：range 不用 x1/y1，x 和 y 字段本身就是 [start, end] 数组
+chart.options({
+  type: 'range',
+  data: [{ x0: 20, x1: 40, y0: 50, y1: 80 }],
+  encode: { x: 'x0', x1: 'x1', y: 'y0', y1: 'y1' },  // ❌
+});
+
+// ✅ 正确：x/y 字段值是数组
+chart.options({
+  type: 'range',
+  data: [{ x: [20, 40], y: [50, 80] }],
+  encode: { x: 'x', y: 'y' },  // ✅
+});
+
+// 💡 大多数情况下，应使用 rangeX 或 rangeY，而非 range：
+// - 只需高亮 X 方向 → rangeX（encode: { x: 'start', x1: 'end' }）
+// - 只需高亮 Y 方向 → rangeY（encode: { y: 'min', y1: 'max' }）
+```
+
+### ❌ 错误：省略 encode（最常见，导致区域不渲染）
+
+`rangeY` / `rangeX` 必须显式写 `encode`，G2 无法从字段名自动推断区间起止。
+
+```javascript
+// ❌ 错误：缺少 encode，区域不会渲染
+{
+  type: 'rangeY',
+  data: [{ y: 54, y1: 72 }],
+  style: { fill: '#FF0000', fillOpacity: 0.1 },
+  // ❌ 没有 encode！
+}
+
+// ✅ 正确：必须写 encode 显式映射字段名
+{
+  type: 'rangeY',
+  data: [{ y: 54, y1: 72 }],
+  encode: { y: 'y', y1: 'y1' },         // ✅ 告诉 G2 哪个字段是起止
+  style: { fill: '#FF0000', fillOpacity: 0.1 },
+}
+
+// ✅ 字段名可以随意，关键是 encode 里要映射
+{
+  type: 'rangeY',
+  data: [{ lower: 54, upper: 72 }],
+  encode: { y: 'lower', y1: 'upper' },   // ✅ 字段名与 data 对应即可
+  style: { fill: '#FF0000', fillOpacity: 0.1 },
+}
+```
+
+### ❌ 错误：rangeX 只写了 x 没有 x1
+```javascript
+// ❌ 错误：rangeX 需要 x（开始）和 x1（结束）两个 encode 字段
+chart.options({
+  type: 'rangeX',
+  data: [{ start: 10, end: 20 }],
+  encode: { x: 'start' },   // ❌ 缺少 x1
+});
+
+// ✅ 正确
+chart.options({
+  type: 'rangeX',
+  data: [{ start: 10, end: 20 }],
+  encode: { x: 'start', x1: 'end' },  // ✅ x 和 x1 都要
+});
+```