/epub_viewer

A Flutter package for rendering Epub documents

Primary LanguageDartBSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

A Flutter package for viewing Epub documents, developed by combining the power of Epubjs and flutter_inappwebview

Features

  • Highlight text
  • Search in Epub
  • List chapters
  • Text selection
  • Highly customizable UI
  • Resume reading using cfi
  • Custom context menus for selection
  • Load from File, URl, Assets

Limitations

  • opf format not supported fully

Getting started

In your Flutter project add the dependency:

flutter pub add flutter_epub_viewer

Make sure to follow and complete each step

Usage

Basic usage

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

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});

  final String title;

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

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

  var textSelectionCfi = '';

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: SafeArea(
          child: Column(
        children: [
          Expanded(
            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) {},
              onEpubLoaded: () async {},
              onRelocated: (value) {},
              onTextSelected: (epubTextSelection) {},
            ),
          ),
        ],
      )),
    );
  }
}

Parameters and callbacks

//Epub controller to manage epub
final  EpubController  epubController;

///Epub source, accepts url, file or assets
///opf format is not tested, use with caution
final  String  epubSource;

///Epub headers to load epub from network
final  Map<String, String> headers;

///Initial cfi string to specify which part of epub to load initially
///if null, the first chapter will be loaded
final  String?  initialCfi;

///Call back when epub is loaded and displayed
final  VoidCallback?  onEpubLoaded;

///Call back when chapters are loaded
final  ValueChanged<List<EpubChapter>>?  onChaptersLoaded;

///Call back when epub page changes
final  ValueChanged<EpubLocation>?  onRelocated;

///Call back when text selection changes
final  ValueChanged<EpubTextSelection>?  onTextSelected;

///Callback for handling annotation click (Highlight and Underline)
final ValueChanged<String>? onAnnotationClicked;

///initial display settings
final  EpubDisplaySettings?  displaySettings;

///context menu for text selection
///if null, the default context menu will be used
final  ContextMenu?  selectionContextMenu;

Methods

///Move epub view to a specific area using Cfi string or chapter href
epubController.display(cfi:cfiString)

///moves to next page
epubController.next()

///Moves to the previous page in epub view
epubController.prev()

///Returns the current location of epub viewer
epubController.getCurrentLocation()

///Returns list of [EpubChapter] from epub,
/// should be called after onChaptersLoaded callback, otherwise returns empty list
epubController.getChapters()

///Search in epub using query string
///Returns a list of [EpubSearchResult]
epubController.search(query:query)

///Adds a highlight to epub viewer
epubController.addHighlight(
	cfi:cfiString,
	color:color
	opacity:0,5
)

///remove highlight
epubController.removeHighlight(cfi:cfi)

///Add underline annotation
epubController.addUnderline(cfi:cfi)

///Remove underline annotation
epubController.removeUnderline(cfi:cfi)

///Set [EpubSpread] value
epubController.setSpread(spread:spread)

///Set [EpubFlow] value
epubController.setFlow(flow:flow)

///Set [EpubManager] value
epubController.setManager(manager:manager)

///Adjust font size in epub viewer
epubController.setFontSize(fontSize:16)

///Extract text from a given cfi range
epubController.extractText(startCfi:cfi,endCfi:cfi)

///Extract text from current page
epubController.extractCurrentPageText()

 ///Given a percentage moves to the corresponding page
///Progress percentage should be between 0.0 and 1.0
epubController.toProgressPercentage(progressPercent)

Known Issues

  • onRelocated callback is broken when snap==true in epubDisplaySettings for android

Upcoming features

  • Annotations customization
  • More callbacks (rendered, error etc)
  • Night mode and Theme customization
  • Reading progress