Guides

注释

ComPDF Flutter SDK 支持注释相关回调和监听事件，用于处理注释创建、属性编辑、点击拦截、选中状态和 iOS Pencil 绘制。

可用回调和事件

类型	名称	触发时机	返回值
阅读器回调	onAnnotationCreationPreparedCallback	准备创建签名、图章、超链接、图片或 Note 注释	CPDFAnnotationType annotationType, CPDFAnnotation? annotation
阅读器回调	onAnnotationStyleDialogDismissedCallback	注释属性弹窗关闭	CPDFAnnotationType type
阅读器回调	onInterceptAnnotationActionCallback	开启拦截后点击已有 Note 或 Link 注释	CPDFAnnotation annotation
监听事件	CPDFEvent.annotationsCreated	注释创建	CPDFAnnotation
监听事件	CPDFEvent.annotationsSelected	注释被选中	CPDFAnnotation
监听事件	CPDFEvent.annotationsDeselected	注释取消选中	CPDFAnnotation?
监听事件	CPDFEvent.pencilDrawingCompleted	iOS Pencil 绘制完成	包含 type 和 pageIndex 的 Map<String, dynamic>
监听事件	CPDFEvent.pencilDrawingDiscarded	iOS Pencil 绘制被放弃	包含 type 和 pageIndex 的 Map<String, dynamic>

注释创建准备回调

当用户点击签名、图章、超链接或图片工具，或调用 controller.setAnnotationMode() 进入创建模式时，会触发 onAnnotationCreationPreparedCallback。关闭 autoShowNoteEditDialog 后，自定义 Note 创建流程也会使用该回调。

如需替换默认选择弹窗，请在 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('准备创建注释： $annotationType');
  },
);

插入签名和图章

await controller?.prepareNextSignature(signImagePath);

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,
  ),
);

注释属性弹窗关闭回调

CPDFReaderWidget(
  document: documentPath,
  configuration: configuration,
  onAnnotationStyleDialogDismissedCallback: (CPDFAnnotationType type) {
    debugPrint('注释属性弹窗已关闭： ${type.name}');
  },
);

注释点击拦截回调

开启 interceptNoteAction 或 interceptLinkAction 后，SDK 会把点击到的 Note 或 Link 注释发送到 Flutter，而不是执行默认的原生行为。你可以用它展示自定义 Note 编辑器、自行处理网页链接，或替换页面跳转逻辑。

监听 onInterceptAnnotationActionCallback 前，请先开启拦截：

CPDFConfiguration(
  annotationsConfig: const CPDFAnnotationsConfig(
    interceptNoteAction: true,
    interceptLinkAction: true,
  ),
);

CPDFReaderWidget(
  document: documentPath,
  configuration: configuration,
  onCreated: (controller) {},
  onInterceptAnnotationActionCallback: (CPDFAnnotation annotation) {
    debugPrint('拦截到注释点击： ${annotation.type}');
  },
);

注释生命周期事件

创建 CPDFReaderWidget 并确保 CPDFReaderWidgetController 可用后，再注册监听事件。

late CPDFReaderWidgetController readerController;

void onAnnotationCreated(dynamic annotation) {
  debugPrint('注释已创建： $annotation');
}

void onAnnotationSelected(dynamic annotation) {
  debugPrint('注释已选中： $annotation');
}

void onAnnotationDeselected(dynamic annotation) {
  debugPrint('注释已取消选中： $annotation');
}

CPDFReaderWidget(
  document: documentPath,
  configuration: configuration,
  onCreated: (controller) {
    readerController = controller;
    readerController.addEventListener(
      CPDFEvent.annotationsCreated,
      onAnnotationCreated,
    );
    readerController.addEventListener(
      CPDFEvent.annotationsSelected,
      onAnnotationSelected,
    );
    readerController.addEventListener(
      CPDFEvent.annotationsDeselected,
      onAnnotationDeselected,
    );
  },
);

Pencil 绘制事件

返回值字段:

字段	类型	说明
type	String	绘制类型，通常为 pencil
pageIndex	int	从 0 开始的页面索引

void onPencilDrawingCompleted(dynamic event) {
  debugPrint('Pencil 绘制完成，页面： ${event['pageIndex']}');
}

void onPencilDrawingDiscarded(dynamic event) {
  debugPrint('Pencil 绘制已放弃，页面： ${event['pageIndex']}');
}

readerController.addEventListener(
  CPDFEvent.pencilDrawingCompleted,
  onPencilDrawingCompleted,
);
readerController.addEventListener(
  CPDFEvent.pencilDrawingDiscarded,
  onPencilDrawingDiscarded,
);

注意： Pencil 绘制事件仅支持 iOS。返回的 pageIndex 从 0 开始计数。

移除监听

移除监听时，需要传入与 addEventListener() 注册时相同的回调引用。

readerController.removeEventListener(
  CPDFEvent.annotationsCreated,
  onAnnotationCreated,
);
readerController.removeAllEventListeners(CPDFEvent.annotationsCreated);
readerController.removeAllEventListeners();