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

package/builtin-skills/antv-g2-chart/references/coordinates/g2-coord-fisheye.md

@@ -0,0 +1,131 @@
+---
+id: "g2-coord-fisheye"
+title: "G2 鱼眼坐标系（fisheye）"
+description: |
+  鱼眼坐标系在焦点附近放大，远离焦点区域压缩，
+  用于在大量密集数据中同时保留局部细节和全局概览。
+  通常配合鱼眼交互（fisheye interaction）实现鼠标跟随的动态放大效果。
+
+library: "g2"
+version: "5.x"
+category: "coordinates"
+tags:
+  - "fisheye"
+  - "鱼眼"
+  - "焦点上下文"
+  - "focus+context"
+  - "coordinate"
+  - "密集数据"
+
+related:
+  - "g2-mark-point-scatter"
+  - "g2-coord-transpose"
+
+use_cases:
+  - "密集散点图的局部细节查看"
+  - "时间序列密集区域的细节探索"
+  - "需要同时看全局和局部细节的场景"
+
+difficulty: "advanced"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/coordinate/fisheye"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'point',
+   Array.from({ length: 200 }, (_, i) => ({
+    x: Math.random() * 100,
+    y: Math.random() * 100,
+    group: i % 5,
+  })),
+  encode: { x: 'x', y: 'y', color: 'group', shape: 'point' },
+  scale: { color: { type: 'ordinal' } },
+  coordinate: {
+    transform: [
+      {
+        type: 'fisheye',
+        focusX: 0.5,       // 焦点 X 位置（0~1 相对坐标）
+        focusY: 0.5,       // 焦点 Y 位置
+        distortionX: 2,    // X 方向放大系数（越大放大越强）
+        distortionY: 2,    // Y 方向放大系数
+      }
+    ]
+  },
+  // 通常配合鱼眼交互，让焦点跟随鼠标
+  interaction: { fisheye: true },
+});
+
+chart.render();
+```
+
+## 配置项
+
+```javascript
+coordinate: {
+  transform: [
+    {
+      type: 'fisheye',
+      focusX: 0,        // 焦点 X（相对坐标 0~1），默认 0
+      focusY: 0,        // 焦点 Y（相对坐标 0~1），默认 0
+      distortionX: 2,   // X 方向扭曲强度，默认 2
+      distortionY: 2,   // Y 方向扭曲强度，默认 2
+      visual: false,    // 是否启用视觉效果，默认 false
+    }
+  ]
+}
+```
+
+## 仅 X 方向鱼眼（时间序列）
+
+```javascript
+chart.options({
+  type: 'line',
+  data: timeSeriesData,
+  encode: { x: 'date', y: 'value', color: 'type' },
+  coordinate: {
+    transform: [
+      {
+        type: 'fisheye',
+        distortionX: 3,   // 仅放大 X 方向
+        distortionY: 0,   // Y 方向不变形
+      }
+    ]
+  },
+  interaction: { fisheye: true },
+});
+```
+
+## 常见错误与修正
+
+### 错误：单独使用鱼眼坐标系但不加交互——效果是静态的
+```javascript
+// ⚠️  可以用，但焦点固定，无法响应鼠标
+chart.options({
+  coordinate: {
+    transform: [
+      {
+        type: 'fisheye',
+        focusX: 0.3,
+        focusY: 0.5,
+      }
+    ]
+  },
+  // 没有 interaction.fisheye
+});
+
+// ✅ 推荐：配合交互实现动态鱼眼
+chart.options({
+  coordinate: { transform: [ { type: 'fisheye' } ] },
+  interaction: { fisheye: true },  // 焦点跟随鼠标
+});
+```

package/builtin-skills/antv-g2-chart/references/coordinates/g2-coord-helix.md

@@ -0,0 +1,141 @@
+---
+id: "g2-coord-helix"
+title: "G2 螺旋坐标系（helix）"
+description: |
+  螺旋坐标系将时间/顺序数据沿螺旋线排布，适合展示具有周期性规律的长时间序列。
+  数据按螺旋盘绕，相同周期位置的数据点上下对齐，便于发现周期模式。
+
+library: "g2"
+version: "5.x"
+category: "coordinates"
+tags:
+  - "helix"
+  - "螺旋"
+  - "螺旋图"
+  - "周期"
+  - "时间序列"
+  - "coordinate"
+
+related:
+  - "g2-mark-interval-basic"
+  - "g2-scale-time"
+
+use_cases:
+  - "展示多年日均气温的周期规律"
+  - "股票价格长时间序列的周期分析"
+  - "周/月/年周期性规律可视化"
+
+difficulty: "advanced"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/coordinate/helix"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+// 生成一年的日均温度数据
+const data = Array.from({ length: 365 }, (_, i) => ({
+  day: i,
+  temp: 15 + 12 * Math.sin((i / 365) * Math.PI * 2) + (Math.random() - 0.5) * 5,
+}));
+
+const chart = new Chart({ container: 'container', width: 600, height: 600 });
+
+chart.options({
+  type: 'interval',
+  data,
+  encode: {
+    x: 'day',    // 顺序（沿螺旋排布）
+    y: 'temp',   // 数值（映射为半径变化）
+    color: 'temp',
+  },
+  scale: {
+    color: { type: 'sequential', palette: 'rdYlBu' },
+  },
+  coordinate: {
+    type: 'helix',
+    startAngle: 0,              // 起始角度，默认 0
+    endAngle: Math.PI * 6,      // 结束角度，默认 6π（3圈）
+    innerRadius: 0.1,
+    outerRadius: 0.9,
+  },
+  style: { lineWidth: 0 },
+  legend: false,
+});
+
+chart.render();
+```
+
+## 配置项
+
+```javascript
+coordinate: {
+  type: 'helix',
+  startAngle: 0,              // 起始角度（弧度），默认 0
+  endAngle: Math.PI * 6,      // 结束角度，默认 6π（3圈）
+  innerRadius: 0,             // 内孔半径，默认 0
+  outerRadius: 1,             // 外径比例，默认 1
+}
+```
+
+## 常见错误与修正
+
+### 错误：数据量太少，螺旋圈数太多——空白区域很大
+```javascript
+// ❌ 数据只有 12 个月却设置 6π（3圈），每圈只有 4 个点
+chart.options({
+  data: monthlyData,  // 只有 12 条
+  coordinate: { type: 'helix', endAngle: Math.PI * 6 },
+});
+
+// ✅ 根据数据量调整圈数：endAngle = 圈数 × 2π
+chart.options({
+  coordinate: {
+    type: 'helix',
+    endAngle: Math.PI * 2,  // 1 圈，适合月度数据
+  },
+});
+```
+
+### 错误：样式设置不当导致图形不可见或渲染异常
+```javascript
+// ❌ 使用了 lineWidth: 0 和 interval 类型但未设置足够宽度，可能导致视觉上“消失”
+chart.options({
+  type: 'interval',
+  coordinate: { type: 'helix' },
+  style: { lineWidth: 0 },
+});
+
+// ✅ 设置合适的 lineWidth 或调整图形类型如 point 更适合细粒度数据
+chart.options({
+  type: 'point', // 对于大量密集数据更合适
+  style: { lineWidth: 2 },
+});
+```
+
+### 错误：动画类型与图形元素不兼容导致无动画效果
+```javascript
+// ❌ growInY 动画可能不适用于所有 helix 场景下的 interval 元素
+chart.options({
+  animate: {
+    enter: {
+      type: 'growInY',
+    }
+  }
+});
+
+// ✅ 使用 fadeIn 等通用动画类型确保兼容性
+chart.options({
+  animate: {
+    enter: {
+      type: 'fadeIn',
+      duration: 2000,
+    }
+  }
+});
+```

