office_viewer 0.0.8
office_viewer: ^0.0.8 copied to clipboard
Tile-based Flutter viewer for local documents. Host-owned chrome, fit-width pan and zoom, soft-fail on corrupt docs. PDF via office_viewer_engine_pdf; DOCX/XLSX/PPTX via in-repo office_viewer_engine_dart.
A Flutter package to view PDF, Word, Excel, and PowerPoint documents on Android and iOS.
Important
Install the core viewer plus engines from pub.dev: office_viewer, office_viewer_engine_pdf (PDF), and office_viewer_engine_dart (DOCX / XLSX / PPTX). Register PDF first, then Dart.
Example app on Android — PDF via pdfrx, Office via the pure Dart OOXML engine.
Features #
- Fit-width zoom with pinch / double-tap and pan clamp
- Part switching (pages, sheets, slides)
- Soft-fail on corrupt or password-protected docs (
OpenOptions(password:)) - Pluggable engines via
OfficeEngineRegistry(first match wins) - PDF via
office_viewer_engine_pdf(pdfrx / PDFium) - DOCX / XLSX / PPTX via
office_viewer_engine_dart(pure Dart OOXML, no native Office binaries)
Requirements #
| Flutter | >=3.47.0 |
| Dart | >=3.12.0 <4.0.0 |
| Platforms | Android and iOS only |
Android minSdk |
Flutter default (flutter.minSdkVersion, typically 21+) |
| iOS deployment target | 15.0+ (see example_app/) |
Support #
| Android | iOS | |
|---|---|---|
| ✓ | ✓ | |
| Word (DOCX) | ✓ | ✓ |
| Excel (XLSX) | ✓ | ✓ |
| PowerPoint (PPTX) | ✓ | ✓ |
| Pan / zoom / fit-width | ✓ | ✓ |
| Password-protected PDF | ✓ | ✓ |
| Password-protected OOXML | soft-fail | soft-fail |
Password-protected OOXML files surface PasswordRequiredError (no decrypt in the Dart engine yet). PDF passwords work via the PDF engine.
Limitations #
- Mobile only for now. Web, Windows, macOS, and Linux are not available yet.
- Other file types (older DOC / XLS / PPT, OpenDocument ODT / ODS / ODP, CSV / TXT) are not supported.
- Viewing only. Edit, search, print, and annotations are out of scope — your app owns chrome and those workflows.
- You open the file. Pass bytes or a local path after your own download / picker; cloud open is not built into the package.
- Large sheets. Huge workbooks can pressure mid-range phones; we clamp sheet extent and cull tiles — still tune heap use for extreme cases.
- Fidelity. Dart OOXML aims for typical decks/sheets/linear docs; complex floats, SmartArt, animations, and advanced effects are out of scope for v1.
Coming next #
- More platforms (Web first, then desktop)
- Broader file-type coverage and higher OOXML fidelity
- Password-protected OOXML decrypt (where license-safe)
Install #
flutter pub add office_viewer office_viewer_engine_pdf office_viewer_engine_dart
import 'dart:io';
import 'package:flutter/material.dart';
import 'package:office_viewer/office_viewer.dart';
import 'package:office_viewer_engine_dart/office_viewer_engine_dart.dart';
import 'package:office_viewer_engine_pdf/office_viewer_engine_pdf.dart';
Getting started #
Register engines once at startup. clear() drops any previous registrations so hot restart / tests start from a known empty registry. Always register PDF first, then Dart.
void main() {
WidgetsFlutterBinding.ensureInitialized();
OfficeEngineRegistry.instance
..clear()
..register(PdfOfficeEngine())
..register(DartOfficeEngine());
runApp(const MyApp());
}
Own an OfficeDocumentController in a State, load a file (path or bytes), handle passwords, and dispose the controller:
class DocumentViewerPage extends StatefulWidget {
const DocumentViewerPage({super.key, required this.path});
final String path; // from file_picker, cache download, etc.
@override
State<DocumentViewerPage> createState() => _DocumentViewerPageState();
}
class _DocumentViewerPageState extends State<DocumentViewerPage> {
late final OfficeDocumentController controller = OfficeDocumentController();
@override
void initState() {
super.initState();
controller.addListener(_onChanged);
_open();
}
void _onChanged() {
if (mounted) setState(() {});
}
Future<void> _open({String? password}) async {
// Prefer a real filename/path so format detection works.
await controller.load(
DocumentSource.file(widget.path),
options: OpenOptions(password: password),
);
// load() does not throw OfficeError — check controller.error / state.
if (controller.error is PasswordRequiredError) {
final pwd = await _askPassword(); // your dialog
if (pwd != null && pwd.isNotEmpty) {
await _open(password: pwd);
}
// Cancel → leave state as failed; show retry in your chrome if needed.
return;
}
}
Future<String?> _askPassword() async => null; // host UI
@override
void dispose() {
controller.removeListener(_onChanged);
controller.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
switch (controller.state) {
case OfficeLoadState.idle:
case OfficeLoadState.loading:
return const Center(child: CircularProgressIndicator());
case OfficeLoadState.failed:
return Center(
child: Text(controller.error?.message ?? 'Could not open file'),
);
case OfficeLoadState.ready:
return OfficeDocumentView(controller: controller);
}
}
}
Bytes work the same way when you already have the file in memory (keep the extension in fileName):
final bytes = await File(widget.path).readAsBytes();
await controller.load(
DocumentSource.bytes(bytes, fileName: 'report.docx'),
);
OfficeLoadState: idle → loading → ready or failed. On failure, read controller.error (PasswordRequiredError, CorruptDocumentError, UnsupportedFormatError, …).
Packages: office_viewer ·
office_viewer_engine_pdf ·
office_viewer_engine_dart
See the minimal PDF sample in example/ and the full Office host in example_app/. Issues: github.com/juzuli/office_viewer/issues.
Controller and view options #
Own OfficeDocumentController outside the view. Gesture locks and zoom bounds live on OfficeViewOptions:
final controller = OfficeDocumentController(
viewOptions: const OfficeViewOptions(
panEnabled: true,
zoomEnabled: true, // pinch / double-tap
minZoom: 1.0, // fit page width (+ padding)
maxZoom: 5.0,
),
);
final bytes = await File('/path/to/a.pdf').readAsBytes();
await controller.load(DocumentSource.bytes(bytes, fileName: 'a.pdf'));
// Runtime locks — host chrome can still call setZoom / goToPart:
controller.lockZoom(); // or lockPan(), setInteraction(panEnabled: false)
controller.setZoom(1.5);
OfficeDocumentView(controller: controller);
// Optional per-widget overrides:
// OfficeDocumentView(controller: c, zoomEnabled: false)
View options #
| Name | Description | Default |
|---|---|---|
panEnabled |
Allow pan gestures | true |
zoomEnabled |
Allow pinch / double-tap zoom | true |
minZoom |
Lower zoom bound (fit-width scale) | 1.0 |
maxZoom |
Upper zoom bound | 5.0 |
Controller helpers #
| Name | Description |
|---|---|
load |
Open a DocumentSource (optional OpenOptions); sets state / error |
dispose |
Release the open handle — call from your State.dispose |
setZoom / goToPart |
Programmatic zoom and part navigation |
lockZoom / lockPan / setInteraction |
Runtime gesture locks |
parts / currentPart / state / error |
Document metadata and load state |
Engines #
| Engine package | Formats | Notes |
|---|---|---|
office_viewer_engine_pdf |
PDFium via pdfrx. Register first. | |
office_viewer_engine_dart |
docx/xlsx/pptx | Pure Dart OOXML. MIT-clean. Register after PDF. |
Concepts #
- Part — a page, sheet, or slide.
PartInfo.sizeis in points. - Tile — a rectangle of one part rendered to RGBA at a given scale (
TileRequest). - Engine —
OfficeEngine.open()returns anOfficeDocumentHandlethat paints tiles. - Registry — first registered engine that supports a format wins. Register PDF first, then Dart. Call
clear()before registering so hot restart does not stack duplicate engines.
Migrating from 0.0.7 (LibreOfficeKit removed) #
office_viewer 0.0.8 drops the private LibreOfficeKit engine. Office files use office_viewer_engine_dart.
- Remove
office_viewer_engine_lokfrom your pubspec and stop registeringLokOfficeEngine. - Add
office_viewer_engine_dartand register PDF → Dart:
OfficeEngineRegistry.instance
..clear()
..register(PdfOfficeEngine())
..register(DartOfficeEngine());
- Delete references to removed API:
PartInfo.contentOriginPartInfo.lokPartIndexOfficeViewerLimits.lokLoadOptions
- Expect only DOCX / XLSX / PPTX / PDF. Older
.doc/.xls/.pptand OpenDocument are unsupported (soft-fail /UnsupportedFormatError).
See CHANGELOG.md 0.0.8 for the full notes.
License #
MIT — see LICENSE.
The packages (office_viewer, office_viewer_engine_pdf, and office_viewer_engine_dart) are MIT. Contributor setup: CONTRIBUTING.md.