病历编辑器接入

本文示例使用以下公共入口；业务类型和服务仍由你的应用定义：

import {  MedicalRecordEditorController,  RenderMedicalRecordEditor,  type MedicalRecordDocument,} from 'ds-ui'

病历编辑器是 DirectSurface UI 中最复杂的业务组件之一。它不是普通富文本控件，而是面向电子病历场景的文档编辑器，包含分页排版、数据元、表格、批注、留痕、审阅侧栏、弹层编辑、打印 SVG 和大文档性能优化。

本文面向业务系统开发者，说明如何把编辑器接入页面、如何组织文档数据、哪些能力由编辑器负责、哪些规则应由业务系统负责。

能力边界

编辑器负责：

• Canvas 实时编辑和绘制。
• 病历文档分页、缩放、滚动和可视页绘制。
• 文本输入、中文 IME、粘贴、拖选、复制和光标。
• 段落格式、字体、颜色、项目符号、编号、缩进。
• 表格插入、合并、拆分、行列增删、边框和斜线。
• 日期、下拉、多选、数据组等数据元的弹层编辑。
• 批注和质控问题的创建、展示、状态流转和锚点状态。
• 留痕显示、留痕提示、审阅项导航和筛选。
• 打印模式下输出 SVG 节点。

业务系统负责：

• 登录用户、当前患者、当前就诊、文书状态和权限判断。
• 是否允许编辑、是否启用留痕、是否显示批注和审阅块。
• 文档 JSON 的加载、保存、归档、版本和服务端审计。
• 模板库、病历分类树、文书实例列表和接口错误处理。
• 打印流程、打印预览、PDF 生成、归档签名和外部质控流程。

编辑器本身不判断病历业务状态。业务应根据流程状态和权限设置 controller/view options，而不是把“已归档不能编辑”“上级医生才能审核”等规则写进底层编辑器。

最小接入

const controller = new MedicalRecordEditorController()const editor = new RenderMedicalRecordEditor({  controller,})

页面关闭时必须释放 controller。推荐页面持有 controller，编辑器只作为页面 render tree 的子节点：

class MedicalRecordPage {  readonly controller = new MedicalRecordEditorController()  readonly editor = new RenderMedicalRecordEditor({    controller: this.controller,  })   dispose(): void {    this.controller.dispose()  }}

如果页面本身也是 RenderObject，通常在页面 dispose() 里先清理页面创建的 DOM、订阅和异步请求，再调用 super.dispose()，最后释放 controller。不要把 controller 放到应用级单例里长期复用。

页面结构

典型病历编辑页面由“模板树 + 工具栏 + 编辑器”组成：

RenderStackPanel vertical
  RenderToolbar
  RenderSplitter horizontal
    left: 模板树 / 文书目录 / 大纲
    right: RenderMedicalRecordEditor

实现要点：

• 病历编辑器自己管理滚动，不要再套一层同方向 ScrollViewer。
• 左侧模板树适合用 RenderTreeView，长文本要有省略和 tooltip。
• 工具栏应读取 controller.getToolbarState()，并在 controller change 事件后刷新。
• 大文档下不要在每次输入后重建整个页面 render tree。

文档数据

MedicalRecordDocument 可以是：

加载文档：

async function loadMedicalRecord(url: string): Promise<void> {  const controller = new MedicalRecordEditorController()  const response = await fetch(url)  if (!response.ok) throw new Error(`HTTP ${response.status}`)  const document = await response.json() as MedicalRecordDocument  controller.loadDocument(document)}

加载本地 JSON：

async function loadLocalMedicalRecord(file: File): Promise<void> {  const controller = new MedicalRecordEditorController()  const text = await file.text()  const document = JSON.parse(text) as MedicalRecordDocument  controller.loadDocument(document)}

保存文档：

const controller = new MedicalRecordEditorController()const schema = controller.serialize()const json = JSON.stringify(schema)

推荐保存口径：

• 页面只保存 controller.serialize() 的结果。
• 不保存临时可视状态，例如滚动条位置、当前 hover、popup 状态。
• 是否保存留痕、批注、审计轨迹取决于文档 JSON 结构和业务服务约定。
• 保存前可以先执行 controller.validate()，把必填数据元或业务校验问题展示给用户。

模板库接入

模板库通常不是编辑器能力，而是业务页面组合：

模板索引接口
  -> TreeView roots
  -> 点击模板节点
  -> fetch 模板 JSON
  -> controller.loadDocument(document)

推荐模板索引字段：

模板树只负责选择模板。真正加载文档后，应调用 controller.loadDocument()，然后把焦点交回编辑器。

工具栏和状态同步

工具栏不要自己猜当前选区状态，应使用：

const controller = new MedicalRecordEditorController()const state = controller.getToolbarState()

常用状态：

监听变化：

