搜索插件、代码仓与 APP 分类

flutter_epub_viewer 封面
插件详情v2.2.1

flutter_epub_viewer

一个结合了 Epubjs 和 flutter_inappwebview 功能的 Flutter 包,用于查看 Epub 文档

AndroidiOS
近 30 天下载
3180
喜欢数
33
Pub 分数
160

安装插件

flutter pub add flutter_epub_viewer

插件介绍

基于插件公开信息、社区数据与项目使用情况整理的选型参考。

一个专为显示EPUB文档而设计的Flutter包,通过利用Epub.js和flutter_inappwebview实现。它能够在Flutter应用中无缝集成交互式、响应式的电子书阅读功能,支持文本选择、导航和样式设置。适用于需要离线或在线阅读书籍的教育、图书馆或内容丰富的应用程序。该包兼容Android和iOS平台。

适合场景

  • 在应用程序中阅读电子书
  • 教育内容传递
  • 离线文档查看
  • 库应用程序集成
  • 交互式教科书显示

主要特点

  • 支持 EPUB 格式
  • 使用 Epub.js 进行渲染
  • 与 flutter_inappwebview 集成
  • 响应式且交互式的用户界面
  • 文本选择和导航

适合对象

  • 电子学习应用程序
  • 数字图书馆工具
  • 内容发布商
  • 移动阅读应用程序
  • 需要离线 EPUB 支持的应用程序

使用建议

  • 初始WebView设置需要互联网
  • epub 渲染的自定义有限
  • 依赖外部网页视图性能
  • 在不同设备上可能存在布局不一致的情况
  • 不适用于非常大的 EPUB 文件

原始 README

以下为关联源码仓库的 README 原文快照,最新内容请访问源码仓库。

Flutter Epub Viewer

Pub Version License

A powerful Flutter package for viewing EPUB documents, built by combining the capabilities of Epub.js and flutter_inappwebview. This package provides a highly customizable and feature-rich EPUB reader for your Flutter applications.

Demo GIF

✨ Features

  • Text Highlighting: Highlight important text within the EPUB.
  • Search Functionality: Search for specific terms or phrases within the book.
  • Chapter Listing: Easy navigation through chapters.
  • Text Selection: Select text for copying or other actions.
  • Customizable UI: Tailor the look and feel to match your app's design.
  • Reading Progress: Resume reading from where you left off using CFI (Canonical Fragment Identifier).
  • Custom Context Menus: Define custom actions for text selection.
  • Versatile Loading: Load EPUBs from Files, URLs, or Assets.
  • Touch Interactions: Receive touch event callbacks with normalized coordinates (onTouchDown, onTouchUp).

🚀 Getting Started

Installation

Add the dependency to your pubspec.yaml file:

flutter pub add flutter_epub_viewer
Platform Setup
Android

Important: You must enable cleartext traffic for the viewer to function correctly on Android 8.0+.

Add android:usesCleartextTraffic="true" to your AndroidManifest.xml file in the <application> tag.

For more details, refer to this StackOverflow answer.

Also, ensure you complete the platform-wise setup for flutter_inappwebview as described here.

Web

Web is supported out of the box — no extra setup is required. Instead of a webview plugin, the viewer renders epub.js inside a native <iframe> and communicates with it through dart:js_interop, so all EpubController/EpubViewer APIs and callbacks behave the same as on mobile.

Notes for web:

  • Prefer EpubSource.fromData(Uint8List) or EpubSource.fromAsset(...). EpubSource.fromUrl(...) works only if the remote server sends permissive CORS headers; EpubSource.fromFile(...) is not available (there is no filesystem).
  • The epub <iframe> composites above the Flutter scene, so Flutter widgets placed over the viewer (a Drawer, dialog, or pushed route) may not receive taps. Keep interactive controls outside the viewer's rectangle (e.g. an AppBar or a side panel) — see the example app.
macOS

macOS uses the same flutter_inappwebview (WKWebView) rendering path as iOS, so all EpubController/EpubViewer APIs and callbacks behave the same as on mobile.

  • Requires a macOS deployment target of 10.13 or higher (a flutter_inappwebview requirement). Set platform :osx, '10.13' (or higher) in your app's macos/Podfile if it is currently lower.
  • Loading an EPUB from the network (EpubSource.fromUrl(...)) or writing highlights/annotations may require the App Sandbox network entitlement. Add com.apple.security.network.client to macos/Runner/*.entitlements if network loads fail.
  • Complete the macOS setup for flutter_inappwebview as described here.

⚠️ Migrating from 1.x to 2.0

  • The package no longer re-exports flutter_inappwebview's ContextMenu. Replace it with the package-owned EpubContextMenu / EpubContextMenuItem:

    selectionContextMenu: EpubContextMenu(
      hideDefaultSystemItems: true,
      items: [
        EpubContextMenuItem(id: 1, title: 'Highlight', action: () { /* ... */ }),
      ],
    ),
    
  • Request methods (getCurrentLocation, search, extractText, getRectFromCfi, …) now return their values directly and throw TimeoutException instead of hanging if the viewer never replies. Tune the wait via EpubController.requestTimeout.

