跳到正文
QuireKit Markdown
开发者文档
预览版 · 未发布
扩展与渲染查看 Markdown ↗

流程图、思维导图与白板

用现有编辑器的图稿渲染文档,并在 Markdown 阅读组件中接入同样的能力。

文档中的算法图由 QuireKit 的流程图、思维导图和白板渲染器绘制。 图里的节点、文字和连线保存在原生图稿中;点击“查看图稿”可以取得 JSON,点击“查看大图”可以放大阅读。

在本站文档里放一张图

本站已经为下面三种代码围栏注册了渲染组件。把编辑器导出的完整图稿放在对应围栏里,正文就会显示图表。

围栏语言图稿渲染器
quirekit-flowchartFlowchartEmbedFlow Editor 使用的 X6 适配器
quirekit-mind-mapMindMapEmbedMind Editor 使用的 SimpleMindMap 适配器
quirekit-whiteboardWhiteboardDocument已有 Excalidraw 白板适配器

例如,下面是一个可以直接复制的流程图图稿。这段围栏由文档的代码组件自动显示为图表:

从片段到解析

正在准备图表…

查看图稿
json

这里只读取图稿,不会改写文档。缩放和“适应画布”只改变查看范围。

看原文与语法树怎样变化

下面由 QuireKit 流程图绘制并播放的场景,展示实际 Markdown 原文和 Lezer 语法树。默认连续插入 加粗文字、行内代码与两项列表;跟随移动片段进入源落点,定位旧分支,再换入新节点。 可以播放、暂停、单步、回退和重播,不能拖动、平移或缩放视图。

正在准备示例…

recording/fixture.ts 定义原文与连续源码修改,recording/snapshots.ts 记录真正的增量解析和公共阅读投影。 中间插入使用 EditorState 源码事务;末尾追加与后置引用实际调用 MarkdownStream.append。 recording/tree.ts 从原生树读取类型、子节点、范围和对象编号,没有按文本相似度猜测复用。

回放只选择不可变的旧、新快照,再交给正常的 QuireMarkdown 显示。不会重复插入片段, 也不会重挂历史 Vue 节点。语法树复用与阅读缓存分别展示:即使后续段落的 Tree 对象保留, 绝对位置变化也可能要求重新投影。本例的慢放是教学编排,不是解析器内部日志或性能测速。

graph/scene.ts 把这些数据变成 FlowchartDocument,graph/trace.ts 编排步骤。 每一步的 scene 描述接受后的完整图形:相同 ID 保留展示对象,新 ID 表示新节点。 sceneDuration 决定位置、文字和节点进出的过渡时长;travel 负责片段沿线移动, pulse 标出受影响分支。第三次插入同时展示新列表和相邻段落的变化。

图形、过渡和播放时钟均由 @quirekit/flowchart-x6 的公共 playback 提供。 本站只把真实快照映射为图稿、操作公共播放器并显示阅读结果。播放使用临时展示图, 不会修改作者图源、编辑历史或静态导出。流程图、思维导图和白板也继续用于静态关系图。

在 QuireMarkdown 中接入

Markdown 引擎允许用 components.pre 替换代码块的显示。下面的完整示例只为三种原生图稿启用渲染,普通代码仍保留代码查看与复制。

正在准备示例…

打开示例源码,可以看到原生图稿生成、格式校验、三个渲染器的加载和挂载释放。 这些渲染器由宿主选择;公共 Markdown 内核没有新增图表编辑器依赖。React 宿主可用同样的图稿及浏览器适配器,另行实现自己的组件挂载。

接入 docs-kit 的站点

使用共享文档层时,可以在 Nuxt plugin 中通过 docsCodeRenderersKey 注册围栏语言到组件的映射。 该入口来自 @quirekit/docs-kit/runtime。组件接收原始 code、language、可选 filename 和 presentation;图稿不能被解释为 Vue 模板。

未注册的语言继续显示为代码,示例的源码面板也继续显示原始文件。各站自行选择渲染器,docs-kit 不安装图表编辑器。

加载与错误处理

图表资源在客户端、图进入可视范围时才加载。服务端保留可读取的图稿;浏览器初始化失败时,可以继续查看和复制原稿。 切换图稿、关闭大图或离开页面,会取消旧加载并销毁渲染实例。本站采用只读查看;编辑及保存仍由已有编辑器和应用负责。

图稿先通过各领域的格式校验。格式不完整时显示原始代码。本站自动预览还限制为 200 个流程图节点与 400 条连线、500 个思维导图主题或白板元素,源码最多 4 Mi 个 UTF-16 单元;超出时保留原稿。这个限制属于文档预览,不是各编辑器协议的容量上限。

QuireKit Markdown · QuireKit流式 Markdown · @quirekit/incremark · MIT