@loom-framework/core 0.1.0-alpha.9 → 0.1.0-alpha.91

package/builtin-skills/antv-g2-chart/references/label-transform/g2-label-transform-contrast-reverse.md

@@ -0,0 +1,170 @@
+---
+id: "g2-label-transform-contrast-reverse"
+title: "G2 ContrastReverse 标签变换"
+description: |
+  标签对比度反转变换。根据背景颜色自动调整标签颜色，
+  确保标签在深色背景上显示浅色，在浅色背景上显示深色。
+
+library: "g2"
+version: "5.x"
+category: "label-transform"
+tags:
+  - "标签"
+  - "label"
+  - "对比度"
+  - "颜色"
+  - "contrast"
+
+related:
+  - "g2-label-transform-overflow-hide"
+  - "g2-comp-label-config"
+
+use_cases:
+  - "柱状图内部标签"
+  - "饼图标签"
+  - "需要根据背景调整颜色的标签"
+
+anti_patterns:
+  - "固定颜色标签不需要此变换"
+
+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"
+---
+
+## 核心概念
+
+ContrastReverse 标签变换会根据元素的颜色自动调整标签颜色：
+- 深色背景 → 浅色标签
+- 浅色背景 → 深色标签
+
+**工作原理：**
+1. 获取元素的填充颜色
+2. 计算颜色的亮度
+3. 根据亮度选择对比色
+
+## 最小可运行示例
+
+```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',
+  },
+  labels: [
+    {
+      text: 'value',
+      position: 'inside',
+      transform: [{ type: 'contrastReverse' }],
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 结合其他变换
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+  labels: [
+    {
+      text: 'value',
+      position: 'inside',
+      transform: [
+        { type: 'contrastReverse' },
+        { type: 'overflowHide' },
+      ],
+    },
+  ],
+});
+```
+
+### 自定义对比色
+
+```javascript
+// 注意：contrastReverse 通常使用默认的黑白对比
+// 如需自定义，可以在 style 中设置
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+  labels: [
+    {
+      text: 'value',
+      position: 'inside',
+      style: {
+        fill: '#fff',  // 固定白色
+        stroke: '#000',  // 描边增加对比度
+        lineWidth: 1,
+      },
+    },
+  ],
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface ContrastReverseTransform {
+  type: 'contrastReverse';
+  // 无额外配置参数
+}
+```
+
+## 与固定颜色的对比
+
+| 方式 | 优点 | 缺点 |
+|------|------|------|
+| contrastReverse | 自动适应 | 可能不符合设计风格 |
+| 固定颜色 | 风格统一 | 可能对比度不足 |
+| 描边 | 增加对比度 | 可能影响清晰度 |
+
+## 常见错误与修正
+
+### 错误 1：transform 格式错误
+
+```javascript
+// ❌ 错误：transform 应该是数组
+labels: [{ text: 'value', transform: { type: 'contrastReverse' } }]
+
+// ✅ 正确
+labels: [{ text: 'value', transform: [{ type: 'contrastReverse' }] }]
+```
+
+### 错误 2：position 设置不当
+
+```javascript
+// ⚠️ 注意：contrastReverse 主要用于 inside 位置
+// outside 位置的标签不在元素上，无法获取背景色
+
+// ✅ 正确：用于 inside 标签
+labels: [{
+  text: 'value',
+  position: 'inside',
+  transform: [{ type: 'contrastReverse' }]
+}]
+```

package/builtin-skills/antv-g2-chart/references/label-transform/g2-label-transform-exceed-adjust.md

