Guides

注释

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

事件概览

事件名称	触发时机	返回值
onAnnotationCreationPrepared	准备创建签名、图章、超链接、图片注释时	注释类型
onAnnotationStyleDialogDismissed	注释属性弹窗关闭时	{ type } 事件对象
onInterceptAnnotationActionCallback	点击便签、超链接注释时	CPDFAnnotation对象
CPDFEvent.ANNOTATIONS_CREATED	创建注释时	创建的注释数据
CPDFEvent.ANNOTATIONS_SELECTED	选中注释时	选中的注释数据
CPDFEvent.ANNOTATIONS_DESELECTED	取消选中注释时	取消选中的注释数据

注释创建准备回调

回调方法：onAnnotationCreationPrepared

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

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

配置

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

ComPDFKit.getDefaultConfig({
  annotationsConfig: {
    autoShowSignPicker: false,   // 禁用签名选择对话框
    autoShowLinkDialog: false,   // 禁用超链接选择对话框
    autoShowPicPicker: false,    // 禁用图片选择对话框
    autoShowStampPicker: false,  // 禁用图章选择对话框
  }
})

监听回调

<CPDFReaderView
  ref={pdfReaderRef}
  document={samplePDF}
  configuration={configuration}
  onAnnotationStyleDialogDismissed={(event) => {
    console.log('Annotation style dialog dismissed:', event.type);
  }}
  onAnnotationCreationPrepared={(type, annotation) => {
    // 签名、图章、图片注释：进入创建模式时触发
    // 超链接注释：用户在页面中滑取矩形抬起手指后触发
    console.log('Preparing to create annotation of type:', type);
    // 在此处弹出自定义选择框
  }}
/>

注释属性弹窗关闭回调

回调方法：onAnnotationStyleDialogDismissed

当用户关闭注释属性弹窗时触发，返回一个事件对象：

{
  type:
    | 'note'
    | 'strikeout'
    | 'underline'
    | 'highlight'
    | 'squiggly'
    | 'ink'
    | 'square'
    | 'circle'
    | 'line'
    | 'arrow'
    | 'freetext'
    | 'stamp'
    | 'pictures';
}

您可以通过 event.type 判断当前关闭的是哪一类注释属性面板，并在 React Native 层刷新工具栏状态或同步业务状态。

插入签名

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

await pdfReaderRef.current?.prepareNextSignature('/path/to/signature.png');

插入图章

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

// 标准图章（查看 CPDFStandardStamp 枚举获取可用类型）
await pdfReaderRef.current?.prepareNextStamp({ standardStamp: CPDFStandardStamp.Approved });

// 图片图章
await pdfReaderRef.current?.prepareNextStamp({ imagePath: '/path/to/stamp.png' });

// 文字图章
await pdfReaderRef.current?.prepareNextStamp({
  textStamp: {
    content: 'ComPDF-ReactNative',
    date: CPDFDateUtil.getTextStampDate({ timeSwitch: false, dateSwitch: true }),
    shape: CPDFTextStampShape.none,
    color: CPDFTextStampColor.white,
  },
});

注释点击拦截回调

回调方法：onInterceptAnnotationAction

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

配置

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

ComPDFKit.getDefaultConfig({
  annotationsConfig: {
    interceptNoteAction: true,  // 拦截便签默认行为事件
    interceptLinkAction: true,  // 拦截超链接默认行为事件
  }
})

监听回调

<CPDFReaderView
  ref={pdfReaderRef}
  document={samplePDF}
  configuration={configuration}
  onInterceptAnnotationAction={(annotation) => {
    console.log('Intercepted annotation action:', annotation.type);
    // 根据注释类型自定义点击行为
    if (annotation.type === CPDFAnnotationType.NOTE) {
      // 自定义便签点击处理
    } else if (annotation.type === CPDFAnnotationType.LINK) {
      // 自定义超链接点击处理
    }
  }}
/>

注释创建事件

事件名称：CPDFEvent.ANNOTATIONS_CREATED

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

pdfReaderRef.current?.addEventListener(CPDFEvent.ANNOTATIONS_CREATED, (annotation) => {
  // annotation 为 CPDFAnnotation 对象或其子类对象
  console.log(JSON.stringify(annotation));
});

注释选中事件

事件名称：CPDFEvent.ANNOTATIONS_SELECTED

当用户选中注释时触发：

pdfReaderRef.current?.addEventListener(CPDFEvent.ANNOTATIONS_SELECTED, (annotation) => {
  // annotation 为 CPDFAnnotation 对象或其子类对象
  console.log(JSON.stringify(annotation));
});

注释取消选中事件

事件名称：CPDFEvent.ANNOTATIONS_DESELECTED

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

pdfReaderRef.current?.addEventListener(CPDFEvent.ANNOTATIONS_DESELECTED, (annotation) => {
  // annotation 为 CPDFAnnotation 对象或其子类对象，可能为空
  console.log(JSON.stringify(annotation));
});