PlantUML预处理输出中的换行符问题解析

问题背景

在PlantUML的预处理过程中，开发者发现当使用%newline()函数时，预处理输出会显示奇怪的字符，而不是预期的换行效果。这个问题在版本1.2025.1中出现，而在之前的1.2024.8版本中表现正常。

技术分析

问题本质

%newline()函数在PlantUML中实际上是一个"显示换行符"，它会在预处理输出中显示为特殊字符。这不是一个bug，而是设计如此。对于需要在实际渲染中产生换行效果的情况，PlantUML提供了更合适的%breakline()函数。

解决方案

正确的做法是使用%breakline()替代%newline()。%breakline()专门用于在预处理和最终渲染中都能正确产生换行效果。以下是改进后的代码示例：

@startuml
!function $fct()
!$r = "BackgroundColor lightgreen" + %breakline()
!$r = $r + "FontColor green" + %breakline()
!return $r
!endfunction

!unquoted procedure $proc()
!$r = "skinparam rectangle<<boundary>> {" + %breakline()
!$r = $r + $fct()
!$r = $r + %breakline() + "}" + %breakline()
$r
!end procedure

$proc()

rectangle r1 <<boundary>> [
Test preproc
I 💚 plantuml
]
@enduml

版本兼容性说明

在PlantUML的C4库中，开发团队曾经实现了一个临时解决方案，使得%newline()在skinparam中也能工作。这是为了给开发者迁移到%breakline()提供过渡时间。但这个解决方案并不总是有效，特别是在某些特定函数如AddBoundaryTag中。

最佳实践建议

1. 统一使用%breakline()：对于所有需要换行效果的场景，建议使用%breakline()而不是%newline()。

2. 预处理检查：在开发复杂PlantUML图表时，定期使用-preproc选项检查预处理输出，确保换行等特殊字符按预期工作。

3. 版本升级注意事项：从1.2024.8升级到1.2025.1或更高版本时，需要检查所有使用%newline()的地方，特别是涉及skinparam等样式定义的代码。

结论

PlantUML中的换行处理有其特定的设计考虑。理解%newline()和%breakline()的区别对于编写可维护的PlantUML代码非常重要。随着PlantUML版本的更新，遵循官方推荐的最佳实践可以避免类似预处理输出问题。开发者应当逐步将现有代码中的%newline()迁移到%breakline()，以确保代码的长期兼容性和可维护性。