Guides

自定义注释创建流程

以下 API 看起来都与“注释事件”有关，但用途不同：

目标	API	对 SDK 默认行为的影响
被动得知注释已创建	CPDFEvent.annotationsCreated	不改变默认行为。
用 Flutter UI 替换签名、图片、图章、链接或 Note 的默认创建弹窗	onAnnotationCreationPreparedCallback	关闭对应自动弹窗后，应用必须完成或取消创建流程。
接管已有 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 后调用 document.updateAnnotation()；取消时移除该注释。
CPDFAnnotationType.note	autoShowNoteEditDialog: false	已创建的 CPDFNoteAnnotation	设置 content 后调用 document.updateAnnotation()；取消时移除该注释。

final configuration = CPDFConfiguration(
  annotationsConfig: const CPDFAnnotationsConfig(
    autoShowSignPicker: false,
    autoShowStampPicker: false,
    autoShowPicPicker: false,
    autoShowLinkDialog: false,
    autoShowNoteEditDialog: false,
  ),
);

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

await controller.prepareNextSignature(signaturePath);
await controller.prepareNextImage(imagePath);
await controller.prepareNextStamp(
  standardStamp: CPDFStandardStamp.approved,
);

Link 和 Note 在回调触发时已经创建。修改 Dart 对象不会自动写回 PDF，必须显式更新或移除：

if (annotation is CPDFNoteAnnotation) {
  annotation.content = 'Updated note content';
  await controller.document.updateAnnotation(annotation);
}

// 用户取消自定义弹窗时：
if (annotation != null) {
  await controller.document.removeAnnotation(annotation);
}

自定义 Note 的创建、确认和取消完整示例参见创建注释。

拦截已有注释的操作

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

拦截表单字段操作

在 CPDFFormsConfig.interceptFormWidgetActions 中只列出需要自定义处理的 CPDFFormType。在回调中修改 CPDFWidget 后，调用 controller.document.updateWidget(widget) 将结果写回 PDF。只有当应用为所有表单类型都提供了完整处理逻辑时，才使用 interceptAllFormWidgetActions: true。