macOS 应用主题切换能做到只改一行代码吗ThemeKit 实操全记录【免费下载链接】ThemeKitmacOS theming library项目地址: https://gitcode.com/gh_mirrors/the/ThemeKit做了三年 macOS 客户端我至今记得第一次给应用加深色模式时的狼狈改了几十个控件的颜色上线前又返工两次。后来一位做编辑器开发的朋友递给我一个叫 ThemeKit 的开源库说macOS 应用主题切换用它只写一行代码。试过之后我把原本计划三天的适配压缩成了半天还在当天下午给应用加上了用户可自定义的换肤功能。这篇文章就完整记录这次实操希望能帮你少走我走过的弯路。一句话认识 ThemeKit它是做什么的ThemeKit 是一个完全用 Swift 编写的 macOS 主题化库核心职责只有一个让 macOS 应用的浅色 / 深色外观切换、以及自定义主题变成声明式的、可自动化的过程。你不需要在每个控件上手动判断当前外观、逐个设置颜色ThemeKit 会替你完成窗口、控件、资源三层的同步更新。它同时支持 Swift 与 Objective-C兼容 macOS 10.10 及以上系统。一张表看清它能替你解决什么问题与其听我罗列功能不如直接看一张能力对照表把 ThemeKit 解决的真问题和对应的机制摆在一起你会遇到的问题ThemeKit 给出的方案对应源码位置窗口外观不跟随主题变化自动监听新窗口并按策略应用外观支持全局 / 指定窗口类 / 排除窗口类四种策略Sources/ThemeManager.swift控件颜色需要逐个手动改ThemeColor是NSColor的子类颜色随当前主题自动解析Sources/ThemeColor.swift渐变、图片也要随主题切换ThemeGradient、ThemeImage提供同样的动态解析机制Sources/ThemeGradient.swift、Sources/ThemeImage.swift想跟随系统外观设置内置SystemTheme自动跟随系统浅色 / 深色偏好Sources/SystemTheme.swift想让非开发者用户也能自定义皮肤.theme纯文本文件定义主题放入指定文件夹即被识别并热更新Sources/UserTheme.swift切换主题时界面需要响应式刷新内置willChangeTheme/didChangeTheme通知也支持 KVO 观察effectiveThemeSources/NotificationNameThemeKit.swift这张表背后的设计思路很朴素把当前是什么主题这件事变成全局状态所有资源只跟这个状态挂钩。你不需要在业务代码里写任何if 深色 else 浅色的分支。动手做把一个普通 macOS 应用接入主题切换的完整过程下面我用一个最小可用的路径带你完整跑一遍接入流程。整个过程的代码量非常少重点在理解每个步骤背后的机制。集成前的准备选一种安装方式ThemeKit 支持 CocoaPods、Carthage 和手动集成三种方式。如果你已经在用 CocoaPods在Podfile里加一行即可target 你的应用名 do use_frameworks! pod macOSThemeKit, ~ 1.2.0 end注意通过 CocoaPods 集成时模块名是macOSThemeKit导入语句要写import macOSThemeKit用 Carthage 或手动集成时模块名才是ThemeKit。这是个非常容易踩的坑先记住它。如果用 Carthage只需要github luckymarmot/ThemeKit三行配置启用主题能力集成完成后在AppDelegate的applicationWillFinishLaunching中做基础配置。下面的代码做了三件事让所有窗口自动主题化、启用用户主题支持、应用上次退出时保存的主题没有则用默认主题func applicationWillFinishLaunching(_ notification: Notification) { // 1. 所有窗口除 NSPanel 外自动跟随主题 ThemeManager.shared.windowThemePolicy .themeAllWindows // 2. 指定用户主题文件夹.theme 文件放到这里就会被识别 let supportURL FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask).first! ThemeManager.shared.userThemesFolderURL supportURL.appendingPathComponent(Bundle.main.bundleIdentifier!) .appendingPathComponent(Themes) // 3. 应用上次主题或默认主题SystemTheme 会跟随系统外观 ThemeManager.shared.applyLastOrDefaultTheme() }到这里你的应用已经具备完整的主题切换能力了。如果只想快速验证甚至可以只写一行ThemeManager.darkTheme.apply() // 一键切到深色但别急着满足真正的价值在下面这一层。用 ThemeColor 让控件颜色自动跟随主题最让开发者头疼的从来不是窗口外观而是自己写的那些控件颜色。ThemeKit 的思路是把颜色定义成主题资源而不是固定值。先通过扩展声明一个颜色资源名extension ThemeColor { /// 声明一个名为 contentTextColor 的动态颜色 static var contentTextColor: ThemeColor { return ThemeColor.color(with: #function) } }然后分别在浅色和深色主题里给它不同的实现extension LightTheme { var contentTextColor: NSColor { return NSColor(calibratedRed: 0.1, green: 0.1, blue: 0.1, alpha: 1.0) } } extension DarkTheme { var contentTextColor: NSColor { return NSColor.lightGray } }之后在界面里你就可以放心地这么写textField.textColor ThemeColor.contentTextColorThemeColor会在每次主题切换时自动重新解析颜色并缓存你不需要在切换回调里手动刷新这些控件。这就是前面说的声明式你只声明文本色是 contentTextColor至于它在深色下是什么、切换时怎么变都由 ThemeKit 兜底。同样的机制适用于渐变ThemeGradient和图片ThemeImage比如 Demo 里用sun/moon两张图片做昼夜图标切换本质就是给同一个资源名在深浅两套主题下配了不同图片。做一个可用的主题切换菜单有了动态资源最后补上一个给用户用的切换入口。ThemeKit 会把内置主题、你写的原生主题类、以及文件夹里的用户主题全部汇总到ThemeManager.shared.themes直接遍历建菜单即可let themeMenu NSMenu(title: 主题) for theme in ThemeManager.shared.themes { let item NSMenuItem(title: theme.shortDisplayName, action: #selector(switchTheme(_:)), keyEquivalent: ) item.representedObject theme themeMenu.addItem(item) } objc func switchTheme(_ sender: NSMenuItem) { guard let theme sender.representedObject as? Theme else { return } theme.apply() // 应用主题整个过程交给 ThemeKit }跑起来的实际效果是点一下菜单应用所有窗口外观同步变化、动态颜色即时更新默认还带一段 0.3 秒的淡入淡出过渡动画。Demo 应用里甚至内置了一个自动轮播主题的 slideshow 功能几秒钟把所有主题切一遍用来验收界面有没有漏网之鱼非常有效。实测效果同一个应用两副面孔上面这套流程的效果官方 Demo 里有一段很直观的动图可以看实际使用中还有两个很容易被忽视但体验提升明显的点其一系统主题联动。用户把 macOS 系统外观从浅色切到深色你的应用如果用的是SystemTheme会立刻跟随切换不需要重新启动。ThemeKit 内部通过didChangeSystemTheme通知感知系统外观变化并在当前主题是系统主题时自动重新应用。其二纹理背景。用户主题文件支持pattern(named:)语法可以把一张图片作为图案平铺成背景色。Demo 里就有一张纸张纹理素材配合它做出来的纸张质感编辑主题比纯色背景有辨识度得多和自己写外观切换代码比ThemeKit 赢在哪很多团队第一反应是外观切换不复杂我自己写。确实做一个简单的深色模式不难难的是做成体系。这里做一个客观对比对比维度自己手写外观切换使用 ThemeKit窗口外观管理需要自行监听窗口创建、手动设置NSAppearance内置windowThemePolicy窗口自动处理自定义控件颜色每个控件都要在切换回调里手动重设容易漏声明式动态颜色切换自动解析无遗漏渐变 / 图片资源需要额外做一套资源映射表ThemeGradient/ThemeImage原生支持用户自定义主题需要自己设计文件格式与解析器.theme文本文件 自动热更新开箱即用主题记忆需要自己写持久化自动写入NSUserDefaults下次启动恢复语言兼容通常只能覆盖 SwiftSwift / Objective-C 双支持结论很明确如果只是给一个静态界面套深色外观手写没问题但只要涉及多个自定义控件、可扩展主题、用户换肤中的任何一项ThemeKit 省下的代码量和维护成本都是数量级的。新手最容易踩的坑与对应解法这部分是本次实操最有价值的地方四个坑我全部真实撞过坑一滚动条在深色主题下全白。当用户在系统偏好里把滚动条设为始终显示深色主题下滚动条可能渲染成一片白。解法是监听主题变化手动给滚动条补背景色scrollView.wantsLayer true scrollView.backgroundColor ThemeColor.contentBackgroundColor NotificationCenter.default.addObserver(forName: .didChangeTheme, object: nil, queue: nil) { _ in scrollView.verticalScroller?.layer?.backgroundColor ThemeColor.contentBackgroundColor.cgColor }坑二字体出现平滑问题、文字发虚。根因是绘制文字时没有背景色。给NSTextField等控件显式设置backgroundColor即可如果是自定义绘制先set()背景色并填充再开启setShouldSmoothFonts(true)绘制文本。坑三以为.themeAllWindows会包含NSPanel。默认策略会排除NSPanel子类如系统弹窗。如果你确实想让某些面板参与主题化要么改用.themeSomeWindows显式声明要么接受这个默认行为别在调试时浪费时间。坑四CocoaPods 集成后import ThemeKit报错。前面提过CocoaPods 方式下模块名是macOSThemeKitSwift 里要import macOSThemeKit。如果团队里两种集成方式混用注意文件头部的导入语句保持一致。另外有个细节提醒切换深浅主题时如果新旧主题同为浅色比如两个自定义浅色主题互切macOS 不会主动刷新控件外观。ThemeKit 内部会先故意切到反向外观再切回来强制控件刷新——所以你自己实现主题类时务必给每个主题正确设置isDarkTheme这个标志直接影响刷新逻辑。进阶玩法再往下挖还有这些能力值得用跑通基础流程后下面几个方向是性价比很高的延伸用户主题文件.theme。非开发者用户只需要会写简单的键值对就能创建属于自己的皮肤// 主题基本信息 displayName 优雅深色 identifier com.myapp.ElegantDark darkTheme true // 颜色与渐变支持变量引用 brandColor $blue labelColor rgb(11, 220, 111) brandGradient linear-gradient($blue, rgba(200, 140, 60, 1.0)) // 公共变量供上面引用 blue rgb(0, 170, 255)文件放进userThemesFolderURL指定的目录后ThemeKit 会通过文件系统监听自动识别如果正在使用的主题文件被修改界面会实时热更新。仓库的Demo/Themes目录下就有现成的示例文件可以研究。窗口级主题控制。有些应用希望某些窗口保持固定外观。除了前面用的全局策略NSWindow还提供了windowTheme属性支持单窗口指定主题以及NSWindow.themeAllWindows()这类手动批量刷新方法。标题栏与工具栏主题化。ThemeKit 本身不直接接管标题栏但 Demo 里给出了成熟的参考方案在标题栏下方叠加一个TitleBarOverlayView绘制层配合ThemeColor.windowTitleBarActiveColor这类动态颜色实现。如果你的应用有自定义标题栏需求直接参考Demo/Demo/TitleBarOverlayView.swift和Demo/Demo/WindowController.swift的实现。监听主题变化的两个姿势。需要做缓存类操作比如重绘一个昂贵的自定义视图时可以用通知或 KVO// 通知方式 NotificationCenter.default.addObserver(self, selector: #selector(onThemeChanged), name: .didChangeTheme, object: nil) // KVO 方式 ThemeManager.shared.addObserver(self, forKeyPath: effectiveTheme, options: [], context: nil)收尾它解决的是主题化这个系统性问题回顾整篇实操ThemeKit 真正厉害的地方不在于某个单点功能而在于它把macOS 应用主题切换从一个需要处处提防的横切关注点变成了声明一次、自动生效的体系。窗口、颜色、渐变、图片、用户主题、系统联动、持久化记忆这些碎片被整合成一套一致的状态机。对新手来说它的上手曲线低到几乎可以忽略对老手来说它的扩展点又足够自由。下一步行动我建议按这个顺序走克隆仓库先跑通官方 Demo用 slideshow 功能把所有内置主题切一遍直观感受切换的完整度git clone https://gitcode.com/gh_mirrors/the/ThemeKit打开Demo/Demo/AppDelegate.swift对照本文的配置流程逐行读注释它是比 README 更生动的教程。从你现有应用里挑一个最刺眼的控件用ThemeColor重构它的颜色然后观察深色切换时它是否自动适配——这一步会给你接入整套方案的最大信心。最后别忘了给自己留个自定义主题文件试着用.theme语法写一个属于自己的配色你会突然理解为什么用户会为换肤功能买单。如果你在接入过程中遇到这里没覆盖到的问题Demo 项目和Docs/目录下的 API 文档里大概率已经有答案。祝你的应用早日拥有两副面孔并且每一副都体面。【免费下载链接】ThemeKitmacOS theming library项目地址: https://gitcode.com/gh_mirrors/the/ThemeKit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考