const controller = new MedicalRecordEditorController()const subscription = controller.on('change', () => {  const state = controller.getToolbarState()  state.canUndo}) subscription.unsubscribe()

页面 dispose 时要释放订阅。也可以直接在页面 dispose 中调用 controller.off('change') 清理页面注册的 handler。

常用编辑 API

文档和历史

文本和段落

表格

批注和质控

状态包括：

数据元

日期、下拉、多选、树形选择等数据元的编辑 UI 由编辑器内置弹层处理。业务如果需要自定义弹层，应基于实际 render rect 定位，不能基于理想文本宽度定位。

视图和打印

文档模式

业务系统应根据文书状态切换模式。例如新建模板用 design，医生书写用 edit 或 form，归档查看用 view。

留痕和批注

留痕和批注是两个不同概念：

推荐业务规则：

• 是否启用留痕由业务状态决定，例如归档后修改、上级医生修改或特定流程节点。
• 同一操作员连续修改同一字段时，可以在业务层合并保存轨迹，避免轨迹膨胀。
• 批注创建后，当前打开会话内继续编辑批注正文可合并到创建记录；不同打开会话再次修改应形成修改审计。
• 如果批注关联正文被修改，应标记 anchorChanged；如果锚点被删除，应标记 orphaned。
• 批注状态流转应走业务命令，例如处理、解决、重开、关闭。

审阅侧栏由编辑器渲染，业务页面可以通过：

const controller = new MedicalRecordEditorController()const editor = new RenderMedicalRecordEditor({  controller,}) editor.setReviewFilter({  type: 'comment',  status: 'active',})editor.activateNextReview()

筛选类型：

性能策略

病历编辑器的大文档性能依赖三点：

1. 编辑器自己管理滚动和可视页绘制。
2. 输入时优先尝试快速 patch，当前段落高度不变时不全量分页。
3. 选区绘制基于全局范围坐标投影到可视页，不展开全量选区树。

接入时不要破坏这些前提：

• 不要在外层套同方向滚动容器。
• 不要每次输入都 loadDocument()。
• 不要 hover 时刷新整个业务页面。
• 不要把大文档、图片缓存或控制器放到全局上下文。
• 不要在 popup 或批注卡片里创建无法释放的订阅。

大文档问题优先用 Runtime Diagnostics 观察 layout、paint、frame 和事件耗时，再看编辑器自己的 debug state。

内存释放

页面关闭时建议执行：

class MedicalRecordPage {  private localInput: HTMLInputElement | null = null  readonly controller = new MedicalRecordEditorController()   dispose(): void {    if (this.localInput) {      this.localInput.onchange = null      this.localInput.remove()      this.localInput = null    }    this.controller.dispose()  }}

释放检查：

• 页面是否还被 workspace、tab manager 或业务缓存引用。
• controller 是否 dispose。
• 本地文件 input、popup、context menu 是否移除。
• 图片、条码、二维码缓存是否属于文档上下文，而不是全局。
• 异步模板加载返回后是否判断页面已关闭。

打印和 SVG

Canvas 模式用于实时编辑；打印模式可以走 SVG。二者是不同输出路径：

使用：

const controller = new MedicalRecordEditorController()const pages = controller.printSvg()

printSvg() 返回每页 SVG 字符串。业务系统可以继续做打印预览、PDF 转换、盖章、签名或上传归档。

调试入口

常用调试方法：

调试建议：

• 光标、hover、popup 卡顿先看运行时诊断面板。
• 输入卡顿先区分是 layout、paint、输入承接控件还是业务页面重建。
• 关闭页面后内存不下降，生成 heap snapshot 检查 controller、document、canvas、popup、input 是否仍被引用。

常见错误

把编辑器放在外层 ScrollViewer 里

病历编辑器自己管理滚动。外层同方向滚动会导致滚轮、popup 定位、审阅块和横向滚动范围不稳定。

每次切换模板都复用旧页面状态

加载新文档后应刷新工具栏、审阅筛选和焦点；如果业务希望滚动到顶部，可以调用 loadDoc(data) 或 nativeScrollTop(0)。

把页面草稿和当前文书放到应用级上下文

当前文书应放页面或 tab 上下文。应用级上下文只放登录用户、租户、权限服务、字典服务等长期共享对象。

批注只当作黄色背景

批注是业务协作信息，应该有作者、时间、状态、审计、锚点状态和后续处理动作。

日期数据元允许任意键盘输入

日期数据元应通过日期弹层或明确的日期输入段录入，避免普通文本输入破坏数据结构。

忽略打印模式验证

Canvas 编辑正常不代表打印正常。条码、二维码、分页、批注、留痕都要在打印 SVG 路径单独验证。

相关文档

• 大文档编辑
• CIS 系统接入
• 患者上下文模式
• 审计与操作日志
• 常用业务场景组合
• Runtime Diagnostics
• 病历模板浏览示例