Guides

配置文档状态与错误回调

CPDFReaderView 完成基础接入后，通常还需要处理以下事件：

文档加载中、加载完成、加载失败。
阅读过程中的错误提示。
阅读器模式或手势模式切换。
点击、滚动、跳页等交互行为。

本页对阅读器中最常用的回调类型进行归类说明，便于在页面中建立稳定的状态管理和交互响应逻辑。

识别所需回调类型

回调类型	解决什么问题	什么时候用
`IDocumentStatusCallback`	文档是否正在加载、是否加载完成、是否加载失败	需要显示 loading、错误页或空态时
`IPDFErrorMessageCallback`	阅读器内部操作失败时返回错误类型	需要统一错误提示或记录日志时
`OnViewModeChangedListener`	当前阅读器工作模式发生变化	需要同步工具栏、功能入口时
`OnTouchModeChangedListener`	当前交互手势模式发生变化	需要切换画笔、截图、浏览态 UI 时
`IReaderViewCallback`	点击、滚动、跳页等阅读行为	需要更新页码、隐藏工具栏、记录阅读位置时

在文档打开前注册回调

通常建议在 CPDFReaderView 初始化完成后立即注册回调，然后再打开并绑定文档。这样可以确保：

文档开始加载时就能收到状态变化。
页面首屏失败时不会漏掉错误处理。
后续模式切换和阅读行为可以统一从同一个入口处理。

监听文档加载生命周期

IDocumentStatusCallback 用于监听文档加载流程，适合驱动 loading、失败态和加载完成后的界面切换。

javakotlin

java

readerView.setDocumentStatusCallback(new IDocumentStatusCallback() {
    @Override
    public void onLoading() {
        Log.d("ComPDF", "Document is loading");
    }

    @Override
    public void onLoadFailed() {
        Log.e("ComPDF", "Document failed to load");
    }

    @Override
    public void onLoadComplete() {
        Log.d("ComPDF", "Document loaded");
        // 如果调用 reloadPages() 重新加载页面，也会再次触发这里。
    }
});

kotlin

readerView.setDocumentStatusCallback(object : IDocumentStatusCallback {
    override fun onLoading() {
        Log.d("ComPDF", "Document is loading")
    }

    override fun onLoadFailed() {
        Log.e("ComPDF", "Document failed to load")
    }

    override fun onLoadComplete() {
        Log.d("ComPDF", "Document loaded")
        // 如果调用 reloadPages() 重新加载页面，也会再次触发这里。
    }
})

这个回调通常用于页面级状态切换，例如：

onLoading() 显示 loading。
onLoadFailed() 显示失败提示或重试按钮。
onLoadComplete() 隐藏 loading，并展示阅读器内容。

统一处理阅读器错误

IPDFErrorMessageCallback 用于接收阅读器内部的错误事件。它和 document.open(...) 的返回值并不相同。

document.open(...) 更偏向“文档是否打开成功”。
IPDFErrorMessageCallback 更偏向“阅读过程中某个动作为什么失败”。

复制、打开链接、进入编辑操作等行为在当前条件不满足时，都可能触发错误回调。

识别常见错误类型

错误枚举	中文说明	常见场景
`NO_EMAIL_APP`	未检测到可用的邮箱应用	分享到邮箱时
`NO_BROWSE_APP`	未检测到可用的浏览器应用	打开 PDF 链接时
`NO_CONTENT_TO_PASTE`	剪贴板中没有内容可粘贴	粘贴操作时
`INVALID_LINK`	无效链接	链接不可用时
`NO_TEXT_ON_PAGE`	页面上没有文本内容	选择或复制文本时
`CANNOT_EDIT`	当前文档不可编辑	文档受权限限制时
`CANNOT_EDIT_ANNOT`	注释不可编辑	注释受限时
`CANNOT_EDIT_FORM`	表单不可编辑	表单受限时
`CANNOT_ADD_ANNOT`	无法添加注释	文档禁止新增注释时
`CANNOT_ADD_FORM`	无法添加表单	文档禁止新增表单时
`NOT_IN_PDFEDIT_MODE`	当前未处于 PDF 编辑模式	在错误模式下操作内容编辑时

注册错误处理回调

javakotlin

java

