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

package/builtin-skills/antv-g2-chart/references/patterns/g2-pattern-responsive.md

@@ -0,0 +1,232 @@
+---
+id: "g2-pattern-responsive"
+title: "G2 响应式图表适配"
+description: |
+  在不同屏幕尺寸和容器大小下自适应图表宽高、字体、边距等配置。
+  涵盖 autoFit 配置、ResizeObserver 动态调整以及移动端适配常见问题。
+
+library: "g2"
+version: "5.x"
+category: "patterns"
+tags:
+  - "响应式"
+  - "responsive"
+  - "自适应"
+  - "autoFit"
+  - "resize"
+  - "移动端"
+  - "容器尺寸"
+
+related:
+  - "g2-core-chart-init"
+
+use_cases:
+  - "图表随浏览器窗口/容器大小变化自动调整"
+  - "移动端和桌面端共用同一图表组件"
+  - "嵌入弹框/侧边栏等动态尺寸容器"
+
+difficulty: "intermediate"
+completeness: "full"
+---
+
+## G2 自适应宽度（autoFit）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+// 方案 1：autoFit: true（宽度自动适配容器，高度固定）
+const chart = new Chart({
+  container: 'container',
+  autoFit: true,     // 宽度 = 容器宽度，高度使用默认值
+  height: 400,       // 高度固定
+});
+
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value' },
+});
+
+chart.render();
+```
+
+## ResizeObserver 动态响应容器变化
+
+```javascript
+// 方案 2：监听容器尺寸变化，手动调整图表
+const container = document.getElementById('container');
+const chart = new Chart({
+  container: 'container',
+  width: container.clientWidth,
+  height: container.clientHeight,
+});
+
+chart.options({ type: 'interval', data, encode: { x: 'month', y: 'value' } });
+chart.render();
+
+// 监听容器大小变化
+const resizeObserver = new ResizeObserver((entries) => {
+  for (const entry of entries) {
+    const { width, height } = entry.contentRect;
+    chart.changeSize(width, height);
+  }
+});
+resizeObserver.observe(container);
+
+// 页面卸载时清理
+window.addEventListener('unload', () => {
+  resizeObserver.disconnect();
+  chart.destroy();
+});
+```
+
+## 窗口 resize 事件（简单方案）
+
+```javascript
+// 方案 3：监听 window resize（防抖处理）
+function debounce(fn, delay) {
+  let timer;
+  return (...args) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => fn(...args), delay);
+  };
+}
+
+const handleResize = debounce(() => {
+  const container = document.getElementById('container');
+  chart.changeSize(container.clientWidth, container.clientHeight);
+}, 300);
+
+window.addEventListener('resize', handleResize);
+```
+
+## 响应式图表的字体/边距适配
+
+```javascript
+// 根据容器宽度动态调整字体大小和边距
+function getResponsiveConfig(containerWidth) {
+  const isMobile = containerWidth < 480;
+  const isTablet = containerWidth < 768;
+
+  return {
+    fontSize: isMobile ? 10 : isTablet ? 11 : 12,
+    tickCount: isMobile ? 4 : isTablet ? 6 : 10,
+    labelRotate: isMobile ? Math.PI / 4 : 0,   // 移动端倾斜标签
+    marginBottom: isMobile ? 40 : 20,
+  };
+}
+
+const containerWidth = document.getElementById('container').clientWidth;
+const config = getResponsiveConfig(containerWidth);
+
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value' },
+  axis: {
+    x: {
+      labelFontSize: config.fontSize,
+      labelTransform: config.labelRotate ? `rotate(${config.labelRotate}rad)` : undefined,
+      tickCount: config.tickCount,
+    },
+    y: {
+      labelFontSize: config.fontSize,
+    },
+  },
+});
+```
+
+## React/Vue 组件中的响应式处理
+
+```javascript
+// React 示例（使用 useEffect 和 ref）
+import { useEffect, useRef } from 'react';
+import { Chart } from '@antv/g2';
+
+function ResponsiveChart({ data }) {
+  const containerRef = useRef(null);
+  const chartRef = useRef(null);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const chart = new Chart({
+      container,
+      autoFit: true,
+      height: 400,
+    });
+
+    chart.options({ type: 'line', data, encode: { x: 'date', y: 'value' } });
+    chart.render();
+    chartRef.current = chart;
+
+    const ro = new ResizeObserver(() => {
+      chartRef.current?.forceFit();
+    });
+    ro.observe(container);
+
+    return () => {
+      ro.disconnect();
+      chartRef.current?.destroy();
+    };
+  }, []);
+
+  useEffect(() => {
+    chartRef.current?.changeData(data);
+  }, [data]);
+
+  return <div ref={containerRef} style={{ width: '100%', height: 400 }} />;
+}
+```
+
+## 移动端常见适配
+
+```javascript
+const isMobile = window.matchMedia('(max-width: 768px)').matches;
+
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value' },
+  // 移动端：转为水平条形图（类别标签更易读）
+  coordinate: isMobile ? [{ type: 'transpose' }] : undefined,
+  // 移动端：减少刻度数量
+  axis: {
+    x: { tickCount: isMobile ? 4 : 8 },
+    y: {
+      labelFontSize: isMobile ? 10 : 12,
+      title: isMobile ? null : '数值',   // 移动端隐藏轴标题节省空间
+    },
+  },
+  // 移动端：隐藏图例（空间有限）
+  legend: isMobile ? false : { position: 'top' },
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：容器 display:none 时初始化图表
+
+```javascript
+// ❌ 问题：容器隐藏时 clientWidth = 0，图表尺寸为 0
+const chart = new Chart({ container: 'hidden-tab', autoFit: true });
+
+// ✅ 解决：等容器可见时再初始化，或显示后调用 changeSize
+container.style.display = 'block';
+chart.changeSize(container.clientWidth, container.clientHeight);
+```
+
+### 错误 2：多次触发 resize 不防抖导致性能问题
+
+```javascript
+// ❌ 每次 resize 都立即重绘（可能每秒触发 60 次）
+window.addEventListener('resize', () => {
+  chart.changeSize(window.innerWidth * 0.8, 400);
+});
+
+// ✅ 防抖处理
+window.addEventListener('resize', debounce(() => {
+  chart.changeSize(window.innerWidth * 0.8, 400);
+}, 300));
+```

