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

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

@@ -0,0 +1,208 @@
+---
+id: "g2-mark-gantt"
+title: "G2 Gantt Chart Mark"
+description: |
+  甘特图 Mark。使用 interval 标记配合 transpose 坐标系，展示项目任务的时间安排。
+  适用于项目管理、任务调度、进度跟踪等场景。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "甘特图"
+  - "gantt"
+  - "项目管理"
+  - "进度"
+
+related:
+  - "g2-mark-interval-basic"
+  - "g2-comp-slider"
+
+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/gantt"
+---
+
+## 核心概念
+
+甘特图展示项目任务的时间安排：
+- 使用 `interval` 标记
+- 配合 `transpose` 坐标变换
+- `y` 和 `y1` 表示开始和结束时间
+
+**关键要素：**
+- 任务名称：映射到横轴
+- 开始时间：映射到 `y`
+- 结束时间：映射到 `y1`
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  theme: 'classic',
+});
+
+chart.options({
+  type: 'interval',
+  autoFit: true,
+  data: [
+    { name: '活动策划', startTime: 1, endTime: 4 },
+    { name: '场地规划', startTime: 3, endTime: 13 },
+    { name: '选择供应商', startTime: 5, endTime: 8 },
+  ],
+  encode: {
+    x: 'name',
+    y: 'startTime',
+    y1: 'endTime',
+    color: 'name',
+  },
+  coordinate: {
+    transform: [{ type: 'transpose' }],
+  },
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 带项目阶段
+
+```javascript
+chart.options({
+  type: 'interval',
+  data: [
+    { name: '需求分析', startTime: 1, endTime: 5, phase: '规划' },
+    { name: '系统设计', startTime: 4, endTime: 10, phase: '设计' },
+    { name: '前端开发', startTime: 8, endTime: 20, phase: '开发' },
+  ],
+  encode: {
+    x: 'name',
+    y: 'startTime',
+    y1: 'endTime',
+    color: 'phase',  // 按阶段着色
+  },
+  coordinate: { transform: [{ type: 'transpose' }] },
+});
+```
+
+### 带时序动画
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: {
+    x: 'name',
+    y: 'startTime',
+    y1: 'endTime',
+    color: 'name',
+    enterDuration: (d) => (d.endTime - d.startTime) * 200,
+    enterDelay: (d) => d.startTime * 100,
+  },
+  coordinate: { transform: [{ type: 'transpose' }] },
+});
+```
+
+### 带里程碑
+
+```javascript
+chart.options({
+  type: 'view',
+  children: [
+    {
+      type: 'interval',
+      data: tasks,
+      encode: { x: 'name', y: 'startTime', y1: 'endTime' },
+      coordinate: { transform: [{ type: 'transpose' }] },
+    },
+    {
+      type: 'point',
+      data: milestones,
+      encode: {
+        x: 'name',
+        y: 'time',
+        shape: 'diamond',
+        size: 8,
+      },
+      coordinate: { transform: [{ type: 'transpose' }] },
+    },
+  ],
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface GanttData {
+  name: string;        // 任务名称
+  startTime: number;   // 开始时间
+  endTime: number;     // 结束时间
+  phase?: string;      // 项目阶段
+}
+
+interface GanttOptions {
+  type: 'interval';
+  encode: {
+    x: string;         // 任务名称字段
+    y: string;         // 开始时间字段
+    y1: string;        // 结束时间字段
+    color?: string;    // 颜色字段
+  };
+  coordinate: {
+    transform: [{ type: 'transpose' }];
+  };
+}
+```
+
+## 甘特图 vs 柱状图
+
+| 特性 | 甘特图 | 柱状图 |
+|------|--------|--------|
+| 用途 | 任务时间安排 | 数值对比 |
+| 数据维度 | 时间区间 | 单一数值 |
+| 视觉形式 | 水平条形 | 垂直柱形 |
+
+## 常见错误与修正
+
+### 错误 1：缺少 transpose
+
+```javascript
+// ❌ 问题：默认是垂直方向
+coordinate: {}
+
+// ✅ 正确：添加 transpose
+coordinate: { transform: [{ type: 'transpose' }] }
+```
+
+### 错误 2：缺少 y1 编码
+
+```javascript
+// ❌ 问题：只有开始时间
+encode: { x: 'name', y: 'startTime' }
+
+// ✅ 正确：添加结束时间
+encode: { x: 'name', y: 'startTime', y1: 'endTime' }
+```
+
+### 错误 3：任务过多
+
+```javascript
+// ⚠️ 注意：任务数量建议不超过 20 个
+// 过多任务会导致图表拥挤
+```

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

@@ -0,0 +1,247 @@
+---
+id: "g2-mark-gauge"
+title: "G2 仪表盘（gauge）"
+description: |
+  G2 v5 内置 gauge Mark，通过 type: 'gauge' 创建仪表盘，
+  数据包含 target（当前值）和 total（最大值），
+  支持分段配色（thresholds）、中心文字和自定义样式。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "仪表盘"
+  - "gauge"
+  - "表盘"
+  - "KPI"
+  - "进度"
+  - "spec"
+
+related:
+  - "g2-core-chart-init"
+  - "g2-mark-arc-pie"
+
+use_cases:
+  - "展示 KPI 完成率/达成度"
+  - "实时监控指标（如 CPU 使用率）"
+  - "进度展示（分数、评级）"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/general/gauge"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 400,
+  height: 300,
+});
+
+chart.options({
+  type: 'gauge',
+  data: {
+    value: {
+      target: 120,   // 当前值
+      total: 400,    // 满分/最大值
+      name: '评分',  // 中心标签
+    },
+  },
+  legend: false,
+});
+
+chart.render();
+```
+
+## 分段配色仪表盘（阈值配色）
+
+```javascript
+chart.options({
+  type: 'gauge',
+  data: {
+    value: {
+      target: 159,
+      total: 280,
+      name: '速度',
+      // thresholds：按百分比分段（0-1），每段用不同颜色
+      thresholds: [100, 200, 280],   // 对应数值分段
+    },
+  },
+  scale: {
+    color: {
+      // 对应每段的颜色
+      range: ['#F4664A', '#FAAD14', '#30BF78'],
+    },
+  },
+  style: {
+    // 中心文字
+    textContent: (target, total) =>
+      `进度\n${((target / total) * 100).toFixed(0)}%`,
+  },
+  legend: false,
+});
+```
+
+## 完整配置说明
+
+```javascript
+chart.options({
+  type: 'gauge',
+  data: {
+    value: {
+      target: 75,       // 当前值（必填）
+      total: 100,       // 最大值（必填）
+      name: 'score',    // 标签名称（可选）
+      thresholds: [40, 70, 100],  // 分段阈值（可选）
+    },
+  },
+
+  // 颜色比例尺（配合 thresholds 使用）
+  scale: {
+    color: {
+      range: ['#F4664A', '#FAAD14', '#30BF78'],
+    },
+  },
+
+  // 仪表盘样式
+  style: {
+    // 弧线端点形状：'round'（圆弧端）| 'butt'（直角端）
+    arcShape: 'round',
+    arcLineWidth: 1,
+    arcStroke: '#fff',
+
+    // 中心文字：签名固定为 (target, total)，无第三个 datum 参数
+    textContent: (target, total) => `${target}/${total}`,
+    textX: '50%',
+    textY: '70%',
+    textFontSize: 24,
+    textFill: '#262626',
+
+    // 指针（false 表示隐藏）
+    pointerShape: false,
+    pinShape: false,
+  },
+
+  legend: false,
+});
+```
+
+## 自定义起止角度
+
+```javascript
+chart.options({
+  type: 'gauge',
+  data: { value: { target: 60, total: 100, name: '完成率' } },
+  // gauge 内部使用 radial 坐标，可通过 coordinate 调整角度
+  coordinate: {
+    type: 'radial',
+    innerRadius: 0.8,
+    startAngle: (-10 / 12) * Math.PI,   // 约 -150°
+    endAngle: (2 / 12) * Math.PI,        // 约 30°
+  },
+  legend: false,
+});
+```
+
+## 多指标仪表盘组合
+
+```javascript
+// 用 facetRect 或 spaceFlex 并排多个仪表盘
+chart.options({
+  type: 'spaceFlex',
+  children: [
+    {
+      type: 'gauge',
+      data: { value: { target: 75, total: 100, name: 'CPU' } },
+      legend: false,
+    },
+    {
+      type: 'gauge',
+      data: { value: { target: 60, total: 100, name: '内存' } },
+      legend: false,
+    },
+    {
+      type: 'gauge',
+      data: { value: { target: 45, total: 100, name: '磁盘' } },
+      legend: false,
+    },
+  ],
+});
+```
+
+## 常见错误与修正
+
+### 错误 0：textContent 函数签名错误——误传第三个 datum 参数
+
+`textContent` 的签名是 `(target, total) => string`，G2 内部**只传两个数值**，不存在第三个参数。
+
+```javascript
+// ❌ 错误：datum 是 undefined，访问 datum.unit 会抛出 TypeError
+style: {
+  textContent: (target, total, datum) => `${target}${datum.unit}\n${datum.name}`,
+  //                            ^^^^^ 始终是 undefined！
+}
+
+// ✅ 正确：用闭包捕获 data 中的额外字段
+const gaugeData = {
+  target: 48,
+  total: 60,
+  name: '响应时长',
+  unit: 'min',
+  thresholds: [15, 30, 45, 60],
+};
+
+chart.options({
+  type: 'gauge',
+  data: { value: gaugeData },
+  style: {
+    // 通过闭包引用外部变量
+    textContent: (target, total) => `${target}${gaugeData.unit}\n${gaugeData.name}`,
+  },
+});
+```
+
+### 错误 1：数据格式不正确
+
+```javascript
+// ❌ 错误：gauge 数据需要嵌套在 value 对象内
+chart.options({
+  type: 'gauge',
+  data: { target: 75, total: 100 },   // ❌ 顶层对象
+});
+
+// ✅ 正确：需要 { value: { target, total } } 结构
+chart.options({
+  type: 'gauge',
+  data: {
+    value: { target: 75, total: 100 },   // ✅
+  },
+});
+```
+
+### 错误 2：thresholds 与 color range 数量不匹配
+
+```javascript
+// ❌ 错误：3 个 thresholds 对应 3 段，但只给了 2 个颜色
+chart.options({
+  type: 'gauge',
+  data: { value: { target: 60, total: 100, thresholds: [40, 70, 100] } },
+  scale: {
+    color: { range: ['#F4664A', '#30BF78'] },   // ❌ 应该有 3 个颜色
+  },
+});
+
+// ✅ 正确：颜色数量 = 阈值段数（thresholds.length 段）
+chart.options({
+  scale: {
+    color: { range: ['#F4664A', '#FAAD14', '#30BF78'] },   // ✅ 3 段 3 色
+  },
+});
+```

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

@@ -0,0 +1,130 @@
+---
+id: "g2-mark-heatmap"
+title: "G2 渐变热力图（heatmap mark）"
+description: |
+  heatmap mark（区别于 cell mark 的色块热力图）使用高斯核密度渐变绘制热力分布，
+  每个点产生向外扩散的热晕效果，适合展示地理空间密度或二维密度分布。
+  通过 color 通道指定强度，size 控制热晕半径。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "heatmap"
+  - "热力图"
+  - "密度热力"
+  - "渐变热力"
+  - "高斯核"
+  - "空间密度"
+
+related:
+  - "g2-mark-cell-heatmap"
+  - "g2-mark-density"
+  - "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/heatmap/"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+// 带密度权重的二维数据
+const data = Array.from({ length: 500 }, () => ({
+  x: Math.random() * 100 + (Math.random() > 0.5 ? 20 : 60),
+  y: Math.random() * 100 + (Math.random() > 0.5 ? 20 : 70),
+  weight: Math.random(),
+}));
+
+const chart = new Chart({ container: 'container', width: 600, height: 500 });
+
+chart.options({
+  type: 'heatmap',   // 渐变热力图（不是 cell 热力图）
+  data,
+  encode: {
+    x: 'x',
+    y: 'y',
+    color: 'weight',  // 热力强度（0~1）
+    size: 30,         // 热晕半径（px），固定值或字段名
+  },
+  style: {
+    opacity: 0.8,
+  },
+  scale: {
+    color: {
+      type: 'sequential',
+      palette: ['blue', 'cyan', 'lime', 'yellow', 'red'],  // 冷色→热色
+    },
+  },
+  axis: false,
+  legend: false,
+});
+
+chart.render();
+```
+
+## 配置项
+
+```javascript
+chart.options({
+  type: 'heatmap',
+  data,
+  encode: {
+    x: 'lng',
+    y: 'lat',
+    color: 'intensity',    // 强度字段（默认 0~1）
+    size: 'radius',        // 热晕半径，可以是字段名或固定数字
+                           // 默认 40（px）
+  },
+  style: {
+    opacity: 1,            // 整体透明度
+  },
+});
+```
+
+## heatmap vs cell 热力图
+
+```javascript
+// heatmap mark：高斯渐变，连续热晕效果，适合点数据密度
+chart.options({ type: 'heatmap', ... });
+
+// cell mark：离散色块，适合矩阵数据（如时间×类别的二维表格）
+chart.options({ type: 'cell', ... });
+```
+
+## 常见错误与修正
+
+### 错误 1：color 通道值域不在 0~1——热力颜色映射异常
+```javascript
+// ❌ 如果 color 值是原始计数（如 500、1000），颜色映射可能不准确
+chart.options({
+  encode: { color: 'rawCount' },  // ⚠️  rawCount 值可能是 0~10000
+});
+
+// ✅ 归一化到 0~1，或设置 scale.color.domain
+chart.options({
+  encode: { color: 'intensity' },  // intensity 已归一化为 0~1
+  // 或配置 domain
+  scale: { color: { domain: [0, 1000] } },  // 显式指定范围
+});
+```
+
+### 错误 2：与 cell mark 混淆——cell 是矩阵格子，heatmap 是连续渐变
+```javascript
+// ❌ 用 cell 展示空间密度——格子状，缺乏连续渐变感
+chart.options({ type: 'cell', encode: { x: 'lng', y: 'lat', color: 'density' } });
+
+// ✅ 空间密度用 heatmap（连续渐变热晕效果）
+chart.options({ type: 'heatmap', encode: { x: 'lng', y: 'lat', color: 'density', size: 30 } });
+```