readerView.setPdfErrorMessageCallback(new IPDFErrorMessageCallback() {
    @Override
    public void onError(ErrorId errorId) {
        switch (errorId) {
            case NO_EMAIL_APP:
                Log.e("ComPDF", "No email app available");
                break;
            case NO_BROWSE_APP:
                Log.e("ComPDF", "No browser app available");
                break;
            case NO_CONTENT_TO_PASTE:
                Log.e("ComPDF", "Nothing to paste");
                break;
            case INVALID_LINK:
                Log.e("ComPDF", "Invalid link");
                break;
            case NO_TEXT_ON_PAGE:
                Log.e("ComPDF", "No text on page");
                break;
            case CANNOT_EDIT:
                Log.e("ComPDF", "Document cannot be edited");
                break;
            case CANNOT_EDIT_ANNOT:
                Log.e("ComPDF", "Annotation cannot be edited");
                break;
            case CANNOT_EDIT_FORM:
                Log.e("ComPDF", "Form cannot be edited");
                break;
            case CANNOT_ADD_ANNOT:
                Log.e("ComPDF", "Cannot add annotation");
                break;
            case CANNOT_ADD_FORM:
                Log.e("ComPDF", "Cannot add form");
                break;
            case NOT_IN_PDFEDIT_MODE:
                Log.e("ComPDF", "Not in PDF edit mode");
                break;
        }
    }
});

kotlin

readerView.setPdfErrorMessageCallback(object : IPDFErrorMessageCallback {
    override fun onError(errorId: ErrorId) {
        val message = when (errorId) {
            ErrorId.NO_EMAIL_APP -> "未检测到可用的邮箱应用"
            ErrorId.NO_BROWSE_APP -> "未检测到可用的浏览器应用"
            ErrorId.NO_CONTENT_TO_PASTE -> "剪贴板中没有内容可粘贴"
            ErrorId.INVALID_LINK -> "无效链接"
            ErrorId.NO_TEXT_ON_PAGE -> "页面上没有文本内容"
            ErrorId.CANNOT_EDIT -> "当前文档不可编辑"
            ErrorId.CANNOT_EDIT_ANNOT -> "注释不可编辑"
            ErrorId.CANNOT_EDIT_FORM -> "表单不可编辑"
            ErrorId.CANNOT_ADD_ANNOT -> "无法添加注释"
            ErrorId.CANNOT_ADD_FORM -> "无法添加表单"
            ErrorId.NOT_IN_PDFEDIT_MODE -> "当前未处于 PDF 编辑模式"
        }
        Log.e("ComPDF", message)
    }
})

如果页面中已经有统一的 Toast、Snackbar 或弹窗体系，可以在这里把错误类型映射为统一提示文案。

区分 ViewMode 与 TouchMode

ViewMode 与 TouchMode 都会影响阅读器行为，但它们对应的层级不同。

使用 ViewMode 同步工作模式

它更偏能力层，例如当前页面是在阅读、注释、表单编辑，还是内容编辑。

当工具栏、底部栏或功能面板需要跟随大模式切换时，应监听 OnViewModeChangedListener。

javakotlin

java

readerView.setOnViewModeChangedListener(new OnViewModeChangedListener() {
    @Override
    public void onViewModeChange(ViewMode viewMode) {
        Log.d("ComPDF", "ViewMode changed: " + viewMode);
    }
});

kotlin

readerView.setOnViewModeChangedListener(object : OnViewModeChangedListener {
    override fun onViewModeChange(viewMode: ViewMode) {
        Log.d("ComPDF", "ViewMode changed: $viewMode")
    }
})

使用 TouchMode 同步交互模式

它更偏交互层，例如当前是浏览、添加注释、截图，还是擦除手绘。

当页面需要跟随手势状态更新按钮选中态、工具栏文案或交互入口时，应监听 OnTouchModeChangedListener。

常见枚举值如下：

枚举值	中文说明	常见场景
`BROWSE`	浏览模式	默认阅读、滚动、缩放
`ADD_ANNOT`	添加注释模式	选择注释工具后
`EDIT`	编辑模式	编辑文本、图像、表单等内容时
`SCREENSHOT`	截图模式	截图或局部截图时
`ERASE_INK`	擦除手绘模式	删除手写笔迹时

javakotlin

java

readerView.setOnTouchModeChangedListener(new OnTouchModeChangedListener() {
    @Override
    public void onTouchModeChanged(TouchMode touchMode) {
        Log.d("ComPDF", "TouchMode changed: " + touchMode);
    }
});

