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

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

@@ -0,0 +1,177 @@
+---
+id: "g2-mark-point-scatter"
+title: "G2 散点图（Point Mark）"
+description: |
+  使用 Point Mark 创建散点图，通过 x/y 位置展示两个数值变量的相关性。
+  本文采用 Spec 模式（chart.options({})），支持气泡图（size 通道）、分类着色、自定义形状等变体。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+subcategory: "point"
+tags:
+  - "散点图"
+  - "气泡图"
+  - "Point"
+  - "scatter"
+  - "bubble"
+  - "相关性"
+  - "分布"
+  - "spec"
+
+related:
+  - "g2-core-encode-channel"
+  - "g2-scale-linear"
+  - "g2-interaction-tooltip"
+
+use_cases:
+  - "展示两个连续变量的相关性"
+  - "发现数据分布和异常值"
+  - "用气泡图展示三维数据（x/y/size）"
+
+anti_patterns:
+  - "数据点超过 10000 个时性能较差，考虑使用密度图"
+  - "两轴都是分类变量时，散点图意义不大"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/point/scatter"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'point',
+  data: [
+    { x: 10, y: 30, category: 'A' },
+    { x: 20, y: 50, category: 'B' },
+    { x: 30, y: 20, category: 'A' },
+    { x: 40, y: 80, category: 'B' },
+    { x: 50, y: 40, category: 'A' },
+    { x: 60, y: 65, category: 'B' },
+  ],
+  encode: {
+    x: 'x',
+    y: 'y',
+    color: 'category',
+  },
+});
+
+chart.render();
+```
+
+## 气泡图（三维数据）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 700, height: 500 });
+
+chart.options({
+  type: 'point',
+  data: [
+    { income: 30000, lifeExpect: 72, population: 1400, country: 'China'  },
+    { income: 60000, lifeExpect: 79, population: 330,  country: 'USA'    },
+    { income: 45000, lifeExpect: 84, population: 125,  country: 'Japan'  },
+    { income: 20000, lifeExpect: 68, population: 1380, country: 'India'  },
+    { income: 35000, lifeExpect: 80, population: 210,  country: 'Brazil' },
+  ],
+  encode: {
+    x: 'income',
+    y: 'lifeExpect',
+    size: 'population',    // 气泡大小 = 第三个维度
+    color: 'country',
+  },
+  scale: {
+    size: { range: [10, 60] },    // 控制气泡大小范围
+  },
+  tooltip: {
+    title: 'country',
+    items: [
+      { field: 'income',     name: '人均收入' },
+      { field: 'lifeExpect', name: '预期寿命' },
+      { field: 'population', name: '人口（百万）' },
+    ],
+  },
+});
+
+chart.render();
+```
+
+## 自定义点形状
+
+```javascript
+chart.options({
+  type: 'point',
+  data: [...],
+  encode: {
+    x: 'x',
+    y: 'y',
+    color: 'type',
+    shape: 'type',    // 将 type 字段映射到形状通道
+  },
+  scale: {
+    shape: {
+      range: ['circle', 'square', 'triangle', 'diamond'],
+    },
+  },
+});
+```
+
+## 散点图 + 趋势线
+
+```javascript
+// 用 type: 'view' + children 叠加散点和回归趋势线
+chart.options({
+  type: 'view',
+  data: [...],
+  children: [
+    {
+      type: 'point',
+      encode: { x: 'x', y: 'y' },
+    },
+    {
+      type: 'line',
+      encode: { x: 'x', y: 'y' },
+      transform: [{ type: 'regression' }],
+      style: { stroke: '#f00', lineWidth: 1.5 },
+    },
+  ],
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：大数据量性能问题
+```javascript
+// ❌ 注意：十万个点会导致渲染缓慢
+chart.options({ type: 'point', data: hugeDataWith100000Points, encode: { x: 'x', y: 'y' } });
+
+// ✅ 优化方案 1：先在数据层面采样
+chart.options({ type: 'point',  sampledData, encode: { x: 'x', y: 'y' } });
+
+// ✅ 优化方案 2：改用密度图展示分布
+chart.options({ type: 'density',  [...], encode: { x: 'x', y: 'y' } });
+```
+
+### 错误 2：size 通道使用字符串常量
+```javascript
+// ❌ 误解：size 传字符串会被当作字段名
+chart.options({ type: 'point', encode: { size: '10' } });  // 寻找名为 '10' 的字段
+
+// ✅ 正确：固定大小用数字，数据映射用字段名字符串
+chart.options({ type: 'point', encode: { size: 10 } });           // 固定大小 10
+chart.options({ type: 'point', encode: { size: 'population' } }); // 映射字段
+```

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

@@ -0,0 +1,130 @@
+---
+id: "g2-mark-polygon"
+title: "G2 多边形图（polygon）"
+description: |
+  polygon mark 根据多个 x/y 通道坐标绘制任意多边形，
+  每条记录对应一个多边形，坐标点通过 x、x1、x2...和 y、y1、y2...通道传入。
+  常用于地图区域着色、Voronoi 图等自定义形状场景。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "polygon"
+  - "多边形"
+  - "Voronoi"
+  - "地图"
+  - "自定义形状"
+
+related:
+  - "g2-mark-image"
+  - "g2-mark-path"
+
+use_cases:
+  - "Voronoi 图（自然邻域分区）"
+  - "自定义形状的区域着色"
+  - "地理区域多边形着色（非标准地图）"
+
+difficulty: "advanced"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/general/other/#polygon"
+---
+
+## 最小可运行示例（Voronoi 图）
+
+```javascript
+import { Chart } from '@antv/g2';
+import { Delaunay } from 'd3-delaunay';
+
+// 随机生成点，计算 Voronoi 分区
+const points = Array.from({ length: 30 }, () => [
+  Math.random() * 600,
+  Math.random() * 400,
+]);
+
+const delaunay = Delaunay.from(points);
+const voronoi = delaunay.voronoi([0, 0, 600, 400]);
+
+// 将 Voronoi 多边形转换为 G2 数据格式
+const polygonData = Array.from({ length: points.length }, (_, i) => {
+  const cell = voronoi.cellPolygon(i);
+  if (!cell) return null;
+  return {
+    x: cell.map(([px]) => px),
+    y: cell.map(([, py]) => py),
+    index: i,
+  };
+}).filter(Boolean);
+
+const chart = new Chart({ container: 'container', width: 600, height: 400 });
+
+chart.options({
+  type: 'polygon',
+  data: polygonData,
+  encode: {
+    x: 'x',    // 多边形各顶点的 x 坐标数组
+    y: 'y',    // 多边形各顶点的 y 坐标数组
+    color: 'index',
+  },
+  scale: {
+    x: { domain: [0, 600] },   // 指定坐标范围（type 默认为 linear）
+    y: { domain: [0, 400] },
+    color: { type: 'ordinal' },
+  },
+  style: {
+    fillOpacity: 0.6,
+    stroke: '#fff',
+    lineWidth: 1,
+  },
+  axis: false,
+  legend: false,
+});
+
+chart.render();
+```
+
+## 数据格式说明
+
+```javascript
+// polygon mark 的数据格式：每条记录的 x/y 字段是数组（多边形顶点序列）
+const data = [
+  {
+    x: [10, 50, 90, 10],   // 多边形顶点 x 坐标（按顺序，首尾自动闭合）
+    y: [10, 80, 10, 10],   // 多边形顶点 y 坐标
+    category: 'A',
+  },
+  {
+    x: [100, 150, 200],    // 三角形
+    y: [20, 100, 20],
+    category: 'B',
+  },
+];
+
+chart.options({
+  type: 'polygon',
+  data,
+  encode: { x: 'x', y: 'y', color: 'category' },
+});
+```
+
+## 常见错误与修正
+
+### 错误：x/y 传入单个数值而不是数组
+```javascript
+// ❌ 错误：polygon 的 x/y 必须是坐标数组，不是单个值
+chart.options({
+  type: 'polygon',
+  data: [{ x: 100, y: 200, ... }],  // ❌ x/y 是单值，只是一个点
+  encode: { x: 'x', y: 'y' },
+});
+
+// ✅ 正确：x/y 是坐标数组
+chart.options({
+  type: 'polygon',
+  data: [{ x: [10, 50, 90], y: [10, 80, 10], ... }],  // ✅ 数组
+  encode: { x: 'x', y: 'y' },
+});
+```

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

@@ -0,0 +1,231 @@
+---
+id: "g2-mark-radar"
+title: "G2 雷达图（polar 坐标 + area/line）"
+description: |
+  G2 v5 雷达图通过 coordinate: { type: 'polar' } + area + line Mark 组合实现，
+  数据采用长表格式，encode.x 映射维度字段，encode.y 映射数值字段，
+  encode.color 区分多个系列。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "雷达图"
+  - "radar"
+  - "polar"
+  - "极坐标"
+  - "蜘蛛网图"
+  - "多维度"
+  - "spec"
+
+related:
+  - "g2-core-view-composition"
+  - "g2-mark-area-basic"
+  - "g2-mark-line-basic"
+
+use_cases:
+  - "多维度能力/指标对比（如 KPI 雷达图）"
+  - "多个对象的综合评分对比"
+  - "运动员/产品多维评测"
+
+anti_patterns:
+  - "维度超过 8 个时，标签会重叠，改用平行坐标图"
+  - "各维度量纲差异过大时，需先归一化"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/general/radar"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 480,
+  height: 480,
+});
+
+const data = [
+  { item: '设计', type: '产品A', score: 70 },
+  { item: '开发', type: '产品A', score: 60 },
+  { item: '营销', type: '产品A', score: 50 },
+  { item: '运营', type: '产品A', score: 80 },
+  { item: '服务', type: '产品A', score: 90 },
+  { item: '设计', type: '产品B', score: 40 },
+  { item: '开发', type: '产品B', score: 75 },
+  { item: '营销', type: '产品B', score: 85 },
+  { item: '运营', type: '产品B', score: 55 },
+  { item: '服务', type: '产品B', score: 65 },
+];
+
+chart.options({
+  type: 'view',
+  data,
+  coordinate: { type: 'polar' },   // 关键：极坐标
+  scale: {
+    x: { padding: 0.5, align: 0 },
+    y: { tickCount: 5, domainMin: 0, domainMax: 100 },
+  },
+  axis: {
+    x: { grid: true },
+    y: { zIndex: 1, title: false },
+  },
+  children: [
+    {
+      type: 'area',
+      encode: { x: 'item', y: 'score', color: 'type' },
+      style: { fillOpacity: 0.2 },
+    },
+    {
+      type: 'line',
+      encode: { x: 'item', y: 'score', color: 'type' },
+      style: { lineWidth: 2 },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 带数据点的雷达图
+
+```javascript
+chart.options({
+  type: 'view',
+  data,
+  coordinate: { type: 'polar' },
+  scale: {
+    x: { padding: 0.5, align: 0 },
+    y: { tickCount: 5, domainMin: 0 },
+  },
+  axis: {
+    x: { grid: true, labelFontSize: 13 },
+    y: { zIndex: 1, title: false, label: false },  // 隐藏 y 轴标签（只显示网格）
+  },
+  children: [
+    {
+      type: 'area',
+      encode: { x: 'item', y: 'score', color: 'type' },
+      style: { fillOpacity: 0.15 },
+    },
+    {
+      type: 'line',
+      encode: { x: 'item', y: 'score', color: 'type' },
+      style: { lineWidth: 2 },
+    },
+    {
+      type: 'point',
+      encode: { x: 'item', y: 'score', color: 'type' },
+      style: { r: 4, fill: 'white', lineWidth: 2 },
+    },
+  ],
+  legend: { color: { position: 'top' } },
+  interaction: [{ type: 'tooltip' }],
+});
+```
+
+## 单系列雷达图（纯色填充）
+
+```javascript
+const singleData = [
+  { item: '攻击', score: 85 },
+  { item: '防御', score: 72 },
+  { item: '速度', score: 90 },
+  { item: '魔法', score: 60 },
+  { item: '体力', score: 78 },
+  { item: '运气', score: 66 },
+];
+
+chart.options({
+  type: 'view',
+  data: singleData,
+  coordinate: { type: 'polar' },
+  scale: {
+    x: { padding: 0.5, align: 0 },
+    y: { tickCount: 4, domainMin: 0, domainMax: 100 },
+  },
+  axis: {
+    x: { grid: true, labelFontSize: 14 },
+    y: { zIndex: 1, title: false },
+  },
+  children: [
+    {
+      type: 'area',
+      encode: { x: 'item', y: 'score' },
+      style: { fill: '#1890ff', fillOpacity: 0.25 },
+    },
+    {
+      type: 'line',
+      encode: { x: 'item', y: 'score' },
+      style: { stroke: '#1890ff', lineWidth: 2 },
+    },
+    {
+      type: 'point',
+      encode: { x: 'item', y: 'score' },
+      style: { r: 5, fill: '#1890ff' },
+      labels: [{ text: (d) => d.score, position: 'top', style: { fontSize: 11 } }],
+    },
+  ],
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：忘记设置 polar 坐标，变成普通面积折线图
+```javascript
+// ❌ 缺少 coordinate，渲染出的是普通折线图而非雷达图
+chart.options({
+  type: 'view',
+  data,
+  // 忘记了 coordinate: { type: 'polar' }
+  children: [{ type: 'area', ... }],
+});
+
+// ✅ 正确：必须声明 polar 坐标
+chart.options({
+  type: 'view',
+  data,
+  coordinate: { type: 'polar' },   // ✅ 关键
+  children: [{ type: 'area', ... }],
+});
+```
+
+### 错误 2：数据格式使用宽表
+
+```javascript
+// ❌ 宽表格式无法直接用 color 区分系列
+const wrongData = [
+  { item: '设计', A: 70, B: 40 },
+  { item: '开发', A: 60, B: 75 },
+];
+
+// ✅ 正确：使用长表格式（每行一个数据点 + 系列字段）
+const correctData = [
+  { item: '设计', type: 'A', score: 70 },
+  { item: '设计', type: 'B', score: 40 },
+  { item: '开发', type: 'A', score: 60 },
+  { item: '开发', type: 'B', score: 75 },
+];
+```
+
+### 错误 3：各维度量纲不统一导致视觉失真
+
+```javascript
+// ❌ 不同维度量级差异大（0-100 vs 0-10000），图形严重失真
+const data = [
+  { item: '销售额', score: 8500 },   // 万元
+  { item: '评分',   score: 85 },     // 百分制
+];
+
+// ✅ 先归一化到 0-100 再绘制
+const normalized = data.map(d => ({
+  ...d,
+  score: (d.score / maxScores[d.item]) * 100,
+}));
+```