1.4 无障碍修饰符

5 分钟阅读

原文链接: https://developer.apple.com/documentation/swiftui/view-accessibility

1.4 无障碍修饰符

让你的 SwiftUI 应用对所有人可用，包括有身体障碍的人。

概述

与所有 Apple UI 框架一样，SwiftUI 自带无障碍支持。框架会内省导航视图、列表、文本输入框、滑块、按钮等常见元素，并默认提供基本的无障碍标签和值。你无需做任何额外工作就能启用这些标准无障碍功能。

SwiftUI 还提供了一些工具，帮助你增强应用的无障碍性。例如，你可以用 accessibilityLabel(_:) 或 accessibilityValue(_:) 视图修饰符，为界面中的元素显式添加无障碍标签。

要了解更多关于为应用添加无障碍功能的内容，参见无障碍基础。

值

accessibilityValue(_:) —— 添加对视图所含值的文本描述。
accessibilityValue(_:isEnabled:) —— 添加对视图所含值的文本描述。

提示

accessibilityHint(_:) —— 告诉用户执行该视图的动作之后会发生什么。
accessibilityHint(_:isEnabled:) —— 告诉用户执行该视图的动作之后会发生什么。

动作

accessibilityAction(::) —— 为视图添加一个无障碍动作。动作让 VoiceOver 这类辅助技术可以通过调用该动作来与视图交互。
accessibilityActions(_:) —— 为视图添加多个无障碍动作。
accessibilityActions(category:_:) —— 为视图添加多个属于特定类别的无障碍动作。动作让 VoiceOver 这类辅助技术可以通过调用该动作来与视图交互，并按类别归组。对同一个视图应用多个类别相同的动作修饰符时，这些动作会合并在一起。
accessibilityAction(named:_:) —— 为视图添加一个无障碍动作。动作让 VoiceOver 这类辅助技术可以通过调用该动作来与视图交互。
accessibilityAction(action:label:) —— 为视图添加一个无障碍动作。动作让 VoiceOver 这类辅助技术可以通过调用该动作来与视图交互。
accessibilityAction(intent:label:) —— 为视图添加一个以 label 内容为标签的无障碍动作。动作让 VoiceOver 这类辅助技术可以通过调用该动作来与视图交互。动作被执行时会调用 intent。
accessibilityAction(_:intent:) —— 为视图添加一个表示 actionKind 的无障碍动作。动作让 VoiceOver 这类辅助技术可以通过调用该动作来与视图交互。动作被执行时会调用 intent。
accessibilityAction(named:intent:) —— 为视图添加一个标签为 name 的无障碍动作。动作让 VoiceOver 这类辅助技术可以通过调用该动作来与视图交互。动作被执行时会调用 intent。
accessibilityAdjustableAction(_:) —— 为视图添加一个可调节的无障碍动作。动作让 VoiceOver 这类辅助技术可以通过调用该动作来与视图交互。
accessibilityScrollAction(_:) —— 为视图添加一个无障碍滚动动作。动作让 VoiceOver 这类辅助技术可以通过调用该动作来与视图交互。
accessibilityScrollStatus(_:isEnabled:) —— 更改用户滚动该视图内某个滚动视图时，无障碍技术所播报的内容。

手势

accessibilityActivationPoint(_:) —— 元素的激活点是辅助技术用来发起手势的位置。
accessibilityActivationPoint(_:isEnabled:) —— 元素的激活点是辅助技术用来发起手势的位置。
accessibilityDragPoint(_:description:) —— 辅助技术开始拖拽交互时应使用的点。
accessibilityDragPoint(_:description:isEnabled:) —— 辅助技术开始拖拽交互时应使用的点。
accessibilityDropPoint(_:description:) —— 辅助技术结束拖拽交互时应使用的点。
accessibilityDropPoint(_:description:isEnabled:) —— 辅助技术结束拖拽交互时应使用的点。
accessibilityDirectTouch(_:options:) —— 显式设置该无障碍元素是否为直接触控区域。直接触控区域会把触摸事件透传给应用，而不是由 VoiceOver 这类辅助技术处理。该修饰符接受可选的 AccessibilityDirectTouchOptions 选项集，用来定制直接触控区域的功能。
accessibilityZoomAction(_:) —— 为视图添加一个无障碍缩放动作。动作让 VoiceOver 这类辅助技术可以通过调用该动作来与视图交互。

元素