package/builtin-skills/antv-g2-chart/references/patterns/g2-pattern-v4-to-v5.md

@@ -0,0 +1,223 @@
+---
+id: "g2-pattern-v4-to-v5"
+title: "G2 v4 → v5 迁移指南"
+description: |
+  G2 v5 相对 v4 有重大 API 变更。
+  本文梳理最常见的 v4 写法及对应的 v5 正确写法，
+  帮助避免 LLM 生成旧版废弃 API 的最常见错误。
+
+library: "g2"
+version: "5.x"
+category: "patterns"
+tags:
+  - "v4"
+  - "v5"
+  - "迁移"
+  - "migration"
+  - "废弃API"
+  - "升级"
+
+related:
+  - "g2-core-chart-init"
+  - "g2-core-encode-channel"
+
+use_cases:
+  - "将旧 G2 v4 代码迁移到 v5"
+  - "识别和修正 LLM 生成的 v4 废弃 API"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-27"
+author: "antv-team"
+---
+
+## 变更 1：导入方式
+
+```javascript
+// ❌ G2 v4 写法
+import G2 from '@antv/g2';
+const chart = new G2.Chart({ container: 'container' });
+
+// ✅ G2 v5 写法
+import { Chart } from '@antv/g2';
+const chart = new Chart({ container: 'container' });
+```
+
+## 变更 2：数据绑定
+
+```javascript
+// ❌ G2 v4：单独调用 .data()
+chart.data(data);
+
+// ✅ G2 v5（方式一）：在 mark 上传入
+chart.options({ type: 'interval',  data, encode: {...} });
+
+// ✅ G2 v5（方式二）：options 的 data 字段
+chart.options({
+  type: 'interval',
+   data,    // data 作为 options 的一个字段
+  encode: { x: 'month', y: 'value' },
+});
+```
+
+## 变更 3：字段编码 API
+
+```javascript
+// ❌ G2 v4：链式 .encode() 方法
+chart.interval()
+  .encode('x', 'month')
+  .encode('y', 'value')
+  .encode('color', 'product');
+
+// ✅ G2 v5：encode 作为对象字段
+chart.options({
+  type: 'interval',
+  encode: {
+    x: 'month',
+    y: 'value',
+    color: 'product',
+  },
+});
+```
+
+## 变更 4：数据变换（transform）
+
+```javascript
+// ❌ G2 v4：方法名和参数不同
+chart.interval().adjust('stack');     // 堆叠
+chart.interval().adjust('dodge');     // 分组
+
+// ✅ G2 v5：使用 transform 数组
+chart.options({
+  type: 'interval',
+  transform: [{ type: 'stackY' }],   // 堆叠
+  // transform: [{ type: 'dodgeX' }],  // 分组
+});
+```
+
+## 变更 5：坐标系配置
+
+```javascript
+// ❌ G2 v4
+chart.coordinate('polar');
+chart.coordinate('theta');
+chart.coordinate().transpose();
+
+// ✅ G2 v5：通过 coordinate 字段对象配置
+chart.options({
+  coordinate: { type: 'polar' },
+  // coordinate: { type: 'theta' },
+  // coordinate: { transform: [{ type: 'transpose' }] },
+});
+```
+
+## 变更 6：辅助标注（guide → annotation）
+
+```javascript
+// ❌ G2 v4：guide API
+chart.guide().line({ start: ['min', 50], end: ['max', 50] });
+chart.guide().text({ position: ['median', 'median'], content: '中位线' });
+
+// ✅ G2 v5：使用 lineY/lineX mark（在 view + children 中）
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    { type: 'line', encode: { x: 'month', y: 'value' } },
+    {
+      type: 'lineY',
+       [{ threshold: 50 }],
+      encode: { y: 'threshold' },
+      style: { stroke: 'red', lineDash: [4, 4] },
+      labels: [{ text: '目标线', position: 'right' }],
+    },
+  ],
+});
+```
+
+## 变更 7：标签配置
+
+```javascript
+// ❌ G2 v4：.label() 方法
+chart.interval().label('value');
+chart.interval().label({ fields: ['value'], formatter: (v) => `${v}万` });
+
+// ✅ G2 v5：labels 数组（注意是复数）
+chart.options({
+  type: 'interval',
+  labels: [
+    {
+      text: 'value',
+      // 或：text: (d) => `${d.value}万`,
+    },
+  ],
+});
+```
+
+## 变更 8：Tooltip 配置
+
+```javascript
+// ❌ G2 v4
+chart.tooltip({
+  showTitle: false,
+  itemTpl: '<li>{name}: {value}</li>',
+});
+
+// ✅ G2 v5
+chart.options({
+  tooltip: {
+    title: (d) => d.month,
+    items: [
+      { field: 'value', name: '数值', valueFormatter: (v) => `${v}万` },
+    ],
+  },
+  interaction: [{ type: 'tooltip' }],
+});
+```
+
+## 变更 9：多 Mark 叠加
+
+```javascript
+// ❌ G2 v4：多次调用 chart 方法直接叠加
+chart.line().encode('x', 'month').encode('y', 'value');
+chart.point().encode('x', 'month').encode('y', 'value');
+
+// ✅ G2 v5：使用 type: 'view' + children
+chart.options({
+  type: 'view',
+  data,
+  encode: { x: 'month', y: 'value' },
+  children: [
+    { type: 'line' },
+    { type: 'point' },
+  ],
+});
+```
+
+## 变更 10：动画配置
+
+```javascript
+// ❌ G2 v4
+chart.animate(true);
+
+// ✅ G2 v5
+chart.options({
+  animate: {
+    enter: { type: 'fadeIn', duration: 300 },
+    update: { type: 'morphing', duration: 500 },
+  },
+});
+```
+
+## v4 错误特征快速检查
+
+在审查 LLM 生成的代码时，检查以下常见 v4 错误特征：
+
+- [ ] `import G2 from '@antv/g2'`（应为命名导入）
+- [ ] `chart.source(data)` 或 `chart.data(data)`（应在 options 中）
+- [ ] `.position('x*y')`（v4 写法）
+- [ ] `.adjust('stack')` / `.adjust('dodge')`（应为 transform 数组）
+- [ ] `chart.guide().line()`（应为 lineY/lineX mark）
+- [ ] `.label()` 方法（应为 `labels` 数组）
+- [ ] 多次 `chart.options()` 调用（应用 view + children）

