Guides

表单

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

可用回调和事件

类型	名称	触发时机	返回值
阅读器回调	onFormStyleDialogDismissed	表单属性弹窗关闭	{ type } 事件对象
阅读器回调	onInterceptWidgetActionCallback	开启拦截后点击已配置的表单 Widget	CPDFWidget widget
监听事件	CPDFEvent.FORM_FIELDS_CREATED	表单字段创建	CPDFWidget
监听事件	CPDFEvent.FORM_FIELDS_SELECTED	表单字段被选中	CPDFWidget
监听事件	CPDFEvent.FORM_FIELDS_DESELECTED	表单字段取消选中	CPDFWidget | null

表单 Widget 点击拦截

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

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

const configuration = ComPDFKit.getDefaultConfig({
  formsConfig: {
    interceptFormWidgetActions: [
      CPDFWidgetType.TEXT_FIELD,
      CPDFWidgetType.CHECKBOX,
      CPDFWidgetType.LISTBOX,
      CPDFWidgetType.COMBOBOX,
    ],
  },
});

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

<CPDFReaderView
  ref={pdfReaderRef}
  document={samplePDF}
  configuration={configuration}
  onInterceptWidgetActionCallback={async (widget) => {
    switch (widget.type) {
      case CPDFWidgetType.TEXT_FIELD: {
        const textWidget = widget as CPDFTextWidget;
        textWidget.update({ text: 'Handled by React Native' });
        await pdfReaderRef.current?._pdfDocument.updateWidget(textWidget);
        break;
      }
      case CPDFWidgetType.CHECKBOX: {
        const checkBox = widget as CPDFCheckboxWidget;
        checkBox.update({ isChecked: !checkBox.isChecked });
        await pdfReaderRef.current?._pdfDocument.updateWidget(checkBox);
        break;
      }
      case CPDFWidgetType.LISTBOX:
      case CPDFWidgetType.COMBOBOX: {
        const choiceWidget = widget as CPDFListboxWidget | CPDFComboboxWidget;
        choiceWidget.update({ selectItemAtIndex: 0 });
        await pdfReaderRef.current?._pdfDocument.updateWidget(choiceWidget);
        break;
      }
      default:
        break;
    }
  }}
/>

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

示例

const onFormFieldCreated = (widget: CPDFWidget) => {
  console.log('表单字段已创建：', widget.type);
};

const onFormFieldSelected = (widget: CPDFWidget) => {
  console.log('表单字段已选中：', widget.type);
};

const onFormFieldDeselected = (widget: CPDFWidget | null) => {
  console.log('表单字段已取消选中：', widget?.type);
};

<CPDFReaderView
  ref={pdfReaderRef}
  document={samplePDF}
  configuration={configuration}
  onViewCreated={() => {
    pdfReaderRef.current?.addEventListener(CPDFEvent.FORM_FIELDS_CREATED, onFormFieldCreated);
    pdfReaderRef.current?.addEventListener(CPDFEvent.FORM_FIELDS_SELECTED, onFormFieldSelected);
    pdfReaderRef.current?.addEventListener(CPDFEvent.FORM_FIELDS_DESELECTED, onFormFieldDeselected);
  }}
  onFormStyleDialogDismissed={(event) => {
    console.log('表单属性弹窗已关闭：', event.type);
  }}
/>

移除监听

pdfReaderRef.current?.removeEventListener(CPDFEvent.FORM_FIELDS_CREATED, onFormFieldCreated);