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

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

@@ -0,0 +1,309 @@
+---
+id: "g2-mark-text"
+title: "G2 文字标注（text Mark）"
+description: |
+  G2 v5 内置 text Mark，用于在图表中绘制自定义文字标注，
+  encode.x/y 确定位置，encode.text 或 style.text 提供内容，
+  常与其他 Mark 叠加使用，实现数据标签、阈值标注和图表标题等效果。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "文字标注"
+  - "text"
+  - "标签"
+  - "注释"
+  - "annotation"
+  - "spec"
+
+related:
+  - "g2-mark-line-basic"
+  - "g2-mark-interval-basic"
+  - "g2-core-view-composition"
+  - "g2-comp-annotation"
+
+use_cases:
+  - "在柱状图顶部显示数值标签"
+  - "标注图表中的特殊事件或阈值"
+  - "添加自定义图表标题或说明文字"
+  - "高亮某个数据点的文字描述"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/annotation/annotation/#text"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 600,
+  height: 400,
+});
+
+const data = [
+  { month: '1月', value: 120 },
+  { month: '2月', value: 180 },
+  { month: '3月', value: 150 },
+  { month: '4月', value: 210 },
+  { month: '5月', value: 170 },
+];
+
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    {
+      type: 'interval',
+      encode: { x: 'month', y: 'value' },
+    },
+    {
+      type: 'text',
+      encode: {
+        x: 'month',
+        y: 'value',
+        text: 'value',   // 数据字段名 → 显示该字段的值
+      },
+      style: {
+        textAlign: 'center',
+        dy: -8,           // 向上偏移
+        fontSize: 12,
+        fill: '#333',
+      },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 固定位置文字标注（不绑定数据）
+
+```javascript
+// 在图表固定位置添加一行文字（如阈值说明）
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    {
+      type: 'line',
+      encode: { x: 'month', y: 'value' },
+    },
+    {
+      // 固定位置文字，使用单条数据
+      type: 'text',
+       [{ x: '3月', y: 200, label: '达标线' }],
+      encode: { x: 'x', y: 'y', text: 'label' },
+      style: {
+        fill: '#ff4d4f',
+        fontSize: 12,
+        fontWeight: 'bold',
+        dx: 5,
+      },
+    },
+  ],
+});
+```
+
+## 结合 lineY 标注水平阈值线
+
+```javascript
+// lineY + text 组合：标注阈值线
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    {
+      type: 'interval',
+      encode: { x: 'month', y: 'value' },
+      style: { fill: '#1890ff' },
+    },
+    {
+      // 水平阈值线
+      type: 'lineY',
+      data: [{ y: 160 }],
+      encode: { y: 'y' },
+      style: { stroke: '#ff4d4f', lineDash: [4, 4], lineWidth: 1.5 },
+    },
+    {
+      // 阈值标注文字
+      type: 'text',
+       [{ month: '5月', value: 160, label: '目标 160' }],
+      encode: { x: 'month', y: 'value', text: 'label' },
+      style: {
+        fill: '#ff4d4f',
+        fontSize: 12,
+        textAlign: 'right',
+        dy: -6,
+      },
+    },
+  ],
+});
+```
+
+## 完整配置项
+
+```javascript
+chart.options({
+  type: 'text',
+  data,
+  encode: {
+    x: 'xField',      // x 位置（对应坐标轴字段）
+    y: 'yField',      // y 位置（对应坐标轴字段）
+    text: 'textField', // 显示的文字内容字段
+    color: 'series',  // 按系列着色（可选）
+  },
+  style: {
+    // 文字样式
+    fontSize: 12,
+    fontWeight: 'normal',
+    fill: '#333',
+    textAlign: 'center',    // 'left' | 'center' | 'right'
+    textBaseline: 'bottom', // 'top' | 'middle' | 'bottom'
+
+    // 位置偏移
+    dx: 0,    // 水平偏移（px）
+    dy: -8,   // 垂直偏移（px，负值向上）
+
+    // 背景框（可选）
+    background: true,
+    backgroundFill: 'rgba(255,255,255,0.8)',
+    backgroundPadding: [2, 4],
+    backgroundRadius: 3,
+
+    // 旋转
+    rotate: 0,   // 旋转角度（度）
+  },
+});
+```
+
+## 散点图数据点标签
+
+```javascript
+const scatterData = [
+  { x: 10, y: 80, name: '产品A' },
+  { x: 20, y: 60, name: '产品B' },
+  { x: 35, y: 90, name: '产品C' },
+  { x: 50, y: 40, name: '产品D' },
+  { x: 65, y: 75, name: '产品E' },
+];
+
+chart.options({
+  type: 'view',
+  data: scatterData,
+  children: [
+    {
+      type: 'point',
+      encode: { x: 'x', y: 'y' },
+      style: { r: 6, fill: '#1890ff' },
+    },
+    {
+      type: 'text',
+      encode: { x: 'x', y: 'y', text: 'name' },
+      style: {
+        dy: -12,
+        textAlign: 'center',
+        fontSize: 11,
+        fill: '#666',
+      },
+    },
+  ],
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：text Mark 独立使用时没有数据
+
+```javascript
+// ❌ 错误：text Mark 需要 data 或者从父 view 继承数据
+chart.options({
+  type: 'text',
+  // 缺少 data，且无父 view 提供数据
+  encode: { x: 'month', y: 'value', text: 'label' },
+});
+
+// ✅ 正确方式一：在父 view 中提供数据
+chart.options({
+  type: 'view',
+  data,               // 父 view 提供数据，子 mark 自动继承
+  children: [
+    { type: 'interval', encode: { x: 'month', y: 'value' } },
+    { type: 'text', encode: { x: 'month', y: 'value', text: 'value' } },
+  ],
+});
+
+// ✅ 正确方式二：text Mark 自带数据（用于固定标注）
+chart.options({
+  type: 'text',
+  data: [{ x: '3月', y: 200, label: '特殊标注' }],
+  encode: { x: 'x', y: 'y', text: 'label' },
+});
+```
+
+### 错误 2：encode.text 写成了字面量字符串而非字段名
+
+```javascript
+// ❌ 错误：encode.text 应该是数据中的字段名，不能写固定文字
+chart.options({
+  type: 'text',
+  encode: {
+    x: 'month',
+    y: 'value',
+    text: '固定文字',   // ❌ 这里写的是字面量，但数据中没有叫 '固定文字' 的字段
+  },
+});
+
+// ✅ 正确：固定文字应用 style.text 或 transform 函数
+chart.options({
+  type: 'text',
+  encode: { x: 'month', y: 'value' },
+  style: {
+    text: (d) => `${d.value}`,   // ✅ 通过函数返回文字内容
+    textAlign: 'center',
+    dy: -8,
+  },
+});
+
+// 或者在 encode 中用函数
+chart.options({
+  type: 'text',
+  encode: {
+    x: 'month',
+    y: 'value',
+    text: (d) => d.value,   // ✅ encode.text 可以是函数
+  },
+});
+```
+
+### 错误 3：text 与 interval 叠加时忘记共用 view
+
+```javascript
+// ❌ 错误：两个独立 chart 无法叠加
+const chart1 = new Chart({ container: 'c1' });
+chart1.options({ type: 'interval', data, encode: { x: 'month', y: 'value' } });
+
+const chart2 = new Chart({ container: 'c2' });
+chart2.options({ type: 'text', data, encode: { x: 'month', y: 'value', text: 'value' } });
+
+// ✅ 正确：用 view 的 children 叠加
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    { type: 'interval', encode: { x: 'month', y: 'value' } },
+    {
+      type: 'text',
+      encode: { x: 'month', y: 'value', text: 'value' },
+      style: { textAlign: 'center', dy: -8 },
+    },
+  ],
+});
+```

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

@@ -0,0 +1,235 @@
+---
+id: "g2-mark-tree"
+title: "G2 树形图（tree）"
+description: |
+  tree mark 将层级数据（树状 JSON）渲染为树形结构，
+  自动布局节点（point mark）和连线（link mark），
+  支持横向/纵向/径向布局，适合组织架构图、决策树、层级分类展示。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "tree"
+  - "树形图"
+  - "层级"
+  - "组织架构"
+  - "树状"
+  - "hierarchy"
+
+related:
+  - "g2-mark-treemap"
+  - "g2-mark-partition"
+  - "g2-mark-sankey"
+
+use_cases:
+  - "组织架构图展示"
+  - "决策树可视化"
+  - "文件目录树形展示"
+  - "分类层级结构可视化"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/hierarchy/tree/"
+---
+
+## 最小可运行示例（横向树形图）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+// 树形数据（嵌套 JSON 格式）
+const treeData = {
+  name: '总公司',
+  children: [
+    {
+      name: '研发部',
+      children: [
+        { name: '前端组', value: 10 },
+        { name: '后端组', value: 15 },
+        { name: '算法组', value: 8 },
+      ],
+    },
+    {
+      name: '市场部',
+      children: [
+        { name: '品牌组', value: 6 },
+        { name: '运营组', value: 9 },
+      ],
+    },
+    {
+      name: '产品部',
+      children: [
+        { name: 'B端产品', value: 7 },
+        { name: 'C端产品', value: 5 },
+      ],
+    },
+  ],
+};
+
+const chart = new Chart({ container: 'container', width: 800, height: 500 });
+
+chart.options({
+  type: 'tree',
+  data: treeData,
+  layout: {
+    // 布局方向：false=纵向（上→下），true=横向（左→右）
+    // G2 tree 使用 d3-hierarchy tidy tree 布局
+  },
+  encode: {
+    value: 'value',  // 节点大小编码字段（可选）
+  },
+  // 节点样式
+  nodeLabels: [
+    { text: 'name', style: { fontSize: 12, dx: 6 } },
+  ],
+  // 连线样式
+  style: {
+    nodeSize: 5,
+    nodeFill: '#5B8FF9',
+    linkStroke: '#aaa',
+    linkLineWidth: 1.5,
+  },
+});
+
+chart.render();
+```
+
+## 纵向树形图（自上而下）
+
+```javascript
+chart.options({
+  type: 'tree',
+  data: treeData,
+  coordinate: { transform: [{ type: 'transpose' }] },  // 转置为纵向
+  nodeLabels: [
+    {
+      text: 'name',
+      style: { fontSize: 11, textBaseline: 'bottom', dy: -6 },
+    },
+  ],
+  style: {
+    nodeFill: '#52c41a',
+    nodeSize: 6,
+    linkShape: 'smooth',  // 连线使用平滑曲线
+  },
+});
+```
+
+## 径向树形图（放射状）
+
+```javascript
+chart.options({
+  type: 'tree',
+  data: treeData,
+  coordinate: { type: 'polar', innerRadius: 0.1 },  // 极坐标 = 径向布局
+  style: {
+    nodeFill: '#ff7875',
+    nodeSize: 4,
+  },
+  nodeLabels: [
+    {
+      text: 'name',
+      style: {
+        fontSize: 10,
+        textAlign: (d) => (d.x > Math.PI ? 'right' : 'left'),
+      },
+    },
+  ],
+});
+```
+
+## 常见错误与修正
+
+### 错误：传入扁平数据而非嵌套 JSON
+```javascript
+// ❌ tree mark 需要嵌套 JSON（children 字段），不接受扁平数组
+chart.options({
+  type: 'tree',
+  data: [
+    { id: 1, parent: null, name: '根' },
+    { id: 2, parent: 1, name: '子' },
+  ],  // ❌ 扁平数据不能直接使用
+});
+
+// ✅ 需要嵌套格式
+chart.options({
+  type: 'tree',
+   { name: '根', children: [{ name: '子' }] },  // ✅ 嵌套 JSON
+});
+```
+
+### 错误：tree 与 treemap 混淆
+```javascript
+// tree：展示层级结构关系（节点+连线，强调层次和连接）
+chart.options({ type: 'tree',  data: { value: hierarchyData } });
+
+// treemap：按面积展示层级数据占比（矩形嵌套，强调大小和比例）
+chart.options({ type: 'treemap',  data: { value: hierarchyData } });
+```
+
+---
+
+## 节点数据访问规则（重要！）
+
+层次结构图中，回调函数接收到的参数 `d` **不是原始数据对象**，而是 G2 用 d3-hierarchy 包装后的层次节点，**原始数据在 `d.data` 中**。
+
+### 回调参数 d 的结构
+
+```javascript
+// d 是 d3-hierarchy 节点，结构如下：
+{
+  value: 10,               // 节点数值（d3 计算的子树总和）
+  depth: 2,                // 层级深度（0 = 根节点）
+  height: 0,               // 子树高度（叶子节点为 0）
+  data: {                  // ← 原始数据在这里！
+    name: '前端组',
+    value: 10,
+    // ... 其它自定义字段
+  },
+  path: ['根', '研发部', '前端组'],
+}
+```
+
+### nodeLabels 中访问字段
+
+tree mark 的 `nodeLabels` 使用字符串 `'name'` 时，G2 内部会查找 `d.data['name']`（有专项处理），所以字符串形式可以工作。但如需访问计算属性（`depth`、`height`）或条件渲染，必须使用回调：
+
+```javascript
+// ✅ 字符串形式（tree 的 nodeLabels 对 data 字段有专项处理）
+nodeLabels: [
+  { text: 'name', style: { fontSize: 12 } },
+]
+
+// ✅ 回调形式（需要条件判断或访问节点属性时）
+nodeLabels: [
+  {
+    text: (d) => {
+      if (d.height > 0) return d.data?.name;  // 父节点显示名称
+      return `${d.data?.name}\n(${d.value})`;  // 叶节点显示名称+数值
+    },
+    style: { fontSize: 12 },
+  },
+]
+```
+
+### encode.color 必须用回调
+
+与其他层次 mark 一样，`encode.color` 字符串对 tree 也**不起作用**：
+
+```javascript
+// ❌ 错误：color: 'type' 等价于 d['type'] = undefined
+encode: {
+  value: 'value',
+  color: 'type',  // ❌ → undefined → 所有节点相同颜色
+}
+
+// ✅ 正确：必须用回调
+encode: {
+  value: 'value',
+  color: (d) => d.data?.type,  // ✅ 通过 d.data 访问原始字段
+}
+```