Guides

注释

ComPDF Flutter SDK 支持多种注释事件监听，帮助您在 Flutter 应用中自定义注释交互行为。

事件概览

事件名称	触发时机	返回值
onAnnotationCreationPreparedCallback	准备创建签名、图章、超链接、图片注释时	注释类型
onInterceptAnnotationActionCallback	点击便签、超链接注释时	CPDFAnnotation对象
annotationsCreated	创建注释时	创建的注释数据
annotationsSelected	选中注释时	选中的注释数据
annotationsDeselected	取消选中注释时	取消选中的注释数据

注释创建准备回调

回调方法：onAnnotationCreationPreparedCallback

当用户点击底部工具栏的签名、图章、超链接、图片工具，或调用 controller.setAnnotationMode() 进入创建模式时触发此回调。

通过此回调，您可以在 Flutter 应用中弹出自定义选择框，替代 ComPDF 内置的选择弹窗。

配置

使用此功能需要在 CPDFConfiguration 中禁用默认选择对话框：

CPDFConfiguration(
  annotationsConfig: const CPDFAnnotationsConfig(
    autoShowSignPicker: false,   // 禁用签名选择对话框
    autoShowLinkDialog: false,   // 禁用超链接选择对话框
    autoShowPicPicker: false,    // 禁用图片选择对话框
    autoShowStampPicker: false,  // 禁用图章选择对话框
  ),
);

监听回调

CPDFReaderWidget(
  document: documentPath,
  configuration: configuration,
  onCreated: (controller) {},
  onAnnotationCreationPreparedCallback: (CPDFAnnotationType annotationType, CPDFAnnotation? annotation) {
    // 签名、图章、图片注释：进入创建模式时触发
    // 超链接注释：用户在页面中滑取矩形抬起手指后触发
    debugPrint('Preparing to create annotation of type: $annotationType');
    // 在此处弹出自定义选择框
  },
);

插入签名

选择签名图片后，调用以下 API 插入签名注释：

await controller?.prepareNextSignature(signImagePath);

插入图章

选择图章后，根据图章类型调用对应 API：

// 标准图章（查看 CPDFStandardStamp 枚举获取可用类型）
await controller?.prepareNextStamp(standardStamp: stamp);

// 图片图章
await controller?.prepareNextStamp(imagePath: imagePath);

// 文字图章
await controller?.prepareNextStamp(
  textStamp: CPDFTextStamp(
    content: 'ComPDF-Flutter',
    date: CPDFDate.getTextStampDate(timeSwitch: false, dateSwitch: true),
    shape: CPDFTextStampShape.none,
    color: CPDFTextStampColor.white,
  ),
);

注释点击拦截回调

回调方法：onInterceptAnnotationActionCallback

当用户点击便签或超链接注释时触发此回调，返回 CPDFAnnotation 对象。通过此回调，您可以在 Flutter 层拦截默认的点击行为，实现自定义交互逻辑。

配置

使用此功能需要在 CPDFConfiguration 中禁用默认的注释点击行为：

CPDFConfiguration(
  annotationsConfig: const CPDFAnnotationsConfig(
    interceptNoteAction: true,  // 拦截便签默认行为事件
    interceptLinkAction: true,  // 拦截超链接默认行为事件
  ),
);

监听回调

CPDFReaderWidget(
  document: documentPath,
  configuration: configuration,
  onCreated: (controller) {},
  onInterceptAnnotationActionCallback: (CPDFAnnotation annotation) {
    debugPrint('Intercepted annotation action: ${annotation.type}');
    // 根据注释类型自定义点击行为
    if (annotation is CPDFNoteAnnotation) {
      // 自定义便签点击处理
    } else if (annotation is CPDFLinkAnnotation) {
      // 自定义超链接点击处理
    }
  },
);

注释创建事件

事件名称：CPDFEvent.annotationsCreated

当用户创建注释时触发，通过 CPDFReaderWidgetController.addEventListener() 监听：

controller.addEventListener(CPDFEvent.annotationsCreated, (event) {
  // event 为 CPDFAnnotation 对象或其子类对象
  print(jsonEncode(event));
});

注释选中事件

事件名称：CPDFEvent.annotationsSelected

当用户选中注释时触发：

controller.addEventListener(CPDFEvent.annotationsSelected, (event) {
  // event 为 CPDFAnnotation 对象或其子类对象
  print(jsonEncode(event));
});

注释取消选中事件

事件名称：CPDFEvent.annotationsDeselected

当用户取消选中注释时触发：

controller.addEventListener(CPDFEvent.annotationsDeselected, (event) {
  // event 为 CPDFAnnotation 对象或其子类对象，可能为空
  print(jsonEncode(event));
});