@@ -0,0 +1,146 @@
+---
+id: "g2-label-transform-exceed-adjust"
+title: "G2 ExceedAdjust 标签变换"
+description: |
+  标签超出调整变换。当标签超出指定范围时自动调整位置，
+  确保标签在可视区域内显示。
+
+library: "g2"
+version: "5.x"
+category: "label-transform"
+tags:
+  - "标签"
+  - "label"
+  - "超出"
+  - "调整"
+  - "exceed"
+
+related:
+  - "g2-label-transform-overflow-hide"
+  - "g2-label-transform-overlap-dodge-y"
+  - "g2-comp-label-config"
+
+use_cases:
+  - "图表边缘标签调整"
+  - "小尺寸元素标签"
+  - "需要保持标签完整的场景"
+
+anti_patterns:
+  - "标签可以隐藏的场景（改用 overflowHide）"
+
+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"
+---
+
+## 核心概念
+
+ExceedAdjust 标签变换会检测标签是否超出可视区域：
+- 如果超出，自动调整标签位置
+- 确保标签完整显示
+
+**工作原理：**
+1. 计算标签的边界框
+2. 检测是否超出图表边界
+3. 如果超出，向内调整位置
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'point',
+  data: [
+    { x: 10, y: 100 },
+    { x: 20, y: 150 },
+    { x: 30, y: 200 },  // 可能在图表顶部边缘
+  ],
+  encode: {
+    x: 'x',
+    y: 'y',
+  },
+  labels: [
+    {
+      text: 'y',
+      position: 'top',
+      transform: [{ type: 'exceedAdjust' }],
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 结合其他变换
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'x', y: 'y' },
+  labels: [
+    {
+      text: 'y',
+      position: 'top',
+      transform: [
+        { type: 'exceedAdjust' },
+        { type: 'overlapDodgeY' },
+      ],
+    },
+  ],
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface ExceedAdjustTransform {
+  type: 'exceedAdjust';
+  // 无额外配置参数
+}
+```
+
+## 与其他标签变换的对比
+
+| Transform | 功能 | 处理方式 |
+|-----------|------|---------|
+| exceedAdjust | 超出调整 | 移动位置 |
+| overflowHide | 溢出隐藏 | 隐藏标签 |
+| overlapDodgeY | 重叠避让 | Y 方向分开 |
+
+## 常见错误与修正
+
+### 错误 1：transform 格式错误
+
+```javascript
+// ❌ 错误：transform 应该是数组
+labels: [{ text: 'value', transform: { type: 'exceedAdjust' } }]
+
+// ✅ 正确
+labels: [{ text: 'value', transform: [{ type: 'exceedAdjust' }] }]
+```
+
+### 错误 2：与其他变换顺序错误
+
+```javascript
+// ⚠️ 注意：变换顺序影响结果
+// 建议先处理超出，再处理重叠
+
+// ✅ 正确顺序
+transform: [
+  { type: 'exceedAdjust' },
+  { type: 'overlapDodgeY' },
+]
+```

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

@@ -0,0 +1,185 @@
+---
+id: "g2-label-transform-overflow-hide"
+title: "G2 OverflowHide 标签变换"
+description: |
+  标签溢出隐藏变换。当标签超出其所属元素的边界时自动隐藏，
+  避免标签溢出造成的视觉混乱。
+
+library: "g2"
+version: "5.x"
+category: "label-transform"
+tags:
+  - "标签"
+  - "label"
+  - "溢出"
+  - "隐藏"
+  - "overflow"
+
+related:
+  - "g2-label-transform-overlap-hide"
+  - "g2-label-transform-overlap-dodge-y"
+  - "g2-comp-label-config"
+
+use_cases:
+  - "饼图标签溢出处理"
+  - "柱状图数据标签"
+  - "小尺寸元素的标签显示"
+
+anti_patterns:
+  - "标签必须全部显示的场景"
+
+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"
+---
+
+## 核心概念
+
+OverflowHide 标签变换会检测标签是否超出其所属元素的边界：
+- 如果标签在元素边界内，正常显示
+- 如果标签超出边界，自动隐藏
+
+**工作原理：**
+1. 计算元素的边界框
+2. 计算标签的边界框
+3. 检测标签是否溢出元素边界
+4. 溢出则隐藏标签
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'interval',
+  data: [
+    { category: 'A', value: 10 },
+    { category: 'B', value: 50 },
+    { category: 'C', value: 5 },  // 小柱子，标签可能溢出
+  ],
+  encode: {
+    x: 'category',
+    y: 'value',
+  },
+  labels: [
+    {
+      text: 'value',
+      position: 'inside',
+      transform: [{ type: 'overflowHide' }],
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 饼图标签溢出处理
+
+```javascript
+chart.options({
+  type: 'interval',
+  coordinate: { type: 'theta' },
+  data,
+  encode: { y: 'value', color: 'category' },
+  labels: [
+    {
+      text: 'category',
+      position: 'inside',
+      transform: [{ type: 'overflowHide' }],
+    },
+  ],
+});
+```
+
+### 结合其他标签变换
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value' },
+  labels: [
+    {
+      text: 'value',
+      position: 'inside',
+      transform: [
+        { type: 'overflowHide' },
+        { type: 'overlapHide' },  // 先处理溢出，再处理重叠
+      ],
+    },
+  ],
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface OverflowHideTransform {
+  type: 'overflowHide';
+  // 无额外配置参数
+}
+```
+
+## 与其他标签变换的对比
+
+| Transform | 功能 | 适用场景 |
+|-----------|------|---------|
+| overflowHide | 隐藏溢出标签 | 标签超出元素边界 |
+| overlapHide | 隐藏重叠标签 | 标签之间重叠 |
+| overlapDodgeY | Y 方向避让 | 标签垂直重叠 |
+
+## 常见错误与修正
+
+### 错误 1：transform 格式错误
+
+```javascript
+// ❌ 错误：transform 应该是数组
+labels: [{ text: 'value', transform: { type: 'overflowHide' } }]
+
+// ✅ 正确
+labels: [{ text: 'value', transform: [{ type: 'overflowHide' }] }]
+```
+
+### 错误 2：position 设置不当
+
+```javascript
+// ⚠️ 注意：outside 位置的标签通常不会溢出
+// overflowHide 主要用于 inside 位置
+
+// 对于 inside 标签
+labels: [{
+  text: 'value',
+  position: 'inside',
+  transform: [{ type: 'overflowHide' }]
+}]
+
+// 对于 outside 标签，考虑使用 overlapHide
+labels: [{
+  text: 'value',
+  position: 'outside',
+  transform: [{ type: 'overlapHide' }]
+}]
+```
+
+### 错误 3：与其他变换顺序错误
+
+```javascript
+// ⚠️ 注意：变换顺序影响结果
+
+// 推荐：先处理溢出，再处理重叠
+transform: [
+  { type: 'overflowHide' },
+  { type: 'overlapHide' },
+]
+```

package/builtin-skills/antv-g2-chart/references/label-transform/g2-label-transform-overflow-stroke.md

@@ -0,0 +1,147 @@
+---
+id: "g2-label-transform-overflow-stroke"
+title: "G2 OverflowStroke 标签变换"
+description: |
+  标签溢出描边变换。当标签超出元素边界时自动添加描边，
+  增强标签的可读性。
+
+library: "g2"
+version: "5.x"
+category: "label-transform"
+tags:
+  - "标签"
+  - "label"
+  - "溢出"
+  - "描边"
+  - "stroke"
+
+related:
+  - "g2-label-transform-overflow-hide"
+  - "g2-label-transform-contrast-reverse"
+  - "g2-comp-label-config"
+
+use_cases:
+  - "饼图外部标签"
+  - "需要增强可读性的标签"
+  - "复杂背景下的标签显示"
+
+anti_patterns:
+  - "简单场景不需要描边"
+
+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"
+---
+
+## 核心概念
+
+OverflowStroke 标签变换会检测标签是否超出元素边界：
+- 如果超出，为标签添加描边
+- 增强标签在复杂背景上的可读性
+
+**工作原理：**
+1. 计算元素和标签的边界框
+2. 检测标签是否超出元素边界
+3. 如果超出，添加描边样式
+
+## 最小可运行示例
+
+```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',
+  },
+  labels: [
+    {
+      text: 'value',
+      position: 'inside',
+      transform: [{ type: 'overflowStroke' }],
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 结合其他变换
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+  labels: [
+    {
+      text: 'value',
+      position: 'inside',
+      transform: [
+        { type: 'overflowStroke' },
+        { type: 'contrastReverse' },
+      ],
+    },
+  ],
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface OverflowStrokeTransform {
+  type: 'overflowStroke';
+  // 无额外配置参数
+}
+```
+
+## 与其他标签变换的对比
+
+| Transform | 功能 | 处理方式 |
+|-----------|------|---------|
+| overflowStroke | 溢出描边 | 添加描边 |
+| overflowHide | 溢出隐藏 | 隐藏标签 |
+| contrastReverse | 对比度反转 | 改变颜色 |
+
+## 常见错误与修正
+
+### 错误 1：transform 格式错误
+
+```javascript
+// ❌ 错误：transform 应该是数组
+labels: [{ text: 'value', transform: { type: 'overflowStroke' } }]
+
+// ✅ 正确
+labels: [{ text: 'value', transform: [{ type: 'overflowStroke' }] }]
+```
+
+### 错误 2：与其他变换顺序错误
+
+```javascript
+// ⚠️ 注意：描边应该在颜色调整之后
+// 建议顺序：contrastReverse → overflowStroke
+
+// ✅ 正确顺序
+transform: [
+  { type: 'contrastReverse' },
+  { type: 'overflowStroke' },
+]
+```