6.7 KiB
SwiftUI 样式驱动组件
SwiftUI iOS 组件库 样式协议 Apple
SwiftUI 样式驱动组件技能
为所有支持 Agent Skills 开放格式 的 AI 编程工具提供专业指导，帮助开发者使用 Apple 样式驱动架构模式构建可扩展的 SwiftUI 组件。
从 Apple 官方模式（ButtonStyle、LabelStyle、ToggleStyle）中提炼而来，为 AI 代理提供可直接使用的精简参考。
适用人群
- 希望构建符合 Apple 标准可扩展性的可复用 SwiftUI 组件库的团队。
- 需要为自定义组件实现多种视觉风格、同时避免代码重复的开发者。
- 希望实现基于环境的样式级联传递（可穿透视图层级）的任何人。
使用方法
方式 A：使用 skills.sh（推荐）
通过一条命令安装此技能：
npx skills add https://github.com/ahmadbrkt/swiftui-style-driven-components-skill --skill swiftui-style-driven-components
更多信息请访问 skills.sh 平台页面。
然后在 AI 代理中使用该技能，例如：
使用 swiftui 样式驱动组件技能，创建一个支持样式协议的 Card 组件
方式 B：Claude Code 插件
个人使用
在 Claude Code 中为个人使用安装此技能：
-
添加插件市场：
/plugin marketplace add ahmadbrkt/SwiftUI-Style-Driven-Components-Skill -
安装技能：
/plugin install swiftui-style-driven-components@swiftui-style-driven-components-skill
项目配置
若希望为仓库中所有协作者自动提供此技能，请在仓库的 .claude/settings.json 中进行配置：
{
"enabledPlugins": {
"swiftui-style-driven-components@swiftui-style-driven-components-skill": true
},
"extraKnownMarketplaces": {
"swiftui-style-driven-components-skill": {
"source": {
"source": "github",
"repo": "ahmadbrkt/SwiftUI-Style-Driven-Components-Skill"
}
}
}
}
团队成员打开项目时，Claude Code 会提示其安装该技能。
方式 C：手动安装
- 克隆本仓库。
- 按照工具的官方技能安装文档，安装或符号链接
swiftui-style-driven-components/文件夹（参见下方链接）。 - 正常使用 AI 工具，并让其在处理组件架构任务时使用 "swiftui-style-driven-components" 技能。
技能保存位置
请参阅各工具的官方文档，以下是几个常用工具的参考：
验证方法：
AI 代理应能引用 swiftui-style-driven-components/SKILL.md 中的分类/操作手册，并跳转到与组件任务相关的参考文件。
技能功能
本技能为 AI 编程工具提供全面的 SwiftUI 样式驱动组件指导，具体包括：
指导组件架构
- 判断何时使用样式协议，何时使用简单组件
- 按照 Apple 的组织模式构建文件结构
- 实现协议 → 配置 → 组件 → 环境的完整链路
- 设计具有内部类型擦除的类型安全 API
创建样式协议
- 定义带有
DynamicProperty的协议以访问环境 - 使用
@ViewBuilder @MainActor确保 UI 线程安全 - 创建带嵌套类型擦除视图的配置类型
- 严格遵循 Apple 的
ButtonStyle、LabelStyle惯例
构建可扩展组件
- 编写从环境中读取样式的组件
- 在内部创建配置（不暴露给初始化器）
- 使用
AnyView对style.makeBody进行类型擦除包装 - 支持在不修改现有组件的情况下添加新样式
实现环境样式
- 使用
@Entry宏定义环境键 - 以存在类型（
any ComponentStyle）存储样式 - 创建用于样式应用的视图修饰符
- 支持可穿透视图层级的子树样式级联
设计系统集成
- 使用设计令牌替代魔法数字
- 实现间距、排版和颜色系统
- 在组件间构建一致的视觉语言
- 通过环境值支持主题化
编写测试与预览
- 为所有样式变体组织快照测试
- 为不同配置构建预览结构
- 使用动态字体（Dynamic Type）测试无障碍支持
- 验证样式隔离与环境传播
本技能的独特之处
Apple 原生模式：严格遵循 Apple 构建 ButtonStyle、LabelStyle、ToggleStyle 及其他样式协议的方式。你的组件将让 SwiftUI 开发者感到原生自然。
无倾向性：专注于结构模式，而非视觉设计。适用于任何设计系统、组件库或项目架构。
实用决策树：包含关于何时使用样式协议、何时可以跳过的清晰指导。并非所有组件都需要此模式——本技能帮你做出判断。
完整示例：每个模式都包含完整、可编译的 Swift 代码，无伪代码或不完整片段。
反模式指导：同时展示正确（✅）和错误（❌）的做法，并解释模式重要性的原因。
技能结构
swiftui-style-driven-components/
├── SKILL.md # 主技能文件，包含决策树
└── references/
├── component-structure.md # 文件组织与命名规范
├── style-protocol.md # 协议定义与配置模式
├── environment-keys.md # 环境注入与使用模式
├── common-patterns.md # 便捷初始化器、参数化样式
├── design-system.md # 设计令牌、排版、颜色
├── testing.md # 快照测试与测试组织
├── previews.md # 预览结构与检查清单
└── accessibility.md # 标签、标识符、动态字体
贡献
欢迎贡献！本仓库遵循 Agent Skills 开放格式，该格式有特定的结构要求。
强烈建议借助 AI 辅助进行贡献：
- 使用 skill-creator 技能 配合 Claude，以确保格式正确
- 这有助于维护 Agent Skills 格式，并确保你的贡献能与 AI 代理正常协作
请阅读 CONTRIBUTING.md，了解：
- 如何使用 skill-creator 技能进行贡献
- Agent Skills 格式要求
- 质量标准与最佳实践
- Pull Request 流程
本技能持续维护，以反映最新的 SwiftUI 样式驱动组件最佳实践，并将随框架演进不断更新。
许可证
本技能为开源项目，采用 MIT 许可证。详情请参阅 LICENSE。