扩展与媒体部署

使用方式

DOM 元素扩展通过 kuiext_* C ABI 与宿主对接，媒体后端使用 kui_media_* 协议。两者加载方式和生命周期不同。部署时同时核对架构、ABI 版本、导出入口、依赖 DLL 和资源文件。

接入和限制

3D 的正式方向是独立 kui_ext_3d，不继续扩展默认关闭的旧仓内模块。编辑器、PDF 和媒体能力以包清单为准。扩展重绘须遵守失效契约，不能只在首次绘制有效后就判定接入完成。

加载 DOM 元素扩展

ExtensionManager 属于 Document。将匹配架构的扩展 DLL 和依赖部署到应用可控目录，传入明确路径。loadExtension 返回 false 时检查 ABI、依赖和错误日志；不要通过扩大系统 DLL 搜索范围解决来源不明的问题。

bool loadElementExtension(kui::Document& document, const std::string& path) {
    auto* manager = document.extensionManager();
    return manager && manager->loadExtension(path);
}

元素扩展与媒体后端

kuiext_* 扩展注册自定义元素，例如 kui-editor、kui-pdf、kui-3d-view。kui_media_* 为内置 audio/video 元素提供后端。二者有不同的入口、加载器和生命周期，媒体 DLL 不通过 ExtensionManager 当作元素扩展加载。

• 编辑器：kui_ext_editor 与匹配的语法依赖。
• PDF：kui_ext_pdf 与 PDFium 运行库。
• 3D：独立 kui_ext_3d 与必需的材质 sidecar。
• 媒体：音频和视频后端及其解码/放音依赖。

扩展实例的重绘

扩展更新内容后要按 host contract 请求失效。只更新内部像素而不通知宿主，可能留下旧画面。检查尺寸变化、可见性、连续动画和销毁时的资源回收；持续绘制的能力需要单独运行验证。

• 编辑器文档 →
• PDF 文档 →
• 3D 文档 →

从最小扩展开始接入

只带上应用需要的组件，依赖以包清单和 CMake component 为准。

1. 确认是 DOM 元素扩展 kuiext_*，还是媒体后端 kui_media_*。
2. 选择对应 SDK component，使用 SDK helper 复制运行时与 sidecar。
3. 在实际调用前检查加载结果；把找不到文件和 ABI 不匹配分开记录。
4. 运行包内最小示例后，再放进应用；换一个工作目录重试。

扩展交付检查

按现象缩小范围，再修改对应文件。