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

package/builtin-skills/antv-g2-chart/references/themes/g2-theme-builtin.md

@@ -0,0 +1,192 @@
+---
+id: "g2-theme-builtin"
+title: "G2 内置主题配置"
+description: |
+  G2 v5 内置 classic（经典）、classicDark（深色）、academy（学术）三种主题。
+  通过 theme 字段或 Chart 构造函数中的 theme 参数全局切换，也可局部覆盖样式变量。
+
+library: "g2"
+version: "5.x"
+category: "themes"
+tags:
+  - "theme"
+  - "主题"
+  - "dark"
+  - "深色主题"
+  - "classicDark"
+  - "spec"
+
+related:
+  - "g2-core-chart-init"
+  - "g2-mark-interval-basic"
+
+use_cases:
+  - "切换图表整体配色风格"
+  - "适配深色模式（Dark Mode）"
+  - "统一多图表的视觉风格"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/theme"
+---
+
+## 内置主题列表
+
+| 主题名 | 说明 |
+|--------|------|
+| `'classic'` | 默认主题（蓝色系，白色背景） |
+| `'classicDark'` | 深色主题（深色背景，明亮配色） |
+| `'academy'` | 学术风主题（灰色调，适合论文/报告） |
+
+## 基本用法（切换主题）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+// 方式 1：构造函数中指定
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+  theme: 'classicDark',    // 深色主题
+});
+
+chart.options({
+  type: 'interval',
+  data: [
+    { genre: 'Sports',   sold: 275 },
+    { genre: 'Strategy', sold: 115 },
+    { genre: 'Action',   sold: 120 },
+  ],
+  encode: { x: 'genre', y: 'sold', color: 'genre' },
+});
+
+chart.render();
+```
+
+```javascript
+// 方式 2：options 中指定
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'genre', y: 'sold', color: 'genre' },
+  theme: 'academy',        // 学术主题
+});
+
+chart.render();
+```
+
+## 深色主题示例
+
+```javascript
+const chart = new Chart({
+  container: 'container',
+  width: 700,
+  height: 400,
+  theme: 'classicDark',
+});
+
+chart.options({
+  type: 'view',
+  data,
+  encode: { x: 'month', y: 'value' },
+  children: [
+    {
+      type: 'area',
+      style: { fillOpacity: 0.3 },
+    },
+    {
+      type: 'line',
+      style: { lineWidth: 2 },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 运行时切换主题
+
+```javascript
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({ type: 'interval', data, encode: { x: 'x', y: 'y' } });
+chart.render();
+
+// 切换到深色主题（需重新渲染）
+chart.theme('classicDark');
+chart.render();
+```
+
+## 局部覆盖主题变量
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'genre', y: 'sold' },
+  theme: {
+    defaultColor: '#ff6b35',         // 默认颜色（第一个系列的颜色）
+    defaultStrokeColor: '#333',      // 默认边框色
+    // 覆盖色板
+    colors10: [
+      '#ff6b35', '#f7c59f', '#efefd0', '#004e89', '#1a936f',
+      '#88d498', '#c6dabf', '#eaf4d3', '#7b2d8b', '#ff3a5c',
+    ],
+  },
+});
+```
+
+## 自定义主题注册
+
+```javascript
+import { Chart, register } from '@antv/g2';
+
+// 注册自定义主题
+register('theme.myTheme', {
+  defaultColor: '#e63946',
+  background: '#f8f9fa',
+  colors10: ['#e63946', '#457b9d', '#1d3557', '#a8dadc', '#f1faee'],
+  // ... 其他变量
+});
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'genre', y: 'sold', color: 'genre' },
+  theme: 'myTheme',   // 使用自定义主题
+});
+
+chart.render();
+```
+
+## 常见错误与修正
+
+### 错误：theme 传入了非字符串/对象类型
+```javascript
+// ❌ 错误：theme 值不存在
+chart.options({ theme: 'dark' });   // 'dark' 不是内置主题名
+
+// ✅ 正确：使用内置主题名
+chart.options({ theme: 'classicDark' });   // 深色主题
+chart.options({ theme: 'classic' });       // 默认主题
+chart.options({ theme: 'academy' });       // 学术主题
+```
+
+### 错误：切换主题后忘记重新渲染
+```javascript
+// ❌ 错误：切换主题后没有重新渲染
+chart.theme('classicDark');
+// 图表没有变化！
+
+// ✅ 正确：切换后需调用 render()
+chart.theme('classicDark');
+chart.render();
+```

package/builtin-skills/antv-g2-chart/references/themes/g2-theme-custom.md

@@ -0,0 +1,183 @@
+---
+id: "g2-theme-custom"
+title: "G2 自定义主题创建（register + create）"
+description: |
+  G2 v5 支持通过 register('theme.xxx', themeConfig) 注册自定义主题。
+  自定义主题可以覆盖配色、字体、各 Mark 的默认样式等。
+  也可以用 theme 字段传入对象，局部覆盖当前主题的特定属性。
+  内置主题包括 classic、classicDark、academy（详见 g2-theme-builtin）。
+
+library: "g2"
+version: "5.x"
+category: "themes"
+tags:
+  - "theme"
+  - "自定义主题"
+  - "register"
+  - "主题注册"
+  - "colors10"
+  - "colors20"
+  - "配色方案"
+
+related:
+  - "g2-theme-builtin"
+  - "g2-core-chart-init"
+
+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/theme"
+---
+
+## 方式一：局部覆盖主题（theme 对象）
+
+最简单的方式是在 options 的 theme 字段中直接传对象，覆盖部分属性：
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'genre', y: 'sold', color: 'genre' },
+  theme: {
+    // 覆盖分类色板
+    colors10: [
+      '#3B82F6', '#EF4444', '#10B981', '#F59E0B',
+      '#8B5CF6', '#F97316', '#06B6D4', '#84CC16',
+      '#EC4899', '#6B7280',
+    ],
+    // 覆盖默认颜色
+    defaultColor: '#3B82F6',
+  },
+});
+
+chart.render();
+```
+
+## 方式二：注册全局自定义主题
+
+```javascript
+import { Chart, register } from '@antv/g2';
+
+// 注册自定义主题（基于 classic 主题扩展）
+register('theme.brand', {
+  // 基础颜色
+  defaultColor: '#e63946',
+  defaultStrokeColor: '#1d1d1d',
+
+  // 分类色板（10色 / 20色）
+  colors10: [
+    '#e63946', '#457b9d', '#1d3557', '#a8dadc',
+    '#f1faee', '#e9c46a', '#f4a261', '#e76f51',
+    '#264653', '#2a9d8f',
+  ],
+  colors20: [
+    '#e63946', '#457b9d', '#1d3557', '#a8dadc',
+    '#f1faee', '#e9c46a', '#f4a261', '#e76f51',
+    '#264653', '#2a9d8f',
+    // 后 10 种（渐变或变体）
+    '#ff6b6b', '#74b9ff', '#55efc4', '#ffeaa7',
+    '#dfe6e9', '#fab1a0', '#fd79a8', '#6c5ce7',
+    '#00b894', '#00cec9',
+  ],
+});
+
+// 使用自定义主题
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'genre', y: 'sold', color: 'genre' },
+  theme: 'brand',   // 使用注册的自定义主题名
+});
+
+chart.render();
+```
+
+## 主题配置项速查
+
+```javascript
+// 以下是可覆盖的主要配置项
+const themeConfig = {
+  // ── 基础颜色 ─────────────────────────────
+  defaultColor: '#1890ff',        // 默认颜色（单系列时）
+  defaultStrokeColor: '#ffffff',  // 默认描边颜色
+
+  // ── 色板 ──────────────────────────────────
+  colors10: [...],   // 10 色分类色板
+  colors20: [...],   // 20 色分类色板
+
+  // ── 背景 ──────────────────────────────────
+  background: '#ffffff',    // 图表背景色
+
+  // ── 字体 ──────────────────────────────────
+  fontFamily: 'sans-serif',  // 全局字体
+
+  // ── 动画默认时长 ───────────────────────────
+  enter: { duration: 300 },
+  update: { duration: 300 },
+  exit: { duration: 300 },
+};
+```
+
+## 深色主题（基于 classicDark 局部覆盖）
+
+```javascript
+// 在 classicDark 基础上修改
+const chart = new Chart({
+  container: 'container',
+  theme: 'classicDark',
+});
+
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value', color: 'type' },
+  // 局部覆盖：修改配色但保留深色背景
+  theme: {
+    colors10: ['#60a5fa', '#34d399', '#f87171', '#a78bfa',
+               '#fbbf24', '#22d3ee', '#f472b6', '#4ade80',
+               '#fb923c', '#e879f9'],
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：register 主题名忘加 'theme.' 前缀
+```javascript
+// ❌ 错误：注册时必须用 'theme.xxx' 格式
+register('brandTheme', { colors10: [...] });    // ❌
+chart.options({ theme: 'brandTheme' });          // 不生效
+
+// ✅ 正确：必须加 'theme.' 前缀
+register('theme.brandTheme', { colors10: [...] });  // ✅
+chart.options({ theme: 'brandTheme' });              // ✅ 使用时不带前缀
+```
+
+### 错误：theme 和 style 混用
+```javascript
+// ❌ 错误：主题配色和单个 mark 的样式混淆
+chart.options({
+  type: 'interval',
+  style: { colors10: [...] },  // ❌ colors10 不在 style 里
+});
+
+// ✅ 颜色主题在 theme 字段
+chart.options({
+  type: 'interval',
+  theme: { colors10: [...] },  // ✅
+  style: { fillOpacity: 0.8 }, // ✅ 单 mark 样式在 style 里
+});
+```

package/builtin-skills/antv-g2-chart/references/transforms/g2-transform-bin.md

@@ -0,0 +1,153 @@
+---
+id: "g2-transform-bin"
+title: "G2 Bin / BinX 数值分桶变换（直方图）"
+description: |
+  binX 将连续的数值 x 通道分成若干区间（桶），统计每个区间内的数据量，
+  是直方图的核心变换。bin 同时对 x 和 y 两个方向分桶，生成二维频率矩阵。
+  通过 thresholds 控制桶的数量，y 通道指定聚合方式（count/sum 等）。
+
+library: "g2"
+version: "5.x"
+category: "transforms"
+tags:
+  - "bin"
+  - "binX"
+  - "分桶"
+  - "直方图"
+  - "histogram"
+  - "频率分布"
+  - "transform"
+
+related:
+  - "g2-transform-groupx"
+  - "g2-mark-interval-basic"
+  - "g2-mark-cell-heatmap"
+
+use_cases:
+  - "绘制直方图（数值分布频率）"
+  - "二维频率热力图（bin 同时对 x/y 分桶）"
+  - "将连续数值转化为离散分组统计"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/transform/bin"
+---
+
+## 最小可运行示例（直方图）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+// 连续数值数据，不需要预先统计频率
+const rawData = Array.from({ length: 1000 }, () => ({
+  age: Math.floor(Math.random() * 50 + 20),  // 20~70 岁之间的随机年龄
+}));
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+chart.options({
+  type: 'interval',
+  data: rawData,
+  encode: {
+    x: 'age',   // 连续数值 → 自动分桶
+    y: '★',     // 占位符，binX 会计算 count
+  },
+  transform: [
+    {
+      type: 'binX',
+      y: 'count',        // 聚合方式：统计每桶数量
+      thresholds: 15,    // 桶的数量（近似值），默认自动计算
+    },
+  ],
+  style: { inset: 1 },  // 柱子之间留 1px 间隙
+  axis: { y: { title: '人数' } },
+});
+
+chart.render();
+```
+
+## BinX 配置项
+
+```javascript
+transform: [
+  {
+    type: 'binX',
+    thresholds: 20,  // 桶数量（整数）或阈值数组（如 [0, 25, 50, 75, 100]）
+    y: 'count',      // 聚合：'count' | 'sum' | 'mean' | 'min' | 'max' | function
+    // groupBy: 'color',  // 按颜色分组分桶（用于分组直方图）
+  },
+]
+```
+
+## 二维频率热力图（bin）
+
+```javascript
+// bin 同时对 x 和 y 方向分桶，生成二维频率矩阵
+chart.options({
+  type: 'cell',
+  data: scatterData,
+  encode: {
+    x: 'x',
+    y: 'y',
+    color: '★',
+  },
+  transform: [
+    {
+      type: 'bin',
+      color: 'count',    // 统计每个格子的点数（映射到颜色）
+      thresholds: [20, 20],  // [x 方向桶数, y 方向桶数]
+    },
+  ],
+  scale: { color: { type: 'sequential', palette: 'ylOrRd' } },
+  style: { lineWidth: 0 },
+});
+```
+
+## 分组直方图（按颜色分桶）
+
+```javascript
+chart.options({
+  type: 'interval',
+  data: employeeData,
+  encode: { x: 'salary', y: '★', color: 'dept' },
+  transform: [
+    { type: 'binX', y: 'count', thresholds: 12 },
+    { type: 'stackY' },   // 堆叠
+  ],
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：对分类字段 x 用 binX——分类应用 groupX
+```javascript
+// ❌ 错误：x 是字符串类别，binX 无法对字符串分桶
+chart.options({
+  encode: { x: 'department', y: '★' },   // department 是字符串
+  transform: [{ type: 'binX', y: 'count' }],  // ❌
+});
+
+// ✅ 字符串类别用 groupX
+chart.options({
+  encode: { x: 'department', y: '★' },
+  transform: [{ type: 'groupX', y: 'count' }],  // ✅
+});
+
+// ✅ binX 用于连续数值
+chart.options({
+  encode: { x: 'age', y: '★' },   // age 是数字
+  transform: [{ type: 'binX', y: 'count' }],  // ✅
+});
+```
+
+### 错误 2：thresholds 设置太大——出现极多细小的桶
+```javascript
+// ❌ 1000 条数据设置 500 个桶，每桶 2 条，直方图没有统计意义
+transform: [{ type: 'binX', y: 'count', thresholds: 500 }]  // ❌
+
+// ✅ 直方图桶数通常在 10~50 之间
+transform: [{ type: 'binX', y: 'count', thresholds: 20 }]  // ✅
+```

package/builtin-skills/antv-g2-chart/references/transforms/g2-transform-binx.md

@@ -0,0 +1,133 @@
+---
+id: "g2-transform-binx"
+title: "G2 BinX 分箱变换（直方图）"
+description: |
+  BinX 将连续 x 值按指定区间（bin）分组，自动统计每个区间内的记录数（或聚合值），
+  是绘制频率直方图的核心 Transform。与 Interval Mark 组合直接使用原始数据即可生成直方图。
+
+library: "g2"
+version: "5.x"
+category: "transforms"
+tags:
+  - "BinX"
+  - "直方图"
+  - "histogram"
+  - "分箱"
+  - "分布"
+  - "频率"
+  - "transform"
+  - "spec"
+
+related:
+  - "g2-mark-interval-basic"
+  - "g2-transform-stacky"
+
+use_cases:
+  - "展示连续数值数据的频率分布"
+  - "探索数据的分布形态（正态、偏态等）"
+
+anti_patterns:
+  - "数据是离散分类时不需要 binX，直接用 interval 即可"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/transform/bin-x"
+---
+
+## 最小可运行示例（直方图）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 400,
+});
+
+// 原始连续数值数据
+const rawData = Array.from({ length: 200 }, () => ({
+  value: Math.random() * 100,
+}));
+
+chart.options({
+  type: 'interval',
+  data: rawData,
+  encode: { x: 'value' },
+  transform: [
+    {
+      type: 'binX',
+      y: 'count',      // 统计每个 bin 内的记录数，结果存入 y 通道
+      thresholds: 20,  // 分成约 20 个 bin
+    },
+  ],
+  style: { inset: 0.5 },    // 柱体间留细缝
+});
+
+chart.render();
+```
+
+## 配置项
+
+```javascript
+transform: [
+  {
+    type: 'binX',
+    // 统计目标
+    y: 'count',       // 'count'（默认，计数）| 'sum' | 'mean' | 'max' | 'min'
+    // 如果是 sum/mean 等，还需指定聚合的字段：
+    // y: 'sum', field: 'amount',
+
+    // 分箱数量控制（三选一）
+    thresholds: 20,           // 目标分箱数（近似值，库会自动调整）
+    // domain: [0, 100],      // 指定值域范围
+    // step: 5,               // 每个 bin 的宽度（与 thresholds 互斥）
+  },
+],
+```
+
+## 分组直方图（按类别着色）
+
+```javascript
+chart.options({
+  type: 'interval',
+   data,  // [{ value: 42, group: 'A' }, ...]
+  encode: { x: 'value', color: 'group' },
+  transform: [
+    { type: 'binX', y: 'count', thresholds: 15 },
+    { type: 'stackY' },   // 堆叠同一 bin 内不同分组的计数
+  ],
+});
+```
+
+## 常见错误与修正
+
+### 错误：对离散分类数据使用 binX
+```javascript
+// ❌ 错误：genre 是分类字段，不需要 binX
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'genre' },
+  transform: [{ type: 'binX', y: 'count' }],  // 不必要！
+});
+
+// ✅ 正确：分类数据直接用 interval，不需要 binX
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'genre', y: 'count' },
+});
+```
+
+### 错误：忘记指定 y 统计量
+```javascript
+// ❌ 错误：没有 y 参数，不知道统计什么
+chart.options({ transform: [{ type: 'binX', thresholds: 20 }] });
+
+// ✅ 正确：必须指定 y
+chart.options({ transform: [{ type: 'binX', y: 'count', thresholds: 20 }] });
+```