Android 的无障碍 API 在 2019 到 2026 这七年里,走了一条“先补语义、再收权限、最后逼你做诚实分类”的路线。Android 10 关心的是“你读到的节点是不是一个输入键”;Android 11 收紧了无障碍按钮的注册方式;Android 12 把 AccessibilityService 的 Play 政策申报变成了上架前置条件;Android 14 让敏感视图可以选择性地只对“工具类”服务可见;Android 16 则直接废弃了一批公告 API,并把 isAccessibilityTool 变成高级保护模式下的准入开关。如果你手里维护的是一个需要跨 10–16 运行的 App,适配不能按“最新版本写了什么”来逐条打补丁,而应该按“哪些行为在某一个版本悄悄换了规则”来排优先级。
下面按版本拆解每个阶段真正需要开发者动手的东西,每个版本配一段 Trae 实操提示词,最后用 Compose 语义和权限模型收尾。
Android 10(API 29):输入键语义与用户自定义超时
Android 10 在无障碍方向加了两个对实际 UI 有影响的能力,它们都不是“大功能”,但缺了会让特定场景的 TalkBack 体验明显不完整。
AccessibilityNodeInfo.isTextEntryKey() 。这个方法用来判断一个节点是否代表软键盘或数字小键盘上的一个输入键。自定义输入法或者游戏内嵌键盘的开发者需要在自己的节点信息里正确回答这个查询,否则 TalkBack 可能不会把某个按键识别为可输入的键,或者给出错误的交互提示。
getRecommendedTimeoutMillis() 。Android 10 开始,用户可以系统级地设置交互元素的超时倍率,这个方法返回的是融合了用户偏好和服务端配置之后的建议超时值。对于有超时关闭逻辑的 Toast、Snackbar、自动消失的提示条,继续使用硬编码的 3000ms 或 5000ms 会直接违背用户的设置意图。正确的做法是把用户设置的超时作为基准,再叠加业务需要的额外时间。
Trae 实操:批量标记 isTextEntryKey 并替换硬编码超时
在 Trae 的 Chat 模式中选中自定义键盘的节点信息代码,输入:
“遍历这个自定义键盘的所有按键节点。在
onInitializeAccessibilityNodeInfo中,对每一个代表字符或数字的按键调用setTextEntryKey(true)。同时检查项目中所有硬编码的超时值(postDelayed、Handler、Toast的自定义 duration、自动消失的 Dialog),把固定毫秒数替换为view.getRecommendedTimeoutMillis(originalMs, FLAG_CONTENT_CONTROLS | FLAG_CONTENT_ICONS | FLAG_CONTENT_TEXT),并保留Build.VERSION.SDK_INT >= 29的回退。”
Trae 会生成带版本判断的替换建议,但硬编码超时的位置需要开发者自己确认——getRecommendedTimeoutMillis 的调用依赖 AccessibilityManager,在 View 不可用的情况下要能拿到正确的 Context。
Android 11(API 30):无障碍按钮从“运行时声明”迁到 metadata
Android 11 做了一个看起来很小、但会让旧代码静默失效的变更:AccessibilityServiceInfo.FLAG_REQUEST_ACCESSIBILITY_BUTTON 在运行时附加不再有效。即使你在 AccessibilityServiceInfo 的 flags 中加了这个标志,系统也不会把无障碍按钮的回调事件传给服务。要接收回调,必须在 res/raw/accessibilityservice.xml 的 accessibilityFlags 中添加 flagRequestAccessibilityButton。
这个变更的风险在于它不崩溃、不报错,按钮就是“不响应”。如果项目中有依赖无障碍快捷按钮触发核心功能的逻辑(比如快速启动某个辅助模式),升级到 targetSdk 30+ 后需要逐项检查 metadata 文件。
Trae 实操:审查运行时声明并生成 metadata 迁移
向 Trae 输入:
“在项目中搜索
FLAG_REQUEST_ACCESSIBILITY_BUTTON的所有使用位置。如果它出现在AccessibilityServiceInfo的运行时 flags 赋值中,标记为需要迁移。然后在res/raw/下生成或修改accessibilityservice.xml,在<accessibility-service>的android:accessibilityFlags属性中加入flagRequestAccessibilityButton。同时检查android:accessibilityEventTypes是否包含了必要的typeAllMask或特定事件类型。”
注意 metadata 文件的位置是 res/raw/ 而不是 res/xml/,这是 Android 11 前后都保持一致的历史约定。Trae 如果默认生成到 res/xml/,需要手动纠正。
Android 12(API 31):AccessibilityService 进入 Play 政策申报时代
Android 12 在技术 API 层面没有大规模新增无障碍方法,但它在分发层面加了一道门槛:targetSdk 31 且包含 AccessibilityService 的应用,必须在 Google Play Console 中完成无障碍权限的申报表单,否则上架会受阻。这不是一个可以靠代码绕过的变更,它要求开发者在产品定位层面回答一个问题:“你为什么需要使用 AccessibilityService。”
对于合法的辅助工具(屏幕阅读器、开关输入、语音控制、盲文支持),这道门槛是保护性的;对于用 AccessibilityService 做自动化、监控或系统增强的应用,它意味着需要在申报中诚实说明用途,并接受 Play 的审核。从 Android 12 开始, “能不能用”和“该不该用”开始分离。
Trae 实操:生成申报用的技术自述草稿
选中 metadata 文件和 AccessibilityService 的主要逻辑,向 Trae 输入:
“根据这个无障碍服务的实际功能,生成一段用于 Google Play 无障碍申报表单的技术自述。要求包括:服务监听的具体事件类型、读取的节点信息范围、执行的操作类型(例如手势、文本输入、滚动)、以及这个服务直接服务于哪一类残障用户。不要写营销语言,只陈述技术事实。”
Trae 可以帮你把分散在代码中的行为整理成一段结构化的文字,但最终申报内容的准确性由开发者负责——Play 的审核会对照应用的实际行为。
Android 13(API 33)与 Android 14(API 34):音频描述偏好与敏感视图的准入过滤
Android 13 加了一个对媒体类应用有意义的偏好查询:AccessibilityManager.isAudioDescriptionRequested() 。用户可以在系统设置中全局开启音频描述,应用可以查询这个偏好来决定是否自动播放带音频描述的媒体轨道,或者提供相应的 UI 入口。这不是强制性的,但正确响应它能让视障用户在观看视频时少走一步。
Android 14 的变更则更具结构性:accessibilityDataSensitive 属性与 isAccessibilityTool 开始联动。设置了 filterTouchesWhenObscured=true 的 View,在 Android 14 上会默认被视为 accessibilityDataSensitive,系统不再向无障碍服务报告这类 View 的事件,getWindows() 和 getRoot() 也可能返回 null。同时,ACCESSIBILITY_DATA_SENSITIVE_AUTO 的语义是:系统自动判断该 View 是否只允许 isAccessibilityTool=true 的服务与之交互。
这意味着,如果你是一个非工具类的 AccessibilityService,并且目标 View 被标记为敏感,你的节点读取和事件接收会在这里被切断。对于需要读取敏感界面(密码、支付确认、两步验证码)的非工具类服务,这是平台层面的结构性限制,不是靠重试或延迟能绕过的。
Trae 实操:标注敏感视图并审查节点的可读性
向 Trae 输入:
“检查项目中设置了
filterTouchesWhenObscured=true的 View。对于这些 View,确认它们是否确实包含敏感信息(密码、验证码、支付金额)。如果是,保持默认的敏感推断;如果业务上需要让工具类无障碍服务读取,显式设置setAccessibilityDataSensitive(ACCESSIBILITY_DATA_SENSITIVE_NO)并注释说明理由。另外,为媒体播放界面添加isAudioDescriptionRequested()的查询,如果返回 true,优先选择带音频描述的轨道或显示音频描述开关。”
setAccessibilityDataSensitive 的显式设置需要谨慎:把它设为 NO 会降低该 View 的保护级别,只应在确实需要工具类服务读取、且业务逻辑合理的情况下使用。
Android 15(API 35):盲文 HID 支持与 Compose 语义的稳定化
Android 15 在无障碍侧最实际的增量是 TalkBack 对 HID 标准盲文显示屏的支持,覆盖 USB 和安全蓝牙连接。对于开发面向盲文用户的 App 来说,这意味着不需要再依赖厂商私有的盲文驱动协议,标准 HID 盲文设备可以在更多场景下直接工作。技术适配层面不需要写新的 API,但需要在测试矩阵中加入 HID 盲文设备的行为验证。
到 Android 15 这个时间点,Compose 的语义 API 已经稳定,mergeDescendants、clearAndSetSemantics、isTraversalGroup、traversalIndex 成为 Compose 界面无障碍质量的核心调节手段。mergeDescendants = true 把父容器和后代的语义合并为一个 TalkBack 焦点,但已经在父级上设置了 clickable 的 Row 不需要再显式加 semantics(mergeDescendants = true) {} ,因为 clickable 本身已经创建了合并边界,重复声明不会改变行为,只会增加噪音。isTraversalGroup 和 traversalIndex 用于修正默认遍历顺序:traversalIndex 是一个浮点值,较小的值在遍历中优先被聚焦,它应该设置在会被 TalkBack 实际选中的子组件上,而不是无意义的容器上。
Trae 实操:生成 Compose 合并与遍历顺序修正
向 Trae 输入:
“这个 Compose Row 包含一个标题 Text、一个副标题 Text 和一个独立的 IconButton。当前 TalkBack 按布局顺序逐个读取,顺序不理想。请把父 Row 用
Modifier.semantics(mergeDescendants = true) { isTraversalGroup = true }标记为一个遍历分组,但不要在 Row 上重复添加空的semantics(mergeDescendants = true) {}如果它已经有clickable。为标题、副标题和 IconButton 分别设置traversalIndex为 0f、1f、2f,确保 IconButton 保持独立可聚焦。”
Trae 可能会生成冗余的合并声明,需要在审查时删掉。同时,traversalIndex 的效果需要在真机 TalkBack 下逐项滑动验证,不能只依赖代码逻辑推断。
Android 16(API 36):announceForAccessibility 废弃与 isAccessibilityTool 的硬约束
Android 16 在无障碍方向做了两件方向相反的事:收走了一组“广播式公告”API,同时把 isAccessibilityTool 从一个声明属性升级为高级保护模式下的实际准入条件。
announceForAccessibility 和 TYPE_ANNOUNCEMENT 事件被废弃,原因是这类脱离 UI 上下文的公告对 TalkBack 用户造成体验不一致。替代路径按场景拆分:窗口级变化改用 setAccessibilityPaneTitle,关键界面更新改用 setAccessibilityLiveRegion(需要谨慎控制粒度,避免每次重组都播报),错误通知改用 CONTENT_CHANGE_TYPE_ERROR 配合 setError。
isAccessibilityTool 的约束则更结构性。Advanced Protection Mode 在 Android 16 上开始限制 AccessibilityService 的使用,未分类为无障碍工具的应用,用户将无法授予其无障碍权限,已授予的也会被自动撤销。官方定义的“工具”包括屏幕阅读器、开关输入、语音输入、盲文访问等直接服务残障用户的应用;自动化、监控、启动器属于非工具类,应声明 isAccessibilityTool="false"。
这意味着,如果你的应用在 Android 10–15 的适配上一直靠 AccessibilityService 做“增强”或“自动化”,Android 16 的高级保护模式会直接把这条路径封死。适配策略不是在 metadata 里写 true 来“骗过”分类,而是要么重新定位为真正的辅助工具,要么为非工具类服务准备降级路径。
Trae 实操:替换废弃公告并审查 isAccessibilityTool 声明
向 Trae 输入:
“在项目中搜索
announceForAccessibility和TYPE_ANNOUNCEMENT。逐处给出替代建议:Dialog 标题变化改用setAccessibilityPaneTitle;需要用户感知的列表更新改用setAccessibilityLiveRegion,并标记出哪些场景可能在频繁刷新时造成过度播报;错误提示改用CONTENT_CHANGE_TYPE_ERROR配合setError。然后检查res/xml/下的accessibility-servicemetadata,判断isAccessibilityTool是否应该为true:如果服务的主要目的是屏幕阅读、开关输入、语音输入或盲文访问,为true;如果是自动化、监控、启动器或系统增强,为false。不要为了让权限不被撤销而写true。”
Trae 在无障碍场景下的代码生成能力已经在多个实际项目中被验证——它可以根据自然语言描述生成 AccessibilityService 的节点查找、状态判断和等待重试骨架。但权限分类的判断必须由开发者做,因为 isAccessibilityTool 的准确性直接关联到 Play 审核和高级保护模式下的实际行为。
跨版本优先级:如果你只有一个适配窗口
如果维护的是一个 minSdk 26、targetSdk 36 的 App,不需要按 10→16 逐版本线性适配,而是按行为变更的破坏力排优先级:
第一优先级(会直接导致功能失效或审核受阻) :Android 11 的无障碍按钮 metadata 迁移、Android 12 的 Play 申报、Android 14 的 accessibilityDataSensitive 对非工具类服务的节点读取限制、Android 16 的 isAccessibilityTool 在高级保护模式下的权限撤销。这四个点中任何一个被忽略,都可能导致某个功能在特定版本或特定用户设置下静默失效。
第二优先级(影响 TalkBack 体验但不至于崩坏) :Android 10 的 isTextEntryKey 和超时 API、Android 16 的公告 API 替代路径。这些是“做了更好、不做用户会感觉到粗糙”的项。
第三优先级(增量能力) :Android 13 的音频描述偏好、Android 15 的盲文 HID。按产品是否需要这些场景来决定投入。
Trae 在这个跨版本工作流中的定位始终是代码生成和模式匹配式审查——它擅长批量找到废弃 API 的调用点、生成带 Build.VERSION.SDK_INT 分支的骨架、把分散的节点信息逻辑整理成结构化描述。但版本行为的实际验证必须回到 Android Studio 和真机:TalkBack 的播报顺序、live region 的打断程度、高级保护模式下的权限撤销行为,这些都无法从代码逻辑完全推断,需要在对应 API 级别的设备上逐项观察。把 Trae 用在“适配的覆盖面”上,把真机验证用在“适配的准确度”上,七年跨度的无障碍适配才不会变成一场靠记忆和猜测的考古。