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

package/builtin-skills/antv-g2-chart/references/label-transform/g2-label-transform-overlap-dodge-y.md

@@ -0,0 +1,225 @@
+---
+id: "g2-label-transform-overlap-dodge-y"
+title: "G2 OverlapDodgeY 标签变换"
+description: |
+  标签 Y 方向避让变换。当标签在 Y 方向重叠时自动调整位置，
+  通过迭代算法避免标签重叠。
+
+library: "g2"
+version: "5.x"
+category: "label-transform"
+tags:
+  - "标签"
+  - "label"
+  - "重叠"
+  - "避让"
+  - "dodge"
+
+related:
+  - "g2-label-transform-overlap-hide"
+  - "g2-label-transform-overflow-hide"
+  - "g2-comp-label-config"
+
+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/label"
+---
+
+## 核心概念
+
+OverlapDodgeY 标签变换通过迭代算法在 Y 方向调整标签位置：
+- 检测相邻标签是否在 X 方向重叠
+- 如果重叠，在 Y 方向分开
+- 迭代直到无重叠或达到最大迭代次数
+
+**算法特点：**
+- 时间复杂度 O(n log n)
+- 支持设置最大迭代次数
+- 支持设置标签间距
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'line',
+  data: [
+    { date: '2024-01-01', value: 100, label: 'Event A' },
+    { date: '2024-01-02', value: 120, label: 'Event B' },
+    { date: '2024-01-02', value: 110, label: 'Event C' },  // 同一天，标签可能重叠
+  ],
+  encode: {
+    x: 'date',
+    y: 'value',
+  },
+  labels: [
+    {
+      text: 'label',
+      position: 'top',
+      transform: [{ type: 'overlapDodgeY' }],
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 自定义间距
+
+```javascript
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value' },
+  labels: [
+    {
+      text: 'label',
+      position: 'top',
+      transform: [
+        {
+          type: 'overlapDodgeY',
+          padding: 4,  // 标签之间的最小间距（像素）
+        },
+      ],
+    },
+  ],
+});
+```
+
+### 控制迭代次数
+
+```javascript
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value' },
+  labels: [
+    {
+      text: 'label',
+      position: 'top',
+      transform: [
+        {
+          type: 'overlapDodgeY',
+          maxIterations: 20,  // 最大迭代次数，默认 10
+          maxError: 0.1,      // 最大误差，默认 0.1
+        },
+      ],
+    },
+  ],
+});
+```
+
+### 结合其他变换
+
+```javascript
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value' },
+  labels: [
+    {
+      text: 'label',
+      position: 'top',
+      transform: [
+        { type: 'overlapDodgeY' },
+        { type: 'overflowHide' },  // 先避让，再处理溢出
+      ],
+    },
+  ],
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface OverlapDodgeYTransform {
+  type: 'overlapDodgeY';
+  padding?: number;         // 标签间距，默认 1
+  maxIterations?: number;   // 最大迭代次数，默认 10
+  maxError?: number;        // 最大误差，默认 0.1
+}
+```
+
+## 与其他标签变换的对比
+
+| Transform | 功能 | 优点 | 缺点 |
+|-----------|------|------|------|
+| overlapDodgeY | Y 方向避让 | 保留所有标签 | 可能改变布局 |
+| overlapHide | 隐藏重叠标签 | 布局稳定 | 丢失部分标签 |
+| overflowHide | 隐藏溢出标签 | 避免溢出 | 可能丢失标签 |
+
+## 工作原理图解
+
+```
+原始状态:
+  Label A -------- Label B
+      ↑ 重叠 ↑
+
+处理后:
+  Label B
+      ↑
+  Label A --------
+
+  (Y 方向分开)
+```
+
+## 常见错误与修正
+
+### 错误 1：transform 格式错误
+
+```javascript
+// ❌ 错误：transform 应该是数组
+labels: [{ text: 'value', transform: { type: 'overlapDodgeY' } }]
+
+// ✅ 正确
+labels: [{ text: 'value', transform: [{ type: 'overlapDodgeY' }] }]
+```
+
+### 错误 2：迭代次数设置不当
+
+```javascript
+// ⚠️ 注意：迭代次数过多会影响性能
+// 标签数量多时，建议减少迭代次数
+
+// 标签较少时
+transform: [{ type: 'overlapDodgeY', maxIterations: 20 }]
+
+// 标签较多时
+transform: [{ type: 'overlapDodgeY', maxIterations: 5 }]
+```
+
+### 错误 3：与其他变换顺序错误
+
+```javascript
+// ❌ 错误：先隐藏再避让，效果不佳
+transform: [
+  { type: 'overlapHide' },
+  { type: 'overlapDodgeY' },
+]
+
+// ✅ 正确：先避让，再隐藏无法处理的
+transform: [
+  { type: 'overlapDodgeY' },
+  { type: 'overlapHide' },
+]
+```

package/builtin-skills/antv-g2-chart/references/label-transform/g2-label-transform-overlap-hide.md

@@ -0,0 +1,213 @@
+---
+id: "g2-label-transform-overlap-hide"
+title: "G2 OverlapHide 标签变换"
+description: |
+  标签重叠隐藏变换。当标签重叠时自动隐藏部分标签，
+  避免视觉混乱。支持按优先级决定隐藏顺序。
+
+library: "g2"
+version: "5.x"
+category: "label-transform"
+tags:
+  - "标签"
+  - "label"
+  - "重叠"
+  - "隐藏"
+  - "overlap"
+
+related:
+  - "g2-label-transform-overlap-dodge-y"
+  - "g2-label-transform-overflow-hide"
+  - "g2-comp-label-config"
+
+use_cases:
+  - "密集数据点的标签显示"
+  - "时间序列图表的标签处理"
+  - "需要简洁显示的场景"
+
+anti_patterns:
+  - "必须显示所有标签的场景（改用 overlapDodgeY）"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/label"
+---
+
+## 核心概念
+
+OverlapHide 标签变换通过检测标签重叠来隐藏部分标签：
+- 按顺序检测每个标签是否与已显示的标签重叠
+- 如果重叠，隐藏当前标签
+- 支持设置优先级决定隐藏顺序
+
+**工作原理：**
+1. 获取所有标签
+2. 按优先级排序（可选）
+3. 依次检测每个标签是否与已显示标签重叠
+4. 重叠则隐藏，否则显示
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'line',
+  data: [
+    { date: '2024-01-01', value: 100 },
+    { date: '2024-01-02', value: 120 },
+    { date: '2024-01-03', value: 110 },
+    { date: '2024-01-04', value: 130 },
+  ],
+  encode: {
+    x: 'date',
+    y: 'value',
+  },
+  labels: [
+    {
+      text: 'value',
+      position: 'top',
+      transform: [{ type: 'overlapHide' }],
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 设置优先级
+
+```javascript
+chart.options({
+  type: 'interval',
+  data: [
+    { category: 'A', value: 100, priority: 2 },
+    { category: 'B', value: 50, priority: 1 },
+    { category: 'C', value: 80, priority: 3 },
+  ],
+  encode: { x: 'category', y: 'value' },
+  labels: [
+    {
+      text: 'value',
+      position: 'inside',
+      transform: [
+        {
+          type: 'overlapHide',
+          priority: (a, b) => a.priority - b.priority,  // 高优先级先显示
+        },
+      ],
+    },
+  ],
+});
+```
+
+### 结合其他变换
+
+```javascript
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'date', y: 'value' },
+  labels: [
+    {
+      text: 'value',
+      position: 'top',
+      transform: [
+        { type: 'overlapDodgeY' },  // 先尝试避让
+        { type: 'overlapHide' },    // 无法避让的隐藏
+      ],
+    },
+  ],
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface OverlapHideTransform {
+  type: 'overlapHide';
+  priority?: (a: any, b: any) => number;  // 优先级比较函数
+}
+```
+
+## 与其他标签变换的对比
+
+| Transform | 功能 | 优点 | 缺点 |
+|-----------|------|------|------|
+| overlapHide | 隐藏重叠标签 | 布局稳定 | 丢失部分标签 |
+| overlapDodgeY | Y 方向避让 | 保留所有标签 | 可能改变布局 |
+| overflowHide | 隐藏溢出标签 | 避免溢出 | 可能丢失标签 |
+
+## 优先级排序示例
+
+```javascript
+// 按数值大小排序：大值优先显示
+labels: [{
+  text: 'value',
+  transform: [{
+    type: 'overlapHide',
+    priority: (a, b) => b.value - a.value
+  }]
+}]
+
+// 按特定顺序排序
+labels: [{
+  text: 'value',
+  transform: [{
+    type: 'overlapHide',
+    priority: (a, b) => {
+      const order = ['A', 'B', 'C', 'D'];
+      return order.indexOf(a.category) - order.indexOf(b.category);
+    }
+  }]
+}]
+```
+
+## 常见错误与修正
+
+### 错误 1：transform 格式错误
+
+```javascript
+// ❌ 错误：transform 应该是数组
+labels: [{ text: 'value', transform: { type: 'overlapHide' } }]
+
+// ✅ 正确
+labels: [{ text: 'value', transform: [{ type: 'overlapHide' }] }]
+```
+
+### 错误 2：优先级函数返回值错误
+
+```javascript
+// ❌ 错误：优先级函数应该返回数字
+priority: (a, b) => a.value > b.value
+
+// ✅ 正确：返回正数表示 a 优先，负数表示 b 优先
+priority: (a, b) => b.value - a.value
+```
+
+### 错误 3：与其他变换顺序错误
+
+```javascript
+// ❌ 错误：先隐藏再处理其他问题
+transform: [
+  { type: 'overlapHide' },
+  { type: 'overlapDodgeY' },  // 已经隐藏的标签无法避让
+]
+
+// ✅ 正确：先尝试其他解决方案，最后隐藏
+transform: [
+  { type: 'overlapDodgeY' },
+  { type: 'overlapHide' },
+]
+```

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

@@ -0,0 +1,196 @@
+---
+id: "g2-mark-arc-diagram"
+title: "G2 Arc Diagram Mark"
+description: |
+  弧长连接图 Mark。使用 line 和 point 组合展示节点之间的链接关系。
+  适用于关系网络分析、社交网络、知识图谱等场景。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "弧长连接图"
+  - "arc diagram"
+  - "关系图"
+  - "网络"
+
+related:
+  - "g2-mark-chord"
+  - "g2-mark-sankey"
+
+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/arc-diagram"
+---
+
+## 核心概念
+
+弧长连接图展示节点之间的链接关系：
+- 节点沿线性轴或环形排列
+- 用弧线表示节点之间的连接
+- 支持线性布局和环形布局
+
+**关键特点：**
+- 一维布局方式
+- 清晰呈现环和桥结构
+- 节点排序影响视觉效果
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  theme: 'classic',
+});
+
+// 数据预处理：计算弧线坐标
+const processData = (nodes, links) => {
+  const arcData = [];
+  const nodePositions = {};
+
+  nodes.forEach((node, i) => {
+    nodePositions[node.id] = i * 15 + 50;
+  });
+
+  links.forEach((link) => {
+    const sourceX = nodePositions[link.source];
+    const targetX = nodePositions[link.target];
+    const distance = Math.abs(targetX - sourceX);
+    const arcHeight = Math.min(150, distance * 0.1);
+
+    for (let i = 0; i <= 15; i++) {
+      const t = i / 15;
+      const x = sourceX + (targetX - sourceX) * t;
+      const y = 600 - arcHeight * Math.sin(Math.PI * t);
+      arcData.push({ x, y, linkId: `${link.source}-${link.target}` });
+    }
+  });
+
+  return { arcData, nodePositions, nodes };
+};
+
+chart.options({
+  type: 'view',
+   data: { type: 'fetch', value: 'relationship.json' },
+  // ... 数据处理和渲染
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 环形布局
+
+```javascript
+chart.options({
+  type: 'view',
+  coordinate: { type: 'polar' },  // 极坐标系
+  data,
+  children: [
+    {
+      type: 'line',
+      encode: { x: 'x', y: 'y', series: 'linkId' },
+    },
+    {
+      type: 'point',
+      encode: { x: 'angle', y: 'radius', color: 'group' },
+    },
+  ],
+});
+```
+
+### 带节点标签
+
+```javascript
+chart.options({
+  type: 'view',
+  children: [
+    { type: 'line', data: arcData, encode: { x: 'x', y: 'y', series: 'linkId' } },
+    { type: 'point', data: nodeData, encode: { x: 'x', y: 'y', color: 'group' } },
+    { type: 'text',  nodeData, encode: { x: 'x', y: 'y', text: 'name' } },
+  ],
+});
+```
+
+### 带交互高亮
+
+```javascript
+chart.options({
+  type: 'view',
+  children: [
+    {
+      type: 'line',
+      data: arcData,
+      encode: { x: 'x', y: 'y', series: 'linkId' },
+      style: { strokeOpacity: 0.4 },
+      state: {
+        active: { strokeOpacity: 1, lineWidth: 2 },
+      },
+    },
+  ],
+  interactions: [{ type: 'elementHighlight' }],
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface ArcDiagramData {
+  nodes: Array<{ id: string; label: string; group?: string }>;
+  links: Array<{ source: string; target: string; value?: number }>;
+}
+
+// 弧长连接图由多个图层组成：
+// 1. line - 弧线连接
+// 2. point - 节点
+// 3. text - 标签（可选）
+```
+
+## 弧长连接图 vs 和弦图
+
+| 特性 | 弧长连接图 | 和弦图 |
+|------|------------|--------|
+| 节点布局 | 线性/环形 | 环形 |
+| 连线方式 | 弧线重叠 | 平铺不重叠 |
+| 适用场景 | 关系展示 | 流向展示 |
+
+## 常见错误与修正
+
+### 错误 1：节点未排序
+
+```javascript
+// ⚠️ 注意：节点排序影响视觉效果
+// 建议按社区或度数排序
+```
+
+### 错误 2：连线过多
+
+```javascript
+// ⚠️ 注意：连线过多会导致视觉混乱
+// 建议过滤或聚合部分连线
+```
+
+### 错误 3：缺少数据预处理
+
+```javascript
+// ❌ 问题：直接使用原始数据
+ { nodes: [...], links: [...] }
+
+// ✅ 正确：预处理计算坐标
+data: { transform: [{ type: 'custom', callback: processData }] }
+```