Doc Viewer 🗂️ #

⚠️ 提示： 本插件目前处于 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，也无需庞大臃肿的框架。

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

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

🛠 环境配置与安装 #

环境要求：

• Flutter SDK：>=3.10.0
• Dart SDK：>=3.0.0 <4.0.0

在你的 pubspec.yaml 中添加 doc_viewer：

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 块中添加：

   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：

   platform :ios, '13.4'
   

2. 安装 Pods：在 ios 目录下运行以下命令：

   pod install
   

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

🚀 使用方法 #

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

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 枚举：

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 对象来配置特定功能。

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 并附上：

• 对问题的清晰描述。
• 复现问题的步骤。
• 引发问题的文档格式（例如 PDF、DOCX）。
• 你的 Flutter 版本以及问题出现的平台（Android/iOS）。

💡 功能需求 #

我们始终欢迎功能需求！如果你希望看到某个特定的文档格式、UI 功能或性能改进：

• 提交 issue 阐述你的功能需求。
• 描述使用场景以及它为何会有帮助。

🛠️ 贡献代码 #

我们非常欢迎 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（Apache 2.0）
• All Documents Reader
• CoreXLSX（Apache 2.0）
• ZIPFoundation（MIT）