字节笔记本

2026年2月23日

vocsy_epub_viewer:Flutter EPUB 电子书阅读器插件

本文介绍 vocsy_epub_viewer,一个功能强大的 Flutter EPUB 电子书阅读器插件。该插件封装了 FolioReader 框架,支持 iOS 和 Android 双平台,提供丰富的阅读功能和自定义选项。

项目简介

vocsy_epub_viewer 最初是 epub_kitty 的一个分支,由于原作者不活跃(不合并 PR 或不处理 issue),开发者创建了该项目并添加了更多功能。该插件在 GitHub 上持续维护,为 Flutter 开发者提供了完整的 EPUB 电子书阅读解决方案。

项目信息详情
最新版本3.0.0
发布时间17 个月前
许可证Apache-2.0
点赞数97
平台支持Android、iOS

核心特性

vocsy_epub_viewer 提供了丰富的阅读功能,以下是各平台支持情况:

功能AndroidiOS
阅读时间/剩余页数显示
最后阅读位置记录
沉浸式阅读模式
从资源加载 EPUB
复制和分享文本
文本高亮
多主题(浅色/深色)
多设备语言支持
更改字体样式
Android 13 支持

安装指南

前置要求

  • iOS 最低部署目标:9.0
  • 需要 Swift 支持

pubspec.yaml 配置

yaml
dependencies:
  vocsy_epub_viewer: ^3.0.0

Android 配置

android/app/build.gradle 的 release 构建类型中添加以下配置,避免发布版本崩溃:

gradle
buildTypes {
    release {
        minifyEnabled false
        shrinkResources false
    }
}

AndroidManifest.xml 中添加必要权限:

xml
<uses-permission android:name="android.permission.INTERNET" />

并在 application 标签中添加:

xml
<application
    xmlns:tools="http://schemas.android.com/tools"
    android:usesCleartextTraffic="true"
    android:requestLegacyExternalStorage="true"
    android:networkSecurityConfig="@xml/network_security_config"
    android:exported="true">

android/app/src/main/res/xml/ 目录下创建 network_security_config.xml 文件:

xml
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="true">
        <trust-anchors>
            <certificates src="system" />
        </trust-anchors>
    </base-config>
</network-security-config>

使用方法

基础配置

dart
import 'package:vocsy_epub_viewer/vocsy_epub_viewer.dart';

// 配置阅读器
VocsyEpub.setConfig(
  themeColor: Theme.of(context).primaryColor,
  identifier: "iosBook",
  scrollDirection: EpubScrollDirection.ALLDIRECTIONS,
  allowSharing: true,
  enableTts: true,
  nightMode: true,
);

打开 EPUB 文件

dart
// 从文件路径打开
VocsyEpub.open(
  'bookPath',
  lastLocation: EpubLocator.fromJson({
    "bookId": "2239",
    "href": "/OEBPS/ch06.xhtml",
    "created": 1539934158390,
    "locations": {
      "cfi": "epubcfi(/0!/4/4[simple_book]/2/2/6)"
    }
  }),
);

// 监听阅读位置
VocsyEpub.locatorStream.listen((locator) {
  print('LOCATOR: ${EpubLocator.fromJson(jsonDecode(locator))}');
  // 将 locator 保存到数据库,下次打开时恢复阅读进度
});

从资源加载

dart
await VocsyEpub.openAsset(
  'assets/book.epub',
  lastLocation: EpubLocator.fromJson({
    "bookId": "2239",
    "href": "/OEBPS/ch06.xhtml",
    "created": 1539934158390,
    "locations": {
      "cfi": "epubcfi(/0!/4/4[simple_book]/2/2/6)"
    }
  }),
);

依赖项

该插件依赖以下 Flutter 包:

  • flutter - Flutter SDK
  • path - 路径操作
  • path_provider - 获取设备存储路径

项目链接

注意事项

  1. iOS 平台部分功能受限(沉浸式阅读、多主题、字体样式更改)
  2. Android 13 已得到支持
  3. 建议在生产环境中禁用代码混淆以避免崩溃
  4. 需要正确配置网络权限和安全配置文件

总结

vocsy_epub_viewer 是一个成熟稳定的 Flutter EPUB 阅读器插件,适合需要在移动应用中集成电子书阅读功能的开发者。虽然 iOS 平台部分功能受限,但核心阅读功能在两个平台上都能良好运行。项目持续维护,社区活跃,是 Flutter 电子书阅读方案的优秀选择。

分享: