# Supported Formats

## PreviewMode

每种文件格式对应一个 PreviewMode：

| Mode | 含义 | 由谁渲染 |
|------|------|---------|
| `NativeReader` | 知习内置阅读器 | App 原生渲染 + Rust 提供 blocks |
| `PlatformPreview` | 平台系统预览 | iOS QuickLook / Android 系统能力 |
| `ExternalOpen` | 外部 App 打开 | 用户选择外部应用 |
| `Unsupported` | 暂不支持 | 显示提示 |

## 格式矩阵

### 第一版（当前优先级）

| 格式 | 扩展名 | PreviewMode | Rust 职责 | App 职责 |
|------|--------|-------------|----------|---------|
| Markdown | `.md` | NativeReader | 解析为 DocumentBlock | 原生渲染 block 列表 |
| 纯文本 | `.txt` | NativeReader | 读取内容，分段落/行 | 原生文本渲染 |
| PDF | `.pdf` | PlatformPreview | 定义阅读位置模型 | iOS PDFKit / Android 系统 |
| PNG | `.png` | NativeReader | metadata（宽高/格式） | 原生图片查看 |
| JPEG | `.jpg` `.jpeg` | NativeReader | metadata | 原生图片查看 |
| WebP | `.webp` | NativeReader | metadata | 原生图片查看 |
| GIF | `.gif` | NativeReader | metadata | 原生图片查看 |
| Word | `.doc` `.docx` | PlatformPreview | 不解析 | QuickLook / 系统预览 |
| Excel | `.xls` `.xlsx` | PlatformPreview | 不解析 | QuickLook / 系统预览 |
| PPT | `.ppt` `.pptx` | ExternalOpen | 不解析 | 外部 App 打开 |

### 第二版（已支持）

| 格式 | 扩展名 | PreviewMode | Rust 职责 | App 职责 |
|------|--------|-------------|----------|---------|
| EPUB | `.epub` | NativeReader | 解析 OPF/spine/NCX TOC，读取章节列表和元数据 | WebView 渲染章节 HTML |
| PDF | `.pdf` | PlatformPreview | 读取元数据（页数/标题/作者），通过 pdfium feature 支持文本提取和搜索 | 系统预览（iOS PDFKit）+ 搜索接口 |

#### EPUB 能力

| 特性 | 状态 |
|------|------|
| 元数据（title/author） | ✅ read_epub_metadata |
| 章节列表（spine + NCX TOC） | ✅ read_epub_chapters |
| EPUB2 NCX 解析 | ✅ |
| EPUB3 NAV 解析 | ⚠️ 降级为 "Chapter N"（#100） |

#### PDF 能力

| 特性 | 状态 |
|------|------|
| 元数据（page_count/title/author） | ✅ read_pdf_metadata |
| 页数检测（/Type /Page + /Count 回退） | ✅ |
| 文本提取 | ⚠️ stub，需 pdfium feature |
| 搜索 | ✅ search_pdf_text（需预提取文本） |

#### Office 能力

| 类型 | PreviewMode | Strategy | 搜索 |
|------|-------------|----------|------|
| Word (.doc/.docx) | PlatformPreview | QLPreviewController | 否（可 Server 转 PDF 后搜索）|
| Excel (.xls/.xlsx) | PlatformPreview | QLPreviewController | 否 |
| PowerPoint (.ppt/.pptx) | ExternalOpen | 外部 App 打开 | 否 |

### 第三版（计划）

| 格式 | 目标 PreviewMode | 备注 |
|------|-----------------|------|
| PDF 增强 | NativeReader（增强） | pdfium 文本提取 + 页级搜索 + 阅读位置同步 |
| EPUB3 NAV | NativeReader | 解析 `<nav epub:type="toc">` 获取真实章节标题 |

### 明确不做

- OCR：不做图片文字识别
- PDF 标注：不做高亮/划线/批注
- Office 内置高保真预览：不解析 Word/Excel/PPT 排版
- 复杂富文本：不做格式保留
- DRM 电子书：不做
- Kindle 格式：不做

## 识别策略

```text
1. magic bytes（文件头，最可靠）
2. MIME type（根据扩展名推测）
3. 文件扩展名（兜底）
```

使用 `infer` crate 做 magic bytes 检测，`mime_guess` 做 MIME 推测。

## 未知格式

无法识别的文件返回 `MaterialType::Unknown` + `PreviewMode::Unsupported`。App 侧应显示友好提示，不崩溃。