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

package/builtin-skills/antv-g2-chart/references/components/g2-comp-axis-radar.md

@@ -0,0 +1,219 @@
+---
+id: "g2-comp-axis-radar"
+title: "G2 雷达图坐标轴（AxisRadar）"
+description: |
+  雷达图专用的坐标轴组件。在极坐标系中显示多个维度的轴线和刻度，
+  是雷达图的核心组件之一。
+
+library: "g2"
+version: "5.x"
+category: "components"
+tags:
+  - "坐标轴"
+  - "雷达图"
+  - "极坐标"
+  - "axis"
+
+related:
+  - "g2-coord-polar"
+  - "g2-mark-radar"
+  - "g2-comp-axis-config"
+
+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/component/axis"
+---
+
+## 核心概念
+
+AxisRadar 是雷达图专用的坐标轴组件：
+- 在极坐标系中显示放射状的轴线
+- 支持多个维度的轴标签
+- 自动计算轴的角度和位置
+
+**特点：**
+- 自动连接各轴形成网格
+- 支持自定义轴样式
+- 与极坐标系配合使用
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'line',
+  coordinate: { type: 'polar' },
+  data: [
+    { item: 'Design', score: 70 },
+    { item: 'Development', score: 60 },
+    { item: 'Marketing', score: 50 },
+    { item: 'Sales', score: 80 },
+    { item: 'Support', score: 90 },
+  ],
+  encode: {
+    x: 'item',
+    y: 'score',
+  },
+  axis: {
+    x: {
+      // 雷达图 X 轴配置
+      title: false,
+      tickLine: null,
+    },
+    y: {
+      // 雷达图 Y 轴（放射状轴）
+      title: 'Score',
+      grid: true,
+      gridConnect: 'line',  // 网格连接方式
+    },
+  },
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 自定义网格样式
+
+```javascript
+chart.options({
+  type: 'line',
+  coordinate: { type: 'polar' },
+  data,
+  encode: { x: 'item', y: 'score' },
+  axis: {
+    y: {
+      grid: true,
+      gridConnect: 'line',
+      gridLineWidth: 1,
+      gridStroke: '#e8e8e8',
+      gridType: 'line',
+    },
+  },
+});
+```
+
+### 隐藏轴线
+
+```javascript
+chart.options({
+  type: 'line',
+  coordinate: { type: 'polar' },
+  data,
+  encode: { x: 'item', y: 'score' },
+  axis: {
+    x: { line: null },
+    y: { line: null },
+  },
+});
+```
+
+### 自定义标签
+
+```javascript
+chart.options({
+  type: 'line',
+  coordinate: { type: 'polar' },
+  data,
+  encode: { x: 'item', y: 'score' },
+  axis: {
+    x: {
+      labelFormatter: (val) => val.toUpperCase(),
+      labelSpacing: 10,
+    },
+    y: {
+      labelFormatter: (val) => `${val}%`,
+    },
+  },
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface AxisRadarOptions {
+  // 基础配置
+  title?: string | { text: string; style?: object };
+  tickLine?: null | { length?: number; style?: object };
+  line?: null | { style?: object };
+
+  // 标签配置
+  labelFormatter?: string | ((val: any) => string);
+  labelSpacing?: number;
+  labelStyle?: object;
+
+  // 网格配置
+  grid?: boolean;
+  gridConnect?: 'line' | 'curve';  // 网格连接方式
+  gridLineWidth?: number;
+  gridStroke?: string;
+  gridType?: 'line' | 'circle';
+
+  // 雷达图特有
+  radar?: {
+    count: number;   // 轴的数量
+    index: number;   // 当前轴的索引
+  };
+}
+```
+
+## 与普通坐标轴的区别
+
+| 特性 | 普通坐标轴 | 雷达图坐标轴 |
+|------|-----------|-------------|
+| 坐标系 | 直角坐标 | 极坐标 |
+| 轴方向 | 水平/垂直 | 放射状 |
+| 网格 | 矩形 | 多边形/圆形 |
+| 标签位置 | 轴两端 | 轴末端外侧 |
+
+## 常见错误与修正
+
+### 错误 1：未使用极坐标系
+
+```javascript
+// ❌ 错误：雷达图轴需要极坐标系
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'item', y: 'score' },
+  axis: { y: { gridConnect: 'line' } },
+});
+
+// ✅ 正确：添加极坐标系
+chart.options({
+  type: 'line',
+  coordinate: { type: 'polar' },
+  data,
+  encode: { x: 'item', y: 'score' },
+  axis: { y: { gridConnect: 'line' } },
+});
+```
+
+### 错误 2：gridConnect 参数错误
+
+```javascript
+// ❌ 错误：gridConnect 只支持 'line' 或 'curve'
+axis: { y: { gridConnect: 'polygon' } }
+
+// ✅ 正确
+axis: { y: { gridConnect: 'line' } }
+```

