# doc_viewer

**Repository Path**: jimonik/doc_viewer

## Basic Information

- **Project Name**: doc_viewer
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-13
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Doc Viewer 🗂️

[![pub package](https://img.shields.io/pub/v/doc_viewer.svg)](https://pub.dev/packages/doc_viewer)
[![License: MIT](https://img.shields.io/badge/license-MIT-purple.svg)](https://opensource.org/licenses/MIT)
[![Platform](https://img.shields.io/badge/platform-android%20%7C%20ios-blue.svg)](https://flutter.dev/)

> ⚠️ **提示：** 本插件目前处于 **Beta 版本**。随着我们持续改进对各类文档格式的支持，API、UI 及渲染行为可能会发生变化。


一个功能强大、高性能的 Flutter 插件，可在 Android 与 iOS 上原生查看多种文档格式。

**Doc Viewer** 充分利用优秀的开源原生 SDK 与操作系统内置框架，快速且精美地渲染文档，同时将 Flutter 层保持得极简高效。

绝无 **商业依赖**、绝无 **云端处理**、**100% 在设备本地渲染**。

---

## ✨ 特性

* **通用格式支持**：支持打开 15 种不同的文档类型，包括 PDF、Word、Excel、PowerPoint、EPUB、CBZ、Text、CSV、RTF 以及 OpenDocument 格式。
* **原生性能**：文档通过优化过的原生库渲染——Android 使用 `PdfiumAndroid`，iOS 使用 `PDFKit`/`QuickLook`。
* **格式专属主题**：精美的、按格式配色的原生标题栏（例如 Word 蓝、Excel 绿、EPUB 紫），开箱即用地提供统一而高级的界面。
* **智能渲染**：电子表格中的公式求值、PDF 的原生缩放与滚动，以及针对电子书和漫画书的 HTML 结构化提取。
* **完全离线**：所有内容均在设备上完成解析与渲染，无需云端 API，也无需庞大臃肿的框架。

---

## 📄 支持的格式与原生渲染引擎

本插件会智能地将每种文件类型路由到最合适的原生渲染引擎：

| 格式 | 扩展名 | Android 引擎 | iOS 引擎 |
| :--- | :--- | :--- | :--- |
| **PDF** | `.pdf` | [PdfiumAndroid](https://github.com/barteksc/AndroidPdfViewer)（硬件加速） | **PDFKit**（内置） |
| **Word (doc, docx)** | `.doc`、`.docx` | [All Documents Reader SDK](https://github.com/ahmadullahpk/all-documents-reader) | **QuickLook**（内置） |
| **Excel (xls, xlsx)** | `.xls`、`.xlsx` | XLS 使用 All Documents Reader；XLSX 使用 Apache POI → HTML 表格 → WebView | **QuickLook**（内置） |
| **PowerPoint (ppt, pptx)**| `.ppt`、`.pptx` | [All Documents Reader SDK](https://github.com/ahmadullahpk/all-documents-reader) | **QuickLook**（内置） |
| **EPUB 电子书** | `.epub` | 原生 ZIP → spine/HTML 提取 → WebView | [ZIPFoundation](https://github.com/weichsel/ZIPFoundation) → spine/HTML → WebView |
| **CBZ 漫画书** | `.cbz` | 原生 ZIP → 图像提取 → WebView | [ZIPFoundation](https://github.com/weichsel/ZIPFoundation) → 图像提取 → WebView |
| **纯文本** | `.txt` | 原生 `TextView`（等宽字体，内存高效） | 原生 `UITextView`（等宽字体） |
| **CSV** | `.csv` | RFC-4180 解析器 → HTML 表格 → WebView | 对齐的纯文本表格 → `UITextView` |
| **富文本** | `.rtf` | 原生 HTML 解析器 → `Html.fromHtml` → `TextView` | `NSAttributedString` → `UITextView` |
| **OpenDocument**| `.odt`、`.ods`、`.odp`| 自研 ZIP/XML 解析器 → HTML → WebView| **QuickLook**（内置） |

---

## 🛠 环境配置与安装

**环境要求：**
* **Flutter SDK**：`>=3.10.0`
* **Dart SDK**：`>=3.0.0 <4.0.0`

在你的 `pubspec.yaml` 中添加 `doc_viewer`：

```yaml
dependencies:
  doc_viewer: ^0.0.2
```

### 🤖 Android 配置

1. **最低 SDK**：确保 `android/app/build.gradle` 中的 `minSdkVersion` 至少为 **24**。
2. **JitPack 仓库**：由于文档阅读器 SDK 托管在 JitPack，请确保已在工程的 `settings.gradle` 或根 `build.gradle` 中添加了 JitPack。

3. **Java resource 冲突**：Android Library 的 `packaging` 配置不会传递到最终 App。如果宿主依赖同时包含 Tika/Log4j 等库，请在 `android/app/build.gradle` 的 `android` 块中添加：

   ```groovy
   packagingOptions {
       resources {
           excludes += [
               "META-INF/DEPENDENCIES",
               "META-INF/INDEX.LIST",
               "META-INF/LICENSE",
               "META-INF/LICENSE.md",
               "META-INF/NOTICE",
               "META-INF/NOTICE.md",
           ]
       }
   }
   ```

### 🍎 iOS 配置

1. **最低 iOS 版本**：确保你的 iOS 部署目标在 `ios/Podfile` 中至少为 **iOS 13.4**：
   ```ruby
   platform :ios, '13.4'
   ```
2. **安装 Pods**：在 `ios` 目录下运行以下命令：
   ```bash
   pod install
   ```

*（注意：iOS 实现使用纯 Swift 库以及 Apple 内置框架，如 QuickLook 和 PDFKit。）*

---

## 🚀 使用方法

使用本插件极其简单，只需提供文档的绝对路径即可。

```dart
import 'package:flutter/material.dart';
import 'package:doc_viewer/doc_viewer.dart';

// ... 在你的 widget 类中

final _docViewerPlugin = DocViewer();

Future<void> openMyDocument(String filePath) async {
  try {
    // 插件会自动根据扩展名推断文档类型。
    final success = await _docViewerPlugin.openDocument(filePath);
    
    if (!success) {
      debugPrint("无法打开该文档。");
    }
  } catch (e) {
    debugPrint("打开文档时出错：$e");
  }
}

// 或者，你也可以显式指定文档类型：
// await _docViewerPlugin.openDocument(filePath, docType: DocType.pdf);
```

### 显式指定文档类型

如果你的文件没有扩展名，或你想强制使用特定的渲染引擎，可以显式传入 `DocType` 枚举：

```dart
await _docViewerPlugin.openDocument(
  '/path/to/file_without_extension', 
  docType: DocType.docx,
);
```

支持的 `DocType` 取值：`pdf`、`doc`、`docx`、`xls`、`xlsx`、`ppt`、`pptx`、`epub`、`cbz`、`txt`、`csv`、`rtf`、`odt`、`ods`、`odp`。

### 配置文档功能

默认情况下，插件会自动启用所有标准查看器功能（缩放、搜索、翻页导航等）。你可以通过传入 `DocumentFeatures` 对象来配置特定功能。

```dart
await _docViewerPlugin.openDocument(
  filePath,
  features: const DocumentFeatures(
    darkMode: true, // 启用原生深色模式渲染
    zoomInOut: true,
    search: true,
    // 注意：其他所有功能（如 textSelection、renderImages 等）
    // 默认均已启用。只需指定你想更改的项即可！
  ),
);
```

---

## 🏗 底层架构

为了保持代码库的可维护性与高性能，原生代码采用策略模式（Strategy Pattern）进行拆分：

* **Android**：`DocViewerPlugin` 负责分发。Office 文档（Word、Excel、PPT）被路由到 SDK 中专门的 `All_Document_Reader_Activity`。其他格式使用 `DocumentViewerActivity`，它作为宿主，将渲染工作分派给 `DocumentRenderer` 的各个具体的整合实现（例如 `PdfDocumentRenderer`、`EpubDocumentRenderer`）。通信通过 `RenderCallbacks` 接口处理。
* **iOS**：`DocViewerPlugin.swift` 将请求路由到各个专用的 `UIViewController` 子类（例如 `PDFViewerViewController`、`XLSXViewerViewController`、`EpubViewerViewController`）。

---

## 🤝 贡献与反馈

我们欢迎贡献与反馈！以下是你可以提供帮助的方式：

### 🐛 报告 Bug
如果你发现了 Bug，请[提交 issue](https://gitee.com/jimonik/doc_viewer.git/issues) 并附上：
* 对问题的清晰描述。
* 复现问题的步骤。
* 引发问题的文档格式（例如 PDF、DOCX）。
* 你的 Flutter 版本以及问题出现的平台（Android/iOS）。

### 💡 功能需求
我们始终欢迎功能需求！如果你希望看到某个特定的文档格式、UI 功能或性能改进：
* [提交 issue](https://gitee.com/jimonik/doc_viewer.git/issues) 阐述你的功能需求。
* 描述使用场景以及它为何会有帮助。

### 🛠️ 贡献代码
我们非常欢迎 Pull Request！如果你想直接为代码做贡献：
1. Fork 本仓库。
2. 为你的功能或修复创建一个新分支（`git checkout -b feature/my-new-feature`）。
3. 提交你的更改（`git commit -m 'Add some feature'`）。
4. 推送到该分支（`git push origin feature/my-new-feature`）。
5. 发起一个 Pull Request。

请确保你的代码遵循标准的 Flutter lint 规则。

---

## 📝 许可证

本项目基于 MIT 许可证授权——详见 LICENSE 文件。

*内部使用的开源库：*
* *[PdfiumAndroid](https://github.com/barteksc/AndroidPdfViewer)（Apache 2.0）*
* *[All Documents Reader](https://github.com/ahmadullahpk/all-documents-reader)*
* *[CoreXLSX](https://github.com/CoreOffice/CoreXLSX)（Apache 2.0）*
* *[ZIPFoundation](https://github.com/weichsel/ZIPFoundation)（MIT）*