package/builtin-skills/antv-g2-chart/references/scales/g2-scale-band.md

@@ -0,0 +1,127 @@
+---
+id: "g2-scale-band"
+title: "G2 Band 分类比例尺"
+description: |
+  Band Scale 是 G2 中用于分类 x 轴（柱状图等）的比例尺，
+  将离散分类值映射到等宽区间（band），支持配置内外间距。
+  当 encode.x 映射字符串/分类字段时自动使用。
+
+library: "g2"
+version: "5.x"
+category: "scales"
+tags:
+  - "band"
+  - "分类比例尺"
+  - "柱状图"
+  - "padding"
+  - "scale"
+  - "ordinal"
+  - "spec"
+
+related:
+  - "g2-mark-interval-basic"
+  - "g2-mark-interval-grouped"
+  - "g2-comp-axis-config"
+
+use_cases:
+  - "配置柱状图的柱体宽度和间距"
+  - "指定分类轴的显示顺序"
+  - "控制分类数据的对齐方式"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/scale/band"
+---
+
+## 自动识别
+
+当 encode.x 映射字符串类型字段时，G2 自动使用 Band Scale，通常无需显式配置：
+
+```javascript
+chart.options({
+  type: 'interval',
+  data: [
+    { genre: 'Sports',   sold: 275 },
+    { genre: 'Strategy', sold: 115 },
+  ],
+  encode: { x: 'genre', y: 'sold' },   // 'genre' 是字符串，自动使用 Band Scale
+});
+```
+
+## 配置柱体宽度（padding）
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'genre', y: 'sold' },
+  scale: {
+    x: {
+      type: 'band',
+      padding: 0.3,         // 柱体内间距（0-1），默认 0.1
+      // paddingInner: 0.3, // 同 padding
+      // paddingOuter: 0.2, // 两端外间距
+    },
+  },
+});
+```
+
+## 自定义分类顺序
+
+```javascript
+// 指定分类显示顺序（不按数据顺序）
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'genre', y: 'sold' },
+  scale: {
+    x: {
+      type: 'band',
+      domain: ['Action', 'Shooter', 'Sports', 'Strategy', 'Other'],  // 显式指定顺序
+    },
+  },
+});
+```
+
+## 热力图（cell mark）
+
+`cell` mark 同样依赖 bandwidth，离散的 x/y 轴应使用 `band`（或省略让 G2 自动推断）。**不要用 `point` 比例尺**——point 的 bandwidth=0，格子会不可见。
+
+```javascript
+chart.options({
+  type: 'cell',
+  data: heatmapData,
+  encode: { x: 'date', y: 'month', color: 'value' },
+  // ✅ 省略 x/y scale，G2 自动为 cell 使用 band
+  scale: {
+    color: { type: 'sequential', palette: 'blues' },
+  },
+});
+
+// ✅ 也可以显式写 band
+scale: {
+  x: { type: 'band' },
+  y: { type: 'band' },
+  color: { type: 'sequential', palette: 'blues' },
+}
+
+// ❌ 不要用 point：bandwidth=0，格子消失
+scale: {
+  x: { type: 'point' },  // ❌
+  y: { type: 'point' },  // ❌
+}
+```
+
+## 常见错误与修正
+
+### 错误：padding 超出 [0, 1] 范围
+```javascript
+// ❌ 错误：padding > 1，柱体宽度变为负值
+chart.options({ scale: { x: { padding: 1.5 } } });
+
+// ✅ 正确：padding 在 0-1 之间，0 = 无间距，0.5 = 柱宽与间距各占一半
+chart.options({ scale: { x: { padding: 0.3 } } });
+```