@loom-framework/core 0.1.0-alpha.17 → 0.1.0-alpha.171

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

@@ -0,0 +1,190 @@
+---
+id: "g2-data-ema"
+title: "G2 EMA 指数移动平均"
+description: |
+  EMA（Exponential Moving Average）数据变换对数据进行指数移动平均平滑处理。
+  通过对最近的数据点赋予更高的权重，减少数据波动性，更清晰地观察趋势。
+  配置在 data.transform 中。
+
+library: "g2"
+version: "5.x"
+category: "data"
+tags:
+  - "ema"
+  - "指数移动平均"
+  - "平滑"
+  - "趋势"
+  - "数据变换"
+  - "data transform"
+
+related:
+  - "g2-mark-line"
+
+use_cases:
+  - "时间序列数据平滑"
+  - "金融数据技术分析"
+  - "训练指标平滑展示"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-27"
+updated: "2025-03-27"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/data/ema"
+---
+
+## 核心概念
+
+**EMA 是数据变换（Data Transform），不是标记变换（Mark Transform）**
+
+- 数据变换配置在 `data.transform` 中
+- 指数移动平均是一种数据平滑算法
+
+**公式**：EMA_t = α × P_t + (1 - α) × EMA_{t-1}
+
+**注意事项**：
+- G2 中 `alpha` 越接近 1，平滑效果越明显
+- `alpha` 越接近 0，EMA 越接近原始数据
+- `field` 字段必须为数值型
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 700, height: 400 });
+
+const data = [
+  { t: 0, y: 100 },
+  { t: 1, y: 180 },
+  { t: 2, y: 120 },
+  { t: 3, y: 200 },
+  { t: 4, y: 150 },
+  { t: 5, y: 250 },
+];
+
+chart.options({
+  type: 'view',
+  children: [
+    {
+      type: 'line',
+       {
+        type: 'inline',
+        value: data,
+        transform: [
+          {
+            type: 'ema',
+            field: 'y',      // 要平滑的字段
+            alpha: 0.6,      // 平滑因子
+            as: 'emaY',      // 输出字段名
+          },
+        ],
+      },
+      encode: { x: 't', y: 'emaY' },
+      style: { stroke: '#f90' },
+    },
+    {
+      type: 'line',
+       { type: 'inline', value: data },
+      encode: { x: 't', y: 'y' },
+      style: { stroke: '#ccc', lineDash: [4, 2] },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 配置项
+
+| 属性  | 描述                                 | 类型     | 默认值     | 必选 |
+| ----- | ------------------------------------ | -------- | ---------- | ---- |
+| field | 需要平滑的字段名                     | `string` | `'y'`      | ✓    |
+| alpha | 平滑因子，控制平滑程度（越大越平滑） | `number` | `0.6`      |      |
+| as    | 生成的新字段名，若不指定将覆盖原字段 | `string` | 同 `field` |      |
+
+## 金融行情平滑
+
+```javascript
+chart.options({
+  type: 'view',
+  children: [
+    {
+      type: 'line',
+       {
+        type: 'fetch',
+        value: 'https://example.com/stock.csv',
+        transform: [
+          {
+            type: 'ema',
+            field: 'close',
+            alpha: 0.7,
+            as: 'emaClose',
+          },
+        ],
+      },
+      encode: { x: 'date', y: 'emaClose' },
+      style: { stroke: '#007aff', lineWidth: 2 },
+    },
+    {
+      type: 'line',
+       { type: 'fetch', value: 'https://example.com/stock.csv' },
+      encode: { x: 'date', y: 'close' },
+      style: { stroke: '#bbb', lineDash: [4, 2] },
+    },
+  ],
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：ema 放在 mark transform 中
+
+```javascript
+// ❌ 错误：ema 是数据变换，不能放在 mark 的 transform 中
+chart.options({
+  type: 'line',
+  data,
+  transform: [{ type: 'ema', field: 'y' }],  // ❌ 错误位置
+});
+
+// ✅ 正确：ema 放在 data.transform 中
+chart.options({
+  type: 'line',
+   {
+    type: 'inline',
+    value: data,
+    transform: [{ type: 'ema', field: 'y', as: 'emaY' }],  // ✅ 正确
+  },
+});
+```
+
+### 错误 2：字段不是数值型
+
+```javascript
+// ❌ 错误：field 字段必须为数值型
+ {
+  transform: [{ type: 'ema', field: 'name' }],  // ❌ name 是字符串
+}
+
+// ✅ 正确：使用数值型字段
+ {
+  transform: [{ type: 'ema', field: 'value' }],
+}
+```
+
+### 错误 3：忘记设置 as 字段
+
+```javascript
+// ⚠️ 注意：不设置 as 会覆盖原字段
+data: {
+  transform: [{ type: 'ema', field: 'y' }],  // y 字段会被覆盖
+}
+encode: { y: 'y' },  // 使用的是平滑后的数据
+
+// ✅ 推荐：设置 as 保留原字段
+ {
+  transform: [{ type: 'ema', field: 'y', as: 'emaY' }],
+}
+// 可以同时展示原始数据和平滑数据
+```

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

@@ -0,0 +1,167 @@
+---
+id: "g2-data-fetch"
+title: "G2 Fetch 远程数据获取"
+description: |
+  Fetch 数据连接器从远程接口获取数据，支持 JSON、CSV 等格式解析。
+  通过设置 data.type 为 'fetch' 启用，让数据源具备动态性。
+
+library: "g2"
+version: "5.x"
+category: "data"
+tags:
+  - "fetch"
+  - "远程数据"
+  - "JSON"
+  - "CSV"
+  - "数据连接器"
+  - "connector"
+
+related:
+  - "g2-data-filter"
+  - "g2-data-fold"
+
+use_cases:
+  - "从 API 获取动态数据"
+  - "加载远程 CSV 文件"
+  - "大屏监控数据展示"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-27"
+updated: "2025-03-27"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/data/fetch"
+---
+
+## 核心概念
+
+**Fetch 是数据连接器（Data Connector），不是数据变换**
+
+- 通过设置 `data.type: 'fetch'` 启用
+- 支持 JSON、CSV 格式自动解析
+- 远程地址不能设置鉴权
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 700, height: 400 });
+
+chart.options({
+  type: 'point',
+   {
+    type: 'fetch',
+    value: 'https://gw.alipayobjects.com/os/antvdemo/assets/data/scatter.json',
+  },
+  encode: {
+    x: 'weight',
+    y: 'height',
+    color: 'gender',
+  },
+});
+
+chart.render();
+```
+
+## 配置项
+
+| 属性      | 描述                                              | 类型               | 默认值                         |
+| --------- | ------------------------------------------------- | ------------------ | ------------------------------ |
+| value     | fetch 请求的网络地址                              | `string`           | -                              |
+| format    | 远程文件的数据格式类型，决定用什么方式解析        | `'json' \| 'csv'`  | 默认取 value 末尾 `.` 后的后缀 |
+| delimiter | 如果是 csv 文件，解析的时候分割符                 | `string`           | `,`                            |
+| autoType  | 如果是 csv 文件，解析的时候是否自动判断列数据类型 | `boolean`          | `true`                         |
+| transform | 对加载后的数据进行变换操作                        | `DataTransform[]`  | `[]`                           |
+
+## 加载 CSV 文件
+
+```javascript
+chart.options({
+  type: 'line',
+   {
+    type: 'fetch',
+    value: 'https://example.com/data.csv',
+    format: 'csv',           // 指定格式
+    delimiter: ',',          // 分隔符
+    autoType: true,          // 自动推断类型
+    transform: [
+      { type: 'filter', callback: (d) => d.value > 0 },
+    ],
+  },
+  encode: { x: 'date', y: 'value' },
+});
+```
+
+## 结合 transform 使用
+
+```javascript
+chart.options({
+  type: 'interval',
+   {
+    type: 'fetch',
+    value: 'https://example.com/sales.json',
+    transform: [
+      { type: 'filter', callback: (d) => d.year === 2024 },
+      { type: 'sortBy', fields: [['amount', false]] },
+      { type: 'slice', end: 10 },
+    ],
+  },
+  encode: { x: 'product', y: 'amount' },
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：远程地址需要鉴权
+
+```javascript
+// ❌ 错误：G2 fetch 不支持鉴权
+data: {
+  type: 'fetch',
+  value: 'https://api.example.com/private-data',  // 需要 token
+}
+
+// ✅ 正确：使用公开的 API 或在服务端代理
+ {
+  type: 'fetch',
+  value: 'https://public-api.example.com/data',  // 无需鉴权
+}
+```
+
+### 错误 2：format 与文件格式不匹配
+
+```javascript
+// ❌ 错误：format 与实际格式不匹配
+data: {
+  type: 'fetch',
+  value: 'https://example.com/data.json',
+  format: 'csv',  // ❌ 实际是 JSON
+}
+
+// ✅ 正确：让 G2 自动推断或指定正确格式
+ {
+  type: 'fetch',
+  value: 'https://example.com/data.json',
+  // format 默认根据后缀推断为 'json'
+}
+
+// 或显式指定
+ {
+  type: 'fetch',
+  value: 'https://example.com/api/data',  // 无后缀
+  format: 'json',  // 显式指定
+}
+```
+
+### 错误 3：CORS 问题
+
+```javascript
+// ❌ 错误：跨域请求被阻止
+// 浏览器控制台会显示 CORS 错误
+
+// ✅ 解决方案：
+// 1. 服务端配置 CORS 头
+// 2. 使用同源请求
+// 3. 使用代理服务器
+```

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

@@ -0,0 +1,212 @@
+---
+id: "g2-data-filter"
+title: "G2 Filter 数据过滤"
+description: |
+  filter 数据变换在数据加载阶段根据条件过滤数据，只保留满足条件的行。
+  与 JavaScript 的 Array.filter 类似，接受一个断言函数（predicate）。
+  配置在 data.transform 中，在渲染前预处理数据。
+
+library: "g2"
+version: "5.x"
+category: "data"
+tags:
+  - "filter"
+  - "过滤"
+  - "数据筛选"
+  - "条件过滤"
+  - "data transform"
+
+related:
+  - "g2-data-fold"
+  - "g2-data-sort"
+  - "g2-interaction-brush"
+
+use_cases:
+  - "只展示满足条件的数据子集（如值大于阈值的数据）"
+  - "排除异常值或空值"
+  - "在数据加载阶段做分类筛选"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/data/filter"
+---
+
+## 核心概念
+
+**filter 是数据变换（Data Transform），不是标记变换（Mark Transform）**
+
+- 数据变换配置在 `data.transform` 中
+- 在数据加载阶段执行，影响所有使用该数据的标记
+- 与 mark transform 不同，数据变换是数据预处理，不涉及视觉通道
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+chart.options({
+  type: 'interval',
+   {
+    type: 'inline',
+    value: [
+      { genre: 'Sports', sold: 275 },
+      { genre: 'Strategy', sold: 115 },
+      { genre: 'Action', sold: 120 },
+      { genre: 'RPG', sold: 98 },
+      { genre: 'Shooter', sold: 35 },
+    ],
+    transform: [
+      {
+        type: 'filter',
+        callback: (d) => d.sold >= 100,  // 只保留销量 ≥ 100 的数据
+      },
+    ],
+  },
+  encode: { x: 'genre', y: 'sold', color: 'genre' },
+});
+
+chart.render();
+```
+
+## 排除空值 / 异常值
+
+```javascript
+chart.options({
+  type: 'line',
+   {
+    type: 'inline',
+    value: rawData,
+    transform: [
+      {
+        type: 'filter',
+        // 过滤掉 null、undefined、NaN
+        callback: (d) => d.value != null && !isNaN(d.value) && d.value > 0,
+      },
+    ],
+  },
+  encode: { x: 'date', y: 'value' },
+});
+```
+
+## 多条件过滤
+
+```javascript
+chart.options({
+  type: 'point',
+   {
+    type: 'inline',
+    value: allData,
+    transform: [
+      {
+        type: 'filter',
+        callback: (d) => d.category === 'A' && d.y > 50,
+      },
+    ],
+  },
+  encode: { x: 'x', y: 'y', color: 'category' },
+});
+```
+
+## 与 fetch 连用
+
+```javascript
+chart.options({
+  type: 'point',
+   {
+    type: 'fetch',
+    value: 'https://example.com/data.json',
+    transform: [
+      {
+        type: 'filter',
+        callback: (d) => d.value > 100,
+      },
+    ],
+  },
+  encode: { x: 'x', y: 'y' },
+});
+```
+
+## 多个数据变换组合
+
+```javascript
+chart.options({
+  type: 'interval',
+   {
+    type: 'inline',
+    value: rawData,
+    transform: [
+      { type: 'filter', callback: (d) => d.value != null },
+      { type: 'sort', callback: (a, b) => b.value - a.value },
+      { type: 'slice', start: 0, end: 10 },  // 只取前 10 条
+    ],
+  },
+  encode: { x: 'category', y: 'value' },
+});
+```
+
+## 配置项
+
+| 属性     | 描述                                 | 类型                                           | 默认值                                                     |
+| -------- | ------------------------------------ | ---------------------------------------------- | ---------------------------------------------------------- |
+| callback | 过滤函数，返回 true 保留该行数据     | `(d: any, idx: number, arr: any[]) => boolean` | `(d) => d !== undefined && d !== null && !Number.isNaN(d)` |
+
+## 常见错误与修正
+
+### 错误 1：filter 放在 mark transform 中
+
+```javascript
+// ❌ 错误：filter 是数据变换，不能放在 mark 的 transform 中
+chart.options({
+  type: 'interval',
+   myData,
+  transform: [{ type: 'filter', callback: (d) => d.value > 100 }],  // ❌ 错误位置
+});
+
+// ✅ 正确：filter 放在 data.transform 中
+chart.options({
+  type: 'interval',
+   {
+    type: 'inline',
+    value: myData,
+    transform: [{ type: 'filter', callback: (d) => d.value > 100 }],  // ✅ 正确
+  },
+});
+```
+
+### 错误 2：callback 不是函数
+
+```javascript
+// ❌ 错误：callback 必须是函数
+data: {
+  transform: [{ type: 'filter', callback: 'value > 100' }],  // ❌ 字符串
+}
+
+// ✅ 正确：使用箭头函数
+ {
+  transform: [{ type: 'filter', callback: (d) => d.value > 100 }],  // ✅
+}
+```
+
+### 错误 3：简写 data 无法配置 transform
+
+```javascript
+// ❌ 错误：简写 data 无法配置 transform
+chart.options({
+  data: myData,  // 简写形式
+  // 无法添加 transform
+});
+
+// ✅ 正确：使用完整 data 配置
+chart.options({
+  data: {
+    type: 'inline',
+    value: myData,
+    transform: [{ type: 'filter', callback: (d) => d.value > 100 }],
+  },
+});
+```