Flutter Guides Create digital signatures

创建数字签名

ComPDF Flutter SDK 自 3.2.0 起支持使用证书签署 PDF 签名域。数字签名记录文档完整性和签署者信息；图片签名仅写入签名图像。

准备证书路径、证书密码和可写的输出路径，打开目标 PDF 后执行下列操作。以下示例中的 document 为当前 CPDFDocument。

import 'package:compdfkit_flutter/compdfkit.dart';
import 'package:compdfkit_flutter/annotation/form/cpdf_signature_widget.dart';

获取未签署的签名域

final widgets = await document.pageAtIndex(0).getWidgets();
final unsignedFields = widgets
    .whereType<CPDFSignatureWidget>()
    .where((field) => !field.isSigned)
    .toList();

isSigned 表示签名域是否已包含数字签名。文档没有签名域时，先按创建表单域添加签名域，再重新读取。

传入签署接口的对象必须属于当前文档，并具有有效的原生 uuid。可使用 getWidgets() 或阅读器回调返回的签名域，不能仅创建一个 Dart 对象后直接签署。

签署并输出副本

if (unsignedFields.isNotEmpty) {
  final success = await document.writeSignature(
    unsignedFields.first,
    '/path/to/signed.pdf',
    CPDFDigitalSignatureConfig(
      certificatePath: certificatePath,
      password: certificatePassword,
      reason: 'Approved',
      location: 'Office',
      permissions: CPDFSignaturePermission.fillAndSign,
      appearance: const CPDFDigitalSignatureAppearance(
        text: 'Signed by Document Signer',
        content: 'Approved',
        drawLogo: false,
      ),
    ),
  );
  if (success) {
    await document.open('/path/to/signed.pdf');
  }
}

签名写入新文件，输出路径应与源文件不同，且父目录已存在。成功后主动打开输出文件查看或验证签名。

配置签名

配置	用途
certificatePath、password	PKCS#12 证书及密码
name、reason、location	签署者名称、签署原因和地点
permissions	签名对应的文档修改权限
appearance	签名文字、颜色、图像和排版
timestampServerUrl	签名时间戳服务，参见时间戳与长期验证

CPDFSignaturePermission 定义签署后允许的文档修改范围：

值	说明
forbidChange	禁止修改文档
fillAndSign	允许填写表单和签署
annotationFillAndSign	允许注释、填写表单和签署

permissions 默认值为 fillAndSign。它描述签名对应的修改权限，不等同于文档打开密码或加密权限。

签名外观可以设置 text、content、textColor、contentColor、imagePath、logoPath、drawLogo、drawOnlyContent 和 contentAlignLeft。图像参数使用本地图片路径。

参数无效时可能抛出 ArgumentError；原生签署失败可能返回 false 或抛出平台异常。应用应在确认成功后再打开输出文件。签署后验证结果，参见读取与验证数字签名。