Guides

事件回调与监听

ComPDFKit_Tools 提供 CPDFCustomEventCallbackHelper 统一事件分发机制，用于监听自定义按钮点击、注释交互拦截等事件。

CPDFCustomEventCallbackHelper

注册回调

java

CPDFCustomEventCallbackHelper.getInstance().addCustomEventCallback(extraMap -> {
    String eventType = extraMap.get(
        CPDFCustomEventField.CUSTOM_EVENT_TYPE).toString();
    // 根据事件类型处理
});

kotlin

CPDFCustomEventCallbackHelper.getInstance().addCustomEventCallback { extraMap ->
    val eventType = extraMap[CPDFCustomEventField.CUSTOM_EVENT_TYPE].toString()
    // 根据事件类型处理
}

移除回调

java

@Override
protected void onDestroy() {
    super.onDestroy();
    CPDFCustomEventCallbackHelper.getInstance().removeCustomEventCallback(this);
}

kotlin

override fun onDestroy() {
    super.onDestroy()
    CPDFCustomEventCallbackHelper.getInstance().removeCustomEventCallback(this)
}

事件类型

工具栏按钮点击

当自定义工具栏按钮被点击时触发。

字段	值/说明
CUSTOM_EVENT_TYPE	CPDFCustomEventType.TOOLBAR_ITEM_TAPPED
identifier	按钮的唯一标识符

java

if (CPDFCustomEventType.TOOLBAR_ITEM_TAPPED.equals(eventType)) {
    String identifier = extraMap.get("identifier").toString();
    switch (identifier) {
        case "custom_download":
            // 处理下载按钮点击
            break;
    }
}

kotlin

if (CPDFCustomEventType.TOOLBAR_ITEM_TAPPED == eventType) {
    when (extraMap["identifier"].toString()) {
        "custom_download" -> {
            // 处理下载按钮点击
        }
    }
}

详见 自定义菜单按钮。

上下文菜单项点击

当自定义上下文菜单项被点击时触发。

字段	值/说明
CUSTOM_EVENT_TYPE	CPDFCustomEventType.CONTEXT_MENU_ITEM_TAPPED
IDENTIFIER	菜单项的唯一标识符
ANNOTATION	关联的注释对象（可为 null）

java

if (CPDFCustomEventType.CONTEXT_MENU_ITEM_TAPPED.equals(eventType)) {
    String identifier = extraMap.get(CPDFCustomEventField.IDENTIFIER).toString();
    CPDFAnnotation annotation = (CPDFAnnotation) extraMap.get(
        CPDFCustomEventField.ANNOTATION);
    // 根据 identifier 处理
}

kotlin

if (CPDFCustomEventType.CONTEXT_MENU_ITEM_TAPPED == eventType) {
    val identifier = extraMap[CPDFCustomEventField.IDENTIFIER].toString()
    val annotation = extraMap[CPDFCustomEventField.ANNOTATION] as? CPDFAnnotation
    // 根据 identifier 处理
}

详见 上下文菜单。

注释交互拦截

当 annotationsConfig 中对应的 intercept*Action 设为 true 时，点击注释将触发事件而非执行默认行为。

拦截配置	事件描述
interceptNoteAction: true	拦截便签注释点击
interceptLinkAction: true	拦截链接注释点击

表单交互拦截

当 formsConfig 中对应的 intercept*Action 设为 true 时，点击表单控件将触发事件（仅 ListBox、ComboBox 和 PushButton 支持）。

拦截配置	事件描述
interceptListBoxAction: true	拦截列表框点击
interceptComboBoxAction: true	拦截下拉框点击
interceptPushButtonAction: true	拦截按钮点击

CPDFCustomEventField 常量

常量	说明
CUSTOM_EVENT_TYPE	事件类型标识
IDENTIFIER	自定义按钮/菜单的唯一标识符
ANNOTATION	关联的注释对象

CPDFCustomEventType 常量

常量	说明
TOOLBAR_ITEM_TAPPED	工具栏按钮点击事件
CONTEXT_MENU_ITEM_TAPPED	上下文菜单项点击事件

最佳实践

1. 及时移除回调：在 onDestroy() 中移除回调，避免内存泄漏
2. 事件类型判断：回调中始终检查 CUSTOM_EVENT_TYPE，不同事件可能复用同一回调
3. 空值保护：从 extraMap 取值时做好空值检查
4. 线程安全：回调在主线程执行，耗时操作需切换到后台线程