SwiftUI — @Environment

SwiftUI 中,EnvironmentEnvironment Values(环境值)提供了一种机制,帮助开发者在整个视图层次结构中轻松共享数据。环境值是 SwiftUI 内置的全局设置,允许我们在不同视图层级中访问和动态调整系统属性。

以下是 SwiftUI 支持的主要 Environment Values 分类和常见值的表格说明。


1. 颜色和主题 #

属性名类型描述版本要求
colorSchemeColorScheme当前的浅色模式(.light)或深色模式(.dark)。iOS 13+ / macOS 10.15+
colorSchemeContrastColorSchemeContrast当前颜色主题的对比度设置(.standard.increased)。iOS 14+ / macOS 11+
accentColorColor?当前界面的默认强调颜色(已被 tint 替代)。iOS 13+ / macOS 10.15+
tintColor?当前界面控件的默认主题色(推荐使用,替代 accentColor)。iOS 15+ / macOS 12+

2. 布局与尺寸 #

属性名类型描述版本要求
layoutDirectionLayoutDirection当前布局方向(.leftToRight.rightToLeft,用于支持多种语言)。iOS 13+ / macOS 10.15+
sizeCategoryContentSizeCategory当前的动态字体大小设置(支持辅助功能,如 .large, .extraLarge)。iOS 13+ / macOS 10.15+
defaultMinListRowHeightCGFloat列表中每一行的最小高度。iOS 13+ / macOS 10.15+
defaultMinListHeaderHeightCGFloat列表头部(Section Header)的最小高度。iOS 13+ / macOS 10.15+
pixelLengthCGFloat一个逻辑点单位对应的像素值(在屏幕坐标中);用于高 DPI 的屏幕适配。iOS 14+ / macOS 11+
windowSizeCGSize获取窗口当前的实际尺寸(适用于 macOS 和 iPadOS 多窗口应用)。iOS 16+ / macOS 13+

3. 动画与交互 #

属性名类型描述版本要求
transactionTransaction当前动画事务的对象,控制视图更新时的动画行为。iOS 13+ / macOS 10.15+
isEnabledBool如果当前交互状态禁用,则环境中的 isEnabled 会为 false(如在按钮状态下)。iOS 15+ / macOS 12+
controlActiveStateControlActiveState当前控件是否处于激活状态(如 .key, .active, .inactive)。iOS 13+ / macOS 10.15+

4. 可访问性(Accessibility) #

属性名类型描述版本要求
accessibilityEnabledBool当前是否启用了辅助功能(如 VoiceOver)。iOS 13+ / macOS 10.15+
reduceMotionBool查询用户是否在系统中启用了「减少动态效果」。iOS 13+ / macOS 10.15+
reduceTransparencyBool用户是否启用了「减少透明度」。iOS 13+ / macOS 10.15+
accessibilityInvertColorsBool是否启用了「反转颜色」的辅助功能。iOS 13+ / macOS 10.15+
buttonShapeBool用户是否启用了「显示按钮形状」选项(适用于按钮的可视化提示)。iOS 13+ / macOS 10.15+

5. 本地化与语言 #

属性名类型描述版本要求
layoutDirectionLayoutDirection当前语言对应的布局方向(如从左到右 LTR,或从右到左 RTL)。iOS 13+ / macOS 10.15+
localeLocale当前应用使用的本地化语言设置。iOS 13+ / macOS 10.15+
calendarCalendar当前系统所使用的日历(如公历或阴历)。iOS 13+ / macOS 10.15+
timeZoneTimeZone当前的系统时区设置。iOS 13+ / macOS 10.15+

6. 滚动与导航 #

属性名类型描述版本要求
scrollViewContentOffsetCGPoint表示 ScrollView 的滚动偏移量。iOS 16+ / macOS 13+
navigationBarHiddenBool是否隐藏导航栏。iOS 13+ / macOS 10.15+
navigationBarBackButtonHiddenBool是否隐藏导航栏的返回按钮。iOS 13+ / macOS 10.15+

7. 设备和系统行为 #

属性名类型描述版本要求
deviceSupportsHapticsBool查询当前设备是否支持 Haptic 触觉反馈(如震动效果)。iOS 13+ / macOS 10.15+
deviceSupportsMultitaskingBool判断是否支持多任务窗口(iPad 的 SlideOver 或 SplitView)。iOS 14+ / macOS 11+
scenePhaseScenePhase检测当前 App 的场景状态:如 .active(活跃)、.inactive(暂停)或 .background(后台)。iOS 14+ / macOS 11+

8. 输入法与键盘 #

属性名类型描述版本要求
keyboardTypeUIKeyboardType表示当前输入框的键盘类型(数字键盘、邮件键盘等)。iOS 13+ / macOS 10.15+
keyboardHiddenBool当前是否隐藏键盘状态。iOS 15+ / macOS 12+
textInputAutocapitalizationTextInputAutocapitalization当前输入框中的自动大写状态。iOS 15+ / macOS 12+

如何使用 Environment Values #

  1. 通过 @Environment 访问特定值
    • 使用 @Environment 自动获取视图环境中提供的值。
struct ContentView: View {
    @Environment(\.colorScheme) var colorScheme

    var body: some View {
        Text("Current Mode: \(colorScheme == .light ? "Light" : "Dark")")
            .foregroundColor(colorScheme == .light ? .black : .white)
            .padding()
    }
}
  1. 自定义 Environment
    • SwiftUI 支持将自定义值注入到视图环境中:
extension EnvironmentValues {
    var customValue: String {
        get { self[CustomValueKey.self] }
        set { self[CustomValueKey.self] = newValue }
    }
}

private struct CustomValueKey: EnvironmentKey {
    static let defaultValue: String = "Default"
}

// 使用
struct CustomEnvironmentView: View {
    @Environment(\.customValue) var customValue: String

    var body: some View {
        Text("Custom Value: \(customValue)")
    }
}

总结 #

SwiftUI 中的Environment Values主要分类包括以下:

  • 颜色和主题colorScheme, tint 等)
  • 布局与尺寸sizeCategory, layoutDirection 等)
  • 动画与交互isEnabled, transaction 等)
  • 可访问性支持reduceMotion, accessibilityInvertColors 等)
  • 本地化与语言支持locale, calendar, timeZone 等)
  • 滚动与导航scrollViewContentOffset, navigationBarHidden 等)
  • 设备与系统行为scenePhase, deviceSupportsHaptics 等)
  • 输入法和键盘keyboardType, textInputAutocapitalization 等)

通过 @Environment,你可以优雅地获取和设置这些全局环境值,在视图层级中实现动态行为和响应式设计。

本文共 1644 字,上次修改于 Jan 11, 2025