• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 支持无障碍
2<!--Kit: ArkUI-->
3<!--Subsystem: ArkUI-->
4<!--Owner: @zhanghangkai10241-->
5<!--Designer: @lmleon-->
6<!--Tester: @fredyuan0912-->
7<!--Adviser: @HelloCrease-->
8
9## 概述
10
11ArkUI提供了丰富的无障碍能力，使开发者能够创建可访问的应用界面，满足视觉、听觉、运动和认知障碍等用户的需求。
12
13组件的[无障碍属性](../reference/apis-arkui/arkui-ts/ts-universal-attributes-accessibility.md)变化时，会触发辅助工具重新读取组件信息、无障碍服务重新扫描组件树、状态播报、虚拟节点动态更新等响应，这些机制确保辅助工具（如屏幕朗读）能及时感知并适配变化，为障碍用户提供连贯的体验。
14
15## 设置无障碍分组
16
17accessibilityGroup属性，用于设置是否启用无障碍分组。若启用，则该组件及其所有子组件将作为一个整体处理，无障碍服务不再单独处理各子组件。accessibilityGroup属性支持以下值：
18
19- false（默认）：不启用无障碍分组。
20
21- true：启用无障碍分组。
22
23这里以Column组件为例，启用无障碍分组：
24
25```ts
26Column() {
27  Text("HelloWorld").fontSize(50).fontWeight(FontWeight.Bold)
28}
29.accessibilityGroup(true)
30```
31
32## 设置无障碍重要性
33
34accessibilityLevel属性表示组件的无障碍重要性，用于控制组件是否能被无障碍服务识别，支持以下值：
35
36- "auto"（默认）：当前组件由无障碍分组服务和ArkUI进行综合判断组件是否可被无障碍辅助服务所识别。
37
38- "yes"：当前组件可被无障碍辅助服务所识别。
39
40- "no"：当前组件不可被无障碍辅助服务所识别。
41
42- "no-hide-descendants"：当前组件及其所有子组件均不可被无障碍辅助服务所识别。
43
44这里以Column组件为例，设置其无障碍重要性为可被无障碍辅助服务所识别：
45
46```ts
47Column() {
48  Text("HelloWorld").fontSize(50).fontWeight(FontWeight.Bold)
49}
50.accessibilityGroup(true)
51.accessibilityLevel("yes")
52```
53
54## 设置无障碍文本
55
56accessibilityText属性用于为无文本内容的组件提供朗读文本。若组件已有文本，则优先播报无障碍文本。
57
58支持字符串或资源引用。
59
60这里以Column组件为例，设置其无障碍文本为“分组”：
61
62```ts
63Column() {
64  Text("HelloWorld").fontSize(50).fontWeight(FontWeight.Bold)
65}
66.accessibilityGroup(true)
67.accessibilityLevel("yes")
68.accessibilityText("分组")
69```
70
71## 设置无障碍说明
72
73accessibilityDescription属性用于提供更详细的组件说明，播报时紧随文本内容之后。
74
75这里以Column组件为例，设置其无障碍说明为“分组”：
76
77```ts
78Column() {
79  Text("HelloWorld")
80}
81.accessibilityGroup(true)
82.accessibilityLevel("yes")
83.accessibilityText("分组")
84.accessibilityDescription("Column组件可以被选中，播报的内容是“分组”")
85```
86
87## 设置无障碍虚拟子节点
88
89accessibilityVirtualNode属性，用于为自绘制组件添加虚拟无障碍节点，辅助工具会读取这些节点的信息而非实际显示内容。
90
91```ts
92@Entry
93@Component
94struct VirtualNodeExample {
95  @Builder customAccessibilityNode() {
96    Text("文本2")
97      .fontSize(50)
98      .fontWeight(FontWeight.Bold)
99  }
100
101  build() {
102    Column() {
103      Text("文本1")
104        .fontSize(50)
105        .fontWeight(FontWeight.Bold)
106    }
107    .accessibilityGroup(true)
108    .accessibilityLevel("yes")
109    .accessibilityVirtualNode(this.customAccessibilityNode)
110  }
111}
112```
113
114## 设置无障碍节点是否被选中
115
116accessibilityChecked和accessibilitySelected是两个用于增强无障碍体验的属性，主要用于向屏幕朗读等辅助工具传达组件的选中状态。
117
118### 在支持多选的情况下，设置无障碍节点是否被选中
119
120accessibilityChecked属性，用于表示组件在支持多选的情况下是否被勾选（如复选框、开关按钮等二态或三态组件），适用于需要明确“选中/未选中”语义的场景，支持以下值：
121
122- undefined（默认）：由系统自动判断（依赖组件自身的状态，如Toggle组件的isOn属性）。
123
124- false：未选中。
125
126- true：选中（如复选框打勾）。
127
128这里以Column组件为例，设置其在支持多选的情况下被选中：
129
130```ts
131Column() {
132  Text("HelloWorld").fontSize(50).fontWeight(FontWeight.Bold)
133}
134.accessibilityGroup(true)
135.accessibilityLevel("yes")
136.accessibilityText("分组")
137.accessibilityDescription("Column组件可以被选中，播报的内容是“分组”")
138.accessibilityChecked(true)
139```
140
141### 在支持单选的情况下，设置无障碍节点是否被选中
142
143accessibilitySelected属性，用于表示组件在支持单选的情况下是否被选择（如单选列表项、标签页等），适用于需要区分“当前选中项”的场景（如单选组、导航菜单），支持以下值：
144
145- undefined（默认）：由系统自动判断。
146
147- false：未选中。
148
149- true：当前选中。
150
151这里以Column组件为例，设置在支持单选的情况下由系统自行确定其选中状态：
152
153```ts
154Column() {
155  Text("HelloWorld").fontSize(50).fontWeight(FontWeight.Bold)
156}
157.accessibilityGroup(true)
158.accessibilityLevel("yes")
159.accessibilityText("分组")
160.accessibilityDescription("Column组件可以被选中，播报的内容是“分组”")
161.accessibilitySelected(undefined)
162```
163
164### accessibilityChecked属性与accessibilitySelected属性的关键区别
165
166在ArkUI无障碍属性中，accessibilityChecked和accessibilitySelected均用于表示组件的状态，但二者应用场景与语义含义存在本质差异。以下是二者的对比：
167
168| 属性    | accessibilityChecked     | accessibilitySelected |
169| ------- | ------------------------ | --------------------- |
170| 常见场景 | 复选框、开关等二态/三态组件。 | 单选列表、标签页等互斥选择场景。 |
171| 语义目标 | 控件物理状态（如开关是否打开）。 | 导航焦点项（如列表当前选中项）。 |
172| 状态持久性 | 通常需显式保存（如表单提交）。 | 临时性（随焦点移动变化）。 |
173| 典型组件 | Checkbox，Toggle。         | List，Tabs。        |
174
175## 使用建议
176
177- 优先级控制
178
179  通过accessibilityLevel确保关键操作可被识别。
180
181- 语义化描述
182
183  为图标、图片等非文本元素添加accessibilityText和accessibilityDescription。
184
185- 分组优化
186
187  对复杂布局使用accessibilityGroup减少冗余播报。
188
189## 场景示例
190
191该示例主要演示accessibilityText无障碍文本和accessibilityDescription无障碍说明的播报内容。
192
193其中，对于该组件的无障碍文本的内容，在既拥有文本属性又拥有无障碍文本属性的情况下，当组件被选中时，仅播报无障碍文本内容。
194
195```ts
196@Entry
197@Component
198struct Index {
199
200  @Builder customAccessibilityNode() {
201    Column() {
202      Text(`virtual node`)
203    }
204    .width(10)
205    .height(10)
206  }
207
208  build() {
209    Row() {
210      Column() {
211        Text("文本1")
212          .fontSize(50)
213          .fontWeight(FontWeight.Bold)
214        Text("文本2")
215          .fontSize(50)
216          .fontWeight(FontWeight.Bold)
217      }
218      .width('100%')
219      .accessibilityGroup(true)
220      .accessibilityLevel("yes")
221      .accessibilityText("分组")
222      .accessibilityDescription("Column组件可以被选中，播报的内容是“分组”")
223      .accessibilityVirtualNode(this.customAccessibilityNode)
224      .accessibilityChecked(true)
225      .accessibilitySelected(undefined)
226    }
227    .height('100%')
228  }
229}
230```
231
232![zh-cn_image_0000001745415556](figures/zh-cn_image_0000001745415556.jpg)
233