# 配置与生命周期

区分初始正文、产品设置和宿主服务，正确更新与销毁编辑器。

先运行[快速接入](/classic/quick-start)的完整示例，再按自己的产品修改配置。Vue 应用使用 `/vue` 入口，共享应用已有的 Vue runtime。

## 创建时确定的内容

| 配置 | 用途 |
| --- | --- |
| `element` | 编辑器宿主；暂不提供时可稍后 `mount()` |
| `document` | 初始规范正文，不是界面语言字典 |
| `preset` | 本次产品采用的文档模型、视图与默认插件 |
| `plugins` | 产品功能区、侧栏、动作和文件服务 |
| `extensions` | 追加普通 Core 扩展；必须与模型和 View 相容 |
| `media`、`host` | 媒体持久化与宿主资源服务；按创建时合同接入 |

不要在每次界面渲染时重新创建实例，也不要为更新按钮状态反复传入 `document`。模型与 Schema 的选择见[文档模型](/build/model)。

## 界面与工作区

| 配置 | 使用方法 | 默认与边界 |
| --- | --- | --- |
| `locale` | `'zh-CN'` 或 `'en'` | 默认中文，只改变界面，不翻译已有正文 |
| `editable` | `false` 切换到只读输入 | 默认 true；程序写入还要检查应用权限 |
| `theme` | 传完整 QuireKit theme | 实例优先于 preset，不是只传一个主色 |
| `view` | `{ backend: 'canvas' }` 或 `'svg'` | 默认 Canvas；产品更新后端会重建 Core |
| `shell` | 显隐菜单、功能区、工具栏、标尺、侧栏、状态栏 | 在预设默认值上逐字段覆盖 |
| `ui` | toolbar、contextMenu、selectionPopup 的 contribution ID 列表或 false | 决定已有控件的组成；不创建新的正文命令 |
| `webFonts` | 字体库配置，或 false | 不提供时使用默认外部字体库配置；关闭后应用仍需准备正文使用的字体 |

例如嵌入正文区域时，可以保留功能区，关闭紧凑工具栏并让窄窗口使用收纳菜单：

```ts [创建选项中的界面配置]
shell: { toolbar: false, ribbon: true, ribbonOverflow: 'collapse' },
ui: { selectionPopup: false },
webFonts: false,
```

`shell` 控制整个区域；`ui` 控制相应区域中的已注册项目。需要新动作或面板时，先通过[产品插件](/classic/plugins)安装 contribution，再使用它的 ID 配置。不要把界面显隐当成写权限。

同时加载 `@quirekit/classic-editor/styles.css` 和所用 Word 包的 `@quirekit/classic-docx/styles.css`。宿主提供实际高度和可用宽度，公开样式负责产品组件、绘制层和浮层定位。

## 用 UI 控制器调整当前工作区

```ts [不重建 Core 的界面操作]
instance.ui.setZoomMode('fit-width')
instance.ui.setRulerVisible(false)
instance.ui.setSidebarVisible('right', false)
```

这些操作不修改正文，也不清空历史。打开已安装的面板用 `openSidebarPanel(side, panelId)`；监听 UI 状态用 `subscribe(listener)`，并保留它返回的释放函数。

## 哪些更新会重建 Core

单独更新 `locale`、`editable`，以及内置普通/Word 预设的 `theme`，会保留同一个 Core、选区、storage、监听和撤销历史。语言不翻译正文，主题只刷新界面和派生绘制颜色；只读更新会取消尚未提交的导入。

传入 `document`、`preset`、`plugins`、`extensions`、`view`、`features`、`shell`、`ui` 或运行时结构设置时，仍会卸载并重建 Core/View。正文默认保留，旧 Core 和历史结束；更新后重新读取 `instance.editor`。即使与 locale 一起传入也按结构更新处理。配置确实改变时再调用，不能每次按键或 Vue 渲染都更新。

自定义 preset 若要保留会话切主题，需要实现 `updatePresentation(context)`，刷新自己拥有的非持久呈现配置，不能修改 Schema 或正文。未实现时，改变主题继续重建。自定义预设接入见[Classic API](/classic/api)。

| 更新字段 | 合并规则 |
| --- | --- |
| `document` | 显式传入时替换，否则保留当前正文 |
| `plugins`、`extensions` | 替换实例级数组；保留项也要放在新数组里，preset 插件仍独立存在 |
| `features`、`shell`、`view`、`canvasRuntime`、`svgRuntime` | 在当前配置上逐字段浅合并 |
| `ui` | 按 surface 更新；某个 surface 的 `items` 是最终列表，false 禁用 |
| `preset`、`theme`、`locale`、`editable`、`webFonts` | 使用传入的新值 |
| `media`、`host`、`surfaceMode` | 不属于 update 选项；更换这些服务时创建新产品实例 |

需要持续观察正文时，用插件 `onMount` / `onUnmount` 绑定和清理当前 Core 的订阅。不要只在第一次创建后订阅旧实例；[保存教程](/classic/files)给出了可复用例程。插件的 `onUpdate` 是界面更新钩子，也会因选区等变化触发，不等同于 Core 的正文 `update`。

## 离开页面与重新挂载

动态导入返回后，先检查宿主是否仍存在。`unmount()` 释放产品壳和 Core，保留正文供下次 `mount(element)` 使用；这也会丢失该 Core 的历史。`destroy()` 最终清理产品资源，离开拥有实例的页面时调用，之后不再挂载。内置导入任务在卸载、销毁或目标正文变化时失效；任意自定义网络请求仍由其拥有者取消。

## 保存和资源

JSON 下载是一次显式快照，不等于自动保存。应用需要保存规范正文及对应媒体资源，处理保存失败和未保存状态，见[Classic 保存与打开](/classic/files)。完整选项、实例方法与 UI 控制器见[实例与配置参考](/classic/reference)；动作、面板和服务见 [Classic API](/classic/api)。