常见问题

富文本应该安装哪个包

安装 @norio-office/rich-text。本地仓库目录名不等于 npm 包名，不要根据目录名安装 Word 编辑器。Vue、Tiptap 等依赖应与当前包声明的版本兼容，具体接入见快速开始。

为什么传入 null 后没有得到空白文档

当前单人模式首次挂载不传 modelValue 或传 null 时，会显示内置示例内容；挂载后改为 null 也不会清空。空文档应明确传入：

const emptyDocument = {
  type: 'doc',
  content: [{ type: 'paragraph' }],
}

这是单人模式的数据赋值方式。协作模式以 Yjs 内容为准，不能这样覆盖协作房间。完整例子见保存、上传与导出。

保存纯文本或 HTML 就够了吗

继续编辑时应保存完整 JSON。getText() 会丢失标题、颜色、表格和图片等结构；HTML 适合展示或交换，不应直接当成完整编辑状态存档。文件打包、资源与 Nordox 说明见 AI 接入中的资源说明。

图片上传 hook 应该返回什么

返回包含 url 的对象，不是 URL 字符串。例如：

{ "url": "https://cdn.example.com/uploads/photo.png", "name": "photo.png" }

编辑器拿到结果后会自动插入图片，不要在 hook 内再次调用插入方法。缺少上传 hook 不会自动回退为 base64。上传接口与错误处理的完整示例见保存、上传与导出。

评论提交后为什么没有永久保存

组件负责评论界面与正文锚点，评论数据由业务系统保存。收到新建、回复、编辑等事件后，业务完成存储，再把更新后的 comments 数组传回组件。不要只更新前端数组就认为服务端已保存，见评论与业务数据。

PDF 导出会完整还原页面吗

当前 PDF 导出使用简化的文字与矩形绘制，生成一张随文档高度延伸的页面，不保证图片、公式、字体和装饰等细节完整还原。几种导出的实现与限制不同，请按导出说明选择并验证业务文件。

AI 如何接上当前富文本

使用 createRichTextAiBridge() 等接口连接当前编辑器，捕获目标后提交局部修改。模型、聊天和保存由应用提供。工具处理器还需要业务宿主能力，例如创建新文档，不能只创建 Bridge 就认为全部工具已接好。见AI 原子级修改。

预览模式下调用媒体 API 需要检查吗

需要。当前媒体实例方法还需由调用方判断预览状态，不能只依赖界面禁止编辑。应用与服务端也需要校验资源访问和写入权限，实例接口见参数与实例 API。

多人编辑需要什么服务

需要部署 Docker 版本，并按协作接入连接 Yjs 相关服务，配置用户身份、文档房间与持久化。单人模式的 v-model 保存示例不能直接作为多人内容同步方案。