package/builtin-skills/antv-g2-chart/references/components/g2-comp-label-config.md

@@ -0,0 +1,174 @@
+---
+id: "g2-comp-label-config"
+title: "G2 数据标签配置（labels）"
+description: |
+  详解 G2 v5 Spec 模式中 labels 字段的配置，涵盖标签文本、位置、格式化、
+  选择器（只显示部分标签）及样式定制。注意：Spec 模式中使用 labels（复数）。
+
+library: "g2"
+version: "5.x"
+category: "components"
+tags:
+  - "labels"
+  - "label"
+  - "数据标签"
+  - "文字标签"
+  - "position"
+  - "formatter"
+  - "spec"
+
+related:
+  - "g2-mark-interval-basic"
+  - "g2-mark-line-basic"
+  - "g2-comp-annotation"
+
+use_cases:
+  - "在柱体上方显示数值"
+  - "在折线末端显示系列名称"
+  - "在饼图扇区内外显示百分比"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/component/label"
+---
+
+## 基本用法
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'genre', y: 'sold' },
+  labels: [
+    {
+      text: 'sold',          // 显示哪个字段的值（字段名字符串或函数）
+      position: 'outside',   // 标签位置
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 常用位置说明
+
+| position 值 | 适用 Mark | 效果 |
+|-------------|-----------|------|
+| `'outside'` | interval | 柱体顶端外侧（默认） |
+| `'inside'` | interval | 柱体内部中央 |
+| `'top'` | interval | 柱体顶部（紧贴顶端） |
+| `'right'` | interval | 柱体右侧 |
+| `'outside'` | arc（饼图）| 扇区外侧引线 |
+| `'inside'` | arc（饼图）| 扇区内部 |
+| `'top'` | point | 点的上方 |
+| `'right'` | line | 折线末端右侧 |
+
+## 格式化标签文本
+
+```javascript
+labels: [
+  {
+    // 函数方式：可访问完整数据行
+    text: (d) => `${d.sold.toLocaleString()} 万`,
+
+    // 或字符串字段名（自动取该字段的值）
+    // text: 'sold',
+  },
+],
+```
+
+## 完整 label 配置项
+
+```javascript
+labels: [
+  {
+    text: (d) => d.value.toFixed(1),  // 标签文本
+    position: 'outside',               // 位置
+
+    // ── 样式 ─────────────────────────────────
+    style: {
+      fontSize: 12,
+      fill: '#333',
+      fontWeight: 'normal',
+      textAlign: 'center',
+      dy: -4,                          // y 方向偏移（px）
+      dx: 0,                           // x 方向偏移
+    },
+
+    // ── 选择器（只显示部分标签）──────────────
+    selector: 'last',                  // 'last' | 'first' | (data) => datum
+    // 过滤（只对满足条件的数据显示标签）
+    filter: (d) => d.value > 50,
+
+    // ── 连接线（饼图外部标签时常用）──────────
+    connector: true,
+    connectorStroke: '#aaa',
+    connectorLineWidth: 1,
+  },
+],
+```
+
+## 折线末端标签
+
+```javascript
+// 只在每条折线的最后一个点显示系列名称
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  labels: [
+    {
+      text: 'type',         // 显示系列名
+      selector: 'last',     // 只在最后一个数据点显示
+      position: 'right',
+      style: { fontSize: 11 },
+    },
+  ],
+});
+```
+
+## 堆叠柱中心标签
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  labels: [
+    {
+      text: (d) => d.value >= 30 ? d.value : '',  // 数值太小时不显示
+      position: 'inside',
+      style: { fill: 'white', fontSize: 11 },
+    },
+  ],
+});
+```
+
+## 常见错误与修正
+
+### 错误：Spec 模式中写成 label（单数）
+```javascript
+// ❌ 错误：链式 API 是 .label()，但 Spec 模式是 labels（复数，且是数组）
+chart.options({ label: { text: 'value' } });
+
+// ✅ 正确：Spec 中用 labels 数组
+chart.options({ labels: [{ text: 'value' }] });
+```
+
+### 错误：text 传入了数字常量
+```javascript
+// ❌ 错误：text 为数字 0，所有标签显示 '0'
+chart.options({ labels: [{ text: 0 }] });
+
+// ✅ 正确：text 应为字段名字符串或函数
+chart.options({ labels: [{ text: 'value' }] });
+chart.options({ labels: [{ text: (d) => d.value.toFixed(1) }] });
+```

package/builtin-skills/antv-g2-chart/references/components/g2-comp-legend-category.md

@@ -0,0 +1,278 @@
+---
+id: "g2-comp-legend-category"
+title: "G2 分类图例（LegendCategory）"
+description: |
+  分类图例组件，用于展示离散类别的图例项。
+  是最常用的图例类型，适用于分类数据的可视化。
+
+library: "g2"
+version: "5.x"
+category: "components"
+tags:
+  - "图例"
+  - "legend"
+  - "分类"
+  - "category"
+
+related:
+  - "g2-comp-legend-config"
+  - "g2-scale-ordinal"
+  - "g2-interaction-legend-filter"
+
+use_cases:
+  - "柱状图的分类图例"
+  - "折线图的系列图例"
+  - "散点图的分组图例"
+
+anti_patterns:
+  - "连续数据应使用连续图例（LegendContinuous）"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/component/legend"
+---
+
+## 核心概念
+
+LegendCategory 是分类图例组件：
+- 显示离散类别的图例项
+- 每项包含图标和标签
+- 支持交互（点击筛选、hover 高亮）
+
+**特点：**
+- 自动从 color/shape 通道推断
+- 支持水平和垂直布局
+- 支持自定义图标
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'interval',
+  data: [
+    { category: 'A', type: 'X', value: 100 },
+    { category: 'A', type: 'Y', value: 150 },
+    { category: 'B', type: 'X', value: 120 },
+    { category: 'B', type: 'Y', value: 180 },
+  ],
+  encode: {
+    x: 'category',
+    y: 'value',
+    color: 'type',
+  },
+  legend: {
+    color: {
+      position: 'top',
+      layout: {
+        justifyContent: 'center',
+      },
+    },
+  },
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 垂直布局
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'type' },
+  legend: {
+    color: {
+      position: 'right',
+      layout: {
+        flexDirection: 'column',
+      },
+    },
+  },
+});
+```
+
+### 自定义标签格式
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'type' },
+  legend: {
+    color: {
+      labelFormatter: (val) => `类型: ${val}`,
+    },
+  },
+});
+```
+
+### 添加标题
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'type' },
+  legend: {
+    color: {
+      title: '类型',
+      position: 'top',
+    },
+  },
+});
+```
+
+### 自定义图标
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'type' },
+  legend: {
+    color: {
+      itemMarker: 'square',  // 'circle' | 'square' | 'line' | ...
+      itemMarkerSize: 12,
+    },
+  },
+});
+```
+
+### 网格布局
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'type' },
+  legend: {
+    color: {
+      cols: 3,  // 每行显示 3 项
+      layout: { justifyContent: 'center' },
+    },
+  },
+});
+```
+
+### 禁用交互
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'type' },
+  legend: {
+    color: {
+      itemMarker: 'circle',
+    },
+  },
+  interaction: {
+    legendFilter: false,  // 禁用点击筛选
+  },
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface LegendCategoryOptions {
+  // 位置和布局
+  position?: 'top' | 'bottom' | 'left' | 'right' | 'center';
+  layout?: {
+    flexDirection?: 'row' | 'column';
+    justifyContent?: 'flex-start' | 'center' | 'flex-end';
+    flexWrap?: 'wrap' | 'nowrap';
+  };
+  cols?: number;  // 网格布局列数
+
+  // 标题
+  title?: string | string[];
+
+  // 图标
+  itemMarker?: string | ((id: any, index: number) => string);
+  itemMarkerSize?: number;
+  itemMarkerLineWidth?: number;
+  itemSpacing?: number;
+
+  // 标签
+  labelFormatter?: string | ((val: any) => string);
+  maxItemWidth?: number;
+
+  // 样式
+  style?: {
+    fill?: string;
+    fontSize?: number;
+    // 更多样式...
+  };
+
+  // 其他
+  dx?: number;
+  dy?: number;
+}
+```
+
+## 与连续图例的区别
+
+| 特性 | 分类图例 | 连续图例 |
+|------|---------|---------|
+| 数据类型 | 离散类别 | 连续数值 |
+| 显示方式 | 图标 + 标签列表 | 色带 + 刻度 |
+| 交互 | 点击筛选 | 无筛选 |
+| 适用场景 | 分类数据 | 数值映射 |
+
+## 常见错误与修正
+
+### 错误 1：position 参数错误
+
+```javascript
+// ❌ 错误：position 应该是预定义值
+legend: { color: { position: 'top-left' } }
+
+// ✅ 正确
+legend: { color: { position: 'top' } }
+```
+
+### 错误 2：未映射 color 通道
+
+```javascript
+// ❌ 错误：没有 color 通道，图例不会显示
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value' },
+  legend: { color: { position: 'top' } },
+});
+
+// ✅ 正确：添加 color 通道
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'type' },
+  legend: { color: { position: 'top' } },
+});
+```
+
+### 错误 3：itemMarker 类型错误
+
+```javascript
+// ❌ 错误：itemMarker 应该是预定义形状名或函数
+legend: { color: { itemMarker: 'triangle-up' } }
+
+// ✅ 正确：使用支持的形状
+legend: { color: { itemMarker: 'triangle' } }
+// 或
+legend: { color: { itemMarker: (id, i) => i === 0 ? 'circle' : 'square' } }
+```