kotlin

readerView.setOnTouchModeChangedListener(object : OnTouchModeChangedListener {
    override fun onTouchModeChanged(touchMode: TouchMode) {
        Log.d("ComPDF", "TouchMode changed: $touchMode")
    }
})

监听阅读过程中的交互事件

IReaderViewCallback 用于接收点击、滚动、跳页等阅读器交互事件，适合处理页码同步、工具栏显隐和阅读位置记录。

方法名	说明	典型用途
`onTapMainDocArea()`	点击主文档区域	点击页面后隐藏或显示工具栏
`onMoveToChild(int pageIndex)`	发生跳页	更新当前页显示
`onEndScroll()`	滚动结束	延迟刷新 UI 或记录当前位置
`onScrolling()`	正在滚动	更新滚动状态或进度
`onRecordLastJumpPageNum(int pageIndex)`	记录最后跳转页	恢复上次阅读位置

javakotlin

java

readerView.setReaderViewCallback(new IReaderViewCallback() {
    @Override
    public void onTapMainDocArea() {
        Log.d("ComPDF", "Tap main document area");
    }

    @Override
    public void onMoveToChild(int pageIndex) {
        Log.d("ComPDF", "Move to page: " + pageIndex);
    }

    @Override
    public void onEndScroll() {
        Log.d("ComPDF", "Scroll ended");
    }

    @Override
    public void onScrolling() {
        Log.d("ComPDF", "Scrolling");
    }

    @Override
    public void onRecordLastJumpPageNum(int pageIndex) {
        Log.d("ComPDF", "Last jump page: " + pageIndex);
    }
});

kotlin

readerView.setReaderViewCallback(object : IReaderViewCallback {
    override fun onTapMainDocArea() {
        Log.d("ComPDF", "Tap main document area")
    }

    override fun onMoveToChild(pageIndex: Int) {
        Log.d("ComPDF", "Move to page: $pageIndex")
    }

    override fun onEndScroll() {
        Log.d("ComPDF", "Scroll ended")
    }

    override fun onScrolling() {
        Log.d("ComPDF", "Scrolling")
    }

    override fun onRecordLastJumpPageNum(pageIndex: Int) {
        Log.d("ComPDF", "Last jump page: $pageIndex")
    }
})

如果页面重点在页码跳转和阅读位置同步，也可以继续查看页面导航。

建立最小回调注册组合

对于常规阅读页，通常建议至少先注册以下三类回调：

IDocumentStatusCallback
IPDFErrorMessageCallback
IReaderViewCallback

这三个回调已经能够覆盖大多数阅读页的加载状态、错误提示和交互同步需求。

继续阅读

阅读器基础接入，参见使用 CPDFReaderView。
页码跳转与阅读位置同步，参见页面导航。
单页、双页、滚动方向和阅读模式配置，参见显示模式。

PDF SDK 与 AI 文档处理

概览与接入

基础阅读

文档导航

文本交互

交互增强

高级定制

无障碍

配置文档状态与错误回调

识别所需回调类型

在文档打开前注册回调

监听文档加载生命周期

统一处理阅读器错误

识别常见错误类型

注册错误处理回调

区分 ViewMode 与 TouchMode

使用 ViewMode 同步工作模式

使用 TouchMode 同步交互模式

监听阅读过程中的交互事件

建立最小回调注册组合

继续阅读

配置文档状态与错误回调 ​

识别所需回调类型 ​

在文档打开前注册回调 ​

监听文档加载生命周期 ​

统一处理阅读器错误 ​

识别常见错误类型 ​

注册错误处理回调 ​

区分 ViewMode 与 TouchMode ​

使用 ViewMode 同步工作模式 ​

使用 TouchMode 同步交互模式 ​

监听阅读过程中的交互事件 ​

建立最小回调注册组合 ​

继续阅读 ​

配置文档状态与错误回调

识别所需回调类型

在文档打开前注册回调

监听文档加载生命周期

统一处理阅读器错误

识别常见错误类型

注册错误处理回调

区分 ViewMode 与 TouchMode

使用 ViewMode 同步工作模式

使用 TouchMode 同步交互模式

监听阅读过程中的交互事件

建立最小回调注册组合

继续阅读