# bpmn-ui **Repository Path**: kingecg/bpmn-ui ## Basic Information - **Project Name**: bpmn-ui - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-02 - **Last Updated**: 2026-11-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # BPMN UI 可定制的 **BPMN 2.0 编辑器组件库**(Angular 13):新建/编辑流程、标准 BPMN 节点、自定义节点、只读 view 模式、查看导出 XML、缩放与鸟瞰图。 代码按三层组织,依赖只能自上而下: | 层 | 包 | 职责 | | --- | --- | --- | | L1 | `@bpmn-ui/svg` | SVG 绘图层:视口/缩放、网格、节点与连线图元、小地图、设计 token 与图标注册表 | | L2 | `@bpmn-ui/flow` | 流程图编辑层:图模型、命令与撤销栈、交互状态机、节点注册表与渲染器组合 | | L3 | `@bpmn-ui/bpmn` | BPMN 编辑器:`bf` 属性、BPMN ⇄ FlowGraph 映射、校验规则、XML 序列化 | | demo | `demo` | 文档与联调用的宿主应用(`projects/demo`) | 设计依据:[详细设计](doc/design/detailed-design.md)、[开发计划](doc/design/development-plan.md)、[评审意见](doc/design/design-review.md)。 各组件的输入、输出与纯函数 API 见 [L1 绘图层组件手册](doc/design/l1-svg-components.md);里程碑与任务进度见 [开发进度](doc/design/progress.md)。 ## 特性 - **一个组件就能用**:`` 自带工具条、元素面板、画布、属性抽屉、状态栏与鸟瞰图,宿主只管把 XML 递进来、把保存意图接出去。 - **BPMN 2.0 双向往返**:`bpmn:Process`/`bpmn:Collaboration`、泳道、网关默认流、条件、子流程都能读进来再写回去;本库不建模的扩展(Camunda 属性、边界事件、数据对象…)按语义原样保留。 - **完整编辑手势**:点击或拖放建节点、框选与多选、拖动、八向手柄缩放、从端口拉连线、撤销/重做栈、剪贴板、行内改名(IME 安全)。 - **泳道可定制**:池 + 泳道画在内容层,跟着画布平移缩放;拖分割线改高度(不低于最高节点),右键插入/删除/改名,双击标题列内联改名,删除时下方泳道自动收拢、pool 缩回。 - **子流程钻入**:双击子流程进去编辑,面包屑返回;导航不进撤销栈,历史始终覆盖整份文档。 - **连线自动路由**:bezier / 折线 / 直线三档,折线避障、同轴分层、同一节点侧的多条线端口散开;`bpmndi` 航点原样恢复。 - **校验与修复**:14 条 BPMN 语义规则 + 3 条结构规则汇总到状态栏,点一条即定位;6 条快速修复各是一步可撤销的命令。 - **鸟瞰图**:`bf-minimap` 只画简化图元,泳道/连线/节点三层分色——容器是浅底、连线是细线、节点是实心块,视口框跟手,按下即导航。 - **可访问**:画布 roving tabindex(一层只占一个 Tab 位)、`role="button"` + `aria-pressed`、`:focus-visible` 焦点环,axe 对 10 个状态零违规。 - **可主题化、可 i18n**:颜色与尺寸全部走 CSS 自定义属性,内置 `zh-CN` / `en-US` 且可运行时切换。 - **三层可拆用**:只要画布与图元(L1),或只要流程编辑器(L2)而不带 BPMN 语义,都可以单独引用。 ## 快速开始 ### 集成到你的 Angular 应用 包还没有发到 npm:先在本仓库构建出 `dist/`,再按你的方式引进来(工作区 `tsconfig` paths、`file:` 依赖或私有 registry 都行;本仓库的 demo 走的是 paths → `dist/`)。 ```bash nvm use v14 npm ci npm run build:libs # 产出 dist/bpmn-svg、dist/bpmn-flow、dist/bpmn-editor ``` ```ts // app.module.ts import { BF_PURCHASE_NODES, BpmnEditorModule } from '@bpmn-ui/bpmn'; @NgModule({ imports: [ // 不需要自定义节点时用 BpmnEditorModule.forRoot() 即可 BpmnEditorModule.forRoot({ catalog: BF_PURCHASE_NODES }), ], }) export class AppModule {} ``` ```scss // styles.scss —— 设计 token 是一组 :root 上的 CSS 自定义属性,全局引一次 @use '@bpmn-ui/svg/styles/tokens'; ``` ```html ``` ```scss .editor { display: block; height: 100%; min-height: 480px; } ``` - 存盘之后调 `markSaved()`,工具条上的脏点才会消失;`[xml]` 是 one-shot,换文档走 `loadXml()`。 - 只读用 `[mode]="'view'"`:元素面板不渲染、画布拒绝写入、属性面板禁用,缩放/搜索/选中仍然可用。 - 完整的输入、输出与方法表见下面「公开 API(`bf-bpmn-editor`)」。 ### 在本仓库开发 ```bash npm start # demo 宿主应用:http://localhost:4200 npm run storybook # 组件故事:http://localhost:6006 ``` `npm test` 通过 `tsconfig.spec.json` 的路径映射直接跑源码,**不用先构建**;但 demo 走根 `tsconfig.json` 的 paths → `dist/`,所以改了库源码要先 `npm run build:libs` 并重启 `ng serve`(dev server 不会重新打包 dist)。更多脚本见「环境」与「常用脚本」。 ## 快捷键 | 操作 | 按键 | | --- | --- | | 撤销 / 重做 | `Ctrl/⌘+Z`、`Ctrl/⌘+Shift+Z`、`Ctrl+Y` | | 删除选中 | `Delete`、`Backspace` | | 复制 / 粘贴 | `Ctrl/⌘+C`、`Ctrl/⌘+V` | | 全选 | `Ctrl/⌘+A` | | 层内移动焦点 | `Tab`、`Shift+Tab` | | 保存(发 `save`) | `Ctrl/⌘+S` | | 搜索元素 | `Ctrl/⌘+F` | | 缩放 / 适配画布 | `+`、`-`、`0` | | 平移 | 按住 `Space` 拖动(中键亦可) | | 取消当前手势 | `Esc` | | 微移选中 | `↑↓←→`,`Shift+↑↓←→` 走大步 | | 重命名 | `F2` | | 打开属性 | `Enter` | 画布内的组合键由 L2 解析,弹层(搜索、菜单、抽屉)各自处理自己的键;同一张表也能从工具条「更多 → 快捷键」打开(`{mod}` 在 macOS 显示 `⌘`)。 ## 常见坑 - **改了库源码 demo 却没变**:demo 引用的是 `dist/`,先 `npm run build:libs`,再重启 `ng serve`。 - **画布尺寸为 0**:`bf-svg-canvas` / `` 需要有确定高度(flex、绝对定位或固定值),组件靠 `ResizeObserver` 测量。 - **插槽里的 SVG 被当成 HTML**:写在 `ng-template` 里的图形元素必须带 `svg:` 前缀(``)。 - **换了 XML 画布没反应**:`[xml]` 只消费第一份文本,后续改动会被忽略(dev 下告警);用 `loadXml()` 或换 `[graph]` 引用。 - **脏点不消失**:库不写盘,存完要自己调 `markSaved()`。 - **自定义节点显示成虚线卡片**:`bf:customType` 没在 `forRoot({ catalog })` 里注册,每种类型会 `console.warn` 一次;`unregisteredNodeTypes(graph, registry)` 可以拿到清单。 - **泳道开关不是移动**:`showLanes=false` 只隐藏图层,节点坐标与滚轮缩放不变。 - **`bpmn-moddle` 版本**:锁 `8.1.0`;9.x 是 ESM-only 且要求 Node ≥ 16,和 Angular 13 / Node 14 的宿主不兼容。 - **未知内容保留是语义保真**:前缀可能被重新绑定(`camunda:` → `ns1:`);未建模元素引用的宿主节点被删后,它的片段仍会写回。 - **剪贴板在非安全上下文**:`navigator.clipboard` 不可用时自动回退到隐藏 textarea + `execCommand`。 ## 环境 ```bash nvm use v14 # Node 14.15.5;Angular 13 只支持 Node 12/14 npm ci # 或 npm install ``` Angular CLI 为 **13.3.x**(全局或本地 `node_modules/.bin/ng` 均可)。`bpmn-moddle` 锁定在 **8.1.0**:9.x 为 ESM-only 且要求 Node >= 16。 ## 常用脚本 | 命令 | 作用 | | --- | --- | | `npm start` | `ng serve demo`,宿主应用运行在 http://localhost:4200 | | `npm run storybook` | Storybook 6.5 开发服务,http://localhost:6006 | | `npm test` | Jest 27(`jest-preset-angular` 11),一次跑完所有库 | | `npm run test:coverage` | 同上并产出 `coverage/` | | `npm run lint` | ESLint(含分层 import 约束) | | `npm run build:libs` | 依次构建 `bpmn-svg` → `bpmn-flow` → `bpmn-editor` 到 `dist/` | | `npm run build:demo` | 构建宿主应用(依赖 `dist/`,所以要先 `build:libs`) | | `npm run build` | `build:libs` + `build:demo` | | `npm run build-storybook` | 产出静态 Storybook 到 `storybook-static/` | | `npm run test-storybook` | 对 `http://127.0.0.1:6006` 上已运行的 Storybook 跑 interaction test(见「Storybook 交互测试」) | | `npm run spike:moddle` | 重跑 M0 的 `bpmn-moddle` + `bf` descriptor 验证,重写 [spike 报告](doc/design/m0-moddle-spike.md);加 `-- --no-write` 只输出结果(CI 用) | `npm test` 通过 `tsconfig.spec.json` 的路径映射直接引用源码,**不需要先构建**;`ng build` 走根 `tsconfig.json`,映射到 `dist/`。 ## 目录 ``` projects/bpmn-svg/ L1:src/lib/{canvas,container,defs,edge,geometry,minimap,node-host,overlay,icon,styles}、styles/{_tokens,_mixins}.scss projects/bpmn-flow/ L2:图模型与编辑层的落点 projects/bpmn-editor/ L3:bf-descriptor.json 与后续的 BPMN 映射/序列化 projects/demo/ 宿主应用(承载组件示例) fixtures/ BPMN XML 夹具(purchase-approval.bpmn,5 节点/1 网关/6 连线) scripts/ spike 与一次性脚本 .storybook/ Storybook 配置(含只覆盖库的 tsconfig) ``` ## demo 宿主应用(T4-8) `npm run build:libs && npm start` 后打开 http://localhost:4200: | 路由 | 页面 | 说明 | | --- | --- | --- | | `/` | 流程列表 | 读 localStorage;首次访问把 `fixtures/purchase-approval.bpmn` 播种为示例(构建时由 angular.json 的 assets 拷到 `assets/fixtures/`,源码里不复制 XML) | | `/edit/:id` | 编辑 | `bf-bpmn-editor` 全功能:palette/属性/搜索/更多菜单/预览切换;提交后 `(xmlChange)`(300ms 防抖)自动写回 localStorage,成功后 `markSaved()` 清脏点 | | `/view/:id` | 只读预览 | `[mode]="'view'"` + `[modeToggle]="false"`:palette 不渲染、属性只读、历史按钮灰掉;工具条的「编辑」按钮回到 `/edit/:id` | - 页面把存储里的文本直接交给 `[xml]`(one-shot),解析失败走 `(error)` 而不是在宿主里再写一个解析器;`^S` 的 `(save)` 与 300ms 的 `(xmlChange)` 共用同一条保存路径(`getXml()` + `markSaved()`)。 - 自定义节点:`BpmnEditorModule.forRoot({ catalog: BF_PURCHASE_NODES })`,示例流程里的 `purchase.*` 节点因此用真实渲染器,而不是 fallback 卡片。 - 列表里的节点/网关/连接数不是另存的一份模型:保存时用 `graphFromXml()` 重新解析再 `statusCounts()`,和状态栏同一口径。 - 新建空白流程会先序列化一份只有 process 的 XML 再入库,所以三个路由拿到的都是同一种输入(XML),不存在“空图特例”。 ## L1 画布 完整签名见 [L1 绘图层组件手册](doc/design/l1-svg-components.md),下面是最常用的用法。 ```html ``` - 四个插槽:`bfCanvasDefs` / `bfCanvasBackground` / `bfCanvasContent` / `bfCanvasOverlay`;内容层与覆盖层分别对应模型坐标和屏幕坐标。 - **插槽里的 SVG 元素必须写 `svg:` 前缀**(如 ``),因为插槽声明在宿主组件的 HTML 模板里,否则会被当成未知 HTML 元素。 - 宿主必须给 `bf-svg-canvas` 一个确定高度(flex/绝对定位/固定高),组件内部按 `ResizeObserver` 适配。 - 交互:滚轮 = 指针锚定缩放(`Ctrl/⌘` 强制缩放、`Shift` 横移、`Alt` 纵移);中键、`Space`+左键、view 模式左键空白拖动 = 平移。 - 方法:`zoomTo(k, anchor?)`、`fitTo(bounds, padding?)`、`centreOn(point)`、`screenToModel(p)`、`modelToScreen(p)`;缩放范围默认 0.2–2.5。 - 事件:`(viewportChange)` 在平移/缩放后按帧发出新视口;`(sizeChange)` 在挂载时及尺寸变化时发出测量后的画布尺寸,需要屏幕坐标或可视区域随画布变化的组件(小地图、检查器、浮动工具条)直接绑它,不必自己量 DOM。 - 网格间距按缩放取 8/16/32 模型 px,线宽固定为 1 物理像素(`1/devicePixelRatio`),并随内容层反变换。 ### 节点宿主 ```html ``` - 内置渲染器按 `node.type` 解析:`task`/`userTask`/`serviceTask`/`subprocess`… → 卡片,`startEvent`/`endEvent` → 事件,`exclusiveGateway`/`parallelGateway`/`inclusiveGateway` → 网关;未注册类型走虚线回退渲染器,并**每种类型只告警一次**。 - 自定义节点:导出 `BfNodeRendererMap`,把类型映射到你自己的组件(`implements BfNodeRenderer`,`OnPush`,模板用 `svg:` 前缀,宿主元素由宿主创建为 SVG ``),通过 `[renderers]` 传入即可覆盖/扩展。 - 卡片文本按字宽估算截断(中文按全角算),不会溢出 150px 卡片;`badge` 作为右上角挂签,不挤占标题。 - 渲染器被创建在 Angular 变更检测树之外(`ViewContainerRef.createComponent` 会在 SVG 里建出 HTML 命名空间的宿主),所以宿主在节点视觉输入变化时**替换**该节点的渲染器实例;位置变化只改外层 `` 的 `transform`,拖拽不会重建。渲染器应保持纯展示,异步状态需自行刷新。 - 键盘:外层 `` 是 `role="button"` + `aria-label`(标题/副标题)+ `aria-pressed`(选中),一层只留一个 `tabindex="0"`(roving);`Tab`/`Shift+Tab` 在层内移动,首尾交还浏览器,`(nodeFocus)` 把 id 交给宿主(L2 用它让选中跟随焦点)。 ### 连线 ```html ``` - `BfSvgEdge` 只吃两端节点的矩形(`source`/`target`)加可选的 `waypoints`、`name`、`condition`、`isDefault`;端口在路由时按几何解析,不需要 L2 指定。 - `bfSvgEdgeHost` 是推荐的入口:它给每条连线算好端口再渲染一个 `g[bfSvgEdge]`。**共享同一节点侧的多条连线会沿着该侧均匀散开**(按 edge id 排序、以边中点为轴对称,间隔 `EDGE_PORT_SPACING = 24`,距角至少 `EDGE_PORT_MARGIN = 10`,边不够长时自动收紧),所以同一对节点之间的多条连线不会重在一个点上;不同侧的连线互不影响。算法可直接复用:`distributeEdgePorts(edges)` 返回 `Map`。 - 单独渲染一条连线时仍可用 `g[bfSvgEdge]`,并用 `[ports]="{source, target}"`(相对边中点的偏移)自行指定端口。已指定的端口优先:`bfSvgEdgeHost` 不会覆盖它,也不会让它占用散开的位置。 - 路由策略:`auto`(默认)/ `bezier` / `orthogonal` / `straight`。`auto` 在正向链接上用 bezier,**反向和重叠用折线**,所以反向连线不会出现 S 形回折;折线拐角为 8px 圆角(`EDGE_CORNER_RADIUS`),stub 长度 `EDGE_STUB = 20`。 - **折线避障**:默认中线被别的节点挡住时,改选「不穿障碍且首末段不短于 stub」的最短候选,与障碍保持 `EDGE_OBSTACLE_CLEARANCE = 8`。没有障碍时几何与之前逐字节一致;bezier / straight / 显式 `waypoints` 不做避障(曲线绕障难读,航点是调用方的显式决定)。 - **通道分层**:host 按 edge id 顺序逐条路由,若新线与已接受的线同轴、间距 ≤ 12px、重叠超过 20px,就换下一个 `lane`(中线外移 `EDGE_LANE_SPACING = 24`);被同一个障碍推开的两条线也会自动分层,不会并成一束。 - 纯拓扑交叉(如 A→D 与 B→C 端点顺序相反)无法靠路由消除,当前也不画跳线:那条路线属于自动布局(L2)的职责。 - 反向链路从两端端口向外出 stub 后走同一条中线(在下方或上方绕行),顶点永远落在两卡片范围之外。 - `waypoints` 存在时按给定顺序串接端口点,并去掉重复点与共线点(`compact`);`bpmndi` 导入因此可原样还原航点。航点一律按折线绘制(曲线无法穿过中间点),只有 `straight` 会关掉 8px 圆角。 - 标签是白底 1px 描边胶囊(圆角 6、11px),放在折线/曲线的弧长中点,名称与条件各一行,过长按字宽截断;空名称+空条件不渲染标签。 - 可视线下方有一条 `stroke="transparent"`、`stroke-width="12"` 的命中路径(`pointer-events="stroke"`),可视线本身 `pointer-events="none"`,因此点击/悬停命中宽度是 12px。 - 箭头 marker(`bf-arrow` / `bf-arrow-selected`)由 `g[bfSvgDefs]` 渲染,画布会自动挂一份;同一页面的多个画布共享这一份定义(详见下文“共享 defs”)。`[markerId]="false"` 可关闭箭头。 - `routeEdge(geometry, router, context?)` 是纯函数,可在无 DOM 环境(含 L2 的命中检测、自动布局)复用:返回 `path`、`strategy`、`sourceSide`/`targetSide`、`points`、`label`。`context` 可传 `{ obstacles, lane }`,不传就是纯几何默认路由。 ### 共享 defs ```html ``` - `url(#id)` 是**文档级**引用,两个画布各自渲染一份 `#bf-arrow` 就是重复 id。`BfSvgDefs` 通过 `BfSvgDefRegistry`(root 级单例)保证整个文档只有一份:第一个挂载的实例负责渲染,其余实例渲染空内容,但 id 保持一致,所以连线不需要知道自己属于哪个画布。 - 拥有者卸载时,注册表把“渲染权”交给下一个仍存活的实例并通知它重绘,因此删掉第一个画布不会让第二个画布丢箭头。 - 自己的 pattern / filter 用 `BfSvgDefRegistry.acquireId('my-pattern')` 取唯一 id(第一个拿到 `my-pattern`,之后是 `my-pattern-2`…),`release()` 归还。网格 pattern 就是这么做的。 ### Overlay(框选框 / 手柄 / 端口) ```html ``` - 画在 overlay 层(**屏幕坐标**),不参与内容层变换:把模型矩形投影到屏幕后再画,所以手柄在任何缩放下都是 7px 方块、端口是半径 4 的圆点,不需要 `1/k` 反算。 - `selection` 是不可见的选中框(`--bf-accent` 1px + 6% 填充);`marquee` 是拖框过程中的虚线框。两者都收模型坐标。 - 八个手柄在选中框小于 `BF_MIN_HANDLE_BOX = 22` 屏幕 px 时按方向收起(先掉角点,再掉短边),避免方块叠成一团;`view` 模式完全不出手柄。 - `handleDown` 发出 `{ kind, point }`(`kind` 为 `nw`…`w`,`point` 是屏幕坐标),`portDown` 发出端口 `id`;两者都会 `stopPropagation`,不会把画布的平移手势一起触发。 - 纯几何在 [overlay.ts](projects/bpmn-svg/src/lib/overlay/overlay.ts),可脱离 DOM 测试。 ### 小地图 ```html ``` - 独立 SVG,只画简化图元——`rect` / `circle` / `diamond` / `line`(`BfMinimapShape`),不实例化任何节点或连线组件;`minimapShapeForNode()`、`minimapShapeForContainer()`、`minimapShapeForPoints()` 负责把几何转成图元。 - **三层底色**:图元带 `tone: 'container' | 'node' | 'edge'`——泳道/池是浅底 + 1px 描边,连线是浅灰细线,节点是实心深色块(另加 1px 白描边压住底色)。组件绘制前按 `container → edge → node` 重排(`paintOrder()`),所以连线不会盖住它指向的节点;不带 `tone` 的图元按节点画,手写的 shapes 仍可用。三层颜色可用 `--bf-minimap-container` / `--bf-minimap-container-stroke` / `--bf-minimap-node` / `--bf-minimap-line` 覆盖。 - `viewBox` 是 0 0 180 120,图元按 `BF_MINIMAP_PADDING = 40` 模型 px 的边距等比缩放后居中(等比 + 留白自己算,不依赖 `preserveAspectRatio`,测试里可复现)。 - **视口框 = 当前可见区域**:`visibleBounds(viewport, canvasSize)` 得到可见模型矩形,投影到**面板像素**后画在缩放组**外面**(画在组里会被二次缩放,框就会又小又偏)。所以 `canvasSize` 必须是主画布的真实尺寸:把画布的 `(sizeChange)` 直接接到它上面,不要写死或自己量 DOM。 - 两层分开重绘:视口/画布尺寸变化只更新那一个框矩形(每帧都跟手),只有 shapes 数组或面板尺寸变了才重算内容包围盒、fit 与全部图元——后者才是耗时部分,按 `throttle = 100ms` 合并。拖动主画布时图元 DOM 不会被重建(同一批节点复用),300 个图元下每帧只有一次矩形更新。 - 在小地图里按下或拖动会发出**模型坐标** `navigate`,宿主调用 `BfSvgCanvas.centreOn(point)` 平移主画布(只平移不改缩放)。 - 默认展开;右上角按钮折叠成 32×32 图标,`[collapsed]` + `(collapsedChange)` 可受控。 ### 容器原语 ```html ``` - 只画四件事:底板(圆角 + `--bf-border` 描边)、左侧标题列(圆角只发生在左侧,右侧与主体齐平)、分割线、两行标题(中文 13/600 + 大写英文 10/字距 1,超宽按字宽截断)。 - `alternate` 把底板换成 `--bf-surface-alt`,用于泳道交替底色;`headerWidth = 0`(或宽于容器)时不画标题列。 - **没有业务语义**:不认识泳道、不做命中区、不做拖高;泳道的组合顺序、命中与高度自适应都在 L2 的 `ContainerLayer`。 - 标题在高度不足 40px 时隐藏、副标题在不足 58px 时隐藏,所以窄条泳道不会画出压线的文字。 ### XML 序列化(L3) ```ts import { BfXmlError, bpmnSerializer, readBfProperties, writeBfProperties } from '@bpmn-ui/bpmn'; const { document, warnings } = await bpmnSerializer.import(xml); // document 是 moddle 文档树:rootElements → bpmn:Process → flowElements … writeBfProperties(task, { assigneeRole: 'APPROVER' }); const out = await bpmnSerializer.export(document); ``` - `import()` / `export()` 是唯一的 XML 出入口:先解析成 `bpmn-moddle` 文档树交给转换器与编辑器,导出时再写回字符串。`bpmn-moddle` 不发类型声明,所以对外只暴露结构等价的 `BfBpmnElement` / `BfBpmnDocument`,不把未类型化的依赖带给宿主。 - `bf:*` 属性(`customType` / `badge` / `laneCode`)与 `bf:properties` 由 [bf-descriptor.json](projects/bpmn-editor/src/lib/bf/bf-descriptor.json) 注册;业务字段一律走 `readBfProperties()` / `writeBfProperties()`,后者按 `name` 排序写入,且不会动 `extensionElements` 里的第三方内容。 - 解析失败抛 `BfXmlError`,带 moddle 报告的行列号与原始告警文本;未解析引用(`sourceRef` 指向不存在的节点)不算失败,进 `warnings`。 - 导出默认缩进美化(`pretty: false` 输出单行);写出前 `bf:properties` 就地按 `name` 排序,所以同一文档导出两次字节一致。 ### BPMN → 图模型 ```ts import { bpmnSerializer, bpmnToGraph } from '@bpmn-ui/bpmn'; const { document, warnings } = await bpmnSerializer.import(xml); const graph = bpmnToGraph(document); // FlowGraph,直接交给 BfFlowEditor ``` - `collaboration` → pool 容器,`laneSet/lane` → lane 容器(`bf:laneCode` 进 `subLabel`),节点归属优先看 `flowNodeRef`,没有就用几何取中线所在泳道。 - 几何只信 BPMN 的 DI:节点/泳道取 `BPMNShape/Bounds`,连线取 `BPMNEdge/waypoint`(`Flow_6` 的三段折线原样保留,不会被路由重算)。整个文档没有任何 DI 时改跑自动布局(见下);只有部分元素缺 DI 时,它们落在 0,0 并用按类型的默认尺寸。 - `bf:customType` 决定 `node.type`(渲染器按它选),原 BPMN 元素类型留在 `props.bpmnType`,导出时才能写回成原来的 `bpmn:userTask`;`bf:properties` 与 `bf:badge` 进 `props`(`badge` 供卡片徽标,`condition` 供连线胶囊)。 - `bpmn:exclusiveGateway/@default` → 对应边的 `isDefault`;子流程的 `flowElements` 变成 `node.children`,`isExpanded="false"` → `collapsed`。 - v1 子集之外的 BPMN(边界事件、数据对象、消息…)**不生成占位节点**,交给未知内容保留(T3-4)原样导出;指向它们的连线会被丢弃。 ### 图模型 → BPMN ```ts import { bpmnSerializer, graphToBpmn } from '@bpmn-ui/bpmn'; const xml = await bpmnSerializer.export(graphToBpmn(graph)); ``` - **布局是唯一真相**:节点 Bounds 按当前图重算,不沿用导入时的 DI;连线有 waypoints 就原样输出(`Flow_6` 的三段折线不会被抹平),为空时才问 L1 路由要一条默认路径。 - 元素类型看 `props.bpmnType`:`type` 是 `bf:customType`(如 `purchase.submit`)的节点仍然写回 `bpmn:userTask`,自定义类型只作为 `bf:customType` 属性出现。 - 属性分流:`customType`/`badge`/`implementation` 写属性,其余业务字段进 `bf:properties`(按 `name` 排序);`props.condition` 写 `bpmn:conditionExpression`,`isDefault` 写网关的 `@default`。 - 泳道的 `flowNodeRef` 由节点 `containerId` 生成,pool 生成 `collaboration/participant`(`processRef` 指向流程);没有 pool 时就不写 collaboration,`BPMNPlane/@bpmnElement` 直接指向流程。 - 往返契约:`bpmnToGraph(graphToBpmn(g))` 与 `g` 深度相等(fixture 已验证),且第二次导出与第一次字节一致。子流程子元素的 DI 目前平铺在同一个 plane 里(moddle 会丢弃嵌套的 `owningElement`);钻入编辑在图上完成,不依赖嵌套 DI。 ### 自动布局 ```ts import { autoLayout } from '@bpmn-ui/flow'; const laid = autoLayout(graph); // 纯函数:不改入参,同输入同输出 ``` - 算法即设计 §6.9.2:Kahn 拓扑分层成列(列间距 40),泳道就是行。同层且同泳道的多个节点纵向堆叠(行间距 24)并把泳道撑高,所以不会重叠;泳道标题列宽(`headerWidth`)计入列起点,网关/事件在自己那一列里水平居中。 - 尺寸只增不减:用户手动拉高的泳道保持高度,内容在其中居中;泳道/池宽度不够时按内容加宽。空图原样返回,第二次调用返回**同一个对象**(幂等)。 - 端点移动过的连线的 `waypoints` 会被清掉(旧航线已无意义,交给 L1 路由重算),没动的连线保留——所以对已排好的图再跑一次是真正的 no-op。 - 环不会让分层死循环:Kahn 队列排不进去的节点按文档顺序追加成后续列。 - `bpmnToGraph()` 在文档完全没有 DI 时自动跑一遍(含嵌套子流程子图);`graphFromXml()` 返回 `autoLaidOut` 标记,编辑器壳据此提示「已自动生成布局」(文案属 T3-12)。 ### 未知内容保留 ```ts import { graphFromXml, xmlFromGraph } from '@bpmn-ui/bpmn'; const { graph, warnings, autoLaidOut } = await graphFromXml(camundaXml); // … 编辑 graph / 走 BfFlowEditor … const xml = await xmlFromGraph(graph); // Camunda 扩展、文档、边界事件都还在 ``` - 加载时用 `DOMParser` 扫描**原始** XML(不是 moddle 树)收集本库不建模的部分:根级元素(`bpmn:message`、`bpmn:signal`…)、容器里不支持的子元素(`bpmn:documentation`、边界事件、数据对象)、`extensionElements` 里的第三方内容(`camunda:properties`…)、未建模属性,以及这些元素的 DI。每项存成 `graph.unknown` 里的 `{ attachTo, slot, raw }`。 - 未建模属性用私有 `` 包一层,带上原命名空间 URI,回注时走 `setAttributeNS`;前缀可能被重新绑定(`camunda:` 可能变成 `ns1:`),**语义保真而非字节保真**(设计 §7.5)。 - 保存时先序列化模型,再按 `attachTo` 注入片段;`attachTo` 是元素 id,或用 `definitions` / `process` / `collaboration` / `plane` 四个字面量(后两个是设计 §7.5 清单的补充,消息流与未识别元素的 DI 只能挂在那里)。目标元素已被删除的片段会直接跳过。 - 删除级联在 L2 命令里完成:`deleteNodes` 会连同被删节点的连线片段一起清理,`deleteEdges` 只清自己的;同一条命令,所以撤销后片段也回来了。 - 保真边界:一个未建模元素(如边界事件)引用的宿主节点被删除后,它的片段仍会保留并原样写回——编辑器当时并不知道这层引用关系。 ### 元素面板(palette) ```html ``` - `BF_BPMN_BASIC_NODES` 是 7 个基础元素的目录(开始/结束事件、用户/服务任务、子流程、排他/并行网关),顺序与截图一致;`type` 用 BPMN 元素本地名(也是渲染器 key),`props.bpmnType` 保证导出的还是 `bpmn:userTask` 这类真实元素。 - `BfPaletteComponent` 只负责表现与手势:左侧「元素」小标签 + 白底描边胶囊(图标 16 + 文案 13),高度 56;`mode="view"` 时整体隐藏。 - 点击(或聚焦后 Enter/Space)→ `pick(type)`,宿主在视口中心创建;按住拖动超过 4px 或 150ms → 浮动 ghost,松手 `drop({ type, clientX, clientY })`。`Esc` / `pointercancel` 取消,拖拽后紧跟的 click 会被吞掉。 - 拖拽落点给的是 **client 坐标**:只有壳层知道画布偏移与缩放,映射到模型坐标与 `addNode(type, point)` 是 M4 的职责(设计 §6.9.5 的 `Placing` 预览也在那时接)。 - `BpmnEditorModule` 默认用这 7 个元素提供 `BF_NODE_REGISTRY`;不传 `[definitions]` 时 palette 直接读这个注册表,所以 `forRoot({ catalog })` 注册的节点会自动出现在面板里(见下)。 ### 自定义节点 ```ts import { BpmnEditorModule, BF_PURCHASE_NODES } from '@bpmn-ui/bpmn'; @NgModule({ imports: [BpmnEditorModule.forRoot({ catalog: BF_PURCHASE_NODES })] }) export class AppModule {} ``` - `forRoot({ catalog })` 把自定义定义追加在 7 个基础元素之后注册(设计 §5.6、A3):同 `type` 覆盖内置定义,`extends` 继承父级的 defaults / fields / renderer,只为差异字段赋值。注册结果同时进入 palette 与编辑器的渲染器表。 - 4 个示例节点:[purchase-node-catalog.ts](projects/bpmn-editor/src/lib/palette/purchase-node-catalog.ts) 的 `purchase.initiator` / `purchase.submit` / `purchase.approve` / `purchase.archive`,分别 `extends` 开始事件、用户任务、用户任务、结束事件,预设 `bf:customType`、`bf:badge` 与 `bf:properties` 业务字段(角色、表单)。父级的 `props.bpmnType` 让导出仍是真实 `bpmn:userTask` 等元素,自定义类型只作为 `bf:customType` 出现。 - `fields` 由属性面板渲染(见下),同 key 覆盖继承来的字段,所以自定义节点可以换掉基础元素的表单标识标签/占位符。 - 未注册的 `bf:customType` 不会丢:导入后 `node.type` 就是那个 key,画布用 L1 fallback 虚线卡片显示原始类型(每种类型 `console.warn` 一次);`unregisteredNodeTypes(graph, registry)` 返回去重排序后的类型列表,壳层(M4)据此提示「N 个未注册节点已降级显示」。导出时 `bf:customType` 原样写回。 ### 泳道 - pool 与 lane 画在**内容层**里(不是背景层),所以泳道和节点一起平移、缩放;拖分割线时按 `1/视口缩放` 折算成模型 px,缩放后手感一致。 - 拖分割线改高度(不低于最高节点 + 24),泳道随内容自动增高;泳道个数与名称可以改: - `editor.addLane(afterId?)`:在某条泳道下面插一条空的(不给 `afterId` 就插到最后)。文档本来没有泳道时先建一个包住现有内容的 pool,两次写入合成一条历史。 - `editor.removeLane(id)`:连泳道里的节点和连线一起删,下面的泳道收上来、pool 缩回——一步撤销全部恢复。 - `editor.renameLane(id, label)`:与双击泳道标题列、右键菜单里的重命名走同一条命令。 - 右键泳道任意位置出 `Rename lane` / `Add lane below` / `Delete lane`;空白画布的右键菜单里有 `Add lane`,所以新建的空文档也能直接长出第一条泳道。命令层的同名函数是 `addLane` / `removeLane` / `renameLane` / `addContainer`,几何在 [lane-layout.ts](projects/bpmn-flow/src/lib/container/lane-layout.ts) 的 `insertLane()` / `removeLaneFromGraph()`。 - 泳道的 `label` 就是 `bpmn:Lane/@name`,改名会随 `(xmlChange)` 一起保存;只读模式下三个方法都返回 `false`,菜单也不出现。 ### 子流程钻入 ```html ``` - 双击子流程卡片(或点卡片底部的 `+` 标记)钻入;`+` 在展开时出现,`−` 在折叠时出现并直接切换 `collapsed`。两者都走命令,所以都能撤销。 - 导航不改文档、不入栈:`SceneStore` 的 `graph` 是当前作用域(顶层或某个子流程),`document` 始终是整份文档,`scope` 是子流程 id 路径,`breadcrumb` 给出祖先标签。历史快照保存整份文档,因此在子流程里做的修改退出后仍可撤销;选中、菜单、内联编辑等 UI 状态在切层时清空。 - 面包屑由编辑器自己画(只在钻入后出现),点根节点回顶层;`goToScope(depth)` 可跳到任意祖先。`enterSubprocess` / `exitSubprocess` / `goToScope` 也开放给宿主工具栏(M4 的「返回」)。 - 没有内容的子流程显示为空画布,第一次编辑才真正创建 `children`——「钻进去看一眼」不会产生历史记录。 - 作用域内的坐标、命中、框选与校验都以当前子图为准;泳道与 Pool 属于所属流程,钻入后不显示(设计 A4 只做「折叠 + 钻入」,不做同屏展开)。 - 渲染层:`BfSvgNode` 的 `subprocess` 标记让卡片渲染器画 `+`/`−`,点击发出 `activate` / `toggleCollapse`;`BfFlowEditor` 把它们变成钻入/折叠命令。 ### 属性面板 ```html ``` - 字段由 `bpmnPropertyFields(node, graph, registry, i18n)` 合成三层:元素类型自带字段(userTask 的 `assignee` / `candidateGroups` / `formKey`,serviceTask 的 `serviceKey`)→ 目录里声明的 `fields`(同 key 覆盖)→ 图推导字段(网关默认流、子流程折叠开关)。`bpmnTypeOf()` 读 `props.bpmnType`,因此 `purchase.approve` 这类自定义节点仍然拿到用户任务字段。 - 选中连线时面板改编辑整条顺序流:`[edgeId]` 接收 L2 的 `(edgeSelect)`(`bf-flow-editor` 的连线选中通道,值为单个 id 或 `null`),面板从 `graph` 现取该边,因此命令写完立刻刷新。字段是「名称」(胶囊第一行,写 `edge.label`)与「条件」(写 `props.condition`,导出成 `bpmn:conditionExpression`);条件留空会删掉这个键,而不是留下一个空表达式。 - 连线的默认流联动:源节点是排他/包容/复杂网关时多一个「设为默认流」开关,勾上直接发 `{ kind: 'defaultFlow' }`(仍走 `setDefaultFlow`),默认流的条件输入禁用并提示「条件不参与判断」,已填的值保留,取消勾选后原样回来。 - 联动:`candidateGroups` 在填了 `assignee` 后隐藏(值保留,清空处理人又出现);排他/包容网关的「默认流」下拉选项来自**当前作用域的出边**,标签取连线条件或目标名;子流程的「折叠显示」读写 `node.collapsed`。后两者不写 `props`,分别变成 `collapsed` / `defaultFlow` 两种 change。 - 分组:L2 的 `bf-property-fields` 加了 `collapsible`,分组标题变成折叠按钮,折叠状态跟着渲染器实例走,切换选中不丢;`groupLabels` 默认取字典(基本/分配/表单/高级 或 General/Assignment/Form/Advanced),宿主可覆盖。 - 插槽:`fields` 整体替换 schema(宿主完全接管字段);`extraTemplate` 在分组下方追加宿主区块,上下文是 `{ $implicit, node, graph }`;字段级自定义控件仍走 `providePropertyFields()`。 - 防抖入栈:文本输入停止 400ms(`BF_PROPERTY_COMMIT_DELAY`)后提交一个 patch,select/toggle 立即提交;同一窗口内多个字段合并成**一次** `change`,所以一次编辑对应一条撤销记录。切换选中时,未提交的 patch 提交给它被输入的那个节点/连线。 - 面板不 dispatch:`change` 是 `{ kind: 'props' | 'collapsed' | 'defaultFlow' | 'edge' }`,用 `bpmnPropertyCommand(change)` 换成命令,再交给 `editor.applyCommand(command)`——L2 在 view 模式统一拒绝,宿主不用自己判断。连线改名与改条件合并成一条 `updateEdge()`,撤销一步全还原。顶部是元素类型胶囊 + 可复制的 id;收起后变成 28px 竖排轨道,`collapsedChange` 回传,由宿主绑回 `[collapsed]`。 - 只读:`mode="view"` 时所有内置控件 `disabled`,选中与复制仍可用。 - L2 侧配套:`setDefaultFlow(gatewayId, edgeId | null)` 在一次命令里清掉旧默认流、设上新的(撤销一步还原);`updateEdge(id, { label?, condition? })` 写连线的名称/条件(`condition` 为空串时删键),`applyCommand()` / `selectNodes()` 分别是宿主写入与外部选中的入口(搜索浮层、状态栏都会用)。 ### BPMN 校验规则 ```ts import { createBpmnValidator } from '@bpmn-ui/bpmn'; const validator = createBpmnValidator(); validator.validate(graph, { disabledRules: ['task.assignee'] }); ``` - `BF_BPMN_RULES` 是设计 §6.6 的 14 条语义规则(zh-CN 快照);`bpmnRules(i18n)` 按当前语言现场构建同一批规则,`createBpmnValidator(rules?, i18n?)` 再叠加 L2 的 3 条结构规则,共 17 条(设计表里的 15 条 = 这 14 条 + L2 的 `node.outOfBounds`,`BF_BPMN_VALIDATION_CODES` 按表顺序列出这 15 个 code)。 - 网关规则按 split / join 语义判断,边数本身不报错:入 0 出 ≥ 1 的网关算合法起点(`process.start.missing` 不会因此报警),入 ≥ 2 出 1 是正常汇聚,入 ≥ 2 出 ≥ 2 只给 `gateway.mixed` 的建议;只有「完全没有连线」和「有入边没有出边」是 error。 - `gateway.split.condition` 只看排他/包容网关:出边 ≥ 2 时,除 `isDefault` 外的每条出边都要有 `props.condition`。`parallel.balance` 是按可达性做的近似配对(分裂的每条分支都能到达同一个并行汇聚,汇聚的每条入边分支也都能从同一个分裂到达),嵌套子流程与环不在近似范围内,消息里写明了。 - `task.assignee` 认可 `assignee` / `candidateGroups`,也认可目录用 `bf:properties` 表达的 `assigneeRole`(示例目录就是这种建模),所以参考流程不会因为「处理角色」而报警。 - 快速修复共 6 条,全部返回 `BfCommand`:添加开始/结束事件、删除孤立网关、把死端网关连到结束事件(没有结束事件时一起创建,`chainCommands` 合成一步)、初始化子流程(补 start/end,保留已有内容)、重新生成重复 ID(保留首次出现的 id,后续按前缀 `_N` 重命名,连线仍指向保留的那个)。撤销一次即回到修复前。 - 规则是纯函数、不写图:`BF_BPMN_RULES` 可以单独注册到自己的 `BfValidator`;`disabledRules` 同时作用于两层。校验目标通常是**当前作用域**图(`state.graph`),所以钻入子流程后校验的是子图;`subprocess.empty` 会主动检查子流程内部的 start/end。 ### XML 抽屉 ```html ``` - 只读抽屉,`[xml]` 由宿主序列化(`xmlFromGraph`);编辑器壳里点「更多 → 导出 XML」会自己做这一步并打开抽屉:行号 gutter + 语法高亮由 `xml-highlight.ts` 完成——单次正则扫描,注释 / CDATA / 处理指令 / DOCTYPE / 标签名 / 属性名 / 属性值分别上色,所有文本先转义再套 ``,所以 `[innerHTML]` 不需要再过 sanitizer(否则 200KB 文档要为净化再付一次全量 DOM 解析)。超过 `BF_XML_HIGHLIGHT_LIMIT`(512K 字符)自动降级为纯文本,并在抽屉里说明。 - 复制走共享的 `copyText()`:优先 `navigator.clipboard`,非安全上下文回退到隐藏 textarea + `execCommand`;只有真的复制成功才把按钮改成「已复制」。 - 下载用 Blob + ``,文件名来自 `[fileName]`,`URL.revokeObjectURL` 在点击后立即回收。 - 导入(编辑模式,view 隐藏):粘贴或选择 `.bpmn` / `.xml`,抽屉自己调 `graphFromXml()`,成功后 `(imported)` 给宿主 `{ graph, xml, warnings, autoLaidOut }`;失败时就地显示 `第 N 行 · 第 M 列:…`(`BfXmlError` 的 0 基行列在 `toXmlDrawerError()` 里转 1 基),并把 textarea 选中到出错行。非结构错误(如根元素不是 `bpmn:definitions`)没有位置,只显示消息与 parser warnings。 - `[open]` 受控:关闭按钮与 `Esc` 都只 `emit(openChange, false)`;`Ctrl/Cmd+Enter` 提交导入。 - 性能:`xml-highlight.spec.ts` 按 200KB 生成文档计时,断言 < 300ms。 ### i18n ```ts import { BF_I18N, BfI18n } from '@bpmn-ui/bpmn'; // 启动语言与宿主词条 @NgModule({ imports: [BpmnEditorModule.forRoot({ i18n: { locale: 'en-US' } })] }) // 运行时切换:注入共享实例,所有 L3 界面一起变 const i18n = inject(BF_I18N) as BfI18n; i18n.use('en-US'); ``` - 两种语言:默认 `zh-CN`,内置 `en-US`。字典是扁平 `key → 模板`,key 按界面分组(`editor.*` / `toolbar.*` / `search.*` / `panel.*` / `group.*` / `field.*` / `palette.*` / `xml.*` / `rule.*` / `fix.*`),zh/en 的 key 集合一致,有单测守着。 - 插值只有 `{name}`:`t('rule.gateway.split.condition', { node, count })`。不做 ICU 复数解析;英文需要单复数时用 `_one` / `_other` 变体,`tn(key, count, params)` 按 count 选键并自动把 `count` 传进去。未提供的占位符原样保留,不会变成 `undefined`。 - 缺 key:dev 下每个 key 只 `console.warn` 一次并回退到 `zh-CN`;两种语言都没有时渲染 key 本身。生产默认不告警,`BfI18nConfig.warn` 可显式打开。 - 覆盖词条:`forRoot({ i18n: { messages: { 'zh-CN': { 'panel.title': '基本信息' } } } })`,宿主词条优先,未覆盖的仍读内置字典。 - 覆盖面:editor 区名与工具条(返回/撤销/重做/搜索/缩放/泳道/预览/更多、脏点、含命令名的工具提示)、搜索浮层(占位符/空态提示/无匹配/列表名)、palette 的标题与元素名(`palette.`,宿主自定义类型没有词条时用 `definition.label`)、属性面板(类型胶囊/标题/分组/字段/占位符/默认流「无」/空态)、XML 抽屉(按钮/行数/导入面板/错误位置)、BPMN 规则消息与 6 条快速修复标签(校验时取当前语言,切换后下一次 `validate()` 即生效)。组件订阅 `changes` 并 `markForCheck`,切换不重挂载。 - 边界:L2 结构规则的消息、节点默认 `label`、XML 内容本身属于数据或下层常量,不参与翻译;`Storybook → L3 BPMN/I18n` 是可交互的中英对照。 ### 编辑器壳(`bf-bpmn-editor`) ```html ``` - 布局:工具条(48px)/ 元素面板(56px)/ 画布 + 属性抽屉 / 状态栏(32px)。抽屉在最右,`propertyPanel="none"` 时整块让给画布。L2 自己的属性 dock 被关掉(`showProperties=false`),由壳统一放 L3 面板。 - 两条缝:palette 点击 → `flow.addNode(type)`(视口中心);palette 拖放 → `flow.clientToModel(clientX, clientY)` 再 `flow.addNode(type, point, { centre: true })`(落点即卡片中心)。属性抽屉的编辑经 `bpmnPropertyCommand()` 变成命令后 `flow.applyCommand()`,所以一次输入就是一步撤销。 - 工具条([toolbar.component.ts](projects/bpmn-editor/src/lib/toolbar/toolbar.component.ts))是纯展示组件:输入当前 `canUndo` / `canRedo` / `undoLabel` / `zoom` / `showLanes` / `dirty` / `mode`,每次点击只发一个意图(`back`/`undo`/`redo`/`search`/`zoomIn`/`zoomOut`/`zoomTo`/`fitToScreen`/`lanesChange`/`preview`/`more`)。图标按钮都有 `title` + `aria-label`,禁用态同时给原生 `disabled` 与 `aria-disabled`;撤销/重做的 tooltip 带命令名(`撤销:移动节点`),脏点用 `role="img"` 报「有未保存的修改」。 - 缩放菜单:百分比按钮是 `aria-haspopup="menu"` 的触发器,展开 50/75/100/125/150/200 与「适配画布」;当前档位 `aria-checked` 带勾,适配后的非整数比例不勾任何一项。`↑↓`/`Home`/`End` 在菜单内移动,`Esc` 或点缩放组以外的地方关闭并把焦点还给百分比按钮;列表项是 `menuitemradio`,适配项是 `menuitem`。预设发绝对值 `zoomTo(0.5…)`,适配发 `fitToScreen()`,宿主不用自己算因子。 - 壳把工具条接到画布:撤销/重做走 `flow.undo()/redo()`,缩放走 `flow.zoomIn()/zoomOut()`、菜单走 `flow.zoomTo(k)`、适配走 L2 新增的 `fitToScreen()`(与 `fitToContent()` 同实现),百分比来自 L2 新增的 `viewportChange`——滚轮、按钮、菜单、适配与迷你图都会更新;泳道开关直接隐藏 pool/lane 图层(节点坐标与滚轮缩放不变,只关视觉)。`back` 以 `(action)` 交给宿主。 - 更多菜单(T4-7,[toolbar.component.ts](projects/bpmn-editor/src/lib/toolbar/toolbar.component.ts)):`import`(编辑模式)/ `export` / `showXml`(编辑模式)/ `autolayout` / `shortcuts` / `clear`,与缩放菜单同一套键盘与外部点击规则。壳把它接成: - **导入 XML**:打开抽屉并直接进导入面板(`importOnOpen`);在面板里点「取消」等同于取消这次导入,抽屉整个关闭(不会顺势露出只读 XML);解析成功就换成新文档 — 把 `event.graph` 赋给 `[graph]` 的下一代引用,L2 通过 `ngOnChanges` 采纳新文档并适配,抽屉关闭并发出 `action: 'import'`,宿主可以借此持久化。 - **导出 XML**:序列化**整份文档**(`flow.document`,不是当前钻入层),文件名取进程名的 slug(`xmlFileNameFor()`,非拉丁名回退 `process.bpmn`),结果送进抽屉预览/复制/下载。 - **显示 XML**:同样打开抽屉看整份文档,但不进导入面板、也不带上「导出」的语义;从抽屉里仍可自行点「导入」或复制/下载。 - **自动布局**:`autoLayoutCommand()` 一步撤销;布局后适配画布。 - **快捷键**:打开只读的快捷键表(`bf-bpmn-shortcut-dialog`,`{mod}` 按平台显示 `⌘`/`Ctrl`)。 - **清空画布**:先弹确认框(`role="alertdialog"`,遮罩点击或 `Esc` 取消,焦点默认在「取消」),确认后 `clearCanvas()` 一步撤销——节点和连线移除、泳道保留;连线为 0 且无节点时菜单项禁用。 - 只读(T4-5,设计 §6.7):预览按钮带 `modeToggle`(默认 `true`)时由壳自己把 `mode` 在 `edit`/`view` 间翻转并发 `modeChange`,宿主把它写回 `[mode]` 就是受控用法;`modeToggle="false"` 时按钮只发 `action: 'preview'`,由宿主改 `mode`。切换是一个开关而不是一组标志:元素面板隐藏并取消进行中的拖拽、画布拒绝拖拽/连线/删除/快捷键写入、属性面板全部禁用、历史按钮灰掉(`undo`/`redo` 在 `view` 下本就由 L2 拒绝)、空状态引导不出现;缩放、平移、泳道显示、搜索与选中仍可用。来回切换只改视图状态,不 dispatch,文档 hash 前后一致。 - 状态栏(T4-6,[status-bar.component.ts](projects/bpmn-editor/src/lib/status-bar/status-bar.component.ts),`bf-bpmn-status-bar`):高 32,左侧校验、中间计数、右侧宿主 `bindingLabel`。校验由壳做:结构 + BPMN 规则经 `BF_VALIDATION_DEBOUNCE_MS` 防抖后交给状态栏;无问题是绿色「校验通过」,有问题变成按钮显示「N 个问题」,质量按 error > warning > info 取聚合色。点开是向上展开的问题列表(role=dialog),标题旁按级别给「N 个错误 / N 个警告 / N 个信息」胶囊,一行一条消息、圆点表示级别、`title` 是规则 code;`↑↓`/`Home`/`End` 在行间移动,`Esc` 或点外部关闭并把焦点还给按钮,点一行发 `locate`,壳用 `focusElement()` 选中并居中(节点、连线、泳道都能定位)。列表清空时浮层自动关闭,不会留一个空对话框。计数是 `statusCounts(graph)` 从当前层模型现算的:节点不含网关,网关单列,连接数即当前层 `edges.length`(fixture 为 5 / 1 / 6),所以数字不会和画布漂移。`bindingLabel` 只是显示,不写进模型。 - 搜索([search-overlay.component.ts](projects/bpmn-editor/src/lib/search/search-overlay.component.ts)):放大镜或 `Ctrl/⌘+F` 在工具条下方展开浮层——画布内由 L2 把快捷键解析成 `action:'search'`,画布外(如元素面板)由壳的宿主监听兜住,输入框内则不抢。≥1 字符起按 label / id / 类型名(不区分大小写子串)过滤**当前层级**的节点,最多 20 条,行内是图标 + 名称 + 类型;`↑/↓` 循环移动、`Enter` 定位、`Esc` 或点击外部关闭,无匹配显示「无匹配元素」。浮层不碰画布:`locate` 只回 id,壳调 L2 新增的 `focusNode(id, { select: true, zoom: 1 })` 选中、回到 100% 并居中,然后把焦点还给画布。无障碍走 combobox/listbox 组合(`aria-activedescendant` / `aria-expanded` / `aria-selected`),`closed` 带 `'escape' | 'outside'` 让壳决定是否收回焦点。 - 响应式按**自身宽度**而不是窗口:`ResizeObserver` 测量壳的盒子,`>= 1280px` 为 `wide`、否则 `compact`(阈值与映射是导出的 `BF_EDITOR_WIDE_MIN_WIDTH` / `editorLayoutForWidth()`)。同一页面上 1440 与 1024 两个壳各自拿对的档位。`compact` 把抽屉从 320 收到 264,画布多出 56px。 - 主题:颜色仍来自 [tokens](projects/bpmn-svg/styles/_tokens.scss);壳额外提供两个可覆写的布局变量——`--bf-editor-side-w`(264,颜色为 `wide` 时 320)与 `--bf-property-panel-width`(面板宽度,默认跟随前一个)。默认先按 264 排,测到 `wide` 再加宽,这样首帧的画布不会被算窄;宿主在自己的样式里给 `bf-bpmn-editor` 赋值即可覆盖。 - 无障碍:壳是 `role="group"`,名字默认取 i18n `editor.label`(`ariaLabel` 可覆盖);画布沿用 L2 的 `role="application"` 和同一名字;工具条是 `role="toolbar"`,泳道与预览按钮带 `aria-pressed`。键盘模型与 axe 门禁见下节。 - Story:`Storybook → L3 BPMN/EditorShell` 的「1440 桌面」「1024 紧凑」「只读预览」三档,画布是 fixture 的真实坐标(状态栏显示 5/1/6,网关带默认流 + 条件所以是「校验通过」);`L3 BPMN/Toolbar` 单独展示按钮契约、缩放菜单、禁用态与事件日志;`L3 BPMN/SearchOverlay` 的「打开」「关闭」两态带 locate/close 日志;`L3 BPMN/Shortcuts` 展示快捷键表,`L3 BPMN/XmlDrawer` 的「导入面板」档对应更多菜单的导入入口。 ### 无障碍(T4-10) - **roving tabindex**:一层里的节点只占**一个** Tab 位。`Tab` / `Shift+Tab` 在当前层级的元素之间移动,到首/尾时交还给浏览器,焦点能正常离开画布(不是键盘陷阱)。聚焦即选中,所以 `↑↓←→` 微移、`F2` 重命名、`Enter` 打开属性作用在刚 Tab 到的元素上;箭头键仍然归编辑器(设计工具里它们是「移动选中元素」),`Tab` 一行也进了快捷键表。 - 每个节点是 `role="button"`,名字取卡片标题(有副标题时用 `,` 连接,如「提交采购申请,负责人 · 审批」),选中态用 `aria-pressed` 表达;只有 roving 的那个带 `tabindex="0"`,其余 `-1`。Tab 位起点优先取有焦点的节点,其次选中节点,最后第一个节点。 - **焦点环**:节点、画布、工具条、菜单项、抽屉按钮、状态栏、搜索输入框都有 `:focus-visible` 的 2px accent 描边(搜索输入框描在字段下沿,因为输入框自身 `outline: none`)。只对 `:focus:not(:focus-visible)` 隐藏指针焦点,这样不支持 `:focus-visible` 的引擎仍保留浏览器默认环。 - 结构:工具条是 `role="toolbar"`(`
`,不是 `