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

package/builtin-skills/antv-g2-chart/references/compositions/g2-comp-facet-rect.md

@@ -0,0 +1,241 @@
+---
+id: "g2-comp-facet-rect"
+title: "G2 矩形分面（facetRect）"
+description: |
+  facetRect 将数据按分类字段拆分，在网格布局中为每个分类绘制一个独立的子图表。
+  适合对比不同分组的数据分布和趋势。通过 type: 'facetRect' + encode.x/y 指定分面维度。
+
+library: "g2"
+version: "5.x"
+category: "compositions"
+tags:
+  - "facetRect"
+  - "分面"
+  - "facet"
+  - "小多图"
+  - "trellis"
+  - "网格布局"
+  - "spec"
+
+related:
+  - "g2-core-view-composition"
+  - "g2-mark-interval-basic"
+  - "g2-mark-point-scatter"
+
+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/composition/facet-rect"
+---
+
+## 基本概念
+
+```
+chart.options({
+  type: 'facetRect',
+  encode: {
+    x: '分面列字段',      // 按此字段将数据分为多列
+    y: '分面行字段',      // 按此字段将数据分为多行（可选）
+  },
+  children: [
+    { type: '子图 Mark', ... },    // 每个子图的配置（共用，数据自动过滤）
+  ],
+});
+```
+
+**关键规则**：
+- `encode.x` → 按该字段的唯一值拆分为多列（列分面）
+- `encode.y` → 按该字段的唯一值拆分为多行（行分面）
+- `children` 中的 Mark 会自动接收过滤后的数据
+
+## 单维度列分面（按类别分列）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 800,
+  height: 300,
+});
+
+const data = [
+  { month: 'Jan', value: 33, region: '华东' },
+  { month: 'Feb', value: 78, region: '华东' },
+  { month: 'Mar', value: 56, region: '华东' },
+  { month: 'Jan', value: 45, region: '华南' },
+  { month: 'Feb', value: 62, region: '华南' },
+  { month: 'Mar', value: 71, region: '华南' },
+  { month: 'Jan', value: 28, region: '华北' },
+  { month: 'Feb', value: 39, region: '华北' },
+  { month: 'Mar', value: 53, region: '华北' },
+];
+
+chart.options({
+  type: 'facetRect',
+  data,
+  encode: { x: 'region' },     // 按 region 列分面（3 列）
+  children: [
+    {
+      type: 'interval',
+      encode: { x: 'month', y: 'value' },
+      style: { fill: '#1890ff' },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 二维分面（行 + 列）
+
+```javascript
+const data = [
+  { quarter: 'Q1', value: 100, region: '华东', type: '线上' },
+  { quarter: 'Q2', value: 130, region: '华东', type: '线上' },
+  { quarter: 'Q1', value: 80,  region: '华南', type: '线上' },
+  { quarter: 'Q2', value: 95,  region: '华南', type: '线上' },
+  { quarter: 'Q1', value: 60,  region: '华东', type: '线下' },
+  { quarter: 'Q2', value: 85,  region: '华东', type: '线下' },
+  { quarter: 'Q1', value: 40,  region: '华南', type: '线下' },
+  { quarter: 'Q2', value: 55,  region: '华南', type: '线下' },
+];
+
+chart.options({
+  type: 'facetRect',
+  data,
+  encode: {
+    x: 'region',   // 列：华东/华南
+    y: 'type',     // 行：线上/线下
+  },
+  children: [
+    {
+      type: 'interval',
+      encode: { x: 'quarter', y: 'value' },
+    },
+  ],
+});
+```
+
+## 分面折线图（多系列趋势对比）
+
+```javascript
+chart.options({
+  type: 'facetRect',
+  data,
+  encode: { x: 'product' },          // 按产品分面
+  children: [
+    {
+      type: 'view',
+      children: [
+        {
+          type: 'area',
+          encode: { x: 'month', y: 'sales' },
+          style: { fill: '#1890ff', fillOpacity: 0.15 },
+        },
+        {
+          type: 'line',
+          encode: { x: 'month', y: 'sales' },
+          style: { stroke: '#1890ff', lineWidth: 2 },
+        },
+      ],
+    },
+  ],
+});
+```
+
+## 配置分面标题样式
+
+```javascript
+chart.options({
+  type: 'facetRect',
+  data,
+  encode: { x: 'region' },
+  children: [
+    {
+      type: 'interval',
+      encode: { x: 'month', y: 'value' },
+    },
+  ],
+  // 分面标题配置（通过 frame 字段）
+  frame: false,                        // 是否显示边框
+  // 标题通过 facetRect 的 title 配置
+  title: {
+    position: 'top',                   // 标题在顶部
+    style: { fontSize: 13, fill: '#333', fontWeight: 'bold' },
+  },
+});
+```
+
+## 共享坐标轴（shareData）
+
+```javascript
+chart.options({
+  type: 'facetRect',
+  data,
+  encode: { x: 'category' },
+  shareData: true,          // 共享数据范围（坐标轴刻度一致）
+  children: [
+    {
+      type: 'point',
+      encode: { x: 'x', y: 'y', color: 'category' },
+    },
+  ],
+});
+```
+
+## 常见错误与修正
+
+### 错误：facetRect 的 children 中写了 data
+```javascript
+// ❌ 错误：不应在子 Mark 中再指定 data，否则分面过滤不生效
+chart.options({
+  type: 'facetRect',
+  data: allData,
+  encode: { x: 'region' },
+  children: [
+    {
+      type: 'interval',
+       allData,            // ❌ 会导致每个分面显示全量数据
+      encode: { x: 'month', y: 'value' },
+    },
+  ],
+});
+
+// ✅ 正确：子 Mark 不指定 data，自动接收分面过滤后的数据
+chart.options({
+  type: 'facetRect',
+  data: allData,
+  encode: { x: 'region' },
+  children: [
+    {
+      type: 'interval',
+      encode: { x: 'month', y: 'value' },   // 不写 data，继承并自动过滤
+    },
+  ],
+});
+```
+
+### 错误：encode 字段与数据字段名不匹配
+```javascript
+// ❌ 错误：encode.x 指定的分面字段在数据中不存在
+chart.options({
+  type: 'facetRect',
+  data: [{ month: 'Jan', value: 33, area: '华东' }],
+  encode: { x: 'region' },   // ❌ 数据中是 'area'，不是 'region'
+});
+
+// ✅ 正确：字段名与数据保持一致
+chart.options({
+  type: 'facetRect',
+  data,
+  encode: { x: 'area' },     // ✅ 与数据字段名一致
+});
+```

package/builtin-skills/antv-g2-chart/references/compositions/g2-comp-geo-map.md

@@ -0,0 +1,210 @@
+---
+id: "g2-comp-geo-map"
+title: "G2 地理地图（geoView / geoPath / d3Projection）"
+description: |
+  G2 v5 通过 geoView、geoPath 组合类型以及 d3Projection 地图投影实现地理可视化。
+  geoView 是地理视图容器，geoPath 是地理路径 Mark（绘制行政区域等 GeoJSON）。
+  支持 geoMercator、geoNaturalEarth1 等多种地图投影。
+  数据格式为 GeoJSON 的 FeatureCollection。
+
+library: "g2"
+version: "5.x"
+category: "compositions"
+tags:
+  - "geoView"
+  - "geoPath"
+  - "地图"
+  - "GeoJSON"
+  - "地理可视化"
+  - "d3Projection"
+  - "choropleth"
+  - "choropleth map"
+
+related:
+  - "g2-comp-geoview"
+  - "g2-core-view-composition"
+
+use_cases:
+  - "省份/城市分布热力地图（choropleth map）"
+  - "世界地图可视化"
+  - "地理数据的空间分布展示"
+
+difficulty: "advanced"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/geo/geo/#choropleth"
+---
+
+## 核心概念
+
+G2 地理可视化的三个核心组件：
+
+| 组件 | 类型 | 说明 |
+|------|------|------|
+| `geoView` | composition | 地理视图容器，配置投影和视口 |
+| `geoPath` | mark（在 geoView 内） | 绘制 GeoJSON 地理路径 |
+| `d3Projection` | 投影函数 | 从 d3-geo 导出的投影函数（geoMercator 等） |
+
+## 最小可运行示例（世界地图）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+async function renderMap() {
+  // 加载 GeoJSON 数据
+  const world = await fetch(
+    'https://assets.antv.antgroup.com/g2/world.json',
+  ).then((res) => res.json());
+
+  const chart = new Chart({ container: 'container', width: 900, height: 500 });
+
+  chart.options({
+    type: 'geoView',       // 地理视图容器
+    data: {
+      type: 'fetch',
+      value: 'https://assets.antv.antgroup.com/g2/world.json',
+    },
+    children: [
+      {
+        type: 'geoPath',   // 地理路径 Mark
+        style: {
+          fill: '#ccc',
+          stroke: '#fff',
+          lineWidth: 0.5,
+        },
+      },
+    ],
+  });
+
+  chart.render();
+}
+renderMap();
+```
+
+## Choropleth Map（着色地图）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const populationData = [
+  { province: '广东', value: 12601 },
+  { province: '山东', value: 10169 },
+  // ...
+];
+
+const chart = new Chart({ container: 'container', width: 900, height: 600 });
+
+chart.options({
+  type: 'geoView',
+  children: [
+    {
+      type: 'geoPath',
+      data: {
+        type: 'fetch',
+        value: 'https://assets.antv.antgroup.com/g2/china.json',
+      },
+      // 将 GeoJSON 属性与业务数据 join
+      join: {
+         populationData,
+        on: ['properties.name', 'province'],   // GeoJSON 属性字段 → 业务数据字段
+      },
+      encode: {
+        color: 'value',   // 按 value 字段着色
+      },
+      style: {
+        stroke: '#fff',
+        lineWidth: 0.5,
+      },
+      scale: {
+        color: {
+          type: 'sequential',
+          range: ['#eaf4d3', '#006d2c'],   // 颜色渐变范围
+        },
+      },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 自定义地图投影
+
+```javascript
+import { Chart } from '@antv/g2';
+import { geoMercator, geoNaturalEarth1 } from '@antv/g2';  // 从 g2 导出 d3-geo 投影
+
+const chart = new Chart({ container: 'container', width: 900, height: 500 });
+
+chart.options({
+  type: 'geoView',
+  projection: {
+    type: 'mercator',       // 内置投影名
+    // type: 'naturalEarth1', // 自然地球投影
+    // type: 'orthographic',  // 正射投影
+  },
+  children: [
+    {
+      type: 'geoPath',
+       { type: 'fetch', value: 'https://assets.antv.antgroup.com/g2/world.json' },
+      style: { fill: '#ccc', stroke: '#fff' },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 内置投影类型
+
+```javascript
+// G2 内置的 d3-geo 投影（在 projection.type 中指定）
+// 'mercator'         - 墨卡托投影（适合局部区域）
+// 'naturalEarth1'    - 自然地球投影（适合世界地图）
+// 'orthographic'     - 正射投影（球形效果）
+// 'equalEarth'       - 等面积地球投影
+// 'albersUsa'        - 美国阿尔伯斯投影
+```
+
+## 常见错误与修正
+
+### 错误：geoPath 没有放在 geoView 里
+```javascript
+// ❌ 错误：geoPath 必须在 geoView 内使用
+chart.options({
+  type: 'geoPath',   // ❌ 不能直接作为顶层类型
+   geojson,
+});
+
+// ✅ 正确：geoPath 在 geoView children 中
+chart.options({
+  type: 'geoView',
+  children: [
+    { type: 'geoPath', data: { type: 'fetch', value: '...' } },  // ✅
+  ],
+});
+```
+
+### 错误：数据不是 GeoJSON 格式
+```javascript
+// ❌ 错误：geoPath 需要 GeoJSON FeatureCollection 格式
+chart.options({
+  type: 'geoView',
+  children: [{
+    type: 'geoPath',
+     [{ province: '广东', lng: 113, lat: 23 }],  // ❌ 普通经纬度数据不行
+  }],
+});
+
+// ✅ 正确：使用标准 GeoJSON FeatureCollection
+// GeoJSON 格式：{ type: 'FeatureCollection', features: [...] }
+chart.options({
+  type: 'geoView',
+  children: [{
+    type: 'geoPath',
+     { type: 'fetch', value: 'china.geojson' },  // ✅ GeoJSON 文件
+  }],
+});
+```

package/builtin-skills/antv-g2-chart/references/compositions/g2-comp-geoview.md

@@ -0,0 +1,143 @@
+---
+id: "g2-comp-geoview"
+title: "G2 地理视图（geoView）"
+description: |
+  geoView 基于 D3 地理投影，在 G2 中绘制地图可视化。
+  支持多种投影方式（mercator、equalEarth、orthographic 等），
+  数据需为 GeoJSON 格式，通过 geoPath mark 渲染地理形状。
+
+library: "g2"
+version: "5.x"
+category: "compositions"
+tags:
+  - "geoView"
+  - "地图"
+  - "地理"
+  - "GeoJSON"
+  - "choropleth"
+  - "地理投影"
+  - "composition"
+
+related:
+  - "g2-mark-cell-heatmap"
+  - "g2-scale-threshold"
+
+use_cases:
+  - "世界地图着色（choropleth map）"
+  - "国家/省份数据地图展示"
+  - "地理空间数据可视化"
+
+difficulty: "advanced"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/geo/geo/#choropleth"
+---
+
+## 最小可运行示例（世界地图）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+// 需要提前加载 world.geo.json 数据
+fetch('https://cdn.jsdelivr.net/npm/world-atlas@2/countries-110m.json')
+  .then(res => res.json())
+  .then(world => {
+    // 将 TopoJSON 转换为 GeoJSON（需要 topojson-client）
+    const countries = topojson.feature(world, world.objects.countries);
+
+    const chart = new Chart({ container: 'container', width: 900, height: 500 });
+
+    chart.options({
+      type: 'geoView',
+      coordinate: {
+        type: 'projection',
+        projection: 'equalEarth',   // 投影方式
+      },
+      children: [
+        {
+          type: 'geoPath',
+           countries,
+          encode: { color: 'id' },   // 按国家 id 着色
+          style: {
+            stroke: '#fff',
+            lineWidth: 0.5,
+            fillOpacity: 0.85,
+          },
+        },
+      ],
+    });
+
+    chart.render();
+  });
+```
+
+## 数据关联着色（choropleth）
+
+```javascript
+// 将 GeoJSON 与数据表格按 name 关联，实现数据着色
+const gdpData = {
+  CN: 17.7, US: 25.5, JP: 4.2, DE: 4.1,
+  // ...
+};
+
+chart.options({
+  type: 'geoView',
+  coordinate: { type: 'projection', projection: 'mercator' },
+  children: [
+    {
+      type: 'geoPath',
+       geoJsonFeatures,
+      encode: {
+        color: (d) => gdpData[d.properties.iso_a2] || 0,  // 关联 GDP 数据
+      },
+      scale: {
+        color: {
+          type: 'sequential',
+          palette: 'blues',
+          unknown: '#eee',   // 无数据国家颜色
+        },
+      },
+      tooltip: {
+        items: [
+          { field: 'properties.name', name: '国家' },
+          { callback: (d) => gdpData[d.properties.iso_a2], name: 'GDP（万亿美元）' },
+        ],
+      },
+    },
+  ],
+});
+```
+
+## 支持的投影方式
+
+```javascript
+// 常用投影
+coordinate: { type: 'projection', projection: 'mercator' }       // 墨卡托（Web地图标准）
+coordinate: { type: 'projection', projection: 'equalEarth' }     // 等面积地球投影
+coordinate: { type: 'projection', projection: 'orthographic' }   // 正交（球形）
+coordinate: { type: 'projection', projection: 'naturalEarth1' }  // 自然地球
+coordinate: { type: 'projection', projection: 'albersUsa' }      // 美国阿尔伯斯
+```
+
+## 常见错误与修正
+
+### 错误：数据不是 GeoJSON 格式——直接传统计数据
+```javascript
+// ❌ geoPath mark 需要 GeoJSON Feature/FeatureCollection 数据
+chart.options({
+  children: [{
+    type: 'geoPath',
+     [{ country: 'China', gdp: 17.7 }],  // ❌ 不是 GeoJSON
+  }],
+});
+
+// ✅ 需要 GeoJSON 格式
+chart.options({
+  children: [{
+    type: 'geoPath',
+     { type: 'FeatureCollection', features: [...] },  // ✅ GeoJSON
+  }],
+});
+```