本章导读：这是“寻迹校园 HarmonyOS NEXT 实战”系列第 40 篇。本文以 Bottom/Top/SideNavigation、ReportCard、ReportMedia、PublishFormPage 和 2026-08-12 焦点验收记录为依据，分析 ArkUI 页面如何用原生 Button、accessibilityText、accessibilityDescription、44×44vp 目标与正反向焦点链支持键盘和辅助技术，同时诚实记录当前图片删除按钮只有 28×28vp、屏幕阅读器全流程仍未完成等缺口。

上图为原创生成的无障碍交互插画，不是项目截图。可点击、可聚焦、可理解、可完成是四个不同层次；触屏能点到不能证明键盘和读屏可用。

一、可点击不等于可访问

一个卡片即使绑定 .onClick()，仍可能存在：

• Tab 无法进入；
• 焦点进入后没有可见反馈；
• 读屏只播报“按钮”，不知道操作对象；
• 图标按钮没有名称；
• 选中态只靠颜色；
• 触控区域小于视觉图标；
• Shift+Tab 跳出应用窗口；
• Phone 和 XL 结构变化后顺序混乱。

无障碍需要从组件语义、名称、操作描述、目标尺寸和运行焦点链共同验证。

二、本章的真实证据范围

证据	路径	能证明什么
导航组件	entry/src/main/ets/components/*Navigation.ets	原生 Button、名称与描述
首页卡片	entry/src/main/ets/pages/HomePage.ets	记录语义与选中说明
媒体组件	entry/src/main/ets/components/ReportMedia.ets	用户照片/品类兜底名称
发布表单	entry/src/main/ets/pages/PublishFormPage.ets	输入名称、照片添加/删除按钮
主题尺寸	common-ui/src/main/ets/theme/AppTheme.ets	44vp 触控目标基准
焦点记录	artifacts/runtime/xunji-responsive-focus-state-audit.md	Phone/XL 模拟器焦点链
精确输入记录	artifacts/runtime/xunji-exact-xl-breakpoint-input-audit.md	Tab/Shift+Tab 与 1280vp 输入

当前没有完整屏幕阅读器播报记录，因此本文不会把焦点测试写成读屏通过。

三、优先用原生 Button 承载动作

导航、记录卡片和候选操作优先使用 Button，而不是给普通 Row 绑定点击。原生交互组件更容易获得：

• 可聚焦语义；
• 系统按压反馈；
• 键盘触发；
• enabled/disabled 状态；
• 自动化定位；
• 辅助技术的控件角色。

普通容器也能补语义，但需要承担更多焦点与状态责任。

四、BottomNavigation 的可访问名称

Phone 底部导航为每项组合名称与状态：

.accessibilityText(
  `${label}${tab !== BottomTab.PUBLISH && this.selectedTab === tab ? '，已选中' : ''}`
)
.accessibilityDescription(
  tab === BottomTab.PUBLISH ? '打开登记类型选择' : `切换到${label}页面`
)

视觉上用户看到图标和短标签；辅助技术能听到“首页，已选中，切换到首页页面”。选中态不再只依赖品牌蓝。

五、Top 与 Side 为什么保持同一语义契约

md 的 TopNavigation 和 lg/xl 的 SideNavigation 虽然布局不同，都接收同一个 BottomTab 和 onSelect，并使用相同页面名称。

这样窗口跨断点后，用户不会在 Phone 听到“登记”，在大屏却听到“新增信息”这种不必要的概念变化。视觉编排可变，业务词汇应稳定。

六、登记按钮要描述目的而不是图标

中央加号的可访问名称不是“加号”，而是：

.accessibilityText('登记')
.accessibilityDescription('打开登记类型选择')

图标形状是视觉实现，用户真正需要知道的是点击后进入丢失/拾得登记类型选择。

七、ReportCard 如何播报一条记录

首页记录卡片组合业务字段：

private accessibilityLabel(): string {
  return `${this.statusLabel()}物品，${this.report.title}，` +
    `${this.report.area}，${this.report.timeLabel}，${this.report.description}`;
}

卡片还根据布局提供动作描述：Phone 为“打开物品详情”，分栏模式为“在右侧预览物品详情”；当前选中时变为“当前正在右侧预览”。

八、名称不能包含私密核验信息

辅助技术播报仍属于用户可感知输出。记录卡片只组合公开标题、区域、时间和公开描述，不应把拾得记录的私密核验特征、联系方式或剪贴板候选文本放进 accessibilityText。

无障碍不是扩大数据暴露范围，仍需遵守隐私分层。

九、ReportMedia 的两种名称

媒体组件根据来源提供不同文本：

.accessibilityText('用户上传的物品照片')

没有用户照片时，品类兜底图使用：

.accessibilityText(`${category}品类示意图`)

这一区分很重要：示意图不能播报成真实物品照片，否则辅助技术用户会得到比视觉用户更错误的事实。

十、44×44vp 是最低交互基准

主题定义：

export class AppSizes {
  static readonly TOUCH_TARGET: number = 44;
  static readonly CONTROL: number = 48;
  static readonly PRIMARY_BUTTON: number = 52;
}

PageHeader 返回按钮直接使用 TOUCH_TARGET，筛选和候选按钮多为 44vp，主操作常为 52vp。视觉图标可以只有 20–24vp，但外层 Button 应提供足够命中区域。

十一、当前图片删除按钮暴露了真实缺口

PublishFormPage 的照片删除按钮已经有明确名称：

.accessibilityText(`删除第 ${index + 1} 张照片`)

但当前尺寸是：

.width(28)
.height(28)

它小于项目自己的 44vp 基准。名称合格不代表目标尺寸合格；这是当前静态审计发现的待修复项，不能在文章中宣称“所有按钮都满足 44×44vp”。

十二、删除按钮应扩大命中区而非放大图标

建议保留 18vp 左右的关闭图标，把外层 Button 扩到 44×44vp，并使用透明或弱背景：

Button('×')
  .width(AppSizes.TOUCH_TARGET)
  .height(AppSizes.TOUCH_TARGET)
  .accessibilityText(`删除第 ${index + 1} 张照片`)

这样视觉重量不会变得笨重，触控、键盘和自动化定位却更稳定。本文只提出审计结论，没有修改项目代码。

十三、输入框为什么需要显式名称

Placeholder 不是可靠标签：用户输入后会消失，读屏行为也可能随组件和系统版本不同。发布表单为关键字段设置：

• 物品名称；
• 事件日期 或当前日期；
• 公开特征；
• 私密核验特征；
• 添加第 N 张照片；
• 打开系统图片选择器。

视觉标签、placeholder、错误文案和可访问名称应该互相补充，而不是互相替代。

十四、错误提示需要和字段形成关系

仅在字段下面显示红字，读屏焦点停留在输入框时可能不知道错误已经出现。理想实现需要：

• 字段名称稳定；
• 必填与格式要求可理解；
• 提交后焦点或播报定位到第一个错误；
• 错误文案描述如何修复；
• 红色不是唯一提示；
• 修复后错误状态及时清除。

当前文章只确认了部分字段名称和可见错误结构，没有完整读屏错误流证据。

十五、enabled 与颜色必须同时更新

禁用按钮既要使用 DISABLED/TEXT_DISABLED，也要设置 .enabled(false)。只改变颜色，键盘仍可能触发；只禁用不改变视觉，用户又看不出当前不可操作。

语义状态、视觉状态和交互状态必须一致。

十六、候选按钮怎样描述嵌入动作

MatchResultsPage 在独立模式和嵌入模式中动作不同：

.accessibilityDescription(
  this.embedded ? '在中间详情栏预览此候选' : '打开候选物品详情'
)

这比统一播报“查看详情”更准确，因为 XL 中点击后不会打开新页面，而是更新中栏。

十七、焦点顺序应服务任务顺序

Phone 首页的自然任务顺序是：

1. 搜索；
2. 类型筛选；
3. 组合筛选；
4. 记录卡片；
5. 底部导航；
6. 回到搜索。

XL 工作台则扩展为：搜索与筛选 → 左栏记录 → 中栏详情操作 → 小艺与候选 → 侧栏导航 → 搜索。

焦点顺序不是 DOM 越短越好，而是要符合用户完成任务的路径。

上图展示两套布局的焦点闭环。Phone 经过底栏回到搜索；XL 经过三栏与侧栏回到搜索，避免焦点跳入系统窗口区。

十八、为什么需要 Shift+Tab 反向测试

只测 Tab 正向可能遗漏：

• 最后一个控件反向无法回到内容区；
• 隐藏组件仍占据焦点顺序；
• 右栏末端候选无法进入；
• 自定义容器只支持单向点击；
• 焦点从侧栏跳出应用。

精确 1280vp 记录中，Tab 从无焦点进入侧栏首页，Shift+Tab 反向进入右栏末端候选按钮，证明了当时模拟器输入链路的双向可达性。

十九、布局断点变化后焦点链也会变化

sm 没有侧栏与右栏，xl 没有底部导航。断点切换后不能要求焦点节点完全相同，但必须保证：

• 当前布局所有关键动作可达；
• 不可见节点不继续接收焦点；
• 正反向顺序闭合；
• 业务选择状态不因焦点变化丢失；
• 用户可以回到搜索或全局导航。

焦点恢复和数据状态恢复应分别测试。

二十、2026-08-12 焦点验收记录

当时的 xunji-responsive-focus-state-audit.md 记录：

• xl 焦点链 passed；
• 焦点在搜索、筛选、4 张记录、中间详情、小艺、3 个候选、侧栏与搜索之间闭环；
• 377vp Phone 焦点链 passed；
• Phone 经过搜索、筛选、4 张记录、4 个底栏入口回到搜索；
• xl → lg → xl 状态恢复 passed。

这是模拟器与当时构建的证据，不能扩展为所有实体键盘或当前 release 包。

二十一、布局树证据与视觉截图各自证明什么

截图适合确认焦点高亮是否可见、页面是否被遮挡；布局树/节点记录适合确认控件名称、边界和当前焦点。

仅看截图无法确认读屏名称，仅读布局树也无法判断高亮是否足够明显。一次完整验收应保存两类证据，并记录输入动作序列。

二十二、空名称审计怎样做

可以按交互组件清单检查：

• 所有只显示图标的 Button；
• 图片添加/删除；
• 返回、关闭、更多；
• 选中型筛选；
• 候选卡片与状态卡片；
• 日期、Photo Picker、系统能力入口；
• XL 中的嵌入页面动作。

检查“名称为空”只是第一步，还要判断名称是否包含对象、状态和结果。

二十三、可访问名称不能使用视觉方向代替对象

“点击右边按钮”“蓝色图标”“上面的卡片”都依赖当前布局。断点变化后这些描述会失效。

更稳定的名称是：

• “切换到消息页面”；
• “删除第 2 张照片”；
• “在中间详情栏预览此候选”；
• “当前设备中的校园失物记录”；
• “返回上一页”。

名称应描述任务，不描述偶然位置。

二十四、屏幕阅读器为什么必须独立验收

键盘焦点通过只能证明控件可达和顺序基本可用。屏幕阅读器还涉及：

• 控件角色与名称组合；
• 状态变化播报；
• 列表数量与层级；
• 表单错误和必填；
• 图片替代文本；
• 弹窗与焦点锁定；
• 页面切换后的标题播报；
• 中文停顿与长文本可理解性。

当前项目没有完成读屏全流程，因此必须保持 not run。

二十五、实体外设仍需验证

模拟器注入的 KEYCODE_TAB 和 KEYCODE_SHIFT_LEFT + KEYCODE_TAB 能证明应用响应，但不能替代：

• 蓝牙键盘的系统组合键；
• 实体鼠标 hover 与点击；
• 触控板滚动；
• 外接显示器焦点切换；
• 输入法与快捷键冲突；
• 设备休眠恢复后的焦点。

特别是当前首发只声明 Phone，大屏外设仍属于后续能力验证。

二十六、无障碍验收清单

项目	当前证据	状态
Phone 正向焦点闭环	2026-08-12 模拟器记录	passed（有日期）
XL 正向焦点闭环	2026-08-12 模拟器记录	passed（有日期）
1280vp Shift+Tab	精确断点记录	passed（有日期）
导航可访问名称	当前代码静态检查	passed
Report/Media 名称	当前代码静态检查	passed
图片删除按钮 44vp	当前为 28×28vp	failed
屏幕阅读器全流程	无运行记录	not run
实体键鼠	无运行记录	not run

把缺口写进表格，比一句“已适配无障碍”更可审查。

二十七、工程复盘：无障碍是组件契约

如果共享导航、PageHeader、ReportCard 和媒体组件在底层拥有正确名称、尺寸与状态，新页面更容易继承一致行为。反之，每页临时给图标加点击，会快速积累空名称和小目标。

无障碍 Token、组件语义、页面焦点顺序和真机读屏验证应形成完整链路，不能只在上线前扫描一次。

二十八、本文小结

“寻迹校园”已经在导航、记录卡片、媒体、输入框和候选动作中使用原生 Button 与可访问名称，并留有 Phone/XL 模拟器焦点闭环和 1280vp 正反向输入证据。

但当前图片删除按钮仍只有 28×28vp，屏幕阅读器全流程和实体键鼠也未验证。准确结论是“部分组件语义与模拟器焦点链通过，仍有触控目标与读屏缺口”，而不是笼统宣称无障碍完成。

系列导航：第 40 篇 / 共 50 篇。上一篇：《1280vp 临界点状态恢复》；下一篇：《ReportMedia 三层媒体策略》。