Guides

图片提取

ComPDF Flutter SDK 提供图片提取接口，用于从 PDF 文档中导出嵌入图片。你可以提取整个文档中的图片，也可以只提取指定页面范围内的图片。

API 概览

图片提取接口位于 CPDFDocument：

Future<CPDFExtractImageResult> extractImages({
  required String directoryPath,
  List<int>? pages,
});

参数说明：

参数	说明
directoryPath	图片输出目录。SDK 会直接将图片写入该目录；如果目录不存在，会尝试创建目录
pages	可选页面索引列表，从 0 开始。传入 null 或空数组时，表示提取全部页面图片

返回值为 CPDFExtractImageResult：

class CPDFExtractImageResult {
  final bool success;
  final int count;
  final String directoryPath;
  final List<String> imagePaths;
}

字段说明：

字段	说明
success	原生图片提取调用是否成功完成
count	提取完成后在 directoryPath 中扫描到的图片文件数量
directoryPath	图片输出目录，即调用时传入的目录路径
imagePaths	提取完成后在 directoryPath 中扫描到的图片文件完整路径列表

输出目录语义

directoryPath 表示调用方指定的实际输出目录。SDK 不会在该目录下自动创建额外子目录，也不会清空目录。

如果你希望 imagePaths 只包含本次提取生成的图片，请在调用前传入一个新的空目录，或由你的业务代码自行清理目录。

final Directory tempDir = await ComPDFKit.getTemporaryDirectory();
final Directory outputDir = Directory(
  '${tempDir.path}/extracted_images_${DateTime.now().millisecondsSinceEpoch}',
);

await outputDir.create(recursive: true);

如果复用已有目录，返回的 imagePaths 可能包含目录中已存在的图片文件。

提取全部页面图片

不传 pages 时，SDK 会尝试提取文档中全部页面的图片。

import 'dart:io';

import 'package:compdfkit_flutter/compdfkit.dart';
import 'package:compdfkit_flutter/document/cpdf_document.dart';

Future<void> extractAllImages(String filePath) async {
  final CPDFDocument document = await CPDFDocument.createInstance();
  await document.open(filePath);

  final Directory tempDir = await ComPDFKit.getTemporaryDirectory();
  final Directory outputDir = Directory(
    '${tempDir.path}/extracted_images_${DateTime.now().millisecondsSinceEpoch}',
  );
  await outputDir.create(recursive: true);

  final CPDFExtractImageResult result = await document.extractImages(
    directoryPath: outputDir.path,
  );

  if (result.success) {
    print('Image count: ${result.count}');
    for (final String imagePath in result.imagePaths) {
      print('Image path: $imagePath');
    }
  } else {
    print('Extract images failed.');
  }
}

提取指定页面图片

通过 pages 参数可以只提取指定页面的图片。页面索引从 0 开始。

final CPDFExtractImageResult result = await document.extractImages(
  directoryPath: outputDir.path,
  pages: [0, 2],
);

print('Extracted image count: ${result.count}');

上面示例会提取第 1 页和第 3 页中的图片。

如果传入无效页面索引，例如负数或大于等于页数的索引，接口会返回平台错误。

在 CPDFReaderWidget 中使用

在阅读器页面中，可以通过 CPDFReaderWidgetController.document 调用相同接口。

Future<void> extractImagesFromReader(
  CPDFReaderWidgetController controller,
) async {
  final Directory tempDir = await ComPDFKit.getTemporaryDirectory();
  final Directory outputDir = Directory(
    '${tempDir.path}/reader_extracted_images_${DateTime.now().millisecondsSinceEpoch}',
  );
  await outputDir.create(recursive: true);

  final CPDFExtractImageResult result =
      await controller.document.extractImages(
    directoryPath: outputDir.path,
  );

  print('Output directory: ${result.directoryPath}');
  print('Image count: ${result.count}');
}

这个方式适用于在自定义阅读器工具栏、菜单或页面操作中提供图片提取能力。

展示提取后的图片

imagePaths 返回的是本地图片文件路径，可以直接使用 Flutter 的 Image.file 展示。

GridView.builder(
  itemCount: result.imagePaths.length,
  gridDelegate: const SliverGridDelegateWithMaxCrossAxisExtent(
    maxCrossAxisExtent: 148,
    mainAxisSpacing: 10,
    crossAxisSpacing: 10,
  ),
  itemBuilder: (context, index) {
    return Image.file(
      File(result.imagePaths[index]),
      fit: BoxFit.contain,
      cacheWidth: 320,
    );
  },
)

如果需要查看大图，可以结合 InteractiveViewer 实现缩放预览。

完整示例

下面示例演示如何打开 PDF，创建独立输出目录，提取图片，并打印提取结果。

import 'dart:io';

import 'package:compdfkit_flutter/compdfkit.dart';
import 'package:compdfkit_flutter/document/cpdf_document.dart';

Future<List<String>> extractPdfImages(String filePath) async {
  final CPDFDocument document = await CPDFDocument.createInstance();
  await document.open(filePath);

  final Directory tempDir = await ComPDFKit.getTemporaryDirectory();
  final Directory outputDir = Directory(
    '${tempDir.path}/extract_images_${DateTime.now().millisecondsSinceEpoch}',
  );
  await outputDir.create(recursive: true);

  final CPDFExtractImageResult result = await document.extractImages(
    directoryPath: outputDir.path,
  );

  if (!result.success) {
    throw Exception('Extract images failed.');
  }

  print('Output directory: ${result.directoryPath}');
  print('Image count: ${result.count}');

  return result.imagePaths;
}

注意事项

• directoryPath 必须是本地可写目录路径，不是单个图片文件路径。
• SDK 会直接使用 directoryPath，不会自动创建额外子目录，也不会清空目录。
• 如果需要只获取本次提取结果，请传入新的空目录。
• pages 使用从 0 开始的页面索引。
• PDF 中没有嵌入图片时，可能返回 success == true、count == 0、imagePaths.isEmpty == true。
• 图片格式由 PDF 内部图片数据和原生 SDK 决定，可能是 JPEG、PNG 或其他支持格式。
• Android 与 iOS 的原生返回值不同，Flutter API 使用 CPDFExtractImageResult 统一结果结构。