Guides

自定义注释创建流程

以下 API 对 SDK 默认流程有不同影响：

流程 API

目标	API	对 SDK 默认行为的影响
被动得知注释已创建	CPDFEvent.ANNOTATIONS_CREATED	不改变默认行为。
用 React Native UI 替换签名、图片、图章、Link 或 Note 的默认创建弹窗	onAnnotationCreationPrepared	关闭对应自动弹窗后，应用必须完成或取消创建流程。
接管已有 Note 或 Link 的点击行为	onInterceptAnnotationActionCallback	SDK 不再执行默认编辑或跳转行为。
接管指定表单字段的点击行为	onInterceptWidgetActionCallback	SDK 不再执行该字段的默认行为。

接管注释创建流程

注释类型	需要关闭的配置	annotation 参数	应用后续操作
CPDFAnnotationType.SIGNATURE	autoShowSignPicker: false	null	选择图片后调用 prepareNextSignature()。
CPDFAnnotationType.STAMP	autoShowStampPicker: false	null	选择图章后调用 prepareNextStamp()。
CPDFAnnotationType.PICTURES	autoShowPicPicker: false	null	选择图片后调用 prepareNextImage()。
CPDFAnnotationType.LINK	autoShowLinkDialog: false	已创建的 CPDFLinkAnnotation	设置 action 后调用 _pdfDocument.updateAnnotation()；取消时移除该注释。
CPDFAnnotationType.NOTE	autoShowNoteEditDialog: false	已创建的 CPDFNoteAnnotation	设置 content 后调用 _pdfDocument.updateAnnotation()；取消时移除该注释。

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

签名、图章和图片在回调触发时尚未添加到页面：

await pdfReaderRef.current?.prepareNextSignature(signaturePath);
await pdfReaderRef.current?.prepareNextImage(imagePath);
await pdfReaderRef.current?.prepareNextStamp({
  standardStamp: CPDFStandardStamp.APPROVED,
});

Link 和 Note 在回调触发时已经添加到页面。修改 JavaScript 对象不会自动写回 PDF，必须显式调用 updateAnnotation() 或 removeAnnotation()。完整 Note 确认和取消流程参见创建注释。

拦截已有注释的操作

在 annotationsConfig 中将 interceptNoteAction 或 interceptLinkAction 设为 true。启用后，应用需要在 onInterceptAnnotationActionCallback 中完成 Note 编辑、网页链接或页面跳转。若只想观察点击而不替换默认行为，不要开启拦截。

拦截表单字段操作

在 formsConfig.interceptFormWidgetActions 中只列出需要自定义处理的 CPDFWidgetType。修改返回的 CPDFWidget 后，调用 pdfReaderRef.current?._pdfDocument.updateWidget(widget)。只有当应用实现了全部表单字段行为时，才使用 interceptAllFormWidgetActions: true。