# 图形支持范围

截至 2026 年 10 月 21 日，NornaKit 已为 33 类图形提供纯 Swift 原生入口、基础解析、专用布局和示例。项目没有运行上游 JavaScript 或 Mermaid 解析器。第三方参考来源见 `THIRD_PARTY_NOTICES.md`。

这是一份基础实现的范围说明，具体语法支持以各类图形的能力和限制为准。所有示例均通过 `NativeDiagramRenderer` 渲染，画布直接使用 CoreGraphics 绘制，SVG 使用相同几何数据导出。未知的独立指令通常会报错；不进行 HTML、Markdown 或 CSS 样式解释，标签支持纯文本、换行、`:sf:名称:` 内联 SF Symbols、四种图标渲染模式、配对标签原生富文本。图标标记整体换行，富文本换行后保留样式；单色图标跟随文字字号、字重、颜色和基线。未知名称保留原文，可用图标取决于渲染时的 macOS 版本。此语法为 NornaKit 扩展，不改变各图形原有的图标配置语法。PNG、JPEG、TIFF 和 PDF 原生绘制图标，SVG 以 4 倍分辨率的透明 PNG 内嵌图标，其他文字和路径仍为矢量元素。

| 图形 | 已实现的核心能力 | 当前限制 |
| --- | --- | --- |
| 流程图 | 14 种基础节点、已有形状的 `@{ shape, label }` 写法、四个方向、分层、循环、子图嵌套、圆角正交连线、障碍避让、分组端点、双向／圆点／叉号／不可见连线、最多 10 层的长连线 | 不支持任意样式、其余扩展形状、边标识符与动画、ELK 配置；并行长边的最小跨度可能合并 |
| 时序图 | participant、actor、别名、JSON 类型与别名配置、边界／控制／实体／数据库／集合／队列符号、消息、自调用、激活、注释、编号、box、嵌套片段、创建与销毁生命周期 | 生命周期指令必须紧接关联消息，创建只作用于新接收方；不支持 links 和消息端口圆点；box 使用默认分组色；rect 支持六位十六进制、rgb 和常用颜色名 |
| 类图 | 类、属性与方法分区、带标题的 namespace、反引号名称、继承、实现、组合、聚合、双端关系标记、关系基数、三种构造型标记写法、棒棒糖接口、独立与关联注释 | 不支持样式和交互指令；泛型及抽象／静态成员记号按纯文本显示；密集基数标签与远端注释连线仍可能拥挤 |
| 状态图 | 初始与终止点、裸状态声明、别名、重复描述、转移、choice、fork／join、带别名的复合状态、局部方向、并发区域、左右单行与多行注释 | 不支持样式和完整 UML 行为语义；并发区域使用虚线容器表达；状态标识符仍按整图共享；注释连线可能穿过其他元素 |
| 实体关系图 | 实体属性表、PK 等文字、四种基数、实线与虚线关系、方向 | 不支持样式及复杂属性语法校验 |
| 饼图 | 非负权重、扇区、百分比、图例、showData | 不支持自定义排序与主题配置指令 |
| 甘特图 | 日期、时长、顺序任务、after 依赖、分区、状态、里程碑、排除周末 | after 需要引用前面已定义的任务；不支持 axisFormat、任意排除日期和交互；周时长在排除周末时按七个工作日处理 |
| Git 分支图 | commit、branch、checkout、switch、merge、cherry-pick、标签、消息与类型、LR 和 TB／BT | 不支持自定义分支排序；合并线与标签布局为基础实现 |
| 思维导图 | 缩进层级、左右分支、曲线、自动换行与层级着色 | 单根节点；形状记号只提取标签，不逐一复刻所有节点外形 |
| 时间线 | 分区、时期、多事件与延续事件 | 支持横向与窄屏纵向排列；不进行日期比例映射 |
| 用户旅程 | 分区、任务、参与者、评分与折线 | 评分限制为 1 到 5；不支持图标配置 |
| XY 坐标图 | 类目轴、数值轴、柱形与折线、多序列、负数、图例 | 不支持 horizontal、连续数值 X 轴和任意图表配置 |
| 象限图 | 四个区域、轴标题、区域标题、归一化坐标点 | 不支持点大小、点样式和 classDef |
| 需求图 | 七种需求／元素类型、属性、七种关系与方向 | 不支持反向关系记法与样式配置 |
| C4 架构图 | Person、System、Container、Component 等常见宏、边界嵌套、Rel、BiRel、Rel_Back | 统一自动布局；不支持方向关系宏、布局宏、样式宏和部署节点专用外形 |
| 桑基图 | 三列 CSV、正数流量、DAG 分层、按权重绘制流带 | 最多 100 个节点；不支持循环流量和配置块 |
| 块图 | columns、节点形状、跨度、space、基础连线 | 不支持嵌套 block、复合样式；复杂连线没有全局避障 |
| 数据包图 | 起止比特、相对长度、跨行字段、字段名 | 每行固定 32 比特；最多 256 行；窄字段隐藏标签，点击可查看名称 |
| 看板 | 缩进声明列与卡片、列标题、卡片数量 | 不支持卡片元数据、图标、人员和链接 |
| 架构图 | service、group、junction、嵌套分组、T／R／B／L 端口、正交连线、内置图标 | 支持 server、database、disk、cloud、internet；不支持外部图标、起点箭头和分组边界端口 |
| 雷达图 | 多轴、多曲线、最大值与最小值、多边形／圆形刻度与图例 | 需要 3 到 30 个轴；不支持自定义布局配置 |
| 矩形树图 | 缩进层级、叶节点权重、面积映射、分类标题 | 使用递归切片布局；小面积不显示标签；父节点面积由子节点求和 |
| 信息图 | 本地引擎信息卡片、showInfo | 显示本项目引擎信息 |
| 智能体流程 | 流程图基础语法、分组、分支、原生分层布局 | 不支持智能体角色元数据、状态徽标和专用装饰 |
| 用例图 | actor、椭圆用例、矩形节点、系统边界、关联、依赖与泛化 | 不支持业务参与者、图标、JSON、注释、include／extend 专用语法和样式 |
| 语法铁路图 | EBNF、基础 ABNF／PEG、函数式 DSL、顺序、选择、可选、重复、终结符和非终结符 | 不支持 ABNF 数值重复、范围、特殊序列、异常和谓词；ABNF／PEG 规则需要各占一行 |
| 目录树 | 空格缩进、目录与文件、层级引导线 | 不支持盒绘字符输入、图标解析、描述和高亮指令 |
| 韦恩图 | 1 到 3 个集合、默认／显式权重、交集标签、区域文字、两圆面积拟合 | 三圆布局按两两交集近似，三重交集只显示数值，不保证面积一致 |
| Cynefin 框架 | 五个领域、条目列表、领域间转移与标签 | 固定领域布局；转移线可能穿过条目；重复声明继续追加条目 |
| Wardley 地图 | anchor、component、归一化／百分数坐标、依赖、演化箭头 | 不支持流水线、注释块、装饰和布局配置 |
| 泳道图 | 顶级 subgraph 作为泳道、跨泳道关系、LR／TD、未分组泳道 | 不支持嵌套泳道、分组端点、BT／RL 和自动转向；局部方向不改变泳道布局 |
| 鱼骨图 | 一个结果、主因、次因、交错分支 | 仅支持三级结构；密集次因可能重叠 |
| 事件建模 | tf／rf、ui／cmd／evt／rmo／pcr、时间顺序、三类泳道、推断和显式引用 | 不支持命名空间分泳道、数据块、note、gwt 和规格；名称作为普通标签显示 |

