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

package/builtin-skills/antv-g2-chart/references/data/g2-data-transform-patterns.md

@@ -0,0 +1,394 @@
+---
+id: "g2-data-transform-patterns"
+title: "G2 数据转换模式"
+description: |
+  G2 可视化前最常用的数据预处理模式：宽转长（fold）、分组聚合、
+  百分比计算、排名/排序、数据过滤、时间粒度聚合。
+  这些模式既可在 JavaScript 前端完成，也可使用 G2 的内置 data transform。
+
+library: "g2"
+version: "5.x"
+category: "data"
+tags:
+  - "数据转换"
+  - "数据处理"
+  - "宽转长"
+  - "fold"
+  - "分组聚合"
+  - "百分比"
+  - "排序"
+  - "时间聚合"
+
+related:
+  - "g2-data-fold"
+  - "g2-data-filter"
+  - "g2-data-sort"
+  - "g2-data-slice"
+
+use_cases:
+  - "将 API 返回的宽表转为 G2 需要的长表"
+  - "前端对数据进行聚合、排名、百分比计算"
+  - "为不同图表类型准备对应格式的数据"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-27"
+author: "antv-team"
+---
+
+## 核心概念
+
+**数据转换有两种方式**：
+
+1. **JavaScript 前端预处理**：在传入 G2 之前用 JS 函数处理
+2. **G2 内置 data transform**：配置在 `data.transform` 中，声明式处理
+
+**推荐**：优先使用 G2 内置 transform，代码更简洁、可序列化。
+
+## 模式 1：宽表转长表（Wide to Long）
+
+**场景**：后端返回每列一个指标的宽表，需转为每行一个观测值的长表
+
+**JavaScript 方式**：
+```javascript
+// 输入：宽表
+const wideData = [
+  { month: 'Jan', 北京: 3.6, 上海: 4.3, 广州: 2.8 },
+  { month: 'Feb', 北京: 3.8, 上海: 4.5, 广州: 3.0 },
+];
+
+function wideToLong(data, idCols, valueCols, keyName = 'key', valueName = 'value') {
+  return data.flatMap(row =>
+    valueCols.map(col => ({
+      ...Object.fromEntries(idCols.map(id => [id, row[id]])),
+      [keyName]: col,
+      [valueName]: row[col],
+    }))
+  );
+}
+
+const longData = wideToLong(wideData, ['month'], ['北京', '上海', '广州'], 'city', 'gdp');
+// 输出：
+// [
+//   { month: 'Jan', city: '北京', gdp: 3.6 },
+//   { month: 'Jan', city: '上海', gdp: 4.3 },
+//   ...
+// ]
+```
+
+**G2 内置方案**（推荐）：
+```javascript
+chart.options({
+  type: 'interval',
+  data: {
+    type: 'inline',
+    value: wideData,
+    transform: [{
+      type: 'fold',
+      fields: ['北京', '上海', '广州'],
+      key: 'city',
+      value: 'gdp',
+    }],
+  },
+  encode: { x: 'month', y: 'gdp', color: 'city' },
+});
+```
+
+## 模式 2：分组聚合（Group + Aggregate）
+
+**场景**：按某字段分组，对另一字段求和/均值/计数
+
+**JavaScript 方式**：
+```javascript
+// 输入：明细数据
+const orderData = [
+  { month: 'Jan', region: '华东', amount: 1200 },
+  { month: 'Jan', region: '华东', amount: 800 },
+  { month: 'Jan', region: '华南', amount: 950 },
+  { month: 'Feb', region: '华东', amount: 1500 },
+];
+
+function groupSum(data, groupKeys, sumKey) {
+  const map = new Map();
+  data.forEach(row => {
+    const key = groupKeys.map(k => row[k]).join('|');
+    if (!map.has(key)) {
+      const group = Object.fromEntries(groupKeys.map(k => [k, row[k]]));
+      group[sumKey] = 0;
+      map.set(key, group);
+    }
+    map.get(key)[sumKey] += row[sumKey];
+  });
+  return Array.from(map.values());
+}
+
+const aggregated = groupSum(orderData, ['month', 'region'], 'amount');
+// 输出：
+// [
+//   { month: 'Jan', region: '华东', amount: 2000 },
+//   { month: 'Jan', region: '华南', amount: 950 },
+//   { month: 'Feb', region: '华东', amount: 1500 },
+// ]
+```
+
+**G2 内置方案**（使用 mark transform）：
+```javascript
+chart.options({
+  type: 'interval',
+   orderData,
+  encode: { x: 'month', y: 'amount', color: 'region' },
+  transform: [{ type: 'groupX', y: 'sum' }],  // 按 x 分组求和
+});
+```
+
+## 模式 3：百分比计算
+
+**场景**：计算每个类别占总量的百分比（饼图标签、百分比柱状图）
+
+**JavaScript 方式**：
+```javascript
+function addPercentage(data, valueKey, pctKey = 'pct') {
+  const total = data.reduce((sum, d) => sum + (d[valueKey] || 0), 0);
+  return data.map(d => ({
+    ...d,
+    [pctKey]: total > 0 ? ((d[valueKey] / total) * 100).toFixed(1) : '0.0',
+  }));
+}
+
+const dataWithPct = addPercentage(
+  [{ city: '北京', gdp: 3.6 }, { city: '上海', gdp: 4.3 }, { city: '广州', gdp: 2.8 }],
+  'gdp'
+);
+// 输出：[{ city: '北京', gdp: 3.6, pct: '33.6' }, ...]
+```
+
+**G2 内置方案**（百分比柱状图）：
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'city', y: 'gdp', color: 'city' },
+  transform: [{ type: 'normalizeY' }],  // Y 轴归一化为百分比
+});
+```
+
+**在饼图标签中使用百分比**：
+```javascript
+const total = data.reduce((sum, d) => sum + d.value, 0);
+
+chart.options({
+  type: 'interval',
+  data,
+  encode: { y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  coordinate: { type: 'theta' },
+  labels: [{
+    text: (d) => `${d.type}\n${((d.value / total) * 100).toFixed(1)}%`,
+    position: 'outside',
+  }],
+});
+```
+
+## 模式 4：排名 / Top N
+
+**场景**：取数值最大/最小的 N 条数据，用于排名图
+
+**JavaScript 方式**：
+```javascript
+function topN(data, valueKey, n, ascending = false) {
+  return [...data]
+    .sort((a, b) => ascending ? a[valueKey] - b[valueKey] : b[valueKey] - a[valueKey])
+    .slice(0, n);
+}
+
+const top5Cities = topN(cityData, 'gdp', 5);
+```
+
+**G2 内置方案**：
+```javascript
+chart.options({
+  type: 'interval',
+  data: {
+    type: 'inline',
+    value: cityData,
+    transform: [
+      { type: 'sortBy', fields: [['gdp', false]] },  // 按 gdp 降序
+      { type: 'slice', end: 5 },                      // 只取前 5 条
+    ],
+  },
+  encode: { x: 'city', y: 'gdp' },
+});
+```
+
+## 模式 5：时间粒度聚合
+
+**场景**：日粒度数据聚合为周/月/季度
+
+**JavaScript 方式**：
+```javascript
+// 日粒度 → 月粒度聚合
+function aggregateByMonth(data, dateKey, valueKey) {
+  const map = new Map();
+  data.forEach(d => {
+    const date = new Date(d[dateKey]);
+    const monthKey = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}`;
+    if (!map.has(monthKey)) {
+      map.set(monthKey, { month: monthKey, total: 0, count: 0 });
+    }
+    const entry = map.get(monthKey);
+    entry.total += d[valueKey];
+    entry.count += 1;
+  });
+  return Array.from(map.values())
+    .map(({ month, total, count }) => ({
+      month,
+      value: total,
+      avg: total / count,
+    }))
+    .sort((a, b) => a.month.localeCompare(b.month));
+}
+
+// 月粒度 → 季度粒度
+function aggregateByQuarter(data, monthKey, valueKey) {
+  return data.reduce((acc, d) => {
+    const [year, month] = d[monthKey].split('-');
+    const quarter = `${year}-Q${Math.ceil(Number(month) / 3)}`;
+    const existing = acc.find(a => a.quarter === quarter);
+    if (existing) {
+      existing[valueKey] += d[valueKey];
+    } else {
+      acc.push({ quarter, [valueKey]: d[valueKey] });
+    }
+    return acc;
+  }, []);
+}
+```
+
+## 模式 6：数据过滤与条件筛选
+
+**场景**：根据维度/时间范围筛选数据
+
+**JavaScript 方式**：
+```javascript
+function filterData(data, conditions) {
+  return data.filter(d =>
+    conditions.every(({ key, op, value }) => {
+      switch (op) {
+        case 'eq':  return d[key] === value;
+        case 'gt':  return d[key] > value;
+        case 'lt':  return d[key] < value;
+        case 'gte': return d[key] >= value;
+        case 'lte': return d[key] <= value;
+        case 'in':  return value.includes(d[key]);
+        default:    return true;
+      }
+    })
+  );
+}
+
+const filtered = filterData(data, [
+  { key: 'region', op: 'in',  value: ['华东', '华南'] },
+  { key: 'sales',  op: 'gt',  value: 1000 },
+]);
+```
+
+**G2 内置方案**：
+```javascript
+chart.options({
+  type: 'interval',
+  data: {
+    type: 'inline',
+    value: data,
+    transform: [
+      { type: 'filter', callback: (d) => ['华东', '华南'].includes(d.region) && d.sales > 1000 },
+    ],
+  },
+  encode: { x: 'region', y: 'sales' },
+});
+```
+
+**联动过滤示例**：
+```javascript
+document.getElementById('region-select').addEventListener('change', (e) => {
+  const region = e.target.value;
+  const filtered = region === 'all'
+    ? allData
+    : allData.filter(d => d.region === region);
+  chart.changeData(filtered);
+});
+```
+
+## 模式 7：数据归一化（0-1 标准化）
+
+**场景**：多指标对比时，将不同量级的数据归一化到相同范围
+
+**JavaScript 方式**：
+```javascript
+// Min-Max 归一化
+function normalize(data, valueKey, normalizedKey = 'normalized') {
+  const values = data.map(d => d[valueKey]);
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  const range = max - min || 1;
+  return data.map(d => ({
+    ...d,
+    [normalizedKey]: (d[valueKey] - min) / range,
+  }));
+}
+
+// 多指标分别归一化（雷达图/平行坐标准备）
+function normalizeMultiple(data, keys) {
+  return keys.reduce((acc, key) => normalize(acc, key, `${key}_norm`), data);
+}
+```
+
+## 常见错误与修正
+
+### 错误 1：fold 后字段名与 encode 不匹配
+
+```javascript
+// ❌ fold 配置了 key='city', value='gdp'，但 encode 还用原字段名
+chart.options({
+  type: 'interval',
+  data: {
+    type: 'inline',
+    value: wideData,
+    transform: [{ type: 'fold', fields: ['北京', '上海'], key: 'city', value: 'gdp' }],
+  },
+  encode: { color: '北京' },  // ❌ '北京' 字段已被 fold 消除
+});
+
+// ✅ encode 要用 fold 生成的新字段名
+chart.options({
+  type: 'interval',
+  data: {
+    type: 'inline',
+    value: wideData,
+    transform: [{ type: 'fold', fields: ['北京', '上海'], key: 'city', value: 'gdp' }],
+  },
+  encode: { y: 'gdp', color: 'city' },  // ✅ 使用 key/value 配置的字段名
+});
+```
+
+### 错误 2：data transform 与 mark transform 混淆
+
+```javascript
+// ❌ 错误：fold 是数据变换，不应放在 mark transform
+chart.options({
+  type: 'interval',
+   wideData,
+  transform: [{ type: 'fold', fields: ['北京', '上海'] }],  // ❌ 错误位置
+});
+
+// ✅ 正确：fold 放在 data.transform 中
+chart.options({
+  type: 'interval',
+  data: {
+    type: 'inline',
+    value: wideData,
+    transform: [{ type: 'fold', fields: ['北京', '上海'], key: 'city', value: 'gdp' }],
+  },
+  transform: [{ type: 'stackY' }],  // mark transform
+});
+```

package/builtin-skills/antv-g2-chart/references/interactions/g2-interaction-adaptive-filter.md

@@ -0,0 +1,118 @@
+---
+id: "g2-interaction-adaptive-filter"
+title: "G2 AdaptiveFilter 自适应过滤交互"
+description: |
+  adaptiveFilter 是 G2 v5 的交互，当数据量过大导致图表渲染性能下降时，
+  自动对数据进行采样或聚合，保持图表响应流畅。
+  适用于大数据量折线图、散点图等场景，结合 sliderFilter 或 scrollbarFilter 使用效果更佳。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "adaptiveFilter"
+  - "自适应过滤"
+  - "大数据"
+  - "性能优化"
+  - "采样"
+  - "interaction"
+
+related:
+  - "g2-interaction-slider-filter"
+  - "g2-transform-sample"
+  - "g2-mark-line-basic"
+
+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/interaction/adaptive-filter"
+---
+
+## 核心概念
+
+`adaptiveFilter` 监听图表的视口变化和数据规模，当可见数据量超过像素容量时，
+自动应用采样策略（LTTB 算法等）减少渲染点数，避免过度绘制导致的性能问题。
+
+通常与 `sliderFilter` 或 `scrollbarFilter` 配合使用，实现"滑动时自动适配数据量"。
+
+## 基本用法
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 800, height: 400 });
+
+chart.options({
+  type: 'line',
+  data: largeDataArray,   // 数千条以上数据
+  encode: { x: 'date', y: 'value' },
+  interaction: {
+    adaptiveFilter: true,   // 启用自适应过滤
+  },
+});
+
+chart.render();
+```
+
+## 与 sliderFilter 配合使用
+
+```javascript
+chart.options({
+  type: 'view',
+  data: largeDataArray,
+  children: [
+    {
+      type: 'line',
+      encode: { x: 'date', y: 'value' },
+    },
+  ],
+  interaction: {
+    sliderFilter: {
+      x: { labelFormatter: (v) => new Date(v).toLocaleDateString() },
+    },
+    adaptiveFilter: true,   // 滑动窗口过滤后自动采样
+  },
+  slider: {
+    x: { values: [0, 0.3] },   // 初始显示前 30% 数据
+  },
+});
+```
+
+## 配置项
+
+```javascript
+chart.options({
+  interaction: {
+    adaptiveFilter: {
+      // 触发自适应采样的数据量阈值（默认 2000）
+      // 可见数据点数超过此值时开始采样
+      maxPoints: 2000,
+    },
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：小数据量也启用 adaptiveFilter 导致数据被意外过滤
+```javascript
+// ❌ 不必要：数据量小时无需启用，反而可能造成数据丢失误解
+chart.options({
+   smallData,   // 只有 50 条数据
+  interaction: { adaptiveFilter: true },
+});
+
+// ✅ 仅在大数据量场景启用
+// adaptiveFilter 适用于 > 1000 条数据的场景
+chart.options({
+  data: massiveData,
+  interaction: { adaptiveFilter: true },
+});
+```

package/builtin-skills/antv-g2-chart/references/interactions/g2-interaction-brush-axis.md

@@ -0,0 +1,112 @@
+---
+id: "g2-interaction-brush-axis"
+title: "G2 轴刷选高亮（brushAxisHighlight）"
+description: |
+  brushAxisHighlight 在平行坐标系中，对单个轴进行区间刷选，
+  高亮满足所有轴选区条件的折线。是平行坐标图最常见的多维过滤交互，
+  可在多个轴上同时设置区间，实现多维度联合过滤。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "brushAxisHighlight"
+  - "轴刷选"
+  - "平行坐标"
+  - "多维过滤"
+  - "interaction"
+
+related:
+  - "g2-coord-parallel"
+  - "g2-interaction-brush-filter"
+
+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/interaction/brush-axis-highlight"
+---
+
+## 最小可运行示例
+
+```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 },
+  { name: '产品E', price: 150, sales: 220, rating: 4.2, stock: 65 },
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+chart.options({
+  type: 'line',
+  data,
+  encode: {
+    position: ['price', 'sales', 'rating', 'stock'],
+    color: 'name',
+  },
+  coordinate: { type: 'parallel' },
+  style: { lineWidth: 1.5, strokeOpacity: 0.7 },
+  interaction: {
+    brushAxisHighlight: true,   // 在每个轴上可拖拽设置过滤区间
+  },
+});
+
+chart.render();
+```
+
+## 与 parallel 坐标系的标准组合
+
+```javascript
+chart.options({
+  type: 'line',
+  data: carData,
+  encode: {
+    position: ['mpg', 'cylinders', 'displacement', 'horsepower', 'weight', 'acceleration'],
+    color: 'origin',
+  },
+  coordinate: { type: 'parallel' },
+  style: { lineWidth: 1, strokeOpacity: 0.5 },
+  interaction: {
+    brushAxisHighlight: {
+      // 未被选中的线条的样式
+      unhighlightedOpacity: 0.1,
+    },
+  },
+  legend: { color: { position: 'top' } },
+});
+```
+
+## 常见错误与修正
+
+### 错误：在非平行坐标系图表上使用 brushAxisHighlight
+```javascript
+// ❌ brushAxisHighlight 专门为平行坐标系设计
+chart.options({
+  type: 'line',
+  encode: { x: 'date', y: 'value' },   // 普通折线图
+  coordinate: { type: 'cartesian' },
+  interaction: { brushAxisHighlight: true },  // ❌ 普通图表没有"轴"可以刷选
+});
+
+// ✅ 应使用普通的 brushHighlight 或 brushFilter
+chart.options({
+  interaction: { brushHighlight: true },  // ✅ 普通矩形刷选
+});
+
+// ✅ 平行坐标图才用 brushAxisHighlight
+chart.options({
+  coordinate: { type: 'parallel' },
+  interaction: { brushAxisHighlight: true },  // ✅
+});
+```