pdf_viewer_plus 2.0.0

A PDF viewer with enhanced features including a thumbnail sidebar for easy navigation.

Changelog

2.0.0 – New rendering engine (pdfx → pdfrx) – July 2026

• Engine swap: the package now renders through pdfrx (PDFium-based, actively maintained) instead of pdfx. Motivations:
  • pdfx's PdfViewPinch shows blank pages while rasterising (hard-coded white placeholder, tiny 400px pre-render buffer, no "page ready" signal) — very visible on heavy scanned PDFs — and mispositions when opening directly on a mid-document page.
  • pdfx has no Swift Package Manager support (Flutter build warning, will become an error) and had no release for over a year.
  • pdfrx provides page preloading (verticalCacheExtent), progressive rendering (low-res first, then sharp), a first-class initialPageNumber, and SPM support.
• Public API unchanged: PdfViewer (pdfPath/pdfData, initialPage, thumbnail sidebar, pinch & double-tap zoom, zoom hint, page indicator, keyboard navigation, semantics) and PdfFlowView keep their exact signatures.
• Internal: thumbnails and flow pages are now rendered to ui.Image (displayed via RawImage) instead of encoded bytes; documents use dispose(); page sizes are read synchronously from document.pages.
• New: PdfViewer.panAxis — constrains panning (e.g. PanAxis.aligned locks each gesture to its dominant axis, so vertical scrolling stays perfectly vertical while horizontal panning remains available when zoomed). Defaults to PanAxis.free (unchanged behaviour).
• New: PdfViewer.backgroundColor — color shown behind and between the pages. Defaults to Colors.grey (unchanged behaviour).
• New: PdfViewer.onScroll — reports the viewer's vertical scroll offset (in view pixels, 0 = top of the document), e.g. to collapse/expand surrounding chrome while the user reads. Defaults to null (no callback).
• New: onError and errorBuilder on both PdfViewer and PdfFlowView. onError is called when the document fails to load or parse — for every failure path, including a corrupt or encrypted PDF that fails inside the renderer (pdfrx's errorBannerBuilder is now funnelled into the same state). The default on-screen error is now a visible message (icon + text, announced to screen readers) instead of a bare icon; errorBuilder lets you replace it entirely.
• Fix: the thumbnail sidebar crashed (ScrollController not attached) when the current page changed while the sidebar was closed, blanking the viewer frame (guarded with hasClients).
• Fix: opening PdfViewer directly on a page other than the first (initialPage != 1) previously left that page blank until the user scrolled (a pdfx limitation). pdfrx opens straight on the target page via initialPageNumber, so it renders immediately — no blank frame and no visible scroll from page 1.
• Fix: the closed sidebar (translated off-screen to the left) was painted outside the viewer's bounds, bleeding onto neighbouring widgets — most visible during a page pop/push transition. The viewer content is now clipped to its own bounds (ClipRect).

Also new: reading-flow view (PdfFlowView)

• New public widget PdfFlowView — a "reading flow" mode that lays out every page as a vertical column of images, sized to the height of its content and without any internal scrolling of its own. Drop it inside a scrolling parent (e.g. a CustomScrollView via SliverToBoxAdapter, or a ListView) and the parent handles all scrolling — the widget never steals the gesture. It is the PDF counterpart of a content-sized WebView with internal scrolling disabled.
  • Reads each page's dimensions without rendering, so slots are laid out at the correct aspect ratio before anything is decoded.
  • Lazy, memory-bounded rendering: each page decodes only when it becomes (close to) visible in the parent viewport and releases its image once it scrolls far enough off screen. Visibility is derived natively from the nearest ancestor Scrollable — no extra dependency.
  • Pages fit the available width, respect the page ratio, and are rendered at devicePixelRatio for sharpness.
  • Parameters: pdfData / pdfPath (exactly one), pageSpacing, padding, backgroundColor, onPageTap (1-indexed — e.g. to open the interactive zoom viewer), pagePlaceholderBuilder (per-page skeleton), and cacheExtent.
• Page open / size / render logic is now shared via PdfUtils.

1.0.3 – Accessibility & Navigation – March 2026

• Accessibility (screen reader support):
  • New PdfSemanticLabels class — fully customisable labels for VoiceOver / TalkBack, exported as part of the public API
  • All loading, error, and navigation states are announced by screen readers
  • Page change announcements via SemanticsService ("Page X of Y")
  • Sidebar toggle button: Semantics(button, toggled) + Tooltip + focus management
  • Thumbnails: each item labelled as a button with its page number and selected state
  • Zoom hint overlay announced as a live region
  • Zoom hint hidden when MediaQuery.disableAnimations is active
  • Keyboard navigation: ← / → arrow keys to change page
  • Focus returns to the toggle button when the sidebar is closed, and moves into the sidebar when it is opened
  • Error state announced as a live region
• New parameters on PdfViewer:
  • initialPage — open the document at a specific page (defaults to 1)
  • onPageChanged — callback fired on every page change
  • showPageIndicator — shows a "current / total" overlay at the bottom of the viewer (defaults to true)
• Double-tap to zoom: double-tap anywhere on the document to zoom in (2.5×) centred on the tap position; double-tap again to reset. Animated with a 250 ms ease-in-out curve.

1.0.2 – Accessibility & Dependency Updates – January 2026

• New features:
  • Added pinch animation overlay for improved accessibility and user guidance
  • Visual hint to help users discover zoom functionality
• Updated Dart SDK requirement from ^3.7.0 → ^3.10.0
• Dependency upgrades:
  • http: from ^1.4.0 → ^1.6.0
  • flutter_lints: from ^5.0.0 → ^6.0.0 (dev dependency)
  • Added lottie: ^3.1.0 for animation support
• Android improvements:
  • Updated Kotlin from 1.8.22 → 2.1.0 (resolves Flutter compatibility warnings)

1.0.1 – Dependency Updates & Metadata Fix – June 2025

• Updated repository URL in pubspec.yaml to correct GitHub link.
• Dependency upgrades:
  • pdfx: from ^2.8.0 → ^2.9.2
  • http: from ^1.3.0 → ^1.4.0
  • flutter_lints: from ^5.0.0 → ^6.0.0 (dev dependency)

1.0.0 Initial Release - June 2025

• First release of the PDF Thumbnail Sidebar package
• Features:
  • PDF viewer with integrated thumbnail sidebar
  • Support for both online PDFs (URLs) and local assets
  • Collapsible sidebar with smooth animations
  • Custom styling options for thumbnails and sidebar
  • Synchronized navigation between viewer and thumbnails
• Dependencies:
  • pdfx for PDF rendering
  • http for downloading remote PDFs