## 通用约束

源码上限为 50000 个 UTF-16 字符，通用数据项上限为 500 个。时序图上限为 60 个参与者与 500 个事件，流程图沿用 200 个节点、500 条连线、64 个子图和 16 层嵌套。超出限制会返回错误。各解析器进一步限制递归深度和坐标范围。

除流程图外，通常每条指令需要独占一行。Front matter 当前支持 title，以及 theme、look、dagre 布局声明和少量与现有实现一致的配置项，保留原始行号；其他配置会明确报错。当前不支持完整 YAML、init 配置、主题变量覆盖、Markdown 富文本、任意 HTML、CSS、点击脚本或外部资源。非绘制指令不会执行脚本或发起网络请求。

各类布局使用同一套 AppKit 语义颜色、系统字体和矢量路径，普通容器默认采用 8 点圆角。连线标签使用 12 点字号并嵌在线条中，关系基数使用 11 点字号。流程、关系、用例和架构连线保留正交转折与圆角，避开其他节点、标题和无关分组；同轴连接自然保持直线。架构图按图形中心定位服务，并在节点预留空间内修正分组标题或标签换行造成的小幅错位，避免同轴连接出现细小的台阶弯。用例图和 C4 图的人物连线统一使用图形连接点，人物名称与说明作为独立避障区域；箭头前预留直线段，避免紧贴圆角。用例图的多条关联线按目标位置排列端口，优先使用错开的圆角通道；人物名称作为独立避障区域，减少连线交叉与贴合，并避开人物名称。回路线优先使用独立的侧面入口，标签沿所属连线的实际直线段选位，并避让全部可见连线。默认跟随系统浅色、深色及增加对比度设置，数据图表采用系统调色板，饼图标签根据扇区颜色选择深色或浅色文字，雷达图通过色块和文字共同标记数据系列。界面按用途分组呈现 33 类图形，不以官网示例顺序或视觉复刻作为产品目标。数据极多、文字很长、循环密集时，可能出现交叉、缩小文字或标签拥挤。

