表单交互事件处理机制
福昕 PDF SDK Web 版 为填表模式 下的表单交互提供了一套完整的事件处理机制,使开发者能够精确控制和定制表单交互行为。该机制支持多种事件类型,包括鼠标事件(如按下、移动、释放等)和键盘事件(如按下、释放等)。开发者可以通过以下三种方式实现事件控制:
- 事件监听:通过
FormFillerService.onMouseDownWidget
、FormFillerService.onMouseDownWidget
等方法监听表单交互事件。 - 拦截器:通过实现
FormInteractionEventInterceptor
接口,拦截并处理表单交互事件。 - 方法重写:通过
ViewerAnnotManager.registerMatchRule
方法注册 mixin 方法,继承WidgetAnnot
并重写相关方法,如handleOnGotFocus
和handleOnClick
等。
以下将详细介绍每种方式的具体用法。
表单交互事件监听
事件监听允许开发者在表单控件交互过程中,通过事件回调处理与控件实现无关的逻辑。这种方式可以在不改变控件原有行为的基础上,添加额外的处理逻辑。典型的应用场景包括:
- 用户行为分析:
- 通过监听表单控件的交互事件(如点击、移动、键盘输入)收集用户行为数据。
- 实时帮助和提示:
- 在用户输入或点击特定字段时,动态触发帮助信息或工具提示的显示。
- 其他场景:
- 根据具体业务需求,扩展更多定制化功能。
福昕 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(一个包含 pageIndex
和 objNumber
的对象)和事件类型。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");
}
})
注意事项:
- 如果不调用
next
方法,拦截器将阻止事件传递,SDK 内部的处理逻辑将不会执行。 click
和right-click
是mousedown/mouseup
在特定条件下的组合事件,无法直接处理,只能通过拦截mousedown
或mouseup
事件实现。
完整示例可参考:examples/UIExtension/form/interaction-event-interceptor/index.js
方法重写
方法重写通过 ViewerAnnotManager.registerMatchRule
注册 mixin 方法,继承 WidgetAnnot
并重写 handleOnGotFocus
和 handleOnClick
等方法。这种方式不仅可以监听事件,还可以控制是否执行 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 | 事件发生后 | 一般 |