X6 文档优化参考项

[q32757468]

优化目标

此次文档优化主要为两个目标：

1. 优化文档内容和结构，方便用户查找内容，确保内容清晰易懂，以及遇到文档方便查找
2. 利于大模型学习以及搜索引擎检索

基本改造思路

代码块

文档中的相对完整的代码示例代码补充完整，例如import语句等，由于代码已经够复杂，所以把代码补充完整并不会影响观感，同时确保示例完整可以确保大模型学习完整，也可以确保用户可以复制既用。

bad ❌ 示例不完整，无法直接运行使用

new Graph({
  container: this.container,
  grid: {
    visible: true,
    type: 'dot',
    args: {
      color: '#a0a0a0', // 网点颜色
      thickness: 1, // 网点大小
    },
  },
})

good ✅ 完整示例，复制后无需改动也可以运行

import { Graph } from '@antv/x6' // 确保引入了 Graph

new Graph({
  container: document.querySelector("container"),
  grid: {
    visible: true,
    type: 'dot',
    args: {
      color: '#a0a0a0',
      thickness: 1,
    },
  },
})

尽量不使用 **<code src="@/xx"></code>** 形式来引入代码块

bad ❌ 使用了code标签，不利于大模型理解

<code id="attrs-ref-elem" src="@/src/api/attrs/ref/index.tsx"></code>

good ✅ 直接使用代码来书写，方便大模型收集理解

import { Graph } from '@antv/x6'

new Graph({
  container: document.querySelector("container"),
  grid: {
    visible: true,
    type: 'dot',
    args: {
      color: '#a0a0a0',
      thickness: 1,
    },
  },
})

---

尽量使用非框架形式来写代码示例

bad ❌ 使用了 react 框架来书写示例，对于不熟悉的同学会有一些理解成本，需要额外到其他地方来找代码学习转换

import * as React from 'react'
import { Graph } from '@antv/x6'

export default class Example extends React.Component {
  private container: HTMLDivElement

  componentDidMount() {
    const graph = new Graph({
      container: this.container,
    })

    graph.addNode({
      x: 40,
      y: 40,
      width: 160,
      height: 48,
      attrs: {
        body: {
          fill: '#ffffff',
          stroke: '#8f8f8f',
          strokeWidth: 1,
          rx: 5,
          ry: 5,
        },
        label: {
          textAnchor: 'left',
          refX: 8,
          text: 'hello test foo bar lint css jsvascript typescript',
          textWrap: {
            width: 144,
            height: 40,
            ellipsis: true,
          },
        },
      },
    })
  }

  refContainer = (container: HTMLDivElement) => {
    this.container = container
  }

  render() {
    return (
      <div>
        <div ref={this.refContainer} className="app-content" />
      </div>
    )
  }
}

good ✅

参考G6使用 js | ob { inject: true } 的形式来写case，同时写为js写法：

const graph = new Graph({
	container: document.querySelector("#container"),
})

graph.addNode({
	x: 40,
	y: 40,
	width: 160,
	height: 48,
	attrs: {
		body: {
			fill: '#ffffff',
			stroke: '#8f8f8f',
			strokeWidth: 1,
			rx: 5,
			ry: 5,
		},
		label: {
			textAnchor: 'left',
			refX: 8,
			text: 'hello test foo bar lint css jsvascript typescript',
			textWrap: {
				width: 144,
				height: 40,
				ellipsis: true,
			},
		},
	},
})

概念介绍

对于一些概念添加概念介绍，告诉用户这个概念是什么，对于没接触过图表的用户来说很重要，告诉用户这个是干什么用的，先有一个简单的概念，再介绍如何使用，必要时需要配上示意图，

同时将这些内容去掉，用简介替换，这部分内容和目录有点重复了，而且也没有帮忙让用户快速了解概念

示意图

对于一些概念偏多的章节，例如 节点/边 等等章节，可以添加拆解示意图来帮助用户理解这些概念的具体含义类似这样：

类型定义

目前文档中对于类型定义比较缺失，只是简单的类型名称，缺乏详细的定义。

为了完善类型定义，应该从需要添加定义和添加类型条装：

1. 对于复杂的类型，应该添加类型定义部分
2. 对于当前章节已定义好的类型或者其他章节定义好的类型，应该添加链接以及高亮，跳转到此处

api示例

对于一些不好理解的api添加示例：

文档api介绍

对于文档中的介绍部分，如果存在对应的api，可以添加api的跳转链接等

明确API以及文档的界限

目前API文档中存在很多介绍使用类的内容，应该考虑统一放在文档章节中，确保用户阅读的连续性，相似的内容可以不用反复跳转，并且确保API中的内容都是API，保持统一性。

FAQ

用户在使用X6或者文档的过程中难免遇到问题，很多问题是前人遇到过的问题，可以通过添加FAQ的形式来辅助用户排查和解决问题：

1. 简单的问题可以直接在文档内直接描述并且给出解决方案
2. 复杂或者社区已有问题可以链接到github中或者社区相关文档中

ideal

文档最终的目的是为了方便用户理解，所以有好的想法可以自行实现，只要有利于实现目标

现状问题

已知问题

• 文档目录缺少中文名称，不方便检索
• sanbox跳转后case失效，原因为默认root创建方式未更新到react19的新方式
• api章节中的mvc中记录的是画布属性和方法，却单独作为了一部分，看的云里雾里
• 文档 refDKeepOffset 的代码示例中的case在v2版本中由于异步渲染的原因结果不符合预期：

...补充中

社区看板

文档建议（目前依然存在 29 个问题可以参考）：
社区看板中筛选近连年的用户反馈中目前未解决问题：

• 在 cell.onapi上期望列出所有的事件名称，但是实际上在事件章节有展示，可以添加链接方便用户查找
• 在定制节点章节用户期望节点链接桩和数据产生关联，可以考虑添加更多的case
• 需要更完善的类型定义

页面评价
按照点踩数量来排名：

1. api/graph/graph 34
2. api/model/node 5
3. api/model/cell 4
4. tutorial/basic/edge 4
5. ...

主要的点踩来源集中在graph页面，访问量很高，点踩量也很高，可以参考点踩数量来有优先级的对文档页面进行优化

Issue收集

还需要参考社区issue中收集的问题
#4781