DocumentPreview
阅读分页文档。中文惯用名：文档预览。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.document-preview |
| 名称 | DocumentPreview |
| 二级分类 | 媒体与内容（media） |
| 用途 | 阅读分页文档 |
| 描述 | 中文惯用名：文档预览。 |
预览
静态结构：卡片 = 工具条（上一页 / 页码指示 / 下一页 / 分隔线 / 缩小 / 放大，0.5x~2x 步进 0.25）+ 阅读体（bg-muted 滚动区：图片页 img、文本页白底纸张卡片，scale 变换 origin top center）。翻页非受控（内部维护）或受控（currentPage + onChange，仅上报不自行切换）。空 pages 渲染「暂无文档内容」。
DSL 结构
{
"type": "DocumentPreview",
"props": {
"pages": [
{
"content": "第一页：项目背景与目标"
},
{
"content": "第二页：实施计划"
}
],
"currentPage": 1
}
}何时用
何时使用
- 阅读分页文档：扫描件、合同条款、分页报告。
- 需要翻页、页码指示与缩放的阅读场景。
何时不用
- 单文件内嵌预览：使用 FilePreview。
- 长文连续阅读：用 Typography / Markdown 排版，不强制分页。
- PDF 二进制解析：本期不支持（pages 需预先转为图片或文本页）。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 文本页 | 白底纸张卡片 | 条款、规范类文档 |
| 图片页 | 扫描件图片 | 合同扫描件、票据 |
| 受控翻页 | currentPage + onChange | 与外部步骤 / 批注联动 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
pages | DocumentPageData[] | [] | 分页内容：{ src?, content? }（src 优先；不解析 PDF 等二进制） |
currentPage | number | — | 受控当前页码（从 1 起）；提供时翻页仅经 onChange 上报 |
onChange | event | — | 翻页事件，传出目标页码（${event} 取页码） |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式 |
使用规范
- PDF 等二进制先在服务端 / 构建期转为图片页或文本页，再交给本组件。
- 文本页内容保持一页一屏的量级，避免单页过长失去分页意义。
- 与批注 / 审核流联动时用受控模式同步当前页。
正例
- ✓ 合同审核：扫描件图片页逐页翻阅 + 放大核对印章。
- ✓ 规范阅读：文本页分页呈现，受控 currentPage 与目录联动。
反例
- ✕ 期望组件直接打开 .pdf 文件（需先转页数据）。
- ✕ 把整本长文档塞进单页 content（应拆分多页）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。