Guides

文档状态与错误回调

在使用 CPDFReaderView查看 PDF 文档时，ComPDF SDK 提供了多种回调接口，用于获取文档加载状态、操作错误或异常信息。通过这些回调，开发者可以实现文档状态提示、错误处理、日志记录等功能，从而提升用户体验。

说明 本章节主要介绍查看器模式下的回调接口。注释操作、内容编辑等功能的回调请参考相关章节。

文档加载状态回调

IDocumentStatusCallback 用于监听 PDF 文档的加载状态，包括加载中、加载失败和加载完成。

java

readerView.setDocumentStatusCallback(new IDocumentStatusCallback() {
    @Override
    public void onLoading() {
        // 文档加载中
    }

    @Override
    public void onLoadFailed() {
        // 文档加载失败
    }

    @Override
    public void onLoadComplete() {
        // 文档加载完成
        // 注意：如果使用 reloadPages() 方法重新加载页面，也会触发该回调
    }
});

kotlin

readerView.setDocumentStatusCallback(object : IDocumentStatusCallback {
    override fun onLoading() {
        // 文档加载中
    }

    override fun onLoadFailed() {
        // 文档加载失败
    }

    override fun onLoadComplete() {
        // 文档加载完成
        // 注意：如果使用 reloadPages() 方法重新加载页面，也会触发该回调
    }
})

PDF 错误回调与提示

在打开、编辑或操作 PDF 文档时，可能会遇到各种错误或异常情况。SDK 提供了 IPDFErrorMessageCallback 接口，用于捕获这些错误并进行自定义处理，例如向用户显示提示或记录日志。 通过实现该接口，应用可以优雅地处理 PDF 操作异常，提升用户体验。

接口定义

interface IPDFErrorMessageCallback {
    fun onError(errorId: ErrorId)
}

• errorId：错误类型枚举 ErrorId，表示当前发生的错误。

常见错误类型

错误枚举	中文说明	适用场景
NO_EMAIL_APP	未检测到可用的邮箱应用	用户尝试通过 PDF 分享到邮箱时
NO_BROWSE_APP	未检测到可用的浏览器应用	用户尝试打开 PDF 中链接时
NO_CONTENT_TO_PASTE	剪贴板中没有内容可粘贴	用户使用复制或粘贴功能时
INVALID_LINK	无效的链接	PDF 内部或外部链接不可用时
NO_TEXT_ON_PAGE	页面上没有文本内容	用户尝试选择或复制文本时
CANNOT_EDIT	当前文档不可编辑	文档只读或权限受限
CANNOT_EDIT_ANNOT	注释不可编辑	注释不可修改或权限受限
CANNOT_EDIT_FORM	表单不可编辑	表单不可填写或权限受限
CANNOT_ADD_ANNOT	无法添加注释	当前文档禁止添加注释
CANNOT_ADD_FORM	无法添加表单	当前文档禁止添加表单
NOT_IN_PDFEDIT_MODE	当前未处于 PDF 编辑模式	在非编辑模式下尝试操作编辑内容

java