package/builtin-skills/antv-g2-chart/references/coordinates/g2-coord-parallel.md

@@ -0,0 +1,129 @@
+---
+id: "g2-coord-parallel"
+title: "G2 平行坐标系（parallel）"
+description: |
+  平行坐标系将多个维度排列为平行的竖轴，每条折线代表一条数据记录，
+  用于发现多维数据中的模式、聚类和异常值。
+  需要配合 line mark 使用，encode 中用 position 通道绑定多个字段。
+
+library: "g2"
+version: "5.x"
+category: "coordinates"
+tags:
+  - "parallel"
+  - "平行坐标"
+  - "parallel coordinates"
+  - "多维"
+  - "高维数据"
+  - "coordinate"
+
+related:
+  - "g2-mark-line-basic"
+  - "g2-coord-transpose"
+
+use_cases:
+  - "多维度数据对比分析（如汽车性能多指标）"
+  - "发现高维数据中的聚类和关联"
+  - "异常值检测"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/coordinate/parallel"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { name: '产品A', price: 120, sales: 300, rating: 4.5, stock: 80 },
+  { name: '产品B', price: 85,  sales: 450, rating: 3.8, stock: 120 },
+  { name: '产品C', price: 200, sales: 180, rating: 4.9, stock: 40 },
+  { name: '产品D', price: 60,  sales: 600, rating: 3.2, stock: 200 },
+];
+
+const chart = new Chart({ container: 'container', width: 600, height: 400 });
+
+chart.options({
+  type: 'line',
+  data,
+  encode: {
+    position: ['price', 'sales', 'rating', 'stock'],  // 多维字段列表
+  },
+  coordinate: { type: 'parallel' },  // 平行坐标系
+  style: {
+    lineWidth: 1.5,
+    strokeOpacity: 0.7,
+  },
+  legend: { color: { position: 'right' } },
+});
+
+chart.render();
+```
+
+## 带交互高亮的平行坐标
+
+```javascript
+chart.options({
+  type: 'line',
+  data,
+  encode: {
+    position: ['cylinders', 'displacement', 'horsepower', 'weight', 'acceleration', 'miles_per_gallon'],
+    color: 'origin',
+  },
+  coordinate: { type: 'parallel' },
+  style: { lineWidth: 1, strokeOpacity: 0.5 },
+  interaction: {
+    elementHighlight: { background: true },  // 悬停高亮
+  },
+  axis: {
+    // 为每个维度单独配置标题
+    position0: { title: '气缸数' },
+    position1: { title: '排量' },
+    position2: { title: '马力' },
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：用 x/y encode 替代 position
+```javascript
+// ❌ 错误：平行坐标不使用 x/y，必须用 position 通道
+chart.options({
+  type: 'line',
+  encode: {
+    x: 'price',      // ❌
+    y: 'sales',      // ❌ 只有两个维度，不是平行坐标
+  },
+  coordinate: { type: 'parallel' },
+});
+
+// ✅ 正确：position 通道传入字段数组
+chart.options({
+  type: 'line',
+  encode: {
+    position: ['price', 'sales', 'rating'],  // ✅ 数组形式
+  },
+  coordinate: { type: 'parallel' },
+});
+```
+
+### 错误 2：在平行坐标中使用 interval 或 point mark
+```javascript
+// ❌ 错误：平行坐标系只适合 line mark
+chart.options({
+  type: 'interval',  // ❌ 在平行坐标中没有意义
+  coordinate: { type: 'parallel' },
+});
+
+// ✅ 正确：配合 line mark
+chart.options({
+  type: 'line',      // ✅
+  coordinate: { type: 'parallel' },
+});
+```

package/builtin-skills/antv-g2-chart/references/coordinates/g2-coord-polar.md

@@ -0,0 +1,143 @@
+---
+id: "g2-coord-polar"
+title: "G2 极坐标系（polar）"
+description: |
+  极坐标系将直角坐标系映射为圆形区域，x 通道映射为角度，y 通道映射为半径。
+  常用于玫瑰图（极坐标柱状图）、极坐标面积图、环形图等。
+  通过 startAngle / endAngle 控制角度范围，innerRadius 控制内孔大小。
+
+library: "g2"
+version: "5.x"
+category: "coordinates"
+tags:
+  - "polar"
+  - "极坐标"
+  - "玫瑰图"
+  - "nightingale"
+  - "coxcomb"
+  - "radial"
+  - "coordinate"
+
+related:
+  - "g2-coord-transpose"
+  - "g2-mark-arc-pie"
+  - "g2-mark-interval-stacked"
+
+use_cases:
+  - "玫瑰图 / 南丁格尔玫瑰图（各分类用角度+半径双重编码）"
+  - "极坐标面积图（周期性数据的环形展示）"
+  - "环形进度条"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/coordinate/polar"
+---
+
+## 最小可运行示例（玫瑰图）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 500, height: 500 });
+
+chart.options({
+  type: 'interval',
+  data: [
+    { month: 'Jan', value: 83 },
+    { month: 'Feb', value: 60 },
+    { month: 'Mar', value: 95 },
+    { month: 'Apr', value: 72 },
+    { month: 'May', value: 110 },
+    { month: 'Jun', value: 88 },
+  ],
+  encode: {
+    x: 'month',   // 映射为角度（方向）
+    y: 'value',   // 映射为半径（长度）
+    color: 'month',
+  },
+  coordinate: { type: 'polar' },  // 关键：极坐标
+});
+
+chart.render();
+```
+
+## 配置项
+
+```javascript
+chart.options({
+  type: 'interval',
+  data: [...],
+  encode: { x: 'month', y: 'value', color: 'month' },
+  coordinate: {
+    type: 'polar',
+    startAngle: -Math.PI / 2,    // 起始角度，默认 -π/2（12点钟方向）
+    endAngle: (Math.PI * 3) / 2, // 结束角度，默认 3π/2（顺时针一圈）
+    innerRadius: 0,              // 内孔半径，0 = 无孔，0.5 = 半径50% 的孔
+    outerRadius: 1,              // 外径比例，默认 1
+  },
+});
+```
+
+## 半圆玫瑰图
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'month' },
+  coordinate: {
+    type: 'polar',
+    startAngle: -Math.PI / 2,   // 从顶部开始
+    endAngle: Math.PI / 2,      // 只到底部，半圆
+  },
+});
+```
+
+## 极坐标堆叠面积图
+
+```javascript
+chart.options({
+  type: 'area',
+  data: timeSeriesData,
+  encode: { x: 'date', y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  coordinate: { type: 'polar', innerRadius: 0.2 },
+  style: { fillOpacity: 0.65 },
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：玫瑰图角度不均匀——x 通道数据类型不是分类
+```javascript
+// ❌ 错误：x 通道是数值，极坐标下角度不均匀
+chart.options({
+  encode: { x: 'timestamp', y: 'value' },  // ❌ 时间戳为数值
+  coordinate: { type: 'polar' },
+});
+
+// ✅ 正确：x 通道应为分类字段（字符串）
+chart.options({
+  encode: { x: 'month', y: 'value' },  // ✅ 字符串类别
+  coordinate: { type: 'polar' },
+});
+```
+
+### 错误 2：与 theta 坐标系混淆
+```javascript
+// ❌ 饼图用 polar 无效——y 通道不会自动转为扇形角度
+chart.options({
+  type: 'interval',
+  encode: { y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  coordinate: { type: 'polar' },  // ❌ 饼图应该用 theta，不是 polar
+});
+
+// ✅ 饼图必须用 theta 坐标系
+chart.options({
+  coordinate: { type: 'theta' },  // ✅
+});
+```