메뉴
SwiftUI 开发标准规范，包括代码组织、MARK 分组、日志记录、预览代码和事件监听的统一规范。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| 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 过滤遵循此规范可以显著提升代码的可读性、可维护性和开发体验。