## 验证方式

`DiagramCatalogTests` 逐类生成原生 PNG，并验证所有主题的 SVG XML 和图元边界。`AppleAppearanceTests` 验证全部类型的原生系统符号、起始示例、四种系统外观下的绘制与导出，并检查主要文字和饼图标签的对比度。`DiagramSemanticsTests` 检查时序片段、甘特日期、架构端口、层级间距、铁路轨道及部分语义错误。原有流程图和子图测试继续检查轮廓端口、嵌套边界及避障。`AdvancedSyntaxTests` 进一步验证扩展节点端口、箭头标记、创建和销毁消息的绑定、生命线端点、接口与基数语义、并发区域隔离、同步条端口和标签避让。测试通过不代表已覆盖上游全部语料。

设置 `NORNA_FIXTURE_DIR` 后运行 `swift test`，可以导出所有内置示例的 PNG 和 SVG。`Sources/NornaKit/DiagramCatalog.swift` 是新增图形的可运行语法参考。`ScaleDiagramExamples.swift` 提供 29 类图形的复杂数据示例，应用菜单与原生预览页共用这些源码；固定坐标或固定框架的象限图、Wardley 地图、Cynefin 框架和信息图不额外增加复杂示例。`ScaleExampleTests` 检查两档示例确实包含不同规模的内容，并验证复杂示例在三种宽度与四种系统外观下的绘制和导出。

## 官网原始案例基准

已保存官网全部 32 类详情页及总览的原始示例，共 600 份去重源码，并保存对应官网静态 SVG 作为参考。本轮结构验证为 304 份可生成、296 份待支持。常用类型中，流程图为 98／174，时序图为 36／39，类图为 33／42，状态图为 22／25。逐例来源、失败行号和宽窄对照见 [验证报告](../Baselines/REPORT.md)及[图像对照](../Baselines/report.html)。这些结果比本地演示更能反映目前的兼容范围，但仍不表示像素或完整语义一致。

自适应布局已接入流程图、时序图、类图、状态图、实体关系图、需求图、C4、用例图、架构图、基础智能体流程、泳道图，以及饼图、XY 图、雷达图、甘特图、时间线、旅程图、看板和矩形树图。其他图形保留自然布局。`maxWidth` 是布局目标，无法容纳时会保留可绘制的尺寸。

## 复杂语法示例与约束

编辑器在这四类图形的“示例”菜单中提供扩展节点与双向连线、参与者生命周期、接口与基数、并发状态示例。源码位于 `Sources/NornaKit/Examples/AdvancedDiagramExamples.swift`。

流程图新加入双圆、六边形、非对称、两种平行四边形和两种梯形。现代形状声明仅接受已支持形状的 `shape` 和 `label`，未知形状或属性会报错。不可见连线参与布局，但不绘制。长连线在无环分层部分保留最小跨度，循环回边不保证跨度。

时序图的 `create participant` 与 `create actor` 必须通过下一条消息创建接收方；`destroy` 必须通过下一条消息销毁发送方或接收方。销毁后再次使用、重复创建、缺失或关联错误的消息均会报错，不会沿用全长生命线。普通参与者声明支持 JSON 的 `type`、`alias`，外部 `as` 别名优先；创建声明暂不支持 JSON 配置。除行内注释外，还接受 `note over A,B` 至 `end note` 的多行扩展写法。

类图注释放在图形外侧，状态图注释放在指定左侧或右侧，避免覆盖节点。基数会在关系两端尝试避让主标签和节点；复杂密集布局仍不保证完全无重叠。

语法参考：[流程图](https://mermaid.js.org/syntax/flowchart.html)、[时序图](https://mermaid.js.org/syntax/sequenceDiagram)、[类图](https://mermaid.js.org/syntax/classDiagram)、[状态图](https://mermaid.js.org/syntax/stateDiagram.html)。本项目只参考语法定义，解析和绘制均由 Swift 实现。