Runtime API 参考

本文示例使用：

import { Application, RenderWindow, type AppHost } from 'ds-ui'

应用级 UI 服务始终来自正在运行的 AppHost：

function openRuntimeTools(host: AppHost): void {  const uiServices = host.uiServices  uiServices.showDevTools({ activeTab: 'runtime' })}

Runtime API 负责应用运行期的 canvas 管理、窗口挂载、布局绘制调度、图层合成、Popup/Tooltip 接入、布局检查、性能采样和运行时快照。业务系统通常通过 Application / AppHost 使用它；只有框架扩展、诊断工具和高级宿主集成才需要直接操作 RuntimeHost。

Runtime API 不负责业务状态管理。业务状态应放在页面 controller、store、App Context 或后端服务中。

导出清单

应用入口：

• Application
• AppHost
• ApplicationRunOptions
• AppOverlayService
• AppOverlayServiceConsumer

运行时核心：

• RuntimeHost
• RuntimeSize
• RuntimeCaptureRect
• RuntimeCaptureImageOptions
• RuntimePaintRequestKind
• RuntimePaintRequestSource
• RuntimePaintRequestRecord

性能诊断：

• RuntimePerformanceMonitor
• RuntimePerformanceMonitorOptions
• RuntimePerformanceDebugState
• RuntimeFramePerformanceSample
• PerformanceOverlayPosition
• RenderRuntimeDiagnosticsPanel
• RenderRuntimeDiagnosticsSnapshotViewer

布局检查：

• LayoutInspectorService
• LayoutInspectorDebugState
• LayoutInspectorTreeNode
• LayoutInspectorAppContextEntry
• LayoutInspectorListener

诊断快照：

• RuntimeDiagnosticsSnapshot
• RuntimeDiagnosticsEnvironmentSnapshot
• RuntimeDiagnosticsRuntimeSnapshot
• RuntimeDiagnosticsLayerSnapshot
• RuntimeDiagnosticsHotspot
• RuntimeDiagnosticsPerformanceSnapshot
• RuntimeDiagnosticsLayoutInspectorSnapshot
• RuntimeDiagnosticsAppContextEntry
• RuntimeDiagnosticsRenderTreeNode
• RuntimeDiagnosticsWindowSnapshot
• parseRuntimeDiagnosticsSnapshotJson
• validateRuntimeDiagnosticsSnapshot
• RuntimeDiagnosticsSnapshotValidationError

Overlay 服务相关：

• AppModalOptions
• AppAlertDialogOptions
• AppConfirmDialogOptions
• AppPromptDialogOptions
• AppLoadingOptions
• AppLoadingHandle
• AppLoadingTask
• AppOverlayContextOptions
• AppPerformanceOverlayController
• AppRuntimeDebugController
• AppCanvasImageDownloadOptions

Application

Application 是推荐的应用启动入口。

const runtimeWindow = new RenderWindow({ title: 'CIS' })const runtimeHost = Application.mount('#app').run(runtimeWindow)

Application.mount(selector)：

如果 selector 找不到 canvas，或匹配元素不是 HTMLCanvasElement，会抛错。框架不会替业务自动创建 canvas。

属性：

方法：

ApplicationRunOptions

宿主框架嵌入时，推荐显式提供 getViewportSize，让 canvas 尺寸跟宿主容器一致，而不是默认使用整个浏览器窗口。

AppHost

AppHost 是应用实例生命周期壳，持有 runtime、overlay 服务和应用级上下文。

属性：

方法：

宿主框架的 unmount / destroy 生命周期中应调用 host.dispose()。如果 canvas DOM 是宿主传入的，dispose 不会移除该 DOM。

RuntimeHostOptions

RuntimeHost 是底层运行时。通常由 AppHost 创建。

构造参数：

RuntimeSize：

RuntimeHost 属性

帧调度和绘制

scheduleFrame() 只表示需要绘制；scheduleLayout() 表示需要重新 layout。组件内部应通过 markNeedsPaint() / markNeedsLayout() 触发管线，不应绕过管线直接调用 runtime。

主窗口和根节点

RuntimeMainWindowOptions：

主窗口关闭会释放整个应用实例；普通 owned window 关闭只移除该窗口分支。

主题

如果主窗口 resolveWindowTheme() 返回不同主题，runtime 在布局前会同步主窗口主题。

尺寸同步目标

尺寸同步适合给图表、外部 canvas、调试面板等对象同步 runtime 尺寸。

RuntimeSizeDependent：

方法：

RuntimeManagedTargetOptions：

图层

业务组件通常不直接注册 runtime 图层。新增框架级 overlay、调试层或特殊合成层时才需要使用。

Paint Request 调试

RuntimePaintRequestRecord 用于分析是谁请求了重绘或 layout。

方法：

debugPaintRequests 适合定位异常频繁重绘。不要在生产环境长期开启 stack 记录。

性能浮层

RuntimePerformanceMonitor 采集帧耗时，并绘制可拖动、可缩小的性能浮层。