accessibilityElement(children:) —— 创建一个新的无障碍元素，或者修改已有无障碍元素的 AccessibilityChildBehavior。
accessibilityChildren(children:) —— 用一个或多个新的合成无障碍元素替换已有无障碍元素的子元素。
accessibilityHidden(_:) —— 指定是否在系统无障碍功能中隐藏该视图。
accessibilityHidden(_:isEnabled:) —— 指定是否在系统无障碍功能中隐藏该视图。

自定义控件

accessibilityRepresentation(representation:) —— 用新的无障碍元素替换该视图的一个或多个无障碍元素。
accessibilityRespondsToUserInteraction(_:) —— 显式设置该无障碍元素是否响应用户交互，从而会被「切换控制」「语音控制」或「全键盘访问」这类技术进行交互。
accessibilityRespondsToUserInteraction(_:isEnabled:) —— 显式设置该无障碍元素是否响应用户交互，从而会被「切换控制」「语音控制」或「全键盘访问」这类技术进行交互。

自定义内容

accessibilityCustomContent(::importance:) —— 为视图添加额外的无障碍信息。

使用转子

accessibilityRotor(_:entries:) —— 用指定的用户可见标签、以及由内容闭包生成的条目，创建一个无障碍转子。
accessibilityRotor(_:entries:entryID:entryLabel:) —— 用指定的用户可见标签和条目创建一个无障碍转子。
accessibilityRotor(_:entries:entryLabel:) —— 用指定的用户可见标签和条目创建一个无障碍转子。
accessibilityRotor(_:textRanges:) —— 用指定的用户可见标签、并为每个指定范围创建条目，从而创建一个无障碍转子。该转子会附着到当前无障碍元素上，每个条目都会指向该元素中指定的范围。

配置转子

accessibilityRotorEntry(id:in:) —— 定义一个显式标识符，把该视图的无障碍元素与无障碍转子中的某个条目绑定起来。
accessibilityLinkedGroup(id:in:) —— 把多个无障碍元素链接起来，让人们可以快速从一个元素导航到另一个元素，即使这些元素在无障碍层级中并不相邻。
accessibilitySortPriority(_:) —— 设置该视图无障碍元素相对于同一层级其他元素的排序优先级。

焦点

accessibilityFocused(_:) —— 把该视图无障碍元素的焦点状态绑定到给定的布尔状态值，从而修改该视图。
accessibilityFocused(_:equals:) —— 把该视图无障碍元素的焦点状态绑定到给定的状态值，从而修改该视图。
accessibilityDefaultFocus(::) —— 通过给某个无障碍焦点状态绑定赋值，定义评估默认无障碍焦点的区域。

特征

accessibilityAddTraits(_:) —— 为视图添加给定特征。
accessibilityRemoveTraits(_:) —— 从该视图移除给定特征。

身份

accessibilityIdentifier(_:) —— 用你指定的字符串标识该视图。
accessibilityIdentifier(_:isEnabled:) —— 用你指定的字符串标识该视图。

颜色反转

accessibilityIgnoresInvertColors(_:) —— 设置该视图是否应忽略系统的「智能反转」设置。

内容描述

accessibilityTextContentType(_:) —— 设置无障碍文本内容类型。
accessibilityHeading(_:) —— 设置该标题的无障碍级别。

VoiceOver

speechAdjustedPitch(_:) —— 提高或降低朗读文本的音高。
speechAlwaysIncludesPunctuation(_:) —— 设置 VoiceOver 是否应始终朗读文本视图中的所有标点。
speechAnnouncementsQueued(_:) —— 控制是让待播报内容排队等待现有朗读结束，还是打断正在进行的朗读。
speechSpellsOutCharacters(_:) —— 设置 VoiceOver 是否应逐字符朗读文本视图的内容。

图表

accessibilityChartDescriptor(_:) —— 为表示图表的视图添加描述符，让图表内容对所有用户都可访问。

大内容

accessibilityShowsLargeContentViewer() —— 添加由大内容查看器显示的默认大内容视图。
accessibilityShowsLargeContentViewer(_:) —— 添加由大内容查看器显示的自定义大内容视图。

快捷操作

accessibilityQuickAction(style:content:) —— 添加在激活时由系统显示的快捷操作。
accessibilityQuickAction(style:isActive:content:) —— 添加在激活时由系统显示的快捷操作。

使用辅助访问

assistiveAccessNavigationIcon(_:) —— 为导航用途配置该视图的图标。
assistiveAccessNavigationIcon(systemImage:) —— 为导航用途配置该视图的图标。

最后修改 September 13, 2026: 更新C和Cpp以及新增Kotlin和SwiftUI (d20dcaaa6)