readerView.setPdfErrorMessageCallback(object : IPDFErrorMessageCallback {
    @Override
    public void onError(ErrorId errorId) {
        switch (errorId) {
            case NO_EMAIL_APP:
                // 没有可用的邮箱应用
                break;
            case NO_BROWSE_APP:
                // 没有可用的浏览器应用
                break;
            case NO_CONTENT_TO_PASTE:
                // 剪贴板中没有内容可粘贴
                break;
            case INVALID_LINK:
                // 无效的链接
                break;
            case NO_TEXT_ON_PAGE:
                // 页面上没有文本内容
                break;
            case CANNOT_EDIT:
                // 当前文档不可编辑
                break;
            case CANNOT_EDIT_ANNOT:
                // 注释不可编辑
                break;
            case CANNOT_EDIT_FORM:
                // 表单不可编辑
                break;
            case CANNOT_ADD_ANNOT:
                // 无法添加注释
                break;
            case CANNOT_ADD_FORM:
                // 无法添加表单
                break;
            case NOT_IN_PDFEDIT_MODE:
                // 当前未处于 PDF 编辑模式
                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("CPDFError", "PDF Error: $message")
    }
})

模式切换回调

CPDFReaderView 支持多种操作模式，通过设置 模式切换回调，可以在模式变化时获取通知，从而执行自定义操作或更新 UI。

java

readerView.setOnViewModeChangedListener(new OnViewModeChangedListener() {
    @Override
    public void onViewModeChange(ViewMode viewMode) {

    }
});

kotlin

readerView.setOnViewModeChangedListener(object : OnViewModeChangedListener {
    override fun onViewModeChange(viewMode: ViewMode) {

    }
})

触控模式切换回调

用户可以通过手势或工具栏操作切换不同的触控模式。触控模式决定了用户与 PDF 页面交互的行为，例如浏览、添加注释或擦除手绘内容。

OnTouchModeChangedListener 接口提供回调通知开发者触控模式变化，以便进行 UI 更新或功能控制。

触控模式枚举

枚举值	中文说明	适用场景
BROWSE	浏览模式	默认查看 PDF 页面，可滚动、缩放
ADD_ANNOT	添加注释模式	用户选择注释工具后添加注释
EDIT	编辑模式	编辑文本、表单或图像等内容
SCREENSHOT	截图模式	用户截取页面截图或局部截图
ERASE_INK	擦除手绘模式	删除手绘笔记或涂鸦内容

java

readerView.setOnTouchModeChangedListener(new OnTouchModeChangedListener() {
    @Override
    public void onTouchModeChanged(TouchMode touchMode) {

    }
});

kotlin

readerView.setOnTouchModeChangedListener(object : OnTouchModeChangedListener {
    override fun onTouchModeChanged(touchMode: TouchMode) {

    }
})

阅读器交互回调 IReaderViewCallback 接口用于监听用户在 PDF 阅读器中的交互操作，如点击、滚动或跳转页面。通过实现该接口，可以自定义行为或更新 UI。

接口方法说明

方法名	中文说明	触发场景
onTapMainDocArea()	用户点击主文档区域	点击 PDF 页面空白区域或文本区域
onMoveToChild(int pageIndex)	页面跳转到子文档或子页索引 pageIndex	调用跳转页面方法或目录跳转
onEndScroll()	滚动操作结束	用户停止滑动 PDF 页面
onScrolling()	滚动中回调	用户滑动 PDF 页面时持续触发
onRecordLastJumpPageNum(int pageIndex)	记录用户最后跳转的页面索引 pageIndex	页面跳转后可用于恢复上次阅读位置

java

readerView.setReaderViewCallback(new IReaderViewCallback() {
    @Override
    public void onTapMainDocArea() {
        // 用户点击文档区域，可用于隐藏/显示工具栏
    }

    @Override
    public void onMoveToChild(int pageIndex) {
        // 页面跳转到子文档或子页索引 pageIndex，可用于更新页码显示
    }

    @Override
    public void onEndScroll() {
        // 滚动结束，可用于刷新工具栏或触发页面加载完成事件
    }

    @Override
    public void onScrolling() {
        // 页面滚动中，可用于实时更新滚动进度条
    }

    @Override
    public void onRecordLastJumpPageNum(int pageIndex) {
        // 记录最后跳转的页面索引 pageIndex，可用于恢复上次阅读位置
    }
});

kotlin

readerView.setReaderViewCallback(object : IReaderViewCallback {
    override fun onTapMainDocArea() {
        // 用户点击文档区域，可用于隐藏/显示工具栏
    }

    override fun onMoveToChild(pageIndex: Int) {
        // 页面跳转到子文档或子页索引 pageIndex，可用于更新页码显示
    }

    override fun onEndScroll() {
        // 滚动结束，可用于刷新工具栏或触发页面加载完成事件
    }

    override fun onScrolling() {
        // 页面滚动中，可用于实时更新滚动进度条
    }

    override fun onRecordLastJumpPageNum(pageIndex: Int) {
        // 记录最后跳转的页面索引 pageIndex，可用于恢复上次阅读位置
    }
})