SwiftUI 无障碍模式参考目录核心原则动态类型与 ScaledMetric无障碍特征装饰性图像元素分组自定义控件总结清单核心原则可点击元素优先使用Button而非onTapGesture。Button免费提供 VoiceOver 支持、焦点处理和正确的特征。动态类型与 ScaledMetric系统文本样式会自动随动态类型缩放。当内置样式适合你的 UI 时优先使用诸如.largeTitle、.title、.title2、.title3、.headline、.subheadline、.body、.callout、.footnote、.caption和.caption2等样式VStack(alignment:.leading){Text(Inbox).font(.title2)Text(3 unread messages).font(.body)Text(Updated just now).font(.caption)}对于自定义字体使用支持动态类型的字体初始化器使文本仍然遵循用户偏好的内容尺寸VStack(alignment:.leading){Text(Article).font(.custom(SourceSerif4-Semibold,size:28,relativeTo:.title2))Text(Body copy).font(.custom(SourceSerif4-Regular,size:17))}Font.custom(_:size:relativeTo:)让你匹配特定的文本样式。Font.custom(_:size:)则相对于 body 样式缩放。对于应响应动态类型的主要内容避免使用固定尺寸的自定义字体。对于非文本的数值如内边距、间距和图像尺寸使用ScaledMetricstructProfileHeader:View{ScaledMetricprivatevaravatarSize60.0ScaledMetricprivatevarspacing12.0varbody:someView{HStack(spacing:spacing){Image(avatar).resizable().frame(width:avatarSize,height:avatarSize)Text(Username)}}}当数值应跟随特定动态类型样式时指定relativeTo文本样式包括应保持与附近文本成比例的图像或图标structStatusRow:View{ScaledMetric(relativeTo:.body)privatevariconSize18.0varbody:someView{HStack(spacing:8){Image(systemName:checkmark.circle.fill).font(.system(size:iconSize))Text(Synced).font(.custom(AvenirNext-Regular,size:17,relativeTo:.body))}}}无障碍特征使用accessibilityAddTraits和accessibilityRemoveTraits处理由状态驱动的特征Text(item.title).accessibilityAddTraits(item.isSelected?[.isSelected,.isButton]:.isButton)对非交互元素使用.disabled(true)让 VoiceOver 播报Dimmed变暗。装饰性图像当资源图像纯粹是视觉性的、不应出现在无障碍树中时使用Image(decorative:bundle:)。Image(decorative:confetti)这适用于背景、装饰元素以及不会在附近文本之外添加含义的图标。如果图像传达了信息请保持其可访问并提供清晰的标签Image(receipt).accessibilityLabel(Receipt)对于非资源图像如 SF Symbols改用accessibilityHidden(true)隐藏装饰性内容Image(systemName:sparkles).accessibilityHidden(true)元素分组.combine – 自动合并子标签HStack{Image(systemName:star.fill)Text(Favorites)Text((\(count)))}.accessibilityElement(children:.combine)VoiceOver 将所有子标签作为一个元素朗读用逗号分隔。.ignore – 为容器手动设置标签HStack{Text(item.name)Spacer()Text(item.price)}.accessibilityElement(children:.ignore).accessibilityLabel(\(item.name),\(item.price)).contain – 语义分组HStack{ForEach(tabs){tabinTabButton(tab:tab)}}.accessibilityElement(children:.contain).accessibilityLabel(Tab bar)当焦点进入/离开时VoiceOver 会播报容器名称。自定义控件可调节控件递增/递减PageControl(selectedIndex:$selectedIndex,pageCount:pageCount).accessibilityElement().accessibilityValue(Page\(selectedIndex1)of\(pageCount)).accessibilityAdjustableAction{directioninswitchdirection{case.increment:guardselectedIndexpageCount-1else{break}selectedIndex1case.decrement:guardselectedIndex0else{break}selectedIndex-1unknowndefault:break}}将自定义视图表示为原生控件当自定义视图在无障碍方面应表现得像原生控件时HStack{Text(label)Toggle(,isOn:$isOn)}.accessibilityRepresentation{Toggle(label,isOn:$isOn)}标签-内容配对NamespaceprivatevarnsHStack{Text(Volume).accessibilityLabeledPair(role:.label,id:volume,in:ns)Slider(value:$volume).accessibilityLabeledPair(role:.content,id:volume,in:ns)}总结清单可点击元素使用Button而非onTapGesture文本使用内置文本样式或支持动态类型的自定义字体应随动态类型缩放的自定义数值使用ScaledMetric将纯装饰性图像标记为装饰性的或对无障碍隐藏使用accessibilityElement(children:)对相关元素分组默认标签不清楚时提供accessibilityLabel自定义控件使用accessibilityRepresentation递增/递减控件使用accessibilityAdjustableAction使用 VoiceOver 分组时确保导航流程合乎逻辑