ThemeKit for SwiftUI
基于 SwiftUI Environment 的主题管理组件，统一管理颜色、字体、圆角等视觉变量，支持动态深色模式与高对比显示，可运行时切换、持久化与远端配置。适用于多品牌皮肤与大型项目的视觉一致性建设。目标平台：iOS 14+，集成复杂度：简单。
功能概述
ThemeKit 通过 SwiftUI 的 Environment 和 EnvironmentObject 将主题作为一等公民贯穿视图层，提供统一的设计令牌（Design Tokens）访问方式。开发者可在不入侵业务代码的前提下，按品牌或场景定义主题包并在运行时切换；同时支持将用户选择持久化，并可接入远端配置以实现灰度与个性化方案。
适用场景：
- 多品牌或多皮肤项目的视觉规范落地与切换
- 统一颜色、字体、圆角等设计令牌的访问和管理
- 动态适配系统深色模式与高对比设置
- 需要远端下发主题配置的大型应用
特性列表
- 基于 SwiftUI Environment 的轻量集成与全局传递
- 统一的 Design Tokens：颜色、字体、圆角等
- 动态深色模式与高对比显示自动适配
- 运行时主题切换与全局刷新
- 多种持久化策略（示例含 UserDefaults）
- 远端配置兼容（可从 JSON 解码为主题包）
- 协议化设计与扩展点，方便自定义与扩展
- 适配 iOS 14+，示例不依赖 async/await
使用方法
集成步骤
- 引入
- 通过 Swift Package Manager 引入组件，或直接将源码文件添加到项目中。
- 在 App 根视图注入主题
- 创建 ThemeManager 并作为 EnvironmentObject 注入
- 将当前主题通过自定义 EnvironmentKey 注入到视图层
- 在业务视图中通过 @Environment 访问主题令牌
代码示例
import SwiftUI
// MARK: - Design Tokens
struct ColorSet {
let light: Color
let dark: Color
let highContrastLight: Color?
let highContrastDark: Color?
func resolved(colorScheme: ColorScheme, contrast: AccessibilityContrast) -> Color {
switch (colorScheme, contrast) {
case (.light, .increased):
return highContrastLight ?? light
case (.dark, .increased):
return highContrastDark ?? dark
case (.light, _):
return light
case (.dark, _):
return dark
@unknown default:
return light
}
}
}
struct Colors {
let primary: ColorSet
let background: ColorSet
let text: ColorSet
}
struct Typography {
let title: Font
let body: Font
let caption: Font
}
struct CornerRadius {
let small: CGFloat
let medium: CGFloat
let large: CGFloat
}
// MARK: - Theme Protocol
protocol Theme {
var id: String { get }
var colors: Colors { get }
var typography: Typography { get }
var cornerRadius: CornerRadius { get }
}
// 示例主题：系统默认主题
struct SystemTheme: Theme {
let id = "system"
let colors = Colors(
primary: ColorSet(
light: Color.blue,
dark: Color.blue.opacity(0.85),
highContrastLight: Color(hue: 0.61, saturation: 1.0, brightness: 0.95),
highContrastDark: Color(hue: 0.61, saturation: 1.0, brightness: 0.85)
),
background: ColorSet(
light: Color(UIColor.systemBackground),
dark: Color(UIColor.systemBackground),
highContrastLight: Color.white,
highContrastDark: Color.black
),
text: ColorSet(
light: Color.primary,
dark: Color.primary,
highContrastLight: Color.black,
highContrastDark: Color.white
)
)
let typography = Typography(
title: .system(.title, design: .rounded).weight(.semibold),
body: .system(.body, design: .default),
caption: .system(.caption, design: .default)
)
let cornerRadius = CornerRadius(small: 6, medium: 10, large: 16)
}
// 示例主题：品牌 A
struct BrandATheme: Theme {
let id = "brandA"
let colors = Colors(
primary: ColorSet(
light: Color(hex: "#0055FF"),
dark: Color(hex: "#77A8FF"),
highContrastLight: Color(hex: "#0033CC"),
highContrastDark: Color(hex: "#99BBFF")
),
background: ColorSet(
light: Color(hex: "#F7F9FC"),
dark: Color(hex: "#0B0F14"),
highContrastLight: Color.white,
highContrastDark: Color.black
),
text: ColorSet(
light: Color(hex: "#0A1F44"),
dark: Color(hex: "#E6EDF7"),
highContrastLight: Color.black,
highContrastDark: Color.white
)
)
let typography = Typography(
title: .system(size: 24, weight: .bold, design: .rounded),
body: .system(size: 17, weight: .regular, design: .default),
caption: .system(size: 13, weight: .regular, design: .default)
)
let cornerRadius = CornerRadius(small: 4, medium: 8, large: 12)
}
// MARK: - Environment Key
private struct ThemeKey: EnvironmentKey {
static let defaultValue: Theme = SystemTheme()
}
extension EnvironmentValues {
var theme: Theme {
get { self[ThemeKey.self] }
set { self[ThemeKey.self] = newValue }
}
}
// MARK: - Persistence Strategy
enum PersistenceStrategy {
case none
case userDefaults(key: String)
func save(themeID: String) {
switch self {
case .none: break
case .userDefaults(let key):
UserDefaults.standard.set(themeID, forKey: key)
}
}
func restoredThemeID() -> String? {
switch self {
case .none: return nil
case .userDefaults(let key):
return UserDefaults.standard.string(forKey: key)
}
}
}
// MARK: - Theme Manager
final class ThemeManager: ObservableObject {
@Published private(set) var current: Theme
private let persistence: PersistenceStrategy
init(defaultTheme: Theme = SystemTheme(),
persistence: PersistenceStrategy = .none) {
self.persistence = persistence
if let restoredID = persistence.restoredThemeID(),
let restoredTheme = ThemeManager.resolveTheme(id: restoredID) {
self.current = restoredTheme
} else {
self.current = defaultTheme
}
}
func apply(_ theme: Theme) {
current = theme
persistence.save(themeID: theme.id)
}
// 注册或从远端解析后的主题可在此处扩展解析
static func resolveTheme(id: String) -> Theme? {
switch id {
case "system": return SystemTheme()
case "brandA": return BrandATheme()
default: return nil
}
}
// MARK: - Remote Config (示例)
struct RemoteThemeDTO: Decodable {
struct ColorPair: Decodable {
let light: String
let dark: String
let highContrastLight: String?
let highContrastDark: String?
}
struct ColorsDTO: Decodable {
let primary: ColorPair
let background: ColorPair
let text: ColorPair
}
struct CornerDTO: Decodable {
let small: CGFloat
let medium: CGFloat
let large: CGFloat
}
let id: String
let colors: ColorsDTO
let cornerRadius: CornerDTO
// 字体远端下发通常涉及命名与尺寸，示例省略或采用系统默认
}
func loadRemoteTheme(from url: URL,
completion: @escaping (Result<Theme, Error>) -> Void) {
URLSession.shared.dataTask(with: url) { data, _, error in
if let error = error {
completion(.failure(error)); return
}
guard let data = data else {
completion(.failure(NSError(domain: "ThemeKit", code: -1,
userInfo: [NSLocalizedDescriptionKey: "Empty data"])))
return
}
do {
let dto = try JSONDecoder().decode(RemoteThemeDTO.self, from: data)
let theme = Self.theme(from: dto)
completion(.success(theme))
} catch {
completion(.failure(error))
}
}.resume()
}
private static func theme(from dto: RemoteThemeDTO) -> Theme {
let colors = Colors(
primary: ColorSet(
light: Color(hex: dto.colors.primary.light),
dark: Color(hex: dto.colors.primary.dark),
highContrastLight: dto.colors.primary.highContrastLight.map(Color.init(hex:)),
highContrastDark: dto.colors.primary.highContrastDark.map(Color.init(hex:))
),
background: ColorSet(
light: Color(hex: dto.colors.background.light),
dark: Color(hex: dto.colors.background.dark),
highContrastLight: dto.colors.background.highContrastLight.map(Color.init(hex:)),
highContrastDark: dto.colors.background.highContrastDark.map(Color.init(hex:))
),
text: ColorSet(
light: Color(hex: dto.colors.text.light),
dark: Color(hex: dto.colors.text.dark),
highContrastLight: dto.colors.text.highContrastLight.map(Color.init(hex:)),
highContrastDark: dto.colors.text.highContrastDark.map(Color.init(hex:))
)
)
let corners = CornerRadius(
small: dto.cornerRadius.small,
medium: dto.cornerRadius.medium,
large: dto.cornerRadius.large
)
// 远端未指定字体时采用系统默认
let typography = Typography(
title: .system(.title, design: .rounded).weight(.semibold),
body: .system(.body, design: .default),
caption: .system(.caption, design: .default)
)
return GenericTheme(id: dto.id, colors: colors, typography: typography, cornerRadius: corners)
}
}
// 通用主题封装，便于远端解析
struct GenericTheme: Theme {
let id: String
let colors: Colors
let typography: Typography
let cornerRadius: CornerRadius
}
// MARK: - Color Hex Support
extension Color {
init(hex: String) {
let cleaned = hex.replacingOccurrences(of: "#", with: "")
var value: UInt64 = 0
Scanner(string: cleaned).scanHexInt64(&value)
let r, g, b: Double
let a: Double = 1.0
switch cleaned.count {
case 6:
r = Double((value & 0xFF0000) >> 16) / 255.0
g = Double((value & 0x00FF00) >> 8) / 255.0
b = Double(value & 0x0000FF) / 255.0
default:
r = 0; g = 0; b = 0
}
self = Color(.sRGB, red: r, green: g, blue: b, opacity: a)
}
}
// MARK: - App Integration
@main
struct ExampleApp: App {
@StateObject private var themeManager = ThemeManager(
defaultTheme: SystemTheme(),
persistence: .userDefaults(key: "ThemeKit.currentThemeID")
)
var body: some Scene {
WindowGroup {
ContentView()
// 运行时切换会触发视图重建，Environment 跟随更新
.environment(\.theme, themeManager.current)
.environmentObject(themeManager)
}
}
}
// MARK: - Usage in Views
struct ContentView: View {
@Environment(\.theme) private var theme
@Environment(\.colorScheme) private var colorScheme
@Environment(\.accessibilityContrast) private var contrast
@EnvironmentObject private var themeManager: ThemeManager
var body: some View {
VStack(spacing: 16) {
Text("ThemeKit for SwiftUI")
.font(theme.typography.title)
.foregroundColor(theme.colors.text.resolved(colorScheme: colorScheme, contrast: contrast))
RoundedRectangle(cornerRadius: theme.cornerRadius.medium)
.fill(theme.colors.primary.resolved(colorScheme: colorScheme, contrast: contrast))
.frame(height: 56)
.overlay(Text("Primary").font(theme.typography.body).foregroundColor(.white))
HStack {
Button("系统主题") { themeManager.apply(SystemTheme()) }
Button("品牌 A") { themeManager.apply(BrandATheme()) }
}
.buttonStyle(.borderedProminent)
}
.padding()
.background(theme.colors.background.resolved(colorScheme: colorScheme, contrast: contrast))
}
}
// MARK: - Remote Theme Load Example
struct RemoteThemeLoaderView: View {
@EnvironmentObject private var themeManager: ThemeManager
@State private var loading = false
@State private var errorMessage: String?
var body: some View {
VStack(spacing: 12) {
Button(loading ? "加载中..." : "从远端加载主题") {
guard !loading else { return }
loading = true
let url = URL(string: "https://example.com/theme.json")!
themeManager.loadRemoteTheme(from: url) { result in
DispatchQueue.main.async {
loading = false
switch result {
case .success(let theme):
themeManager.apply(theme)
case .failure(let error):
errorMessage = error.localizedDescription
}
}
}
}
if let errorMessage = errorMessage {
Text(errorMessage).foregroundColor(.red).font(.caption)
}
}
.padding()
}
}
注意事项
- Environment 更新机制：将
.environment(\.theme, themeManager.current) 放在根视图或导航根节点处，确保 @Published 变更触发视图重建并传播环境值。
- 高对比与深色模式：
- 使用
@Environment(\.accessibilityContrast) 和 @Environment(\.colorScheme) 获取当前设置，颜色应通过 ColorSet.resolved(...) 适配。
- 字体与动态类型：
- 示例使用
Font.system，实际项目若需自定义字体，请确保资源可用并与动态类型兼容（PreferredContentSizeCategory）。
- 远端配置：
- 建议仅下发安全的设计令牌（颜色、圆角、部分字号）。字体文件分发需考虑授权与体积。
- 对远端数据做校验与降级策略，避免非法值导致渲染异常。
- 持久化策略：
- UserDefaults 适合轻量主题 ID 存储；如需多进程共享可使用 App Group。
- 与 UIKit/Asset Catalog 的颜色混用：
- 若使用 Asset Catalog 的动态颜色，确保与 ThemeKit 的动态解析不冲突，避免双重适配导致色彩异常。
- 性能建议：
- 保持主题令牌为轻量值类型；避免在
resolved 中执行重计算或 I/O。
相关链接
