PlantUML Newpage 不工作？渲染与输出修复指南

如果 PlantUML newpage 在 OnUML 中看似无效，原因在于当前的预览模型：每个 PlantUML 图表标签页只显示一张渲染图片。OnUML 目前不提供下一页控件，也不能从一份包含 newpage 的源代码中下载一组图片。

PlantUML 语言可以使用 newpage 拆分受支持的时序图，但这不会自动让所有在线编辑器都变成多页查看器。在 OnUML 中，可靠的做法是将每个面向读者的页面或场景分别放入一个图表标签页。

要点总结

• OnUML 目前每个 PlantUML 图表标签页只预览和导出一张渲染图片。
• newpage 不会在 OnUML 预览中创建页面导航。
• PNG 和 SVG 操作导出的是当前预览所显示的图片，而非多页文件包。
• 如果每个部分都必须在 OnUML 中可见、可编辑、可分享和可下载，请使用多个图表标签页。
• 尽可能让一张时序图专注于读者的一项任务。

快速诊断

newpage 的含义

在 PlantUML 时序图语法中，newpage 标记不同部分之间的分页。最小源代码如下：

@startuml
title Sign-in flow
actor User
participant App

User -> App: Submit credentials
App --> User: Authentication result

newpage Recovery flow

User -> App: Request password reset
App --> User: Send reset instructions
@enduml

该语法在 PlantUML 语言层面描述多个渲染页面，但没有规定编辑器必须如何显示、导航、命名或下载这些页面。

OnUML 的 PlantUML 预览为每个图表标签页请求并显示一张图片。因此，当前界面不会显示后续的 newpage 部分。

OnUML 推荐方案：使用多个图表标签页

不要把两个场景放在一个 newpage 后面，而是在完整的 OnUML 编辑器中创建两个 PlantUML 图表标签页。下面两段预览对应要粘贴到这些标签页中的源代码；博客会分别渲染它们，不会复刻编辑器的标签栏。

1. 打开完整编辑器并选择 PlantUML 模式。
2. 在预览下方的图表标签栏中双击当前标签，将其重命名为 Sign-in flow。
3. 用下方标签页 1 源代码替换其中代码。
4. 点击标签栏右端的 + 按钮，其工具提示为 Add diagram。
5. 双击新标签，将其重命名为 Recovery flow，再粘贴标签页 2 源代码。
6. 点击各标签页，在两张图表之间切换并检查预览。

标签页 1：登录流程

@startuml
title Sign-in flow
actor User
participant App

User -> App: Submit credentials
App --> User: Authentication result
@enduml

标签页 2：恢复流程

@startuml
title Recovery flow
actor User
participant App

User -> App: Request password reset
App --> User: Send reset instructions
@enduml

这种结构更适合 OnUML，因为每张图表都可以：

• 直接预览
• 用清晰的标签标题重命名
• 独立编辑
• 下载为 PNG 或 SVG
• 包含在已保存的项目中
• 作为项目工作流的一部分分享

这样还更便于将各图片嵌入文档，因为无需依赖页面顺序就能清楚理解它的用途。

在 OnUML 中逐步修复

1. 在完整的 OnUML 编辑器中打开源代码。
2. 选择 PlantUML 模式。
3. 双击预览下方标签栏中的当前标签，然后输入描述性图表名称。
4. 将第一个 newpage 之前的内容复制到该标签页，并为其添加自己的 @startuml 和 @enduml。
5. 点击标签栏右端的 +（Add diagram）按钮。
6. 双击新标签进行重命名，再把下一个部分移入其中。
7. 对所有剩余部分重复此操作。
8. 点击各标签切换图表，并检查所有预览。
9. 根据需要从每个标签页下载 PNG 或 SVG。
10. 如果希望将这些图表作为一个 OnUML 项目保留，请登录并选择 Save。

除非其他 PlantUML 环境也使用同一份源代码并需要 newpage，否则不要在拆分后的标签页中保留它。

何时应保留一张图表

并非所有情况都需要拆分。当消息构成一个简短而连续的交互，并且读者应将其理解为一条完整时间线时，请保留一张时序图。

如果图表很长，但仍代表同一场景，请先尝试以下方法：

• 删除不影响读者决策的实现细节。
• 使用 ref 概括次要交互。
• 用一条有意义的消息替代重复的底层消息。
• 将错误恢复移到单独图表。
• 让参与者标签保持简短一致。

使用引用的示例：

@startuml
actor User
participant App
participant Identity

User -> App: Sign in
App -> Identity: Verify credentials

ref over App, Identity
Token validation and account checks
end ref

Identity --> App: Authentication result
App --> User: Open dashboard
@enduml

ref 块无需创建另一个渲染页面，也能保留上下文。

导出结果

将源代码拆分到标签页后：

1. 打开第一个标签并检查预览。
2. 选择 PNG 获取常规图片，或选择 SVG 获取可缩放文档图片。
3. 对每个标签重复操作。
4. 重命名下载文件以明确顺序，例如：
   • 01-sign-in-flow.svg
   • 02-recovery-flow.svg

PlantUML 导出指南介绍了 OnUML 项目、浏览器草稿、PNG/SVG 下载和公开分享之间的区别。

常见错误

期望 newpage 添加界面控件

PlantUML 语法无法向 OnUML 界面添加上一页或下一页按钮。导航属于编辑器功能。

未检查所有标签页就导出

每个标签页都有自己的当前预览。下载前请逐个打开并检查。

在必需交互的中间拆分

读者需要完整顺序才能理解行为时，应让消息保持在一起。按场景或职责拆分，而不是简单按行数拆分。

将分享链接当作多页 PDF

分享链接提供对共享图表内容的浏览器访问，但不会将 PlantUML 页面组装为 PDF。

只把重要工作保存在未保存的草稿中

浏览器本地草稿很方便，但不是永久备份。图表很重要时，请保存 OnUML 项目，并另行保留源代码。

常见问题解答

OnUML 支持 PlantUML newpage 导航吗？

目前不支持。PlantUML 预览每个图表标签页只显示一张渲染图片，不提供上一页或下一页控件。

为什么只能看到第一页？

源代码可能描述了多个 PlantUML 页面，但 OnUML 当前预览只显示一张图片。请将各部分拆分到独立图表标签页。

PNG 或 SVG 会下载所有 newpage 部分吗？

不会。当前导出操作只下载活动预览中可见的图片。请分别导出拆分后的每个标签页。

可以将这些页面保存在同一个 OnUML 项目中吗？

可以。将每个部分放在独立图表标签页中，再保存项目。这样既能保留图表之间的关系，也不会将部分内容隐藏在 newpage 之后。

OnUML 可以将页面导出为一个 PDF 吗？

不能直接导出。请将各标签页导出为 SVG 或 PNG，再在用于生成 PDF 的文档工具中组装。

后续步骤

• 打开完整的 OnUML 编辑器，将时序图拆分到多个图表标签页。
• 使用 PlantUML 示例指南选择更小的图表结构。
• 按照 PlantUML 导出指南，将每个标签页下载为 PNG 或 SVG。
• 阅读 PlantUML 所见即所得指南，了解 PlantUML 预览和直接画布编辑为何属于不同工作流。

在 OnUML 中，多个图表标签页是 newpage 工作流的实用替代方案：每个部分都保持可见、可编辑、可下载，也更易维护。