182 lines
6.7 KiB
Markdown
182 lines
6.7 KiB
Markdown
# SwiftUI 样式驱动组件
|
||
|
||
`SwiftUI` `iOS` `组件库` `样式协议` `Apple`
|
||
|
||
# SwiftUI 样式驱动组件技能
|
||
|
||
为所有支持 [Agent Skills 开放格式](https://agentskills.io/home) 的 AI 编程工具提供专业指导，帮助开发者使用 Apple 样式驱动架构模式构建可扩展的 SwiftUI 组件。
|
||
|
||
从 Apple 官方模式（`ButtonStyle`、`LabelStyle`、`ToggleStyle`）中提炼而来，为 AI 代理提供可直接使用的精简参考。
|
||
|
||
## 适用人群
|
||
|
||
- 希望构建符合 Apple 标准可扩展性的可复用 SwiftUI 组件库的团队。
|
||
- 需要为自定义组件实现多种视觉风格、同时避免代码重复的开发者。
|
||
- 希望实现基于环境的样式级联传递（可穿透视图层级）的任何人。
|
||
|
||
## 使用方法
|
||
|
||
### 方式 A：使用 skills.sh（推荐）
|
||
|
||
通过一条命令安装此技能：
|
||
|
||
```bash
|
||
npx skills add https://github.com/ahmadbrkt/swiftui-style-driven-components-skill --skill swiftui-style-driven-components
|
||
```
|
||
|
||
更多信息请访问 [skills.sh 平台页面](https://skills.sh/ahmadbrkt/SwiftUI-Style-Driven-Components-Skill/swiftui-style-driven-components)。
|
||
|
||
然后在 AI 代理中使用该技能，例如：
|
||
> 使用 swiftui 样式驱动组件技能，创建一个支持样式协议的 Card 组件
|
||
|
||
### 方式 B：Claude Code 插件
|
||
|
||
#### 个人使用
|
||
|
||
在 Claude Code 中为个人使用安装此技能：
|
||
|
||
1. 添加插件市场：
|
||
```bash
|
||
/plugin marketplace add ahmadbrkt/SwiftUI-Style-Driven-Components-Skill
|
||
```
|
||
|
||
2. 安装技能：
|
||
```bash
|
||
/plugin install swiftui-style-driven-components@swiftui-style-driven-components-skill
|
||
```
|
||
|
||
#### 项目配置
|
||
|
||
若希望为仓库中所有协作者自动提供此技能，请在仓库的 `.claude/settings.json` 中进行配置：
|
||
|
||
```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：手动安装
|
||
|
||
1. **克隆**本仓库。
|
||
2. 按照工具的官方技能安装文档，**安装或符号链接** `swiftui-style-driven-components/` 文件夹（参见下方链接）。
|
||
3. **正常使用 AI 工具**，并让其在处理组件架构任务时使用 "swiftui-style-driven-components" 技能。
|
||
|
||
#### 技能保存位置
|
||
|
||
请参阅各工具的官方文档，以下是几个常用工具的参考：
|
||
|
||
- **Codex：** [技能保存位置](https://developers.openai.com/codex/skills/#where-to-save-skills)
|
||
- **Claude：** [使用技能](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#using-skills)
|
||
- **Cursor：** [启用技能](https://cursor.com/docs/context/skills#enabling-skills)
|
||
|
||
**验证方法**：
|
||
|
||
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 开放格式](https://agentskills.io/home)，该格式有特定的结构要求。
|
||
|
||
**强烈建议借助 AI 辅助进行贡献：**
|
||
|
||
- 使用 [skill-creator 技能](https://github.com/anthropics/skills/tree/main/skills/skill-creator) 配合 Claude，以确保格式正确
|
||
- 这有助于维护 Agent Skills 格式，并确保你的贡献能与 AI 代理正常协作
|
||
|
||
**请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，了解：**
|
||
|
||
- 如何使用 skill-creator 技能进行贡献
|
||
- Agent Skills 格式要求
|
||
- 质量标准与最佳实践
|
||
- Pull Request 流程
|
||
|
||
本技能持续维护，以反映最新的 SwiftUI 样式驱动组件最佳实践，并将随框架演进不断更新。
|
||
|
||
## 许可证
|
||
|
||
本技能为开源项目，采用 MIT 许可证。详情请参阅 [LICENSE](LICENSE)。 |