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

package/builtin-skills/antv-g2-chart/references/marks/g2-mark-histogram.md

@@ -0,0 +1,186 @@
+---
+id: "g2-mark-histogram"
+title: "G2 Histogram Mark"
+description: |
+  直方图 Mark。使用 rect 标记配合 binX 转换，展示连续数值数据的分布情况。
+  适用于统计分析、数据分布探索等场景。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "直方图"
+  - "histogram"
+  - "分布"
+  - "统计"
+
+related:
+  - "g2-mark-boxplot"
+  - "g2-transform-binx"
+
+use_cases:
+  - "数据分布分析"
+  - "统计分析"
+  - "频数统计"
+
+anti_patterns:
+  - "分类数据比较应使用柱状图"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/mark/histogram"
+---
+
+## 核心概念
+
+直方图用于展示连续数值数据的分布情况。与柱状图不同：
+- 直方图使用 `rect` 标记，支持 `x` 和 `x1` 通道表示区间
+- 必须配合 `binX` 转换，自动分箱统计
+- 柱子之间无间隔，表示数据连续
+
+**关键要素：**
+- `rect` 标记：支持区间表示
+- `binX` 转换：自动分箱统计
+- `x1` 通道：表示区间结束位置
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  autoFit: true,
+});
+
+chart.options({
+  type: 'rect',
+  data: {
+    type: 'fetch',
+    value: 'https://gw.alipayobjects.com/os/antvdemo/assets/data/diamond.json',
+  },
+  encode: {
+    x: 'carat',
+    y: 'count',
+  },
+  transform: [
+    { type: 'binX', y: 'count' },
+  ],
+  style: {
+    fill: '#1890FF',
+    fillOpacity: 0.9,
+  },
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 指定分箱数量
+
+```javascript
+chart.options({
+  type: 'rect',
+  data,
+  encode: { x: 'value', y: 'count' },
+  transform: [
+    { type: 'binX', y: 'count', thresholds: 30 },  // 指定分箱数量
+  ],
+});
+```
+
+### 多分布对比
+
+```javascript
+chart.options({
+  type: 'rect',
+  data,
+  encode: {
+    x: 'price',
+    y: 'count',
+    color: 'group',
+  },
+  transform: [
+    { type: 'binX', y: 'count', groupBy: ['group'] },
+  ],
+  style: { fillOpacity: 0.7 },
+});
+```
+
+### 带坐标轴标题
+
+```javascript
+chart.options({
+  type: 'rect',
+  data,
+  encode: { x: 'carat', y: 'count' },
+  transform: [{ type: 'binX', y: 'count' }],
+  axis: {
+    x: { title: '钻石重量（克拉）' },
+    y: { title: '频数' },
+  },
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface HistogramOptions {
+  type: 'rect';
+  encode: {
+    x: string;           // 连续数值字段
+    y: 'count';          // 统计数量
+    color?: string;      // 分组字段
+  };
+  transform: [
+    {
+      type: 'binX';
+      y: 'count';
+      thresholds?: number;  // 分箱数量
+      groupBy?: string[];   // 分组字段
+    }
+  ];
+}
+```
+
+## 直方图 vs 柱状图
+
+| 特性 | 直方图 | 柱状图 |
+|------|--------|--------|
+| 数据类型 | 连续数值 | 分类数据 |
+| Mark 类型 | `rect` | `interval` |
+| 柱子间隔 | 无间隔 | 有间隔 |
+| X 轴 | 连续区间 | 离散类别 |
+
+## 常见错误与修正
+
+### 错误 1：使用 interval 标记
+
+```javascript
+// ❌ 问题：interval 不支持区间表示
+type: 'interval'
+
+// ✅ 正确：使用 rect 标记
+type: 'rect'
+```
+
+### 错误 2：缺少 binX 转换
+
+```javascript
+// ❌ 问题：没有分箱统计
+encode: { x: 'value', y: 'count' }
+
+// ✅ 正确：添加 binX 转换
+transform: [{ type: 'binX', y: 'count' }]
+```
+
+### 错误 3：数据量过少
+
+```javascript
+// ⚠️ 注意：直方图需要足够的数据量
+// 建议数据量 >= 50 条
+```

package/builtin-skills/antv-g2-chart/references/marks/g2-mark-image.md

@@ -0,0 +1,129 @@
+---
+id: "g2-mark-image"
+title: "G2 Image 图片标记"
+description: |
+  image mark 在图表的指定位置渲染图片，可用于图标型散点图（以图标代替点）、
+  地图上的图标标注、带图片的标签等场景。
+  通过 src 通道绑定图片 URL，x/y 通道确定位置，size 通道控制大小。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "image"
+  - "图片"
+  - "图标"
+  - "icon"
+  - "图片散点图"
+
+related:
+  - "g2-mark-point-scatter"
+  - "g2-mark-text"
+
+use_cases:
+  - "以品牌 logo / 图标代替散点（图标散点图）"
+  - "在特定坐标位置插入说明图片"
+  - "结合地图的图标标注"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/general/point/#image"
+---
+
+## 最小可运行示例（图标散点图）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { country: '中国',    gdp: 17.7, icon: 'https://example.com/flags/cn.png' },
+  { country: '美国',    gdp: 25.5, icon: 'https://example.com/flags/us.png' },
+  { country: '日本',    gdp: 4.2,  icon: 'https://example.com/flags/jp.png' },
+  { country: '德国',    gdp: 4.1,  icon: 'https://example.com/flags/de.png' },
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+chart.options({
+  type: 'image',
+  data,
+  encode: {
+    x: 'country',  // x 位置（分类轴）
+    y: 'gdp',      // y 位置（数值轴）
+    src: 'icon',   // 图片 URL 字段
+    size: 40,      // 图片大小（px），固定值或字段名
+  },
+});
+
+chart.render();
+```
+
+## image + point 叠加（图标 + 数据点）
+
+```javascript
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    {
+      type: 'image',
+      encode: { x: 'x', y: 'y', src: 'icon', size: 32 },
+    },
+    {
+      type: 'text',
+      encode: { x: 'x', y: 'y', text: 'label' },
+      style: { textAnchor: 'middle', dy: 20, fontSize: 12 },
+    },
+  ],
+});
+```
+
+## 配置项
+
+```javascript
+chart.options({
+  type: 'image',
+  data,
+  encode: {
+    x: 'xField',       // x 坐标
+    y: 'yField',       // y 坐标
+    src: 'imageUrl',   // 图片 URL 字段（或固定 URL 字符串）
+    size: 'sizeField', // 图片大小（px），可以是字段名或固定数值
+  },
+  style: {
+    preserveAspectRatio: 'xMidYMid meet',  // 图片缩放策略（SVG 标准）
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：src 通道写的是图片数据本身，不是 URL
+```javascript
+// ❌ 错误：src 应该是 URL 字段名，不是 base64 或 blob
+chart.options({
+  encode: { src: btoa(imageData) },  // ❌ 不能传 base64 字符串（需要完整的 data: URL）
+});
+
+// ✅ 正确：传 URL 字段名，数据中是完整 URL
+chart.options({
+  encode: { src: 'iconUrl' },  // ✅ 数据中 iconUrl 字段是 'https://...' 格式
+});
+```
+
+### 错误 2：没有设置 size——图片默认大小可能过大或过小
+```javascript
+// ❌ 未设置 size，图片可能太大覆盖其他元素
+chart.options({
+  type: 'image',
+  encode: { x: 'x', y: 'y', src: 'icon' },  // ❌ 没有 size
+});
+
+// ✅ 明确设置合适的 size
+chart.options({
+  encode: { x: 'x', y: 'y', src: 'icon', size: 36 },  // ✅
+});
+```