常见问题
生产环境可以直接使用吗
组件还在持续迭代中，建议用于生产前结合业务场景做完整测试。发现问题可反馈至 norio-office@qq.com。
为什么需要显式引入样式
组件样式会作为独立 CSS 文件发布，推荐在应用入口显式引入：
import '@norio-office/rich-text/style.css'这样可以避免不同构建工具对 CSS side effects 处理不一致导致样式缺失。
为什么推荐使用 JSONContent
JSONContent 和编辑器内部结构一致，回显更稳定，也更适合再次进入编辑态。单人模式下建议优先保存 JSON；只读展示时再按场景导出 HTML、PDF 或图片。
为什么上传要交给业务层
每个业务系统的上传接口、鉴权方式、存储平台、返回结构都不同。组件只负责把用户选择的 File 交给上传 hook，并在 hook 返回最终 URL 后插入内容。
组件不会内置业务上传接口，也不会自动回退为 base64/blob URL。
页面拖拽上传如何分流
页面拖拽上传会按文件类型分流：
image/*走uploadImagevideo/*走uploadVideo- 其他格式走
uploadFile，并插入本地文件卡片
如果没有传对应上传 hook，业务侧需要自行处理无法上传的提示或接入边界。
preview 模式和 editable=false 有什么区别
editable=false 更偏向关闭编辑能力，但仍保留原有编辑器壳层。mode="preview" 则会进入只读预览外壳，工具栏隐藏，并支持更适合阅读场景的大纲布局和窄屏缩放。
水印会写入编辑器内容吗
不会。watermark 只作为页面视觉层渲染，不写入编辑器 JSON，也不会影响 getText() 的纯文本结果。PDF、图片和打印导出会保留水印。
@mention-search 为什么不像普通事件
mention-search 是函数式监听写法，对应 onMentionSearch prop。Vue 模板里的 @mention-search="handler" 会作为函数 prop 传入组件，可直接返回数组或 Promise。
mention 默认关闭，只有传入 :mention="true" 后，输入 @ 才会打开候选面板并调用搜索函数。
点击提及候选项会直接插入吗
不会。点击候选项只会触发 mention-item-click 并选中当前项；点击弹窗底部“提及”按钮才会插入结构化提及节点并触发 mention-submit。关闭弹窗或不点击“提及”时，编辑器会保留普通 @ 文本。
白名单 Props 不传时会怎样
不传时，内置导出项、插入菜单项和工具栏动作默认全部可用。只有当你显式传了数组，组件才会进入白名单裁剪模式。
什么时候使用外置目录组件
内置大纲适合默认编辑器布局。如果你希望把目录放到业务系统自己的侧栏、抽屉或固定区域里，可以设置 :show-outline="false"，再使用 RichTextOutline 接收编辑器实例。
协同模式为什么不能依赖 modelValue 初始化
协同模式下的真实数据源是 Yjs 文档。组件仍会 emit JSON 快照，但外部 modelValue 的变化不会再反向写入编辑器。
默认情况下组件不会把 modelValue 写入空的协同 fragment。如果是后端已有 Yjs 快照，必须以快照为准，不要传 initializeContent: true。如果是全新的空房间，业务侧先确认当前客户端拥有初始化权，再传 initializeContent: true 和 initialContent。
富文本协同的 documentType 用什么
统一协同服务里当前富文本组件的类型是 rich。不要把它作为未来 Word 组件的 documentType=word 接入。
同一个协同房间里的所有客户端必须使用同一个 field，普通一文档一编辑器场景固定用 content。
随包 Yjs 服务适合生产吗
不适合直接当生产服务使用。随包 yjs/ 示例主要用于快速验证协同接入，它是最小 WebSocket 服务示例，默认纯内存运行，重启后文档状态会丢失。
本地文件卡片适合什么场景
适合在文档里插入业务附件、下载文件入口、材料清单等。业务侧可以监听 local-file-click、local-file-download 和 upload-error 等事件，再决定如何预览、鉴权和下载。
后续增加公开能力时文档应补什么
建议每次补齐三类内容：
- 功能说明
- 接入示例
- 限制或注意事项