Guides

表单

ComPDF Flutter SDK 支持表单相关回调和监听事件，用于处理表单属性面板、字段创建、字段选中和取消选中。

可用回调和事件

类型	名称	触发时机	返回值
阅读器回调	onFormStyleDialogDismissedCallback	表单属性弹窗关闭	CPDFFormType type
阅读器回调	onInterceptWidgetActionCallback	开启拦截后点击已配置的表单 Widget	CPDFWidget widget
监听事件	CPDFEvent.formFieldsCreated	表单字段创建	CPDFWidget
监听事件	CPDFEvent.formFieldsSelected	表单字段被选中	CPDFWidget
监听事件	CPDFEvent.formFieldsDeselected	表单字段取消选中	CPDFWidget?

表单 Widget 点击拦截

当你需要用自己的 UI 或业务逻辑替换 SDK 默认的表单字段点击行为时，可以使用表单 Widget 点击拦截。你可以通过 interceptAllFormWidgetActions 拦截全部表单 Widget，也可以通过 interceptFormWidgetActions 只拦截指定类型。

推荐只拦截需要自定义处理的类型：

final configuration = CPDFConfiguration(
  formsConfig: const CPDFFormsConfig(
    interceptFormWidgetActions: [
      CPDFFormType.textField,
      CPDFFormType.checkBox,
      CPDFFormType.listBox,
      CPDFFormType.comboBox,
    ],
  ),
);

在 CPDFReaderWidget.onInterceptWidgetActionCallback 中处理被拦截的 Widget。如果你修改了 Widget 的值，请调用 updateWidget 将自定义结果应用到文档。

CPDFReaderWidget(
  document: documentPath,
  configuration: configuration,
  onCreated: (controller) {
    readerController = controller;
  },
  onInterceptWidgetActionCallback: (CPDFWidget widget) async {
    switch (widget.type) {
      case CPDFFormType.textField:
        final textWidget = widget as CPDFTextWidget;
        textWidget.text = 'Handled by Flutter';
        await readerController.document.updateWidget(textWidget);
        break;
      case CPDFFormType.checkBox:
        final checkBox = widget as CPDFCheckBoxWidget;
        checkBox.isChecked = !checkBox.isChecked;
        await readerController.document.updateWidget(checkBox);
        break;
      case CPDFFormType.listBox:
        final listBox = widget as CPDFListBoxWidget;
        listBox.selectItemAtIndex = 0;
        await readerController.document.updateWidget(listBox);
        break;
      case CPDFFormType.comboBox:
        final comboBox = widget as CPDFComboBoxWidget;
        comboBox.selectItemAtIndex = 0;
        await readerController.document.updateWidget(comboBox);
        break;
      default:
        break;
    }
  },
);

如果需要拦截所有表单 Widget 类型，可以设置 interceptAllFormWidgetActions: true。仅当你的应用会为全部表单 Widget 提供完整自定义行为时再使用它。

示例

late CPDFReaderWidgetController readerController;

void onFormFieldCreated(dynamic widget) {
  debugPrint('表单字段已创建： $widget');
}

void onFormFieldSelected(dynamic widget) {
  debugPrint('表单字段已选中： $widget');
}

void onFormFieldDeselected(dynamic widget) {
  debugPrint('表单字段已取消选中： $widget');
}

CPDFReaderWidget(
  document: documentPath,
  configuration: configuration,
  onCreated: (controller) {
    readerController = controller;
    readerController.addEventListener(CPDFEvent.formFieldsCreated, onFormFieldCreated);
    readerController.addEventListener(CPDFEvent.formFieldsSelected, onFormFieldSelected);
    readerController.addEventListener(CPDFEvent.formFieldsDeselected, onFormFieldDeselected);
  },
  onFormStyleDialogDismissedCallback: (CPDFFormType type) {
    debugPrint('表单属性弹窗已关闭： ${type.name}');
  },
);

移除监听

readerController.removeEventListener(CPDFEvent.formFieldsCreated, onFormFieldCreated);