RuntimePerformanceMonitorOptions：

常用方法：

后台采集与浮层显示是两个状态：可以只开启 enabled 在后台采集而不创建浮层；但只要浮层可见，采集就一定处于开启状态。隐藏浮层不会自动清空历史样本，也不会替调用方关闭已经开启的后台采集。

RuntimeFramePerformanceSample：

布局检查

LayoutInspectorService 用于检查 render tree、命中路径、节点矩形和 App Context。

节点类型名来自 RenderObject.debugInfo().typeName。框架组件应声明稳定的 static debugTypeName，业务实例可用 debugTypeName 覆盖类型语义，用 debugName 标识实例语义。constructor.name 只作为 fallback，不应作为发布态调试标识依赖。

属性：

方法：

LayoutInspectorDebugState：

诊断快照

createDiagnosticsSnapshot() 会生成 RuntimeDiagnosticsSnapshot。

顶层字段：

快照用于问题定位和离线分析，不是业务持久化格式。快照可能包含业务状态摘要，导出前应按系统要求脱敏。

Canvas 截图

RuntimeHost 和 AppHost 都提供截图导出。

RuntimeCaptureImageOptions：

RuntimeCaptureRect：

const runtimeCaptureWindow = new RenderWindow({ title: '截图示例' })const runtimeCaptureHost = Application.mount('#app').run(runtimeCaptureWindow) void runtimeCaptureHost.captureImageBlob({  rect: { x: 0, y: 0, width: 640, height: 360 },  scale: 2,}).then(blob => {  blob.size})

截图 API 只导出当前 canvas 像素。批量文档截图、场景切换、文件命名、隐藏浮层等属于业务或文档工具策略。

AppOverlayService

AppOverlayService 是应用级 UI 服务集合，包含通知、上下文菜单、模态框、加载、tooltip、布局检查、运行时诊断和截图下载。

属性：

常用方法：

Overlay 方法中的 source、context、contextValues 和 disposeContextOnClose 用于控制弹窗上下文。需要继承页面上下文时传入触发源 source。

showDockWindow() 用于开发者工具、请求日志、布局检查器这类宿主级工具区。停靠窗口是独立 runtime root，不是主窗口 owned window；主内容 viewport 会被停靠区域挤压，普通 modal、loading、popup 只覆盖主内容区。停靠窗口使用 host-docked chrome：标题栏提供左侧/右侧/底部/浮动切换，不提供最大化按钮；和主内容相邻的边缘可拖拽调整尺寸。同一 side 上的多个停靠窗口会共享该 side 的厚度，并沿垂直或水平方向分段显示，避免互相覆盖。业务流程中的抽屉、局部选择器和阻断遮罩仍应使用 Drawer、Modal、Popup 或 RenderOverlayHost。

AppDockWindowOptions 继承 AppOverlayContextOptions，并支持：

生命周期和销毁

RuntimeHost.dispose() 会处理：

• 卸载主窗口、owned windows 和宿主停靠窗口。
• 从 dispatcher 移除 roots。
• pipelineOwner.forget(root) 并 root.dispose()。
• 释放 frame scheduler、dispatcher、tooltip manager。
• 重置焦点、输入、键盘绑定、Popup 和 overlay invalidator 等运行时单例。
• 释放 pipelineOwner.appContext。
• 清空 size dependents 和 paint request history。

AppHost.dispose() 还会释放 overlay 服务和应用级上下文。宿主框架关闭页面、Vue/React unmount 或切换微前端实例时，应明确调用它。

使用边界

• 普通业务页面不要直接调用 RuntimeHost.addRoot()，优先通过窗口、workspace、modal 或 overlay 服务管理。
• 不要在组件 paint 阶段调用 runtime layout/resize API。
• 性能浮层和 paint request debug 适合开发与测试环境，生产环境应由业务开关控制。
• 诊断快照可能包含业务状态摘要，导出或上传前要脱敏。
• 截图导出的是当前 canvas，不代表打印输出。文档打印应使用专门打印管线。
• 如果 canvas DOM 由宿主创建，runtime dispose 不会移除 DOM，宿主仍负责 DOM 生命周期。

主题来源优先级

Application.run(mainWindow, { theme }) 中显式传入的主题属于 runtime 主题源，不会在首帧被 mainWindow.resolveWindowTheme() 覆盖。

• AppHost.setTheme(theme)：设置并保持显式 runtime 主题。
• AppHost.useMainWindowTheme()：恢复跟随主窗口主题。
• 未传入 ApplicationRunOptions.theme 时，默认跟随主窗口 resolveWindowTheme()；主窗口未提供主题时使用默认暗色主题。

主题值相同但对象不同不会重复安排布局。仅颜色变化时 runtime 标记重绘；字体、尺寸或 typography 变化时才标记根节点重新布局。主窗口主题在当前布局帧内完成同步，不会因此额外安排一个无效后续帧。

相关文档

• 应用上下文
• Commands API
• 布局系统总览
• Popup 弹出层
• 运行时诊断
• 生命周期和销毁