Menu
SwiftUI 开发标准规范，包括代码组织、MARK 分组、日志记录、预览代码和事件监听的统一规范。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | swiftui-standards |
| description | SwiftUI 开发标准规范，包括代码组织、MARK 分组、日志记录、预览代码和事件监听的统一规范。 |
本技能确保所有 SwiftUI 代码遵循项目的统一开发规范。
文件组织：
目录结构：
Core/
├── Events/ # 所有事件相关代码
│ ├── AppEvents.swift
│ └── SettingEvents.swift
├── Bootstrap/
├── Contract/
└── Models/
所有 SwiftUI 视图文件必须按以下顺序使用 MARK 分组：
// MARK: - View - SwiftUI View 主体实现
// MARK: - Action - 用户交互触发的行为
// MARK: - Setter - 状态/属性的集中更新方法
// MARK: - Event Handler - 事件处理函数
// MARK: - Preview - 多尺寸预览
示例模板：
import SwiftUI
struct MyView: View {
@State private var isLoading = false
@State private var items: [String] = []
var body: some View {
List(items, id: \.self) { Text($0) }
.onAppear(perform: handleOnAppear)
}
}
// MARK: - View
extension MyView {
private var filteredItems: [String] {
items.filter { !$0.isEmpty }
}
}
// MARK: - Action
extension MyView {
func refresh() {
// 刷新逻辑
}
}
// MARK: - Setter
extension MyView {
@MainActor
func setItems(_ newValue: [String]) {
items = newValue
isLoading = false
}
}
// MARK: - Event Handler
extension MyView {
func handleOnAppear() {
isLoading = true
}
}
// MARK: - Preview
#if os(macOS)
#Preview("App - Large") {
ContentView()
.inRootView()
.frame(width: 600, height: 1000)
}
#Preview("App - Small") {
ContentView()
.inRootView()
.frame(width: 600, height: 600)
}
#endif
#if os(iOS)
#Preview("iPhone") {
ContentView()
.inRootView()
}
#endif
使用 os.Logger 进行日志记录，禁止使用 os_log。 详见 .cursor/rules/swift-log.mdc。
Core 模块使用 AppLogger.core：
struct MyView: View, SuperLog {
nonisolated static let emoji = "🎯"
nonisolated static let verbose = false
func someFunction() {
if Self.verbose {
AppLogger.core.info("\(Self.emoji) Some operation started")
}
AppLogger.core.info("\(Self.emoji) Operation completed")
}
}
Plugin 模块使用插件 logger：
struct MyTool: AgentTool, SuperLog {
nonisolated static let emoji = "🔍"
nonisolated static let verbose = false
func execute() {
if Self.verbose {
MyPlugin.logger.info("\(Self.emoji) Executing tool")
}
}
}
SuperLog 协议要求：
nonisolated static let emoji - 独特的 emoji 标识nonisolated static let verbose - 详细日志控制\(Self.emoji) 作为前缀日志级别：
// 总是输出
AppLogger.core.info("\(Self.emoji) Important operation completed")
// 仅开发时输出
if Self.verbose {
AppLogger.core.info("\(Self.emoji) Detailed debug information")
}
// 错误和警告
AppLogger.core.error("Operation failed: \(error.localizedDescription)")
AppLogger.core.warning("Using fallback configuration")
事件抛出时，必须为 View 扩展添加 onXxx 方法：
// 在 Core/Events/ 目录中实现
extension View {
func onCustomEvent(perform action: @escaping () -> Void) -> some View {
self.onReceive(NotificationCenter.default.publisher(for: .customEvent)) { _ in
action()
}
}
}
// 使用时必须使用 perform: 语法
.onCustomEvent(perform: handleEvent)
func handleEvent() {
// 事件处理逻辑
}
事件文件组织：
Core/Events/ 目录AppEvents.swift - 应用生命周期事件SettingEvents.swift - 设置相关事件每个 Swift 文件底部必须添加多尺寸预览：
#if os(macOS)
#Preview("App - Large") {
ContentView()
.inRootView()
.frame(width: 600, height: 1000)
}
#Preview("App - Small") {
ContentView()
.inRootView()
.frame(width: 600, height: 600)
}
#endif
#if os(iOS)
#Preview("iPhone") {
ContentView()
.inRootView()
}
#endif
🌿 - View 组件📱 - 移动端🖥️ - 桌面端🎛️ - 控制面板📋 - 表单组件🏠 - 数据提供者💾 - 数据存储📊 - 数据分析🔄 - 数据同步🔧 - 工具类📁 - 文件管理🌳 - 项目管理📝 - 文本编辑🔍 - 搜索功能🍎 - macOS⚙️ - 系统配置🔗 - 网络连接🔔 - 通知系统onXxx / handleXxxos.Logger（AppLogger.core 或 PluginName.logger），禁止 os_logimport os，禁止 import OSLoglog stream --predicate 'subsystem == "com.coffic.lumi"'perform: 语法一行完成Core/Events/ 目录inRootView() 包装onXxx 方法名在项目中唯一@MainActorlog stream 按 subsystem、category 过滤遵循此规范可以显著提升代码的可读性、可维护性和开发体验。