See the CHANGELOG for the full list of changes.

📖 Usage

Basic Example

Here is a simple example of how to use EpubViewer in your application:

import 'package:flutter_epub_viewer/flutter_epub_viewer.dart';
import 'package:flutter/material.dart';

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key});

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  final epubController = EpubController();

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: SafeArea(
        child: EpubViewer(
          epubSource: EpubSource.fromUrl(
              'https://github.com/IDPF/epub3-samples/releases/download/20230704/accessible_epub_3.epub'),
          epubController: epubController,
          displaySettings:
              EpubDisplaySettings(flow: EpubFlow.paginated, snap: true),
          onChaptersLoaded: (chapters) {
            // Handle chapters loaded
          },
          onEpubLoaded: () async {
            // Handle epub loaded
          },
          onRelocated: (value) {
            // Handle page change
          },
          onTextSelected: (epubTextSelection) {
            // Handle text selection
          },
        ),
      ),
    );
  }
}
Parameters
Parameter Type Description
epubController EpubController Controller to manage EPUB actions and state.
epubSource EpubSource Source of the EPUB (URL, File, or Asset). Note: OPF format is not fully tested.
headers Map<String, String> HTTP headers for loading EPUBs from the network.
initialCfi String? Initial CFI string to specify the starting position. Defaults to the first chapter if null.
displaySettings EpubDisplaySettings? Initial display settings (flow, snap, etc.).
selectionContextMenu EpubContextMenu? Custom context menu for text selection (mobile). If null, the default menu is used. Ignored on web.
selectAnnotationRange bool If true, clicking an annotation automatically selects the text range. Defaults to false.
Callbacks
Callback Description
onEpubLoaded Called when the EPUB is successfully loaded and displayed.
onChaptersLoaded Called when the chapters are loaded. Returns a list of EpubChapter.
onRelocated Called when the EPUB page changes. Returns EpubLocation.
onTextSelected Called when text is selected. Returns EpubTextSelection.
onAnnotationClicked Called when an annotation (highlight/underline) is clicked. Provides CFI range and rect.
onTouchDown Called on touch down event. Provides normalized (x, y) coordinates.
onTouchUp Called on touch up event. Provides normalized (x, y) coordinates.
EpubController Methods

Use the EpubController to interact with the viewer programmatically:

// Navigation
epubController.display(cfi: cfiString); // Move to specific CFI or chapter href
epubController.next(); // Go to next page
epubController.prev(); // Go to previous page
epubController.toProgressPercentage(0.5); // Go to 50% progress
epubController.moveToFistPage(); // Go to first page
epubController.moveToLastPage(); // Go to last page

// Information
epubController.getCurrentLocation(); // Get current location info
epubController.getChapters(); // Get list of chapters
epubController.getMetadata(); // Get book metadata

// Search
epubController.search(query: "search term"); // Search in EPUB

// Annotations
epubController.addHighlight(cfi: cfiString, color: Colors.yellow); // Add highlight
epubController.removeHighlight(cfi: cfiString); // Remove highlight
epubController.addUnderline(cfi: cfiString); // Add underline
epubController.removeUnderline(cfi: cfiString); // Remove underline

// Custom Theme
EpubTheme.custom(
  customCss: {
    'p': {
      'font-family': 'Roboto, sans-serif',
      'font-size': '18px',
      'line-height': '1.5',
      'color': '#333333',
    },
    'h1': {
       'color': 'blue'
    },
    "a": {
      "color": "inherit !important",
      "-webkit-text-fill-color": "red !important"
    },
    "a:link": {
      "color": "inherit !important",
      "-webkit-text-fill-color": "red !important"
    },
  },
);

// Selection
epubController.clearSelection(); // Clear active selection
epubController.extractText(startCfi: start, endCfi: end); // Extract text from range
epubController.extractCurrentPageText(); // Extract text from current page

// Settings
epubController.setSpread(spread: EpubSpread.auto); // Set spread mode
epubController.setFlow(flow: EpubFlow.paginated); // Set flow mode
epubController.setManager(manager: EpubManager.defaultManager); // Set manager
epubController.setFontSize(fontSize: 16); // Adjust font size

⚠️ Limitations & Known Issues

  • OPF Support: The OPF format is not fully supported yet.
  • Android Animation: onRelocated callback may be broken when useSnapAnimationAndroid is set to true in EpubDisplaySettings on Android.
  • Scrolled Flow: Chapter navigation might break initially when using scrolled flow.

🔮 Upcoming Features

  • Advanced annotation customization.
  • Additional callbacks (e.g., rendered, error events).

🤝 Contributing

Contributions are welcome! We appreciate your help in making this package better.

  1. Fork the repository on GitHub.
  2. Clone your fork locally.
  3. Create a new branch for your feature or bug fix.
  4. Commit your changes with descriptive commit messages.
  5. Push your branch to your fork.
  6. Submit a Pull Request to the main repository.

Please ensure your code follows the existing style and includes relevant tests.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

❤️ Acknowledgments

👥 Contributors

Big thanks to all the contributors who have helped build this project!

所属分类

依赖

依赖清单 3 项

源码仓库

使用此插件的项目

暂无相关数据。