Guides

注释

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

可用回调和事件

类型	名称	触发时机	返回值
阅读器回调	onAnnotationCreationPrepared	准备创建签名、图章、超链接、图片或 Note 注释	CPDFAnnotationType type, CPDFAnnotation | null
阅读器回调	onAnnotationStyleDialogDismissed	注释属性弹窗关闭	{ type } 事件对象
阅读器回调	onInterceptAnnotationActionCallback	开启拦截后点击已有 Note 或 Link 注释	CPDFAnnotation annotation
监听事件	CPDFEvent.ANNOTATIONS_CREATED	注释创建	CPDFAnnotation
监听事件	CPDFEvent.ANNOTATIONS_SELECTED	注释被选中	CPDFAnnotation
监听事件	CPDFEvent.ANNOTATIONS_DESELECTED	注释取消选中	CPDFAnnotation | null
监听事件	CPDFEvent.PENCIL_DRAWING_COMPLETED	iOS Pencil 绘制完成	{ type: 'pencil', pageIndex: number }
监听事件	CPDFEvent.PENCIL_DRAWING_DISCARDED	iOS Pencil 绘制被放弃	{ type: 'pencil', pageIndex: number }

注释创建准备回调

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

如需替换默认选择弹窗，请在 CPDFConfiguration 中关闭对应选项：

const configuration = ComPDFKit.getDefaultConfig({
  annotationsConfig: {
    autoShowSignPicker: false,
    autoShowLinkDialog: false,
    autoShowPicPicker: false,
    autoShowStampPicker: false,
  },
});

<CPDFReaderView
  ref={pdfReaderRef}
  document={samplePDF}
  configuration={configuration}
  onAnnotationCreationPrepared={(type, annotation) => {
    console.log('准备创建注释：', type);
  }}
/>

插入签名和图章

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

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

注释属性弹窗关闭回调

<CPDFReaderView
  ref={pdfReaderRef}
  document={samplePDF}
  configuration={configuration}
  onAnnotationStyleDialogDismissed={(event) => {
    console.log('注释属性弹窗已关闭：', event.type);
  }}
/>

注释点击拦截回调

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

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

const configuration = ComPDFKit.getDefaultConfig({
  annotationsConfig: {
    interceptNoteAction: true,
    interceptLinkAction: true,
  },
});

<CPDFReaderView
  ref={pdfReaderRef}
  document={samplePDF}
  configuration={configuration}
  onInterceptAnnotationActionCallback={(annotation) => {
    console.log('拦截到注释点击：', annotation.type);
  }}
/>

注释生命周期事件

创建 CPDFReaderView 并确保 pdfReaderRef.current 可用后，再注册监听事件。

const onAnnotationCreated = (annotation: CPDFAnnotation) => {
  console.log('注释已创建：', annotation.type);
};

const onAnnotationSelected = (annotation: CPDFAnnotation) => {
  console.log('注释已选中：', annotation.type);
};

const onAnnotationDeselected = (annotation: CPDFAnnotation | null) => {
  console.log('注释已取消选中：', annotation?.type);
};

<CPDFReaderView
  ref={pdfReaderRef}
  document={samplePDF}
  configuration={configuration}
  onViewCreated={() => {
    pdfReaderRef.current?.addEventListener(CPDFEvent.ANNOTATIONS_CREATED, onAnnotationCreated);
    pdfReaderRef.current?.addEventListener(CPDFEvent.ANNOTATIONS_SELECTED, onAnnotationSelected);
    pdfReaderRef.current?.addEventListener(CPDFEvent.ANNOTATIONS_DESELECTED, onAnnotationDeselected);
  }}
/>

Pencil 绘制事件

返回值字段:

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

const onPencilDrawingCompleted = (event: { type: 'pencil'; pageIndex: number }) => {
  console.log('Pencil 绘制完成，页面：', event.pageIndex);
};

const onPencilDrawingDiscarded = (event: { type: 'pencil'; pageIndex: number }) => {
  console.log('Pencil 绘制已放弃，页面：', event.pageIndex);
};

pdfReaderRef.current?.addEventListener(
  CPDFEvent.PENCIL_DRAWING_COMPLETED,
  onPencilDrawingCompleted,
);
pdfReaderRef.current?.addEventListener(
  CPDFEvent.PENCIL_DRAWING_DISCARDED,
  onPencilDrawingDiscarded,
);

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

移除监听

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

pdfReaderRef.current?.removeEventListener(
  CPDFEvent.ANNOTATIONS_CREATED,
  onAnnotationCreated,
);