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

package/builtin-skills/antv-g2-chart/references/palette/g2-palette-category10.md

@@ -0,0 +1,196 @@
+---
+id: "g2-palette-category10"
+title: "G2 Category10 调色板"
+description: |
+  AntV 经典 10 色调色板，用于分类数据的颜色映射。
+  包含 10 种精心设计的颜色，适合大多数分类可视化场景。
+
+library: "g2"
+version: "5.x"
+category: "palette"
+tags:
+  - "调色板"
+  - "palette"
+  - "颜色"
+  - "分类"
+  - "10色"
+
+related:
+  - "g2-palette-category20"
+  - "g2-scale-ordinal"
+  - "g2-theme-builtin"
+
+use_cases:
+  - "分类数据的默认颜色"
+  - "柱状图、折线图的颜色映射"
+  - "需要 10 种以内颜色的场景"
+
+anti_patterns:
+  - "超过 10 个类别时应考虑 Category20 或自定义调色板"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/palette"
+---
+
+## 核心概念
+
+Category10 是 AntV 的默认分类调色板：
+- 包含 10 种颜色
+- 颜色经过精心设计，易于区分
+- 适合大多数分类可视化场景
+
+**颜色列表：**
+```
+#5B8FF9  - 蓝色
+#5AD8A6  - 绿色
+#5D7092  - 灰蓝色
+#F6BD16  - 黄色
+#6F5EF9  - 紫色
+#6DC8EC  - 青色
+#945FB9  - 深紫色
+#FF9845  - 橙色
+#1E9493  - 深青色
+#FF99C3  - 粉色
+```
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'interval',
+  data: [
+    { category: 'A', value: 100 },
+    { category: 'B', value: 150 },
+    { category: 'C', value: 80 },
+  ],
+  encode: {
+    x: 'category',
+    y: 'value',
+    color: 'category',
+  },
+  // Category10 是默认调色板，无需显式指定
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 显式指定调色板
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+  scale: {
+    color: {
+      type: 'ordinal',
+      range: 'category10',  // 显式指定
+    },
+  },
+});
+```
+
+### 自定义颜色范围
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+  scale: {
+    color: {
+      type: 'ordinal',
+      range: [
+        '#5B8FF9',
+        '#5AD8A6',
+        '#5D7092',
+        '#F6BD16',
+        '#6F5EF9',
+      ],
+    },
+  },
+});
+```
+
+### 使用 Theme 配置
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+  theme: {
+    defaultCategory10: 'category10',
+  },
+});
+```
+
+## 完整颜色参考
+
+| 索引 | 颜色值 | 颜色名 |
+|------|--------|--------|
+| 0 | #5B8FF9 | 蓝色 |
+| 1 | #5AD8A6 | 绿色 |
+| 2 | #5D7092 | 灰蓝色 |
+| 3 | #F6BD16 | 黄色 |
+| 4 | #6F5EF9 | 紫色 |
+| 5 | #6DC8EC | 青色 |
+| 6 | #945FB9 | 深紫色 |
+| 7 | #FF9845 | 橙色 |
+| 8 | #1E9493 | 深青色 |
+| 9 | #FF99C3 | 粉色 |
+
+## 与 Category20 的对比
+
+| 特性 | Category10 | Category20 |
+|------|------------|------------|
+| 颜色数量 | 10 | 20 |
+| 颜色风格 | 饱和度一致 | 饱和度交替 |
+| 适用场景 | ≤10 类别 | 10-20 类别 |
+| 默认使用 | 是 | 否 |
+
+## 常见错误与修正
+
+### 错误 1：类别超过 10 个
+
+```javascript
+// ⚠️ 注意：超过 10 个类别会循环使用颜色
+// 类别 11 会使用与类别 1 相同的颜色
+
+// ✅ 解决方案 1：使用 Category20
+scale: {
+  color: { type: 'ordinal', range: 'category20' }
+}
+
+// ✅ 解决方案 2：自定义更多颜色
+scale: {
+  color: {
+    type: 'ordinal',
+    range: [...customColors]
+  }
+}
+```
+
+### 错误 2：颜色值格式错误
+
+```javascript
+// ❌ 错误：颜色值格式不正确
+range: ['rgb(91, 143, 249)', ...]
+
+// ✅ 正确：使用标准 HEX 格式
+range: ['#5B8FF9', ...]
+```

package/builtin-skills/antv-g2-chart/references/palette/g2-palette-category20.md

@@ -0,0 +1,238 @@
+---
+id: "g2-palette-category20"
+title: "G2 Category20 调色板"
+description: |
+  AntV 经典 20 色调色板，用于分类数据的颜色映射。
+  包含 20 种颜色，采用饱和度交替的设计，适合更多类别的可视化场景。
+
+library: "g2"
+version: "5.x"
+category: "palette"
+tags:
+  - "调色板"
+  - "palette"
+  - "颜色"
+  - "分类"
+  - "20色"
+
+related:
+  - "g2-palette-category10"
+  - "g2-scale-ordinal"
+  - "g2-theme-builtin"
+
+use_cases:
+  - "超过 10 个类别的颜色映射"
+  - "需要更多颜色区分的场景"
+  - "复杂分类数据可视化"
+
+anti_patterns:
+  - "类别较少时建议使用 Category10"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/palette"
+---
+
+## 核心概念
+
+Category20 是 AntV 的扩展分类调色板：
+- 包含 20 种颜色
+- 采用饱和度交替的设计模式
+- 适合 10-20 个类别的场景
+
+**设计特点：**
+- 前半部分为饱和色（与 Category10 一致）
+- 后半部分为低饱和度色
+- 交替使用可增加区分度
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'interval',
+  data: [
+    { category: 'A', value: 100 },
+    { category: 'B', value: 150 },
+    // ... 更多类别
+  ],
+  encode: {
+    x: 'category',
+    y: 'value',
+    color: 'category',
+  },
+  scale: {
+    color: {
+      type: 'ordinal',
+      range: 'category20',
+    },
+  },
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 显式指定颜色范围
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+  scale: {
+    color: {
+      type: 'ordinal',
+      range: [
+        '#5B8FF9', '#CDDDFD',
+        '#5AD8A6', '#CDF3E4',
+        '#5D7092', '#CED4DE',
+        '#F6BD16', '#FCEBB9',
+        '#6F5EF9', '#D3CEFD',
+        '#6DC8EC', '#D3EEF9',
+        '#945FB9', '#DECFEA',
+        '#FF9845', '#FFE0C7',
+        '#1E9493', '#BBDEDE',
+        '#FF99C3', '#FFE0ED',
+      ],
+    },
+  },
+});
+```
+
+### 结合自定义颜色
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+  scale: {
+    color: {
+      type: 'ordinal',
+      range: [
+        ...customColors.slice(0, 10),
+        '#5B8FF9', '#CDDDFD', // 补充 Category20 的颜色
+        // ...
+      ],
+    },
+  },
+});
+```
+
+## 完整颜色参考
+
+| 索引 | 颜色值 | 饱和度 |
+|------|--------|--------|
+| 0 | #5B8FF9 | 高 |
+| 1 | #CDDDFD | 低 |
+| 2 | #5AD8A6 | 高 |
+| 3 | #CDF3E4 | 低 |
+| 4 | #5D7092 | 高 |
+| 5 | #CED4DE | 低 |
+| 6 | #F6BD16 | 高 |
+| 7 | #FCEBB9 | 低 |
+| 8 | #6F5EF9 | 高 |
+| 9 | #D3CEFD | 低 |
+| 10 | #6DC8EC | 高 |
+| 11 | #D3EEF9 | 低 |
+| 12 | #945FB9 | 高 |
+| 13 | #DECFEA | 低 |
+| 14 | #FF9845 | 高 |
+| 15 | #FFE0C7 | 低 |
+| 16 | #1E9493 | 高 |
+| 17 | #BBDEDE | 低 |
+| 18 | #FF99C3 | 高 |
+| 19 | #FFE0ED | 低 |
+
+## 与 Category10 的对比
+
+| 特性 | Category10 | Category20 |
+|------|------------|------------|
+| 颜色数量 | 10 | 20 |
+| 颜色风格 | 饱和度一致 | 饱和度交替 |
+| 适用场景 | ≤10 类别 | 10-20 类别 |
+| 默认使用 | 是 | 否 |
+| 区分难度 | 较易 | 需注意相邻色 |
+
+## 设计建议
+
+### 类别数量建议
+
+| 类别数量 | 推荐调色板 |
+|---------|-----------|
+| 1-5 | Category10 |
+| 6-10 | Category10 |
+| 11-15 | Category20 |
+| 16-20 | Category20 |
+| >20 | 自定义或分组 |
+
+### 使用技巧
+
+```javascript
+// 技巧：利用饱和度交替增加区分度
+// 将重要类别放在高饱和度位置（偶数索引）
+
+// 例如：高亮重要类别
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+  scale: {
+    color: {
+      type: 'ordinal',
+      range: [
+        '#5B8FF9',  // 高饱和 - 类别 A
+        '#CDDDFD',  // 低饱和 - 类别 B
+        '#5AD8A6',  // 高饱和 - 类别 C（重要）
+        // ...
+      ],
+    },
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：类别超过 20 个
+
+```javascript
+// ⚠️ 注意：超过 20 个类别会循环使用颜色
+
+// ✅ 解决方案 1：自定义更多颜色
+scale: {
+  color: {
+    type: 'ordinal',
+    range: [...30colors]
+  }
+}
+
+// ✅ 解决方案 2：合并小类别
+// 将小类别合并为"其他"类别
+```
+
+### 错误 2：相邻颜色区分度不够
+
+```javascript
+// ⚠️ 注意：相邻的低饱和度颜色可能难以区分
+
+// ✅ 解决方案：调整 domain 顺序
+scale: {
+  color: {
+    type: 'ordinal',
+    domain: ['A', 'C', 'E', 'B', 'D'],  // 交替高/低饱和度
+    range: 'category20'
+  }
+}
+```

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

@@ -0,0 +1,181 @@
+---
+id: "g2-pattern-performance"
+title: "G2 大数据量性能优化"
+description: |
+  G2 处理大量数据时的性能优化策略：数据预聚合、LTTB 降采样、
+  Canvas 渲染器确认、高频实时数据节流更新等。
+  提供各场景的数据量阈值参考和具体优化方案。
+
+library: "g2"
+version: "5.x"
+category: "patterns"
+tags:
+  - "性能优化"
+  - "performance"
+  - "大数据"
+  - "Canvas"
+  - "降采样"
+  - "聚合"
+
+related:
+  - "g2-core-chart-init"
+  - "g2-data-transform-patterns"
+
+use_cases:
+  - "图表数据量超过万条时的优化"
+  - "实时数据流的高频更新场景"
+
+difficulty: "advanced"
+completeness: "full"
+---
+
+## 数据量阈值参考
+
+| 场景 | 数据量 | 建议方案 |
+|------|--------|---------|
+| 折线图 | < 1,000 点 | 直接渲染 |
+| 折线图 | 1,000 ~ 10,000 点 | 降采样到 500 点以内 |
+| 折线图 | > 10,000 点 | 后端聚合 + 时间范围过滤 |
+| 散点图 | < 5,000 点 | 直接渲染 |
+| 散点图 | 5,000 ~ 50,000 点 | 开启 Canvas 渲染 + 降采样 |
+
+## 数据预聚合（最重要的优化）
+
+```javascript
+// 10 万条日粒度数据 → 聚合为 365 条月粒度
+function aggregateTimeSeries(data, dateKey, valueKey, granularity = 'month') {
+  const getGroupKey = (dateStr) => {
+    const d = new Date(dateStr);
+    if (granularity === 'month') {
+      return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
+    }
+    if (granularity === 'quarter') {
+      return `${d.getFullYear()}-Q${Math.ceil((d.getMonth() + 1) / 3)}`;
+    }
+    return d.getFullYear().toString();
+  };
+
+  const groups = {};
+  data.forEach(d => {
+    const key = getGroupKey(d[dateKey]);
+    if (!groups[key]) groups[key] = { date: key, sum: 0, count: 0, min: Infinity, max: -Infinity };
+    groups[key].sum += d[valueKey];
+    groups[key].count += 1;
+    groups[key].min = Math.min(groups[key].min, d[valueKey]);
+    groups[key].max = Math.max(groups[key].max, d[valueKey]);
+  });
+
+  return Object.values(groups)
+    .map(g => ({ date: g.date, value: g.sum / g.count, min: g.min, max: g.max }))
+    .sort((a, b) => a.date.localeCompare(b.date));
+}
+
+chart.options({
+  data: aggregateTimeSeries(rawData, 'timestamp', 'value'),
+  type: 'line',
+  encode: { x: 'date', y: 'value' },
+});
+```
+
+## 折线图降采样（LTTB 算法）
+
+```javascript
+// Largest Triangle Three Buckets (LTTB) 降采样
+// 保留视觉上最重要的 N 个点，同时保持折线形状
+function lttb(data, threshold) {
+  const dataLength = data.length;
+  if (threshold >= dataLength || threshold === 0) return data;
+
+  const sampled = [];
+  let sampledIndex = 0;
+  const bucketSize = (dataLength - 2) / (threshold - 2);
+  let a = 0;
+  sampled[sampledIndex++] = data[a];
+
+  for (let i = 0; i < threshold - 2; i++) {
+    const rangeStart = Math.floor((i + 1) * bucketSize) + 1;
+    const rangeEnd = Math.min(Math.floor((i + 2) * bucketSize) + 1, dataLength);
+
+    let avgX = 0, avgY = 0;
+    const avgRangeStart = Math.floor((i + 1) * bucketSize) + 1;
+    const avgRangeEnd = Math.min(Math.floor((i + 2) * bucketSize) + 1, dataLength);
+    for (let j = avgRangeStart; j < avgRangeEnd; j++) {
+      avgX += data[j].x;
+      avgY += data[j].y;
+    }
+    avgX /= (avgRangeEnd - avgRangeStart);
+    avgY /= (avgRangeEnd - avgRangeStart);
+
+    let maxArea = -1;
+    let nextA = rangeStart;
+    const pointAX = data[a].x;
+    const pointAY = data[a].y;
+    for (let j = rangeStart; j < rangeEnd; j++) {
+      const area = Math.abs(
+        (pointAX - avgX) * (data[j].y - pointAY) -
+        (pointAX - data[j].x) * (avgY - pointAY)
+      );
+      if (area > maxArea) { maxArea = area; nextA = j; }
+    }
+    sampled[sampledIndex++] = data[nextA];
+    a = nextA;
+  }
+  sampled[sampledIndex++] = data[dataLength - 1];
+  return sampled;
+}
+
+// 10000 个点降采样到 500 个
+const sampledData = lttb(rawData, 500);
+chart.options({  sampledData, type: 'line', encode: { x: 'x', y: 'y' } });
+```
+
+## 确认使用 Canvas 渲染器
+
+```javascript
+// G2 默认使用 Canvas 渲染，比 SVG 快得多
+// 大数据量时确认没有被切换为 SVG
+const chart = new Chart({
+  container: 'container',
+  renderer: 'canvas',   // 默认，大数据量下比 SVG 快 5-10x
+  width: 800,
+  height: 400,
+});
+```
+
+## 高频实时数据更新优化
+
+```javascript
+// 使用 requestAnimationFrame 节流（最多每帧更新一次）
+let pendingData = null;
+let rafId = null;
+
+function updateChart(newData) {
+  pendingData = newData;
+
+  if (!rafId) {
+    rafId = requestAnimationFrame(() => {
+      if (pendingData) {
+        chart.changeData(pendingData);
+        pendingData = null;
+      }
+      rafId = null;
+    });
+  }
+}
+
+// 模拟实时数据流（每 100ms 有新数据）
+setInterval(() => {
+  const newPoint = { time: Date.now(), value: Math.random() * 100 };
+  updateChart([...currentData.slice(-500), newPoint]);  // 只保留最近 500 个点
+}, 100);
+```
+
+## 常见错误与修正
+
+```javascript
+// ❌ 10 万行数据直接传给 G2，页面卡死
+chart.options({ data: tenThousandRows });
+
+// ✅ 先聚合/降采样到合理数量（< 1000 点）
+chart.options({ data: aggregateTimeSeries(tenThousandRows, 'date', 'value') });
+```