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

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

@@ -0,0 +1,363 @@
+---
+id: "g2-comp-legend-config"
+title: "G2 图例配置（legend）"
+description: |
+  详解 G2 v5 Spec 模式中 legend 字段的配置，
+  涵盖图例位置、布局、标题、颜色图例、过滤交互及隐藏图例等用法。
+
+library: "g2"
+version: "5.x"
+category: "components"
+tags:
+  - "legend"
+  - "图例"
+  - "位置"
+  - "过滤"
+  - "颜色图例"
+  - "spec"
+
+related:
+  - "g2-core-chart-init"
+  - "g2-interaction-legend-filter"
+  - "g2-comp-axis-config"
+  - "g2-comp-legend-category"
+  - "g2-comp-legend-continuous"
+
+use_cases:
+  - "调整图例位置和布局"
+  - "自定义图例标题和样式"
+  - "隐藏不需要的图例"
+  - "配置连续颜色图例（色带）"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/component/legend"
+---
+
+## 基本用法
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  legend: {
+    color: {               // 对应 encode.color 通道的图例
+      position: 'bottom',  // 'top'(默认) | 'bottom' | 'left' | 'right'
+    },
+  },
+});
+
+chart.render();
+```
+
+---
+
+## 增量修改配置
+
+如果已有图表，只想修改某个配置项（如图例位置），可以使用以下方式：
+
+```javascript
+// 方式一：重新调用 options，只传需要修改的配置
+chart.options({
+  legend: {
+    color: {
+      position: 'right',  // 只修改位置
+    },
+  },
+});
+chart.render();  // 需要重新渲染
+
+// 方式二：完整配置后修改
+const options = {
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  legend: { color: { position: 'top' } },
+};
+chart.options(options);
+
+// 后续修改
+options.legend = { color: { position: 'bottom' } };
+chart.options(options);
+chart.render();
+```
+
+---
+
+## 完整配置项参考
+
+### 通用配置（分类图例 & 连续图例）
+
+| 属性 | 描述 | 类型 | 默认值 |
+|------|------|------|--------|
+| `position` | 图例位置 | `'top' \| 'right' \| 'left' \| 'bottom'` | `'top'` |
+| `orientation` | 图例朝向 | `'horizontal' \| 'vertical'` | `'horizontal'` |
+| `layout` | Flex 布局配置 | `{ justifyContent, alignItems, flexDirection }` | - |
+| `size` | 图例容器尺寸 | `number` | - |
+| `length` | 图例容器长度 | `number` | - |
+| `crossPadding` | 图例到图表区域的距离 | `number` | `12` |
+| `order` | 布局排序 | `number` | `1` |
+| `title` | 图例标题 | `string \| string[]` | - |
+
+### 分类图例配置
+
+| 属性 | 描述 | 类型 | 默认值 |
+|------|------|------|--------|
+| `cols` | 每行显示的图例项数量 | `number` | - |
+| `colPadding` | 图例项横向间隔 | `number` | `12` |
+| `rowPadding` | 图例项纵向间隔 | `number` | `8` |
+| `maxRows` | 图例最大行数 | `number` | `3` |
+| `maxCols` | 图例最大列数 | `number` | `3` |
+| `itemWidth` | 图例项宽度 | `number` | - |
+| `itemSpan` | 图例项图标、标签、值的空间划分 | `number \| number[]` | `[1, 1, 1]` |
+| `itemSpacing` | 图例项内部间距 | `number \| number[]` | `[8, 8, 4]` |
+| `focus` | 是否启用图例聚焦 | `boolean` | `false` |
+| `focusMarkerSize` | 图例聚焦图标大小 | `number` | `12` |
+| `defaultSelect` | 默认选中的图例项 | `string[]` | - |
+
+### 图例项图标样式（itemMarker）
+
+| 属性 | 描述 | 类型 | 默认值 |
+|------|------|------|--------|
+| `itemMarker` | 图例项图标 | `string \| (datum, index, data) => string` | - |
+| `itemMarkerSize` | 图标大小 | `number` | `8` |
+| `itemMarkerFill` | **图标填充色** | `string` | - |
+| `itemMarkerFillOpacity` | 图标填充透明度 | `number` | - |
+| `itemMarkerStroke` | 图标描边 | `string` | - |
+| `itemMarkerStrokeOpacity` | 图标描边透明度 | `number` | - |
+| `itemMarkerLineWidth` | 图标描边宽度 | `number` | - |
+| `itemMarkerRadius` | 图标圆角 | `number` | - |
+
+### 图例项标签样式（itemLabel）
+
+| 属性 | 描述 | 类型 | 默认值 |
+|------|------|------|--------|
+| `itemLabelFill` | **标签文字填充色** | `string` | `#333` |
+| `itemLabelFillOpacity` | 标签文字填充透明度 | `number` | - |
+| `itemLabelFontSize` | 标签文字大小 | `number` | `12` |
+| `itemLabelFontFamily` | 标签文字字体 | `string` | - |
+| `itemLabelFontWeight` | 标签字体粗细 | `number \| string` | - |
+| `itemLabelTextAlign` | 标签水平对齐方式 | `string` | - |
+| `itemLabelTextBaseline` | 标签垂直基线 | `string` | - |
+| `itemLabelStroke` | 标签文字描边 | `string` | - |
+| `itemLabelLineWidth` | 标签文字描边宽度 | `number` | - |
+| `itemLabelDx` | 标签水平偏移量 | `number` | - |
+| `itemLabelDy` | 标签垂直偏移量 | `number` | - |
+
+### 图例项值样式（itemValue）
+
+图例项右侧可以额外显示一个"值"列（通过 `formatter` 或数据字段），适合显示数量、百分比等辅助信息。
+
+| 属性 | 描述 | 类型 | 默认值 |
+|------|------|------|--------|
+| `itemValueFill` | 值文字填充色 | `string` | `#1D2129` |
+| `itemValueFillOpacity` | 值文字填充透明度 | `number` | `0.65` |
+| `itemValueFontSize` | 值文字大小 | `number` | `12` |
+| `itemValueFontFamily` | 值文字字体 | `string` | - |
+| `itemValueFontWeight` | 值文字字体粗细 | `number \| string` | - |
+| `itemValueStroke` | 值文字描边 | `string` | - |
+| `itemValueLineWidth` | 值文字描边宽度 | `number` | - |
+
+### 图例项背景样式（itemBackground）
+
+| 属性 | 描述 | 类型 | 默认值 |
+|------|------|------|--------|
+| `itemBackgroundFill` | 图例项背景填充色 | `string` | - |
+| `itemBackgroundFillOpacity` | 图例项背景填充透明度 | `number` | - |
+| `itemBackgroundStroke` | 图例项背景描边 | `string` | - |
+| `itemBackgroundStrokeOpacity` | 图例项背景描边透明度 | `number` | - |
+| `itemBackgroundLineWidth` | 图例项背景描边宽度 | `number` | - |
+| `itemBackgroundRadius` | 图例项背景圆角 | `number` | - |
+
+### 图例标题样式（title）
+
+| 属性 | 描述 | 类型 | 默认值 |
+|------|------|------|--------|
+| `titleFill` | **标题填充色** | `string` | `#666` |
+| `titleFillOpacity` | 标题填充透明度 | `number` | - |
+| `titleFontSize` | 标题字体大小 | `number` | `12` |
+| `titleFontFamily` | 标题字体 | `string` | - |
+| `titleFontWeight` | 标题字体粗细 | `number \| string` | - |
+| `titleStroke` | 标题描边 | `string` | - |
+| `titleLineWidth` | 标题描边宽度 | `number` | - |
+| `titleSpacing` | 标题与图例项的间距 | `number` | - |
+
+### 连续图例配置
+
+| 属性 | 描述 | 类型 | 默认值 |
+|------|------|------|--------|
+| `color` | 色带颜色 | `string[]` | - |
+| `block` | 是否按区间显示 | `boolean` | `false` |
+| `type` | 连续图例类型 | `'size' \| 'color'` | `'color'` |
+
+---
+
+## 常用配置示例
+
+### 隐藏图例
+
+```javascript
+// 隐藏特定通道的图例
+legend: { color: false }
+
+// 全部隐藏（不常用）
+legend: false
+```
+
+### 修改图例位置和布局
+
+```javascript
+chart.options({
+  legend: {
+    color: {
+      position: 'bottom',
+      layout: {
+        justifyContent: 'center',  // 水平居中
+        alignItems: 'center',      // 垂直居中
+      },
+    },
+  },
+});
+```
+
+### 修改图例项图标颜色
+
+```javascript
+chart.options({
+  legend: {
+    color: {
+      itemMarkerFill: 'red',       // 图标填充色
+      itemMarkerSize: 10,          // 图标大小
+      itemMarkerStroke: 'darkred', // 图标描边
+    },
+  },
+});
+```
+
+### 修改图例标签颜色
+
+```javascript
+chart.options({
+  legend: {
+    color: {
+      itemLabelFill: '#333',
+      itemLabelFontSize: 14,
+      itemLabelFontWeight: 'bold',
+    },
+  },
+});
+```
+
+### 修改图例标题样式
+
+```javascript
+chart.options({
+  legend: {
+    color: {
+      title: '产品类型',
+      titleFill: '#1D2129',
+      titleFontSize: 14,
+      titleFontWeight: 'bold',
+      titleSpacing: 12,
+    },
+  },
+});
+```
+
+### 饼图图例放底部居中
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  coordinate: { type: 'theta', outerRadius: 0.8 },
+  legend: {
+    color: {
+      position: 'bottom',
+      layout: { justifyContent: 'center' },
+    },
+  },
+});
+```
+
+### 连续颜色图例（色带）
+
+当 `color` 通道映射连续数值时，图例自动变为色带形式。
+
+```javascript
+chart.options({
+  type: 'cell',
+  data,
+  encode: { x: 'x', y: 'y', color: 'value' },  // value 是连续数值
+  scale: { color: { palette: 'Blues' } },
+  legend: {
+    color: {
+      position: 'right',
+      length: 200,
+      labelFormatter: (v) => Number(v).toFixed(0),  // 注意：v 可能是 string，需先转换为数字
+    },
+  },
+});
+```
+
+> **更多连续图例配置**：[连续图例详细文档](g2-comp-legend-continuous.md) 涵盖阈值图例、size 通道图例、自定义色带等高级用法。
+
+---
+
+## 常见错误与修正
+
+### 错误 1：legend 写成数组
+
+```javascript
+// ❌ 错误：legend 是对象，不是数组
+chart.options({ legend: [{ color: { position: 'bottom' } }] });
+
+// ✅ 正确
+chart.options({ legend: { color: { position: 'bottom' } } });
+```
+
+### 错误 2：legend.color 与 encode.color 不对应
+
+```javascript
+// ❌ 错误：encode 没有 color 通道，配置 legend.color 无效
+chart.options({
+  encode: { x: 'month', y: 'value' },  // 没有 color
+  legend: { color: { position: 'bottom' } },
+});
+
+// ✅ 正确：只有 encode.color 有映射时，legend.color 才有效
+chart.options({
+  encode: { x: 'month', y: 'value', color: 'type' },
+  legend: { color: { position: 'bottom' } },
+});
+```
+
+### 错误 3：样式属性名错误
+
+```javascript
+// ❌ 错误的属性名
+legend: { color: { markerFill: 'red' } }  // 不存在
+
+// ✅ 正确的属性名（带前缀）
+legend: { color: { itemMarkerFill: 'red' } }  // 正确
+```
+
+### 错误 4：混淆图例标题与图表标题
+
+```javascript
+// ❌ 图例标题写在 axis 里
+axis: { x: { title: '产品类型' } }  // 这是 X 轴标题
+
+// ✅ 图例标题在 legend 里
+legend: { color: { title: '产品类型' } }  // 这是图例标题
+```

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

@@ -0,0 +1,264 @@
+---
+id: "g2-comp-legend-continuous"
+title: "G2 连续图例（legendContinuous）"
+description: |
+  连续图例用于展示连续数值到颜色的映射关系，常见于热力图、地理可视化等场景。
+  支持色带（ribbon）和块状（block）两种形态，可配置标签格式化、范围等。
+
+library: "g2"
+version: "5.x"
+category: "components"
+tags:
+  - "legend"
+  - "连续图例"
+  - "色带"
+  - "color legend"
+  - "热力图"
+
+related:
+  - "g2-comp-legend-config"
+  - "g2-comp-legend-category"
+  - "g2-scale-sequential"
+
+use_cases:
+  - "热力图的颜色映射说明"
+  - "地理可视化的数值范围图例"
+  - "连续数值的颜色编码"
+
+anti_patterns:
+  - "分类数据应使用分类图例（legendCategory）"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/component/legend"
+---
+
+## 核心概念
+
+连续图例（Continuous Legend）展示连续数值到视觉通道（通常是颜色）的映射：
+- 当 `encode.color` 映射到连续数值字段时，图例自动变为连续图例
+- 支持线性比例尺（linear）、阈值比例尺（threshold）、分位数比例尺（quantile/quantize）
+- 默认显示为色带（ribbon）形式
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = Array.from({ length: 100 }, (_, i) => ({
+  x: i % 10,
+  y: Math.floor(i / 10),
+  value: Math.random() * 100,
+}));
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+chart.options({
+  type: 'cell',
+  data,
+  encode: { x: 'x', y: 'y', color: 'value' },  // value 是连续数值
+  scale: { color: { palette: 'Blues' } },
+  legend: {
+    color: {
+      position: 'right',
+      length: 200,
+      labelFormatter: (v) => Number(v).toFixed(0),  // 注意：v 可能是 string，需先转换
+    },
+  },
+});
+
+chart.render();
+```
+
+## 完整配置项
+
+```javascript
+chart.options({
+  type: 'cell',
+  data,
+  encode: { x: 'x', y: 'y', color: 'value' },
+  legend: {
+    color: {
+      // ── 位置 ─────────────────────────────────
+      position: 'right',       // 'top' | 'bottom' | 'left' | 'right'
+      layout: {
+        justifyContent: 'center',
+      },
+
+      // ── 尺寸 ─────────────────────────────────
+      length: 200,             // 色带长度（px）
+      size: 20,                // 色带宽度/高度（px）
+
+      // ── 标题 ─────────────────────────────────
+      title: '数值范围',
+      titleFontSize: 12,
+
+      // ── 标签 ─────────────────────────────────
+      labelFormatter: (v) => Number(v).toFixed(1),  // 注意：v 可能是 string，需先转换
+      labelAlign: 'value',     // 'value' | 'range'
+
+      // ── 样式 ─────────────────────────────────
+      style: {
+        ribbonFill: 'black',   // 默认色带填充色（无颜色映射时）
+      },
+    },
+  },
+});
+```
+
+## 常用变体
+
+### 阈值图例（分段色带）
+
+```javascript
+// 使用 threshold/quantize/quantile 比例尺时，图例自动变为分段
+chart.options({
+  type: 'cell',
+  data,
+  encode: { x: 'x', y: 'y', color: 'value' },
+  scale: {
+    color: {
+      type: 'quantize',       // 分段比例尺
+      domain: [0, 100],
+      range: ['#f7fbff', '#6baed6', '#08519c'],  // 3 段颜色
+    },
+  },
+  legend: {
+    color: {
+      position: 'right',
+    },
+  },
+});
+```
+
+### 水平色带
+
+```javascript
+chart.options({
+  type: 'cell',
+  data,
+  encode: { x: 'x', y: 'y', color: 'value' },
+  legend: {
+    color: {
+      position: 'bottom',
+      length: 400,
+      size: 15,
+      layout: { justifyContent: 'center' },
+    },
+  },
+});
+```
+
+### 自定义色带颜色
+
+```javascript
+chart.options({
+  type: 'cell',
+  data,
+  encode: { x: 'x', y: 'y', color: 'value' },
+  scale: {
+    color: {
+      type: 'linear',
+      domain: [0, 100],
+      range: ['#e6f5ff', '#0066cc'],  // 渐变范围
+    },
+  },
+  legend: {
+    color: {
+      position: 'right',
+      labelFormatter: (v) => `${Number(v)}°C`,  // 注意：v 可能是 string，需先转换
+    },
+  },
+});
+```
+
+### size 通道图例
+
+```javascript
+// size 通道也会生成连续图例
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'x', y: 'y', size: 'value' },
+  legend: {
+    size: {
+      position: 'right',
+      title: '大小',
+    },
+  },
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface LegendContinuousOptions {
+  position?: 'top' | 'bottom' | 'left' | 'right';
+  layout?: FlexLayout;
+  title?: string | string[];
+  length?: number;           // 色带长度
+  size?: number;             // 色带宽度
+  labelFormatter?: string | ((value: number) => string);
+  labelAlign?: 'value' | 'range';
+  style?: {
+    ribbonFill?: string;
+    [key: string]: any;
+  };
+}
+```
+
+## 连续图例 vs 分类图例
+
+| 特性 | 连续图例 | 分类图例 |
+|------|----------|----------|
+| 数据类型 | 连续数值 | 离散分类 |
+| 视觉形式 | 色带/块状 | 图例项列表 |
+| 比例尺 | linear, threshold, quantize | band, ordinal |
+| 适用场景 | 热力图、地图、气泡图 | 柱状图、折线图 |
+
+## 常见错误与修正
+
+### 错误 1：分类数据使用连续图例
+
+```javascript
+// ❌ 问题：category 是分类字段，不应使用连续图例
+encode: { color: 'category' }  // 分类数据
+// 连续图例显示效果不佳
+
+// ✅ 正确：分类数据自动使用分类图例
+// G2 会根据数据类型自动选择图例类型
+```
+
+### 错误 2：labelFormatter 参数类型错误
+
+```javascript
+// ❌ 问题：labelFormatter 的参数 v 可能是 string 类型（不是 number）
+// G2 连续图例传入的刻度值为字符串，直接调用 .toFixed() 会报错
+labelFormatter: (v) => v.toFixed(1)   // ❌ TypeError: v.toFixed is not a function
+labelFormatter: (v) => v * 100        // ❌ 返回数字而不是字符串
+
+// ✅ 正确：先转换为数字，再格式化，最终返回字符串
+labelFormatter: (v) => Number(v).toFixed(1)          // ✅ 保留 1 位小数
+labelFormatter: (v) => `${(Number(v) * 100).toFixed(0)}%`  // ✅ 百分比格式
+labelFormatter: (v) => `${parseFloat(v).toFixed(0)}m`      // ✅ 带单位
+```
+
+### 错误 3：length 设置过小
+
+```javascript
+// ❌ 问题：色带长度太小，标签重叠
+legend: { color: { length: 50 } }  // 太短
+
+// ✅ 正确：根据标签数量设置合适长度
+legend: { color: { length: 200 } }  // 合适
+```
+
+## 与 legendCategory 的选择
+
+- **使用连续图例**：当 color/size 通道映射到连续数值字段
+- **使用分类图例**：当 color 通道映射到分类字段
+
+G2 会根据比例尺类型自动选择正确的图例类型，无需手动指定。