Guides

TalkBack 无障碍支持

ComPDF SDK 支持 Android TalkBack 和硬件键盘导航，帮助用户以语音或键盘方式浏览 PDF 文档。

说明

• 无障碍功能默认关闭。
• TalkBack 可朗读 PDF 中可提取的文本内容，并在翻页或缩放时播报相应状态。
• 对于纯扫描图片或不含文本层的 PDF，建议先通过 OCR 生成可提取文本，以获得更好的朗读体验。
• 使用 TalkBack 前，请先在 Android 设备的“设置 > 无障碍”中启用 TalkBack。

配置无障碍功能

推荐使用 CPDFAccessibilityConfig 统一配置 TalkBack 和键盘导航，再通过 setAccessibilityConfig() 应用到 CPDFReaderView。

import com.compdfkit.ui.reader.accessibility.CPDFAccessibilityConfig;

CPDFReaderView readerView = findViewById(R.id.readerview);

CPDFAccessibilityConfig accessibilityConfig = CPDFAccessibilityConfig.newBuilder()
        // 启用 TalkBack
        .setTalkBackEnabled(true)
        // 启用硬件键盘导航
        .setKeyboardNavigationEnabled(true)
        // 暴露 PDF 中可提取的文本内容
        .setExposeText(true)
        .build();

readerView.setAccessibilityConfig(accessibilityConfig);

配置完成后，用户可使用 TalkBack 浏览 PDF 文本内容。查看器会在切换页面或调整缩放比例时播报当前页码和缩放状态。

可通过以下代码获取当前配置状态：

CPDFAccessibilityConfig currentConfig = readerView.getAccessibilityConfig();

boolean talkBackEnabled = currentConfig.isTalkBackEnabled();
boolean keyboardNavigationEnabled = currentConfig.isKeyboardNavigationEnabled();

自定义朗读文案

你可以通过 AccessibilityLabelProvider 自定义 TalkBack 朗读的标题和状态描述，例如为每段 PDF 文本添加页码提示。

import com.compdfkit.ui.reader.accessibility.AccessibilityLabelContext;
import com.compdfkit.ui.reader.accessibility.AccessibilitySemanticNode;
import com.compdfkit.ui.reader.accessibility.strategy.AccessibilityLabelProvider;

readerView.setAccessibilityConfig(
        readerView.getAccessibilityConfig()
                .toBuilder()
                .setLabelProvider(new AccessibilityLabelProvider() {
                    @Override
                    public CharSequence getLabel(
                            AccessibilitySemanticNode node,
                            AccessibilityLabelContext context) {
                        CharSequence originalLabel = node.getLabel();
                        if (originalLabel == null || originalLabel.length() == 0) {
                            return null;
                        }

                        // 在原始文本前添加当前页码
                        return "第 " + (context.getPageIndex() + 1)
                                + " 页：" + originalLabel;
                    }

                    @Override
                    public CharSequence getStateDescription(
                            AccessibilitySemanticNode node,
                            AccessibilityLabelContext context) {
                        return "PDF 正文";
                    }
                })
                .build()
);

getLabel() 用于自定义朗读标题，getStateDescription() 用于补充状态说明。若返回 null，SDK 会保留原始朗读文案。

说明 使用 readerView.getAccessibilityConfig().toBuilder() 可以在保留现有 TalkBack、键盘导航和文本暴露配置的基础上，仅新增自定义朗读文案。

快捷启用方式

如果只需启用其中一项功能，也可以使用以下快捷方法：

// 仅启用 TalkBack 支持
readerView.setEnableAccessibility(true);

// 仅启用硬件键盘导航
readerView.setKeyboardNavigationEnabled(true);

如需关闭对应功能，将参数设置为 false：

readerView.setEnableAccessibility(false);
readerView.setKeyboardNavigationEnabled(false);

使用硬件键盘浏览文档

启用键盘导航后，用户可使用以下按键浏览 PDF：

按键	操作
方向键	在连续阅读模式下滚动页面；在单页模式下切换页面
Page Up / Page Down	跳转至上一页 / 下一页
Home / End	跳转至首页 / 末页
Space	向下滚动；Shift + Space 向上滚动
Ctrl + + / Ctrl + -	放大 / 缩小页面
Ctrl + 0	恢复为 100% 缩放
Tab / Shift + Tab	在页面文本内容间切换焦点
Enter 或方向键中键	朗读当前焦点内容
Esc	清除当前键盘焦点

你可以根据应用场景调整键盘导航行为：

// 设置方向键单次滚动距离为查看器宽度或高度的 20%
readerView.setKeyboardScrollStep(0.2f);

// 设置 Page Up、Page Down 和翻页时每次移动 2 页
readerView.setKeyboardPageStep(2);

// 双页模式下，设置键盘翻页时按单页移动
readerView.setKeyboardDoublePageNavigationBySpread(false);