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

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

@@ -0,0 +1,148 @@
+---
+id: "g2-mark-arc-donut"
+title: "G2 环形图（Donut Chart）"
+description: |
+  在饼图基础上通过设置 coordinate.innerRadius 创建环形图（甜甜圈图），
+  中间空白区域可放置汇总数字或说明文字，在保留占比展示的同时减少视觉重量。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+subcategory: "arc"
+tags:
+  - "环形图"
+  - "甜甜圈"
+  - "donut"
+  - "innerRadius"
+  - "占比"
+  - "饼图变体"
+  - "spec"
+
+related:
+  - "g2-mark-arc-pie"
+  - "g2-transform-stacky"
+
+use_cases:
+  - "展示各类别占比，中心区域显示汇总数据"
+  - "比饼图更现代的占比展示方式"
+  - "KPI 卡片中的占比环"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/general/donut"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 480,
+  height: 480,
+});
+
+chart.options({
+  type: 'interval',
+  data: [
+    { type: '分类一', value: 27 },
+    { type: '分类二', value: 25 },
+    { type: '分类三', value: 18 },
+    { type: '分类四', value: 15 },
+    { type: '其他',   value: 15 },
+  ],
+  encode: { y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  coordinate: {
+    type: 'theta',
+    outerRadius: 0.8,
+    innerRadius: 0.5,    // 关键：设置内径产生空心效果
+  },
+});
+
+chart.render();
+```
+
+## 带中心文字的环形图
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { type: '已完成', value: 75 },
+  { type: '未完成', value: 25 },
+];
+const total = data.reduce((s, d) => s + d.value, 0);
+
+const chart = new Chart({ container: 'container', width: 400, height: 400 });
+
+chart.options({
+  type: 'view',
+  children: [
+    {
+      type: 'interval',
+       data,
+      encode: { y: 'value', color: 'type' },
+      transform: [{ type: 'stackY' }],
+      coordinate: { type: 'theta', outerRadius: 0.85, innerRadius: 0.6 },
+      scale: {
+        color: { range: ['#1890ff', '#f0f0f0'] },
+      },
+      legend: false,
+    },
+    {
+      // 中心文字用 text mark 在极坐标中心绘制
+      type: 'text',
+       [{ value: data[0].value }],
+      encode: { text: (d) => `${d.value}%` },
+      style: {
+        x: '50%', y: '50%',
+        textAlign: 'center',
+        fontSize: 32,
+        fontWeight: 'bold',
+        fill: '#1890ff',
+      },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 带外部标签的环形图
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  coordinate: { type: 'theta', outerRadius: 0.8, innerRadius: 0.5 },
+  labels: [
+    {
+      text: (d) => `${d.type}: ${d.value}`,
+      position: 'outside',
+      connector: true,
+    },
+  ],
+});
+```
+
+## 常见错误与修正
+
+### 错误：innerRadius 大于 outerRadius
+```javascript
+// ❌ 错误：内径大于外径，圆环消失
+chart.options({
+  coordinate: { type: 'theta', outerRadius: 0.5, innerRadius: 0.8 },
+});
+
+// ✅ 正确：innerRadius < outerRadius，推荐比例 0.5-0.7
+chart.options({
+  coordinate: { type: 'theta', outerRadius: 0.8, innerRadius: 0.5 },
+});
+```

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

@@ -0,0 +1,212 @@
+---
+id: "g2-mark-arc-pie"
+title: "G2 饼图（Interval + theta 坐标系）"
+description: |
+  使用 Interval Mark 配合 theta 坐标系和 stackY 变换创建饼图，
+  展示各部分在整体中的占比关系。本文采用 Spec 模式（chart.options({})）。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+subcategory: "arc"
+tags:
+  - "饼图"
+  - "pie chart"
+  - "占比"
+  - "比例"
+  - "theta坐标系"
+  - "stackY"
+  - "spec"
+
+related:
+  - "g2-mark-arc-donut"
+  - "g2-core-chart-init"
+  - "g2-transform-stacky"
+  - "g2-interaction-tooltip"
+
+use_cases:
+  - "展示各类别占总量的比例"
+  - "显示市场份额分布"
+  - "可视化资源分配比例"
+
+anti_patterns:
+  - "类别超过 6-7 个时饼图难以阅读，改用柱状图"
+  - "需要精确比较数值时不适用（人眼对角度判断不准确）"
+  - "有零值或负值时饼图无意义"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/general/pie"
+---
+
+## 核心概念
+
+G2 v5 饼图的 Spec 结构：
+- `coordinate: { type: 'theta' }` — 将直角坐标转换为圆形角度坐标
+- `transform: [{ type: 'stackY' }]` — 将各分类数值累积为角度区间（**必须**）
+- `encode.y` — 映射数值字段（角度大小）
+- `encode.color` — 映射分类字段（扇区颜色）
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'interval',
+  data: [
+    { type: '分类一', value: 27 },
+    { type: '分类二', value: 25 },
+    { type: '分类三', value: 18 },
+    { type: '分类四', value: 15 },
+    { type: '分类五', value: 10 },
+    { type: '其他',   value: 5  },
+  ],
+  encode: {
+    y: 'value',       // 映射数值字段（决定扇区角度大小）
+    color: 'type',    // 映射分类字段（决定扇区颜色）
+  },
+  transform: [{ type: 'stackY' }],   // 必须：将 y 值转换为角度区间
+  coordinate: { type: 'theta', outerRadius: 0.8 },
+  legend: {
+    color: { position: 'bottom', layout: { justifyContent: 'center' } },
+  },
+  labels: [
+    {
+      text: (d) => `${d.type}\n${d.value}`,
+      position: 'outside',
+      connector: true,
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 带百分比标签的饼图
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { type: '分类一', value: 27 },
+  { type: '分类二', value: 25 },
+  { type: '分类三', value: 18 },
+  { type: '分类四', value: 15 },
+  { type: '其他',   value: 15 },
+];
+const total = data.reduce((sum, d) => sum + d.value, 0);
+
+const chart = new Chart({ container: 'container', width: 600, height: 480 });
+
+chart.options({
+  type: 'interval',
+  data,
+  encode: { y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  coordinate: { type: 'theta', outerRadius: 0.8 },
+  labels: [
+    {
+      text: (d) => `${((d.value / total) * 100).toFixed(1)}%`,
+      position: 'inside',
+      style: { fill: 'white', fontSize: 12, fontWeight: 'bold' },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 环形图（Donut）
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  coordinate: {
+    type: 'theta',
+    outerRadius: 0.8,
+    innerRadius: 0.5,    // 设置内径即为环形图
+  },
+});
+```
+
+## 玫瑰图（极坐标柱状图）
+
+```javascript
+// 极坐标下每个扇区角度相同，半径由数值决定
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'type', y: 'value', color: 'type' },
+  coordinate: { type: 'polar' },   // 注意：玫瑰图用 polar，不用 theta
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：忘记 transform stackY
+```javascript
+// ❌ 错误：没有 stackY，所有扇形从 0 开始角度，完全重叠
+chart.options({
+  type: 'interval',
+  data,
+  encode: { y: 'value', color: 'type' },
+  coordinate: { type: 'theta' },
+  // 缺少 transform！
+});
+
+// ✅ 正确：必须声明 stackY
+chart.options({
+  type: 'interval',
+  data,
+  encode: { y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],   // 必须！
+  coordinate: { type: 'theta' },
+});
+```
+
+### 错误 2：饼图误用 x 通道
+```javascript
+// ❌ 错误：theta 坐标系中 x 通道无效，不要在饼图中 encode.x
+chart.options({
+  type: 'interval',
+  encode: { x: 'type', y: 'value' },    // x 在 theta 下没有意义
+  coordinate: { type: 'theta' },
+});
+
+// ✅ 正确：饼图只需 encode.y（数值）和 encode.color（分类）
+chart.options({
+  type: 'interval',
+  encode: { y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  coordinate: { type: 'theta' },
+});
+```
+
+### 错误 3：G2 v4 饼图写法
+```javascript
+// ❌ 错误（G2 v4 写法）
+chart.coord('theta', { radius: 0.75 });
+chart.interval().position('value').color('type');
+
+// ✅ 正确（G2 v5 Spec 写法）
+chart.options({
+  type: 'interval',
+  data,
+  encode: { y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  coordinate: { type: 'theta', outerRadius: 0.8 },
+});
+```

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

@@ -0,0 +1,168 @@
+---
+id: "g2-mark-area-basic"
+title: "G2 基础面积图（Area Mark）"
+description: |
+  使用 Area Mark 创建面积图，在折线图的基础上填充线下方区域，
+  强调数据的量级和趋势。本文采用 Spec 模式，涵盖单系列、渐变填充等用法。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+subcategory: "area"
+tags:
+  - "面积图"
+  - "Area"
+  - "area chart"
+  - "趋势"
+  - "量级"
+  - "填充"
+  - "spec"
+
+related:
+  - "g2-mark-line-basic"
+  - "g2-mark-area-stacked"
+  - "g2-core-encode-channel"
+
+use_cases:
+  - "展示数值随时间的变化趋势，同时强调量级"
+  - "叠加折线时作为背景填充"
+  - "对比多个系列的总量分布"
+
+anti_patterns:
+  - "多系列面积图（无堆叠）时各系列互相遮挡，改用堆叠面积图或折线图"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/area/basic"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'area',
+  data: [
+    { month: 'Jan', value: 33 },
+    { month: 'Feb', value: 78 },
+    { month: 'Mar', value: 56 },
+    { month: 'Apr', value: 91 },
+    { month: 'May', value: 67 },
+    { month: 'Jun', value: 45 },
+  ],
+  encode: { x: 'month', y: 'value' },
+});
+
+chart.render();
+```
+
+## 渐变填充面积图
+
+```javascript
+chart.options({
+  type: 'area',
+  data,
+  encode: { x: 'month', y: 'value' },
+  style: {
+    fill: 'linear-gradient(180deg, #1890ff 0%, rgba(24,144,255,0.1) 100%)',
+    fillOpacity: 0.8,
+  },
+});
+```
+
+## 面积图 + 折线（叠加）
+
+```javascript
+// 面积提供背景量感，折线提供精确走势
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    {
+      type: 'area',
+      encode: { x: 'month', y: 'value' },
+      style: { fillOpacity: 0.2, fill: '#1890ff' },
+    },
+    {
+      type: 'line',
+      encode: { x: 'month', y: 'value' },
+      style: { stroke: '#1890ff', lineWidth: 2 },
+    },
+    {
+      type: 'point',
+      encode: { x: 'month', y: 'value', shape: 'circle' },
+      style: { fill: '#1890ff', r: 4 },
+    },
+  ],
+});
+```
+
+## 平滑曲线面积图
+
+```javascript
+chart.options({
+  type: 'area',
+  data,
+  encode: {
+    x: 'month',
+    y: 'value',
+    shape: 'smooth',    // 平滑插值
+  },
+  style: { fillOpacity: 0.6 },
+});
+```
+
+## 时间序列面积图
+
+```javascript
+chart.options({
+  type: 'area',
+  data: [
+    { date: new Date('2024-01'), value: 100 },
+    { date: new Date('2024-02'), value: 130 },
+    { date: new Date('2024-03'), value: 90  },
+    { date: new Date('2024-04'), value: 160 },
+    { date: new Date('2024-05'), value: 145 },
+  ],
+  encode: { x: 'date', y: 'value' },
+  axis: {
+    x: { labelFormatter: 'YYYY-MM' },
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：多系列面积图不加 stackY 导致互相遮挡
+```javascript
+// ❌ 问题：多系列面积相互覆盖，后面的系列遮挡前面的
+chart.options({
+  type: 'area',
+  data: multiSeriesData,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  // 没有 stackY，各系列从 y=0 开始叠加，互相遮盖
+});
+
+// ✅ 方案 1：堆叠面积图（见 g2-mark-area-stacked）
+chart.options({
+  type: 'area',
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+});
+
+// ✅ 方案 2：改用折线图对比多系列
+chart.options({
+  type: 'line',
+  encode: { x: 'month', y: 'value', color: 'type' },
+});
+```

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

@@ -0,0 +1,150 @@
+---
+id: "g2-mark-area-stacked"
+title: "G2 堆叠面积图"
+description: |
+  使用 Area Mark 配合 stackY Transform 创建堆叠面积图，
+  同时展示各系列的变化趋势和总量的积累效果，各系列的面积从上一个系列顶端开始填充。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+subcategory: "area"
+tags:
+  - "堆叠面积图"
+  - "stacked area"
+  - "stackY"
+  - "多系列"
+  - "趋势"
+  - "总量"
+  - "spec"
+
+related:
+  - "g2-mark-area-basic"
+  - "g2-transform-stacky"
+  - "g2-mark-interval-stacked"
+
+use_cases:
+  - "展示多个系列的总量随时间的变化"
+  - "同时关注各系列趋势和总体规模"
+  - "流量来源、收入构成等场景"
+
+anti_patterns:
+  - "系列超过 5 个时颜色难以区分"
+  - "需要精确对比单个系列的变化时（基准线不统一），改用折线图"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/area/stacked"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'area',
+  data: [
+    { month: 'Jan', type: 'A', value: 100 },
+    { month: 'Jan', type: 'B', value: 200 },
+    { month: 'Jan', type: 'C', value: 150 },
+    { month: 'Feb', type: 'A', value: 120 },
+    { month: 'Feb', type: 'B', value: 180 },
+    { month: 'Feb', type: 'C', value: 160 },
+    { month: 'Mar', type: 'A', value: 90  },
+    { month: 'Mar', type: 'B', value: 220 },
+    { month: 'Mar', type: 'C', value: 130 },
+  ],
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+});
+
+chart.render();
+```
+
+## 平滑堆叠面积图
+
+```javascript
+chart.options({
+  type: 'area',
+  data,
+  encode: {
+    x: 'month',
+    y: 'value',
+    color: 'type',
+    shape: 'smooth',
+  },
+  transform: [{ type: 'stackY' }],
+  style: { fillOpacity: 0.85 },
+});
+```
+
+## 堆叠面积 + 折线描边
+
+```javascript
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    {
+      type: 'area',
+      encode: { x: 'month', y: 'value', color: 'type' },
+      transform: [{ type: 'stackY' }],
+      style: { fillOpacity: 0.7 },
+    },
+    {
+      type: 'line',
+      encode: { x: 'month', y: 'value', color: 'type', series: 'type' },
+      transform: [{ type: 'stackY' }],
+      style: { lineWidth: 1.5 },
+    },
+  ],
+});
+```
+
+## 百分比堆叠面积图
+
+```javascript
+chart.options({
+  type: 'area',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [
+    { type: 'stackY' },
+    { type: 'normalizeY' },
+  ],
+  axis: {
+    y: { labelFormatter: (v) => `${(v * 100).toFixed(0)}%` },
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：忘记 stackY 导致系列互相遮挡
+```javascript
+// ❌ 错误：各系列面积都从 y=0 起，相互覆盖
+chart.options({
+  type: 'area',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  // 没有 transform！
+});
+
+// ✅ 正确
+chart.options({
+  type: 'area',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+});
+```