Guides

页面缩略图

ComPDF Flutter SDK 支持将 PDF 页面渲染为缩略图，适用于页面预览、缩略图导航、文档目录、页面选择器以及自定义 PDF 管理界面等场景。

两种接入方式：

• 使用 CPDFPageThumbnailProvider 作为 Flutter Image 组件的图片来源。
• 使用 CPDFPageThumbnail 快速构建带占位图和错误图的缩略图 Widget。

如果应用已经打开了 PDF 文档，建议基于现有 CPDFDocument 渲染缩略图，避免重复打开文件。

快速开始

以下示例将一个已打开文档的第一页渲染为缩略图：

final CPDFDocument document = await CPDFDocument.createInstance();
await document.open('/path/to/sample.pdf');

CPDFPageThumbnail.document(
  document: document,
  pageIndex: 0,
  options: const CPDFPageThumbnailOptions(width: 240),
)

API 概览

类	用途
CPDFPageThumbnailProvider	作为 ImageProvider 传入 Flutter Image 组件
CPDFPageThumbnail	快速缩略图 Widget，自带占位图和错误处理
CPDFPageThumbnailOptions	渲染参数：尺寸、背景、图片格式、缓存策略
CPDFPageThumbnailService	缓存管理与页面度量
CPDFPageThumbnailCachePolicy	缓存策略：内存、磁盘、两者、或禁用

使用 CPDFPageThumbnailProvider

CPDFPageThumbnailProvider 是一个 ImageProvider，直接传入 Flutter 的 Image 组件。

import 'package:compdfkit_flutter/compdfkit.dart';
import 'package:flutter/material.dart';

class ThumbnailView extends StatelessWidget {
  const ThumbnailView({
    super.key,
    required this.document,
    required this.pageIndex,
  });

  final CPDFDocument document;
  final int pageIndex;

  @override
  Widget build(BuildContext context) {
    return Image(
      image: CPDFPageThumbnailProvider.document(
        document: document,
        pageIndex: pageIndex,
        options: const CPDFPageThumbnailOptions(
          width: 300,
          compression: CPDFPageCompression.jpeg,
        ),
      ),
      fit: BoxFit.contain,
      errorBuilder: (context, error, stackTrace) {
        return const Icon(Icons.broken_image_outlined);
      },
    );
  }
}

使用 CPDFPageThumbnail

CPDFPageThumbnail 封装了 CPDFPageThumbnailProvider，内置占位和错误状态处理。

CPDFPageThumbnail.document(
  document: document,
  pageIndex: 0,
  options: const CPDFPageThumbnailOptions(width: 300),
  fit: BoxFit.contain,
  placeholderBuilder: (context) {
    return const Center(child: CircularProgressIndicator());
  },
  errorBuilder: (context, error, stackTrace) {
    return const Icon(Icons.broken_image_outlined);
  },
)

从文件路径生成缩略图

如果没有 CPDFDocument 实例，也可以从本地 PDF 文件路径创建缩略图。

Image(
  image: CPDFPageThumbnailProvider.file(
    filePath: '/path/to/sample.pdf',
    pageIndex: 0,
    password: '',
    options: const CPDFPageThumbnailOptions(width: 240),
  ),
)

当应用中已打开文档时，建议优先使用 document 来源。

渲染选项

通过 CPDFPageThumbnailOptions 控制缩略图尺寸、背景、图片格式和缓存策略。

const options = CPDFPageThumbnailOptions(
  width: 600,
  backgroundColor: Colors.white,
  drawAnnot: true,
  drawForm: true,
  compression: CPDFPageCompression.jpeg,
  jpegQuality: 85,
  cachePolicy: CPDFPageThumbnailCachePolicy.memoryAndDisk,
);

参数	说明
width / height	缩略图目标尺寸，单位为像素。只设置一个值时，另一个值按页面比例计算
scale	未设置 width 和 height 时，按页面原始尺寸缩放
backgroundColor	页面背景色
drawAnnot	是否在缩略图中绘制注释
drawForm	是否在缩略图中绘制表单控件
compression	图片格式，支持 png 和 jpeg
jpegQuality	JPEG 图片质量，范围为 1-100
cachePolicy	缩略图缓存策略
diskCacheTtl	磁盘缓存有效期
maxPixelCount	单张缩略图允许的最大像素数

在缩略图列表中，建议设置明确的 width 或 height，避免渲染尺寸过大。

缓存机制

缩略图默认启用缓存，以减少重复渲染并提升列表滑动体验。

缓存策略

策略	说明
memoryOnly	仅使用内存缓存
memoryAndDisk	默认策略，同时使用内存和磁盘缓存
diskOnly	仅使用磁盘缓存
noCache	不使用 SDK 缓存

缓存标识

缓存键根据文档来源、页面索引、页面旋转角度、渲染尺寸、背景色、注释/表单开关、图片格式等信息生成。页面旋转或渲染参数变化时，会自动使用新的缓存条目。

缓存目录

磁盘缓存存放在 ComPDFKit.getTemporaryDirectory() 下的专用目录中：

<temporaryDirectory>/compdfkit_page_thumbnails/

缓存文件名经过 hash 处理，不保留页面索引或原始扩展名。缓存内容不会被加密。

清理缓存

await CPDFPageThumbnailService.shared.clearCache();

文档更新后的刷新

如果文档内容发生变更且文件修改时间无法反映该变化（例如内存中编辑尚未保存），通过 cacheVersion 强制刷新缩略图：

var cacheVersion = 0;

final provider = CPDFPageThumbnailProvider.document(
  document: document,
  pageIndex: pageIndex,
  cacheVersion: cacheVersion,
);

// 文档内容变化后，递增版本号。
cacheVersion++;

页面旋转发生变化时，缓存会自动区分不同旋转角度。

错误处理

缩略图加载可能因文件路径无效、密码错误、页面索引无效或渲染失败而失败。建议始终提供错误占位。

Image(
  image: CPDFPageThumbnailProvider.document(
    document: document,
    pageIndex: pageIndex,
  ),
  errorBuilder: (context, error, stackTrace) {
    return const Icon(Icons.broken_image_outlined);
  },
)

CPDFPageThumbnail 也支持 errorBuilder：

CPDFPageThumbnail.document(
  document: document,
  pageIndex: pageIndex,
  errorBuilder: (context, error, stackTrace) {
    return const Text('Thumbnail failed');
  },
)

使用建议

• 已打开文档时，优先使用 CPDFPageThumbnailProvider.document 或 CPDFPageThumbnail.document。
• 在已有 CPDFReaderWidgetController 的页面中，使用 controller.document 作为文档来源。
• 缩略图列表中设置固定宽度或高度。
• 长列表建议保留默认缓存策略，减少重复渲染。
• 文档内存编辑后缩略图未刷新时，更新 cacheVersion。
• 始终配置 errorBuilder，保证加载失败时界面有明确反馈。