Skip to content

表单交互事件处理机制

福昕 PDF SDK Web 版 为填表模式 下的表单交互提供了一套完整的事件处理机制,使开发者能够精确控制和定制表单交互行为。该机制支持多种事件类型,包括鼠标事件(如按下、移动、释放等)和键盘事件(如按下、释放等)。开发者可以通过以下三种方式实现事件控制:

  • 事件监听:通过 FormFillerService.onMouseDownWidgetFormFillerService.onMouseDownWidget 等方法监听表单交互事件。
  • 拦截器:通过实现 FormInteractionEventInterceptor 接口,拦截并处理表单交互事件。
  • 方法重写:通过 ViewerAnnotManager.registerMatchRule 方法注册 mixin 方法,继承 WidgetAnnot 并重写相关方法,如 handleOnGotFocushandleOnClick 等。

以下将详细介绍每种方式的具体用法。

表单交互事件监听

事件监听允许开发者在表单控件交互过程中,通过事件回调处理与控件实现无关的逻辑。这种方式可以在不改变控件原有行为的基础上,添加额外的处理逻辑。典型的应用场景包括:

  • 用户行为分析
    • 通过监听表单控件的交互事件(如点击、移动、键盘输入)收集用户行为数据。
  • 实时帮助和提示
    • 在用户输入或点击特定字段时,动态触发帮助信息或工具提示的显示。
  • 其他场景
    • 根据具体业务需求,扩展更多定制化功能。

福昕 PDF SDK Web 版 提供了以下事件监听方法:

  • FormFillerService.onMouseDownWidget:监听鼠标按下事件。
  • FormFillerService.onMouseMoveWidget:监听鼠标移动事件。
  • FormFillerService.onMouseUpWidget:监听鼠标释放事件。
  • FormFillerService.onClickWidget:监听鼠标左键点击事件。
  • FormFillerService.onRightClickWidget:监听鼠标右键点击事件。
  • FormFillerService.onMouseOverWidget:监听鼠标移入事件。
  • FormFillerService.onMouseLeaveWidget:监听鼠标移出事件。
  • FormFillerService.onKeyDown:监听键盘按下事件。
  • FormFillerService.onKeyUp:监听键盘释放事件。
  • FormFillerService.onFocusChange:监听焦点变化事件。

更多接口信息请参考 FormFillerService 文档。

以下是一个简单的示例:

javascript
const formFillerService = pdfViewer.getFormFillerService();
// 使用 removeEvent 函数可以在需要时移除事件监听
const removeEvent = formFillerService.onMouseOverWidget((widgetId, event) => {
    console.log('Mouse over widget:', widgetId, event);
});

const removeEvent = formFillerService.onMouseDownWidget((widgetId, event) => {
    if (widgetId) {
        console.log('Mouse down on widget:', widgetId, event);
    } else {
        console.log('Mouse down on page');
    }
});

表单交互事件拦截器

拦截器机制允许开发者在事件发生前或发生后进行干预,从而选择性地允许或阻止事件传播。典型的应用场景包括:

  • 访问控制
    • 根据用户角色或权限动态控制表单字段的可交互性。
  • 用户界面保护
    • 通过拦截事件(如 mouseup),在执行高风险操作前提示用户确认,降低误操作风险。
  • 行为修改
    • 根据场景需求修改表单交互行为。

福昕 PDF SDK Web 版 提供的拦截器接口如下:

typescript
interface FormInteractionEvent {
    type: string; // mousedown|mousemove|mouseup|keydown|keyup
    timestamp: number; // 事件发生的时间戳,单位为毫秒
}

interface FormInteractionEventInterceptorOptions {
    type: FormInteractionEvent;
    widgetId: AnnotId;
}

type FormInteractionEventInterceptor = (options: FormInteractionEventInterceptorOptions, next: () => Promise<unknown>) => Promise<void>;

其中,options 参数包含目标表单域的 ID(一个包含 pageIndexobjNumber 的对象)和事件类型。next 函数用于调用下一个拦截器。更多详细信息请参考 FormInteractionEventInterceptor 文档。

以下是一个拦截器实现示例:

javascript
// removeInterceptor 用于在特定时机移除拦截器
const removeInterceptor = formFillerService.appendInteractionEventInterceptor(async (options, next) => {
    if (options.type === 'mouseup') {
        // 拦截鼠标释放事件
        console.log("Before mouse up");
        // 调用下一个拦截器或处理真实事件
        await next();
        // 在鼠标释放事件完成后执行 
        console.log("After mouse up");
    }
})

注意事项:

  1. 如果不调用 next 方法,拦截器将阻止事件传递,SDK 内部的处理逻辑将不会执行。
  2. clickright-clickmousedown/mouseup 在特定条件下的组合事件,无法直接处理,只能通过拦截 mousedownmouseup 事件实现。

完整示例可参考:examples/UIExtension/form/interaction-event-interceptor/index.js

方法重写

方法重写通过 ViewerAnnotManager.registerMatchRule 注册 mixin 方法,继承 WidgetAnnot 并重写 handleOnGotFocushandleOnClick 等方法。这种方式不仅可以监听事件,还可以控制是否执行 SDK 内部的表现层处理逻辑。典型的应用场景包括:

  • 事件监听器支持的所有场景。
  • 需要覆盖 福昕 PDF SDK Web 版 表现层处理逻辑的场景。

福昕 PDF SDK Web 版 提供的可重写的事件相关方法如下:

  • handleOnClick:处理鼠标左键点击事件。
  • handleOnMouseOver:处理鼠标移入事件。
  • handleOnMouseLeave:处理鼠标移出事件。
  • handleOnGotFocus:处理获取焦点事件。
  • handleOnLostFocus:处理失去焦点事件。

注意:若需覆盖鼠标右键事件或自定义右键菜单,可以通过重写 showContextMenu 方法来实现。

以下是一个简单的示例:

javascript
pdfViewer.getAnnotManager().registerMatchRule(function (annot, AnnotComponentClass) {
    if (annot.getType() !== 'widget') {
        return;
    }
    return class CustomWidgetAnnot extends AnnotComponentClass {
        handleOnClick() {
            super.handleOnClick();
            console.log('CustomWidgetAnnot handleOnClick');
        }

        handleOnMouseOver() {
            super.handleOnMouseOver();
            console.log('Handle on mouse over');
        }

        handleOnMouseLeave() {
            super.handleOnMouseLeave();
            console.log('Handle on mouse leave');
        }

        handleOnGotFocus() {
            super.handleOnGotFocus();
            console.log('Handle on got focus');
        }

        handleOnLostFocus() {
            super.handleOnLostFocus();
            console.log('Handle on lost focus');
        }
    }
})

方法对比

方法支持范围控制层次灵活性
事件监听mousedown/mouseover/mouseup/click/right-click/mouseover/mouseleave/keydown/keyup/focus-change事件发生后一般
拦截器mousedown/mousemove/mouseup/keydown/keyup事件发生前和发生后最高
方法重写click/mouseover/mouseleave/get-focus/lost-focus事件发生后一般