oxdraw 图表工具概述
oxdraw 旨在通过声明式、可复现的语法,简化高质量图表的创建与维护。图表使用 Mermaid 语法编写,同时提供 Web 界面供用户精细调整节点位置、连接路径、颜色和其他样式。任何通过界面进行的视觉修改都会以声明式代码的形式自动保存回源文件,确保图表保持确定性并支持版本控制。
除了常规图表,oxdraw 还支持直接在图表中嵌入图像,并能查看代码库的代码地图,其中节点可以链接到具体的代码段。所有样式修改都以注释形式保存在 Mermaid 文件中,从而保持与 Mermaid 生态其他工具的兼容性。
该项目的愿景是结合代码生成图表(如 Mermaid)的优势与图形编辑器(如 Lucidchart)的自定义灵活性。
核心组件与安装
项目仓库由以下部分构成:
- Rust CLI:用于将
.mmd 文件编译为图像。
- 基于 React 的 Web 界面:用于交互式编辑。
- AI 与静态分析算法:用于自动生成代码地图。
可以通过 Cargo 安装:
cargo install oxdraw
主要功能与使用
渲染图表:
oxdraw --input flow.mmd
启动交互式编辑器:
oxdraw --input flow.mmd --edit
编辑器功能丰富,包括:
- 拖拽节点:更新位置,支持网格对齐和实时参考线。
- 调整连接路径:拖拽边控制点或标签来重塑路径,双击边可插入新控制点,双击控制点可删除手动路径。
- 移动子图:拖拽子图容器可整体移动其所有成员节点。
- 样式定制:为单独节点/边设置填充、描边、文本颜色,以及边线类型(实线/虚线)、箭头方向等。
- 源码同步:源码面板自动同步并保存对 Mermaid 文件的修改。
图表分享:
- 导出为图像(PNG 或 SVG)。
- 通过 URL 分享:通过静态网站上的“分享”按钮,将图表数据保存在 URL 的哈希片段中,便于他人查看和编辑。
AI 生成代码地图与映射文档:
- 生成代码地图:可视化代码库结构,节点映射到代码段。
oxdraw --code-map ./ --gemini YOUR_API_KEY
- 生成“编码文档”:创建包含嵌入映射元数据的 Markdown 文档,文档中的标题、段落和内联代码可以点击并跳转到代码库。
oxdraw --codedown ./ --gemini YOUR_API_KEY
- 增强现有 Markdown 文件:为已有文档添加代码映射。
oxdraw --augment-markdown docs/notes.md --repo-path . --gemini YOUR_API_KEY
以上 AI 功能支持通过 --gemini 指定 API 密钥,也可使用 --no-ai 进行静态分析生成。
图表绘制算法:
算法在路径布局上存在多种权衡(如平滑线条与清晰直角、避免重叠与减少路径长度、减少折点等)。当前实现允许通过删除关系、移动节点来观察算法如何重新计算布局,并计划未来提供更多偏好变体。
CLI 标志汇总
CLI 提供了丰富的命令行选项,涵盖输入输出控制(-i, -o)、输出格式与缩放(--png, --scale)、编辑器设置(--edit, --serve-host, --serve-port)、背景色、AI 相关参数(--api-key, --model, --gemini, --prompt)以及代码地图/编码文档生成(--code-map, --codedown, --codedown-style, --augment-markdown)等功能。
社区与集成
项目欢迎用户反馈和贡献,已有多个相关集成项目:
- Typst-Oxdraw:将 oxdraw 图表集成到 Typst 文档中。
- Asciidoctor:支持 oxdraw。
- oxmap:一个 TUI 工具,使用 oxdraw 的库生成流程图。