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

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

@@ -0,0 +1,149 @@
+---
+id: "g2-comp-title"
+title: "G2 图表标题配置（title）"
+description: |
+  G2 v5 通过顶层 title 字段为图表添加标题和副标题。
+  支持自定义标题文本、字体样式、对齐方式和与绘图区的间距。
+  title 字段可在 Chart 构造函数或 options 中配置。
+
+library: "g2"
+version: "5.x"
+category: "components"
+tags:
+  - "title"
+  - "图表标题"
+  - "subtitle"
+  - "副标题"
+  - "标题样式"
+
+related:
+  - "g2-core-chart-init"
+  - "g2-comp-axis-config"
+  - "g2-comp-legend-config"
+
+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/component/title"
+---
+
+## 基本用法
+
+```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' },
+  title: {
+    title: '月度销售额',        // 主标题
+    subtitle: '单位：万元',     // 副标题
+  },
+});
+
+chart.render();
+```
+
+## 完整配置项
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value' },
+  title: {
+    // ── 文本内容 ────────────────────────────
+    title: '月度销售趋势分析',        // 主标题文本
+    subtitle: '数据来源：2024年度报告',  // 副标题文本（可选）
+
+    // ── 对齐 ─────────────────────────────────
+    align: 'left',    // 'left'（默认）| 'center' | 'right'
+
+    // ── 间距 ─────────────────────────────────
+    spacing: 4,       // 主标题与副标题之间的间距，默认 2
+
+    // ── 主标题样式 ────────────────────────────
+    titleFontSize: 16,
+    titleFontWeight: 'bold',
+    titleFill: '#1d1d1d',
+    titleSpacing: 8,     // 标题与图表内容区域之间的间距
+
+    // ── 副标题样式 ────────────────────────────
+    subtitleFontSize: 12,
+    subtitleFill: '#8c8c8c',
+    subtitleFontWeight: 'normal',
+  },
+});
+```
+
+## 居中标题
+
+```javascript
+chart.options({
+  title: {
+    title: '季度对比报告',
+    subtitle: 'Q1-Q4 各季度销售数据',
+    align: 'center',          // 居中对齐
+    titleFontSize: 18,
+    titleFontWeight: 600,
+    subtitleFontSize: 13,
+    subtitleFill: '#999',
+  },
+});
+```
+
+## 在构造函数中配置
+
+```javascript
+// title 也可以在 Chart 构造函数的选项中配置
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+  title: {
+    title: '销售趋势',
+    align: 'center',
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：title 写成字符串而不是对象
+```javascript
+// ❌ 错误：title 字段必须是配置对象，不能直接写字符串
+chart.options({
+  title: '月度销售额',   // ❌ 不支持字符串
+});
+
+// ✅ 正确：title 字段是对象，主标题文本在 title.title 中
+chart.options({
+  title: {
+    title: '月度销售额',   // ✅ 正确写法
+  },
+});
+```
+
+### 错误：把图表标题与坐标轴标题混淆
+```javascript
+// ❌ 错误：在 axis 里写整体图表标题
+chart.options({
+  axis: { x: { title: '月度销售额' } },  // ❌ 这是 X 轴标题，不是图表标题
+});
+
+// ✅ 图表标题用顶层 title 字段
+chart.options({
+  title: { title: '月度销售额' },     // ✅ 图表标题
+  axis: { x: { title: '月份' } },     // ✅ X 轴标题
+});
+```

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

@@ -0,0 +1,358 @@
+---
+id: "g2-comp-tooltip-config"
+title: "G2 Tooltip 配置与自定义"
+description: |
+  G2 v5 tooltip 通过 tooltip 顶层配置或 interaction: [{ type: 'tooltip' }] 启用，
+  支持自定义内容（items 字段过滤、render 函数完全自定义 HTML），
+  groupKey 控制合并规则，crosshairs 显示十字准线。
+
+library: "g2"
+version: "5.x"
+category: "components"
+tags:
+  - "tooltip"
+  - "提示框"
+  - "自定义"
+  - "交互"
+  - "spec"
+
+related:
+  - "g2-interaction-tooltip"
+  - "g2-mark-line-basic"
+  - "g2-mark-interval-basic"
+
+use_cases:
+  - "自定义 tooltip 显示字段和格式"
+  - "多系列共享 tooltip（分组 tooltip）"
+  - "完全自定义 tooltip HTML 模板"
+  - "显示十字准线辅助定位"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/component/tooltip"
+---
+
+## 最小可运行示例（启用默认 tooltip）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 600,
+  height: 400,
+});
+
+const data = [
+  { month: '1月', value: 120, type: '销售额' },
+  { month: '2月', value: 180, type: '销售额' },
+  { month: '3月', value: 150, type: '销售额' },
+];
+
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  // tooltip 默认开启，此配置可自定义
+  tooltip: {
+    title: (d) => `${d.month} 数据`,   // 自定义标题
+    items: [
+      { channel: 'y', name: '销售额', valueFormatter: (v) => `¥${v}` },
+    ],
+  },
+});
+
+chart.render();
+```
+
+## 多字段 tooltip（显示多个信息项）
+
+```javascript
+const data = [
+  { date: '2024-01', revenue: 1200, cost: 800, profit: 400 },
+  { date: '2024-02', revenue: 1800, cost: 950, profit: 850 },
+  { date: '2024-03', revenue: 1500, cost: 1000, profit: 500 },
+];
+
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'revenue' },
+  tooltip: {
+    title: 'date',
+    // items 中每项对应一行显示内容
+    items: [
+      { field: 'revenue', name: '收入', valueFormatter: (v) => `¥${v}` },
+      { field: 'cost', name: '成本', valueFormatter: (v) => `¥${v}` },
+      { field: 'profit', name: '利润', valueFormatter: (v) => `¥${v}` },
+    ],
+  },
+});
+```
+
+## 完全自定义 HTML（render 函数）
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+  tooltip: {
+    render: (event, { title, items }) => {
+      // 返回 HTML 字符串，完全自定义 tooltip 内容
+      return `
+        <div style="padding: 8px 12px; background: #fff; border-radius: 4px; box-shadow: 0 2px 8px rgba(0,0,0,0.15);">
+          <div style="font-weight: bold; margin-bottom: 6px;">${title}</div>
+          ${items.map(({ name, value, color }) => `
+            <div style="display: flex; align-items: center; gap: 8px; margin-bottom: 4px;">
+              <span style="width: 8px; height: 8px; background: ${color}; border-radius: 50%; display: inline-block;"></span>
+              <span>${name}：</span>
+              <span style="font-weight: 500;">${value}</span>
+            </div>
+          `).join('')}
+        </div>
+      `;
+    },
+  },
+});
+```
+
+## 多系列共享 tooltip（groupKey）
+
+```javascript
+// 多折线图，鼠标悬停时同时显示所有系列的值
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    {
+      type: 'line',
+      encode: { x: 'month', y: 'value', color: 'type' },
+      tooltip: {
+        // groupKey：按哪个字段合并多系列的 tooltip
+        // 默认按 x 值合并，所有系列在同一 x 处的点显示在一个 tooltip 中
+        title: 'month',
+      },
+    },
+  ],
+  interaction: [{ type: 'tooltip', shared: true }],   // shared: true 显示共享 tooltip
+});
+```
+
+## 完整配置项
+
+```javascript
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'month', y: 'value' },
+
+  tooltip: {
+    // 标题
+    title: 'month',               // 字段名 或 函数 (d) => string
+
+    // 显示项
+    items: [
+      {
+        field: 'value',           // 数据字段名
+        channel: 'y',             // 或者用通道名（'x' | 'y' | 'color' 等）
+        name: '销售额',           // 显示名称（覆盖默认）
+        color: '#1890ff',         // 色块颜色
+        // valueFormatter 接受：
+        //   函数 (value) => string   ← 需要拼接单位时必须用这种形式
+        //   d3-format 字符串 '.2f'   ← 只格式化数字本身，不支持追加文字
+        valueFormatter: (v) => `${v} 万元`,   // ✅ 函数形式，可拼接单位
+        // valueFormatter: '.2f',             // ✅ d3-format，仅格式化数字
+        // valueFormatter: '.0f 米',          // ❌ 错误！d3-format 后不能追加文字
+      },
+    ],
+
+    // 渲染
+    render: (event, { title, items }) => `<div>...</div>`,  // 完全自定义 HTML
+
+    // 触发方式
+    // 在 interaction 中配置
+  },
+
+  // tooltip 交互（可补充配置）
+  interaction: [
+    {
+      type: 'tooltip',
+      shared: true,       // 多 Mark 共享 tooltip
+      crosshairs: true,   // 显示十字准线
+    },
+  ],
+});
+```
+
+## 十字准线（crosshairs）
+
+十字准线通过 `interaction` 中的 `tooltip` 交互项配置：
+
+```javascript
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'month', y: 'value' },
+  interaction: [
+    {
+      type: 'tooltip',
+      crosshairs: true,           // 显示十字准线（默认开启）
+      crosshairsStroke: '#aaa',   // 准线颜色
+      crosshairsLineWidth: 1,     // 准线宽度
+      crosshairsLineDash: [4, 4], // 虚线样式
+    },
+  ],
+});
+```
+
+## 通过 CSS 自定义 tooltip 样式
+
+当 `render` 函数的定制化程度不够时，可以通过 CSS 直接覆盖默认样式：
+
+```javascript
+// 方式 1：在页面全局 CSS 中覆盖
+// .g2-tooltip { background: #1a1a1a; color: #fff; border-radius: 8px; }
+// .g2-tooltip-title { font-size: 14px; font-weight: bold; }
+// .g2-tooltip-list-item-value { color: #fadb14; }
+
+// 方式 2：通过 interaction 的 css 参数（局部覆盖）
+chart.options({
+  interaction: [
+    {
+      type: 'tooltip',
+      css: {
+        '.g2-tooltip': {
+          background: '#1a1a1a',
+          color: '#fff',
+          borderRadius: '8px',
+          padding: '8px 12px',
+        },
+        '.g2-tooltip-title': {
+          fontSize: '14px',
+          fontWeight: 'bold',
+          marginBottom: '6px',
+        },
+        '.g2-tooltip-list-item-value': {
+          color: '#fadb14',
+        },
+      },
+    },
+  ],
+});
+```
+
+**内置 CSS 类名：**
+- `.g2-tooltip` — tooltip 容器
+- `.g2-tooltip-title` — 标题
+- `.g2-tooltip-list-item` — 单条数据项
+- `.g2-tooltip-list-item-name-label` — 数据项名称
+- `.g2-tooltip-list-item-value` — 数据项值
+- `.g2-tooltip-list-item-marker` — 数据项颜色标记点
+
+---
+
+## 常见错误与修正
+
+### 错误 1：tooltip.items 字段名与数据不匹配
+
+```javascript
+// ❌ 错误：数据字段是 'revenue' 但 items 写的是 'value'
+const data = [{ month: '1月', revenue: 1200 }];
+chart.options({
+  tooltip: {
+    items: [{ field: 'value' }],   // ❌ 数据中没有 'value' 字段
+  },
+});
+
+// ✅ 正确：field 与数据字段名对应
+chart.options({
+  tooltip: {
+    items: [{ field: 'revenue', name: '收入' }],   // ✅
+  },
+});
+```
+
+### 错误 2：render 函数忘记返回字符串
+
+```javascript
+// ❌ 错误：render 函数没有 return 语句
+chart.options({
+  tooltip: {
+    render: (event, { title, items }) => {
+      const html = `<div>${title}</div>`;
+      // 忘记 return！
+    },
+  },
+});
+
+// ✅ 正确：必须返回 HTML 字符串
+chart.options({
+  tooltip: {
+    render: (event, { title, items }) => {
+      return `<div>${title}</div>`;   // ✅
+    },
+  },
+});
+```
+
+### 错误 3：valueFormatter 用 d3-format 字符串拼接单位
+
+`valueFormatter` 支持两种形式：函数 `(v) => string` 或 d3-format 字符串（如 `'.2f'`）。**d3-format 字符串只格式化数字本身，不能在后面追加文字单位**——带空格的写法如 `'.0f 米'` 会被当作无效格式符，导致显示异常或直接报错。
+
+```javascript
+// ❌ 错误：d3-format 字符串后追加文字单位
+chart.options({
+  tooltip: {
+    items: [
+      { field: 'distance', name: '距离', valueFormatter: '.0f 米' },  // ❌ 无效格式，d3-format 不支持拼接文字
+      { field: 'price',    name: '价格', valueFormatter: '.2f 元' },  // ❌ 同上
+    ],
+  },
+});
+
+// ✅ 正确：需要拼接单位时必须用函数形式
+chart.options({
+  tooltip: {
+    items: [
+      { field: 'distance', name: '距离', valueFormatter: (v) => `${Math.round(v)} 米` },  // ✅ 函数形式
+      { field: 'price',    name: '价格', valueFormatter: (v) => `¥${v.toFixed(2)}` },     // ✅ 函数形式
+    ],
+  },
+});
+
+// ✅ 仅格式化数字（不需要单位）时可用 d3-format 字符串
+chart.options({
+  tooltip: {
+    items: [
+      { field: 'ratio', name: '占比', valueFormatter: '.1%' },  // ✅ 纯 d3-format，无文字
+      { field: 'value', name: '数值', valueFormatter: ',.0f' }, // ✅ 千分位整数
+    ],
+  },
+});
+```
+
+### 错误 4：多系列 tooltip 未配置 shared
+
+```javascript
+// ❌ 问题：多折线图 tooltip 只显示当前 hover 的那条线
+chart.options({
+  type: 'view',
+  children: [
+    { type: 'line', encode: { x: 'month', y: 'value', color: 'type' } },
+  ],
+  // 没有 shared: true，tooltip 只显示鼠标直接悬停的那条线
+});
+
+// ✅ 正确：设置 shared: true 显示所有系列
+chart.options({
+  type: 'view',
+  children: [
+    { type: 'line', encode: { x: 'month', y: 'value', color: 'type' } },
+  ],
+  interaction: [{ type: 'tooltip', shared: true }],   // ✅
+});
+```

package/builtin-skills/antv-g2-chart/references/compositions/g2-comp-facet-circle.md

@@ -0,0 +1,97 @@
+---
+id: "g2-comp-facet-circle"
+title: "G2 圆形分面（facetCircle）"
+description: |
+  facetCircle 将数据按某个字段分成多个子集，每个子集的图表排列在圆形轨迹上。
+  与 facetRect 的矩形网格不同，facetCircle 适合展示循环性数据（如 12 个月的环形排列）。
+  每个子图共享相同的 y 轴范围，便于对比。
+
+library: "g2"
+version: "5.x"
+category: "compositions"
+tags:
+  - "facetCircle"
+  - "圆形分面"
+  - "facet"
+  - "分面"
+  - "循环"
+  - "小多图"
+
+related:
+  - "g2-comp-facet-rect"
+  - "g2-comp-repeat-matrix"
+
+use_cases:
+  - "12 个月的环形小多图对比"
+  - "周期性时间数据的圆形分面（7天 / 12月）"
+  - "循环分类的图表排列"
+
+difficulty: "advanced"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/composition/facet-circle"
+---
+
+## 最小可运行示例（12 个月圆形分面）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+// 每个月的每日数据
+const data = [];
+const months = ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'];
+months.forEach((month, mi) => {
+  for (let day = 1; day <= 10; day++) {
+    data.push({ month, day, value: Math.random() * 100 });
+  }
+});
+
+const chart = new Chart({ container: 'container', width: 640, height: 640 });
+
+chart.options({
+  type: 'facetCircle',
+  data,
+  encode: { position: 'month' },  // 按月份分面（决定每个子图的位置）
+  children: [
+    {
+      type: 'interval',
+      encode: { x: 'day', y: 'value', color: 'value' },
+      scale: { color: { type: 'sequential', palette: 'blues' } },
+      style: { lineWidth: 0 },
+      coordinate: { type: 'polar' },  // 每个子图用极坐标
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 常见错误与修正
+
+### 错误：children 中没有用 coordinate: polar——子图是矩形而非环形
+```javascript
+// ❌ facetCircle 虽然分面排列是圆形，但子图本身仍可以是直角坐标
+// 通常需要在 children 中指定 polar 坐标系才有圆形效果
+chart.options({
+  type: 'facetCircle',
+  encode: { position: 'month' },
+  children: [
+    {
+      type: 'interval',
+      encode: { x: 'day', y: 'value' },
+      // ❌ 没有 coordinate: polar，子图是普通柱状图，排列在圆圈上但不是极坐标
+    },
+  ],
+});
+
+// ✅ 通常在子图中加上 polar 坐标
+children: [
+  {
+    type: 'interval',
+    encode: { x: 'day', y: 'value' },
+    coordinate: { type: 'polar' },  // ✅
+  },
+]
+```