Flutter Guides Compress

文档压缩优化

ComPDF Flutter SDK 自 3.2.0 起支持压缩优化 PDF，并将结果保存为副本。通过 CPDFDocument 配置优化项目、图像质量和分辨率，接收进度或取消任务。

以下示例中的 document 为已打开的 CPDFDocument。

import 'package:compdfkit_flutter/compdfkit.dart';

压缩并输出副本

优化完成后，SDK 会从源文件重新打开当前文档。需要保留的修改应在开始前保存。

final saved = await document.save();
if (!saved) {
  throw StateError('Save the document before optimization.');
}
final current = await document.getOptimizeOptions();
final options = current.copyWith(
  flags: {
    CPDFOptimizeFlag.removeUnusedObjects,
    CPDFOptimizeFlag.removeEmptyObjects,
    CPDFOptimizeFlag.compressImages,
    CPDFOptimizeFlag.optimizePageContent,
  },
  imageQuality: 60,
);
try {
  final result = await document.optimizeToFile(
    '/path/to/optimized.pdf',
    options: options,
    onProgress: (pageIndex) => print('Processing page $pageIndex'),
  );
  if (result.cancelled) {
    print('Optimization cancelled.');
  } else if (result.ok) {
    print('Processed ${result.pagesProcessed} pages.');
  }
} on CPDFOptimizeException catch (error) {
  print('${error.code}: ${error.message}');
}

outputPath 必须可写、父目录已存在，且与当前文档路径不同。成功后，当前阅读器仍显示源文档；主动打开输出文件以查看压缩结果。

配置优化选项

getOptimizeOptions() 返回原生文档当前选项的副本，修改该对象不会自动应用；需通过 optimizeToFile(options: ...) 传入。

参数	说明
flags	要执行的优化项目，例如清理无用对象、压缩图像、优化页面内容
imageQuality	全局图像质量，范围为 0～100
colorImageOptions	彩色图像的压缩与降采样设置
grayscaleImageOptions	灰度图像的压缩与降采样设置
monochromeImageOptions	单色图像的压缩与降采样设置
colorSpaceConvert	可选的 ICC 色彩空间转换设置

启用 CPDFOptimizeFlag.compressImages 后，可分别设置三类图像参数：

final imageOptions = options.copyWith(
  colorImageOptions: options.colorImageOptions.copyWith(
    upperPpi: 225,
    targetPpi: 150,
    quality: 60,
    compressAlgorithm: CPDFCompressAlgorithm.jpeg2000,
  ),
);

upperPpi 为触发降采样的分辨率阈值，targetPpi 为目标分辨率；quality 为该类图像的质量，范围为 0～100。imageOptions 可作为下一次优化的 options 传入。

默认优化项目包含删除全部书签和 JavaScript。需要保留这些内容时，显式指定 flags，如快速开始示例所示。删除注释、表单、嵌入字体等项目也应根据业务需要选择；压缩后的文件不保证一定小于源文件。

图像压缩算法

通过 CPDFOptimizeImageOptions.compressAlgorithm 为每类图像选择算法。blockSize 为编码器使用的块大小，必须大于 0；可沿用 getOptimizeOptions() 返回的配置。

CPDFCompressAlgorithm	用途
none	保留图像现有编码
flate	无损 Flate 压缩
runLength	无损游程编码
jpeg	有损 JPEG 压缩
jpeg2000	有损 JPEG 2000 压缩
jbig2	用于单色图像的 JBIG2 压缩

ICC 色彩空间转换

通过 CPDFColorSpaceConvertOptions 配置 RGB 与 CMYK 转换。iccData 接收 ICC 配置文件的原始字节，不是文件路径；未提供数据或数据为空时不执行转换。

import 'dart:io';

final iccData = await File('/path/to/profile.icc').readAsBytes();
final colorOptions = options.copyWith(
  colorSpaceConvert: CPDFColorSpaceConvertOptions(
    iccData: iccData,
    rgbToCmyk: true,
  ),
);
final result = await document.optimizeToFile(
  '/path/to/converted.pdf',
  options: colorOptions,
);

rgbToCmyk 为 true 时从 RGB 转为 CMYK，为 false 时从 CMYK 转为 RGB。选择与转换方向相符的 ICC 配置文件，并检查输出色彩效果。调用前仍需保存要保留的修改。

进度与取消

onProgress 返回从 0 开始的页面索引，不是百分比。应用可结合页数显示进度，但应等待方法返回后再判断任务完成。

await document.cancelOptimize();

取消为协作式操作。原优化调用结束时返回 cancelled == true、ok == false，应将其作为用户取消处理。

读取执行结果

CPDFOptimizeResult 包含以下结果：

字段	说明
ok	是否完成优化并成功输出
cancelled	是否因取消而结束
pagesProcessed	已处理的页面数
stepsUs	优化步骤耗时，单位为微秒
saveUs	输出文件耗时，单位为微秒

取消时不应将输出视为成功结果。耗时字段用于统计，不表示整体操作的全部耗时。

平台差异与异常

Android 每个文档同时允许一个优化任务；iOS 所有文档合计同时允许一个。冲突时抛出 OPTIMIZE_ALREADY_RUNNING。

optimizeToFile() 的 fontSubset 参数默认值为 false；Android 可启用字体子集，iOS 按原生保存方式输出。

输出路径或选项无效时，检查 INVALID_OUTPUT_PATH、INVALID_OPTIMIZE_OPTIONS。出现 OPTIMIZE_RESTORE_FAILED 表示当前文档未能从源文件恢复，应关闭并重新打开源文档，不要保存当前内存文档。