文件格式支持矩阵
1. 概述
Document Runtime 支持以下文件格式的解析、元数据提取、文本提取和搜索。
2. 能力矩阵
| 格式 |
枚举值 |
MIME 检测 |
预览模式 |
文本提取 |
元数据 |
搜索 |
定位 |
锚点 |
| Markdown |
Markdown |
扩展名 .md / .markdown |
NativeReader |
✅ Block 解析 |
✅ 行/词/字符统计 |
✅ |
✅ Block+Scroll |
✅ Block ID |
| 纯文本 |
Text |
扩展名 .txt |
NativeReader |
✅ 按行 |
✅ 行/词/字符统计 |
✅ |
✅ 行号+Scroll |
❌ |
| PDF |
Pdf |
文件头 %PDF- |
PlatformPreview |
✅ BT/ET 流式扫描 |
✅ 页数/标题/作者 |
✅ |
✅ 页码+Progress |
✅ 页码 |
| EPUB |
Epub |
文件头 PK + mimetype |
NativeReader |
✅ HTML strip |
✅ 标题/作者/章节数 |
✅ |
✅ 章节+Progress |
✅ 章节 ID |
| 图片 |
Image |
文件头魔术字节 |
NativeReader |
❌ |
✅ 宽/高/格式 |
❌ |
✅ Zoom+Offset |
❌ |
| Word |
Word |
扩展名 .docx |
PlatformPreview |
❌ |
❌ |
❌ |
❌ |
✅ 整体 |
| Excel |
Excel |
扩展名 .xlsx |
PlatformPreview |
❌ |
❌ |
❌ |
❌ |
✅ 整体 |
| PowerPoint |
PowerPoint |
扩展名 .pptx |
ExternalOpen |
❌ |
❌ |
❌ |
❌ |
✅ 整体 |
| 未知 |
Unknown |
— |
Unsupported |
❌ |
❌ |
❌ |
❌ |
❌ |
3. MIME 检测
3.1 检测策略
1. 文件头魔术字节（前 8KB）
├─ %PDF- → PDF
├─ PK + mimetype=application/epub+zip → EPUB
└─ PNG/JPG/GIF/WebP 头 → Image
2. 扩展名回退
├─ .md / .markdown → Markdown
├─ .txt → Text
├─ .epub → EPUB
└─ .pdf → PDF
3.2 代码路径
// material_type.rs
pub fn detect_material_type(file_path: &str) -> Result<MaterialType, DocumentError>
4. 各格式详情
4.1 Markdown
| 能力 |
说明 |
| 解析 |
parse_markdown() → Vec<DocumentBlock>（8 种块类型） |
| 块类型 |
Heading / Paragraph / List / CodeBlock / Quote / Table / Image / HorizontalRule |
| 元数据 |
YAML Front Matter 自动解析为 metadata |
| 搜索 |
search_blocks() — 在每个块的文本内容中搜索 |
| 定位 |
ReadingPosition::Markdown(blockId, scrollProgress) |
| 锚点 |
resolveNoteAnchors() — #heading-id / #paragraph-id |
4.2 纯文本
| 能力 |
说明 |
| 解析 |
按换行符分割为行，不作为结构化块 |
| 元数据 |
行数、词数（text_stats()）、字符数 |
| 搜索 |
search_text() — 按行搜索，返回行号 |
| 定位 |
ReadingPosition::Text(lineNumber, scrollProgress) |
4.3 PDF
| 能力 |
说明 |
| 页数检测 |
/Type /Page 对象计数 → /Pages /Count → 默认 1 |
| 文本提取 |
扫描 BT..ET 块，提取括号内文本（extract_pdf_text()） |
| 元数据 |
/Title, /Author 字段，仅支持 ASCII/PDFDocEncoding |
| 限制 |
最大扫描 8MB（MAX_SCAN_BYTES）；加密 PDF 不解析 |
| 搜索 |
依赖 extract_pdf_text() 输出 |
| 定位 |
ReadingPosition::Pdf(pageNumber, pageProgress, overallProgress) |
4.4 EPUB
| 能力 |
说明 |
| TOC |
NCX（EPUB2）→ NAV（EPUB3）回退 |
| 章节列表 |
Spine 解析 → read_epub_chapters() |
| 文本提取 |
extract_epub_chapter_texts() — HTML 标签移除 + 空白合并 |
| 元数据 |
dc:title, dc:creator |
| 定位 |
ReadingPosition::Epub(chapterId, chapterProgress, overallProgress) |
| 路径策略 |
含 / 或 .xhtml/.html→直接用；否则 OEBPS/{id}.xhtml |
4.5 图片
| 能力 |
说明 |
| 支持格式 |
PNG / JPG / GIF / WebP |
| 元数据 |
read_image_meta() → 宽度、高度、格式 |
| 搜索 |
不支持 |
| 定位 |
ReadingPosition::Image(zoomScale, offsetX, offsetY) |
4.6 Office（Word / Excel / PowerPoint）
| 能力 |
说明 |
| 预览 |
PlatformPreview / ExternalOpen（不内置渲染） |
| 文本提取 |
不支持（依赖第三方预览组件） |
| 搜索 |
不支持 |
| 锚点 |
仅 Material 级别 |
5. PreviewMode 对照
| MaterialType |
PreviewMode |
渲染方式 |
| Markdown |
NativeReader |
Rust 解析 → SwiftUI 渲染 |
| Text |
NativeReader |
SwiftUI 文本视图 |
| Pdf |
PlatformPreview |
WKWebView / PDFKit |
| Image |
NativeReader |
SwiftUI Image |
| Epub |
NativeReader |
Rust HTML strip → SwiftUI |
| Word |
PlatformPreview |
WKWebView / Office URI |
| Excel |
PlatformPreview |
WKWebView / Office URI |
| PowerPoint |
ExternalOpen |
系统分享 Sheet |
| Unknown |
Unsupported |
错误提示 |
6. 搜索能力
| 格式 |
搜索方式 |
返回粒度 |
| Markdown |
search_blocks() |
Block ID + 片段 |
| Text |
search_text() |
行号 + 片段 |
| PDF |
预提取文本后搜索 |
页码 |
| EPUB |
预提取文本后搜索 |
章节 ID |
| Image |
不支持 |
— |
| Office |
不支持 |
— |
验证函数：validate_search_result() — 校验搜索结果片段中的匹配位置是否正确。
7. 限制与边界
| 项 |
值 |
说明 |
| Markdown 文档大小 |
无硬限制 |
依赖内存 |
| PDF 扫描上限 |
8 MB |
MAX_SCAN_BYTES |
| PDF 文本提取 |
BT/ET 块扫描 |
不解析 CMap/Type0 字体 |
| EPUB 支持版本 |
EPUB 2.0 / 3.0 |
NCX + NAV 回退 |
| 图片元数据 |
仅基础 |
不含 EXIF GPS/时间 |
| Office 解析 |
不支持 |
仅预览模式判断 |
8. 相关文档
9ab9a1a052