# View：适配器与工作区参数

后端选择、runtime 参数、几何查询和失效处理。

## 注册与选择

Canvas/SVG 宿主同时导入 `@quirekit/view/styles.css`。它提供内容、覆盖层与输入层的基础定位，主题和工作区尺寸由宿主提供；独立 Core 接入不依赖 Classic 的产品样式。完整示例与[挂载说明](/build/view)包含这一导入。

| 后端 | 注册 | 说明 |
| --- | --- | --- |
| `canvas` | `canvasViewExtension({ runtime })` | Canvas 内容与 View 输入/几何 |
| `svg` | `svgViewExtension({ runtime })` | 共享分页语义的 SVG 表面 |
| `html` | `htmlViewExtension({ runtime })`（`@quirekit/view-html`） | retained DOM 连续流，不等于原生 DOM view |
| `dom` | `DomViewExtension`（`@quirekit/dom-view`） | 原生 contenteditable，单独的适配器 |

### canvasViewExtension

`@quirekit/view` · AGPL-3.0-only

创建已配置的 Canvas 挂载视图扩展。
@param options - Canvas 运行时选项。
@returns 可安装到 Core 的 Canvas 视图扩展。

```ts
function canvasViewExtension(options?: Partial<CanvasViewExtensionOptions>): QuireExtension<CanvasViewExtensionOptions>
```

### svgViewExtension

`@quirekit/view` · AGPL-3.0-only

创建已配置的 SVG 挂载视图扩展。
@param options - SVG 运行时选项。
@returns 可安装到 Core 的 SVG 视图扩展。

```ts
function svgViewExtension(options?: Partial<SvgViewExtensionOptions>): QuireExtension<SvgViewExtensionOptions>
```

### htmlViewExtension

`@quirekit/view-html` · AGPL-3.0-only

创建已配置的 retained HTML 挂载视图扩展。
@param options - HTML 运行时选项。
@returns 可安装到 Core 的 HTML 视图扩展。

```ts
function htmlViewExtension(options?: Partial<HtmlViewExtensionOptions>): QuireExtension<HtmlViewExtensionOptions>
```

## 常用 Canvas runtime 参数

| 参数 | 用途与单位 | 接入注意 |
| --- | --- | --- |
| `width` / `height` | 首选内容 surface 尺寸，CSS px | 不是 Word twip，也不替代文档模型页设置 |
| `pageStack` | 分页面 surface 展示 | 分页事实由 profile/Engine 产生 |
| `scrollSource` / `scrollViewport` | 指定滚动所有权 | 产品内滚动用同一个 viewport 元素 |
| `viewportPadding` | 视口留白，CSS px | 与文档页边距分别配置 |
| `devicePixelRatio` / `getDevicePixelRatio` | 绘制 backing 密度 | 不当作正文缩放比例 |
| `surfaceConfig` | 选区、对象选择和呈现样式 | 不写入规范正文 |
| `mediaResolver` | 稳定资产引用到可用字节/资源 | 与持久化及文件转换使用相容的资源服务 |
| `onRender` | 完成一次挂载渲染的事实 | 读取 `renderResult.layoutSnapshot`，不再启动第二次排版 |
| `onVisiblePagesChange` | 实际挂载页集合 | 可用于诊断，不等同文档总页数 |
| `textMeasurer` / `lineBreaker` | 测量和断行策略 | 需要一致、可验证的字体与布局策略 |

SVG 有自身 runtime 合同，如 `textMeasurementBackend: 'browser'`。不要只按相似字段名给不同后端套一份未经类型检查的对象；教程的公共回调使用共享 `QuireMountedViewRenderEvent`。

## mounted View 的常用能力

`editor.mountedView` 在未挂载时可能不存在；`editor.view` 需要有效主视图。`focus()`、`hasFocus()`、`scrollToSelection()` 负责输入和可见性。`coordsAtPos()` / `posAtCoords()` 使用浏览器 client CSS px；`getCaretRect()` 和 `getTextRangeRects(range, sourceDocument)` 只在后端有当前几何时返回结果。

当 API 要求 `sourceDocument`，传当前捕获的不可变文档身份。陈旧帧返回 null/不可用是正常的拒绝信号，不能用旧坐标命中新的正文。监听 `onGeometryUpdate()` 后在需要时重读，并释放返回的订阅。

完整工作区、模式切换和缩放见[挂载教程](/build/view)；Editor 的 mount/changeMode 参数见 [Editor API](/api/editor)。