Flutter 프로젝트에서 EPUB 형식의 전자책 기능을 구현할 때 epub_viewer 패키지는 신뢰할 수 있는 선택지입니다. 이 라이브러리는 기존에 유지보수가 중단된 epub_kitty 프로젝트를 기반으로 포크되어 개발되었으며, iOS 와 Android 플랫폼 모두에서 균일한 렌더링 성능을 제공합니다. 내부적으로 Folioreader 엔진을 활용하여 독서 시간 추적, 이전 읽기 위치 복원, 집중 모드 등 다양한 편의 기능을 기본적으로 포함하고 있습니다.

패키지 의존성 설정

프로젝트에 뷰어 기능을 추가하려면 먼저 pubspec.yaml 설정 파일에 패키지를 등록해야 합니다./pub.dev 에서 최신 버전을 확인하여 다음과 같이 의존성을 기입합니다.

dependencies:
  flutter:
    sdk: flutter
  epub_viewer: ^3.0.0  # 실제 사용 시 최신 버전으로 변경

설정 파일을 저장한 후 터미널에서 flutter pub get 명령을 실행하여 패키지를 프로젝트에 설치합니다.

뷰어 위젯 구현

전자책 화면을 표시하는 위젯을 생성합니다. 아래 코드 예제는 EpubController 를 관리하며 자산 (asset) 경로에 있는 파일을 로드하는 구조로 작성되었습니다. 기존 예시와 변수 명칭 및 초기화 로직을 차별화하여 가독성을 높였습니다.

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

class EpubReaderScreen extends StatefulWidget {
  final String assetPath;

  const EpubReaderScreen({Key? key, required this.assetPath}) : super(key: key);

  @override
  State<EpubReaderScreen> createState() => _EpubReaderScreenState();
}

class _EpubReaderScreenState extends State<EpubReaderScreen> {
  late EpubController _readerController;

  @override
  void initState() {
    super.initState();
    _initializeController();
  }

  void _initializeController() {
    _readerController = EpubController(
      document: EpubDocument.openAsset(widget.assetPath),
      epubCfi: null, // 특정 페이지 이동이 필요할 경우 CFI 문자열 입력
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('EPUB 리더기'),
        elevation: 0,
      ),
      body: EpubViewer(
        controller: _readerController,
        onDocumentLoaded: () {
          debugPrint('EPUB 문서 로드 완료');
        },
      ),
    );
  }
}

코드를 실행하기 전에 assets 폴더에 실제 EPUB 파일을 배치하고, pubspec.yaml 의 flutter.assets 섹션에 해당 파일 경로를 명시해야 합니다.

사용자 경험 최적화

epub_viewer 가 제공하는 콜백 인터페이스를 활용하면 사용자 행동에 따라 UI 를 동적으로 변경할 수 있습니다. 예를 들어 페이지 전환 이벤트를 감지하여 진행률 바를 업데이트하거나, 시스템 테마 변경에 반응하여 다크 모드를 자동으로 적용할 수 있습니다. 텍스트 가독성을 높이기 위해 폰트 크기 조정 기능을 구현하거나, 커스텀 네비게이션 바를 추가하는 것도 권장되는 사례입니다.

주변 기술 스택 연계

단순 읽기 기능을 넘어 полноцен한 독서 앱을 구축하려면 상태 관리 및 데이터 저장 솔루션과 연동해야 합니다. Riverpod 또는 Provider 를 이용해 전역 읽기 상태를 관리하고, sqflite 나 hive 를 사용하여 사용자의 북마크와 진행 이력을 로컬에 영구 저장할 수 있습니다. 또한 책의 메타데이터나 소개 부분을 HTML 로 렌더링해야 한다면 flutter_html 패키지를 함께 사용하는 것이 효율적입니다.