SymbolPicker

SymbolPicker（原生 SwiftUI SF 符号选择器）的专家指导。当开发人员提及以下内容时使用：(1) SymbolPicker、(2) 选择 SF 符号、(3) 使用颜色选取符号、(4) 自定义符号选择器外观、(5) 跨平台符号选择（iOS、macOS、visionOS）、(6) 特定修饰符，例如 .symbolPickerSymbolsStyle 或 .symbolPickerDismiss。

# SymbolPicker Skill

## Overview

This skill provides expert guidance on `SymbolPicker`, a native, customizable SwiftUI component for selecting SF Symbols on iOS, iPadOS, macOS, and visionOS. It mimics Apple’s native interface while offering extensive customization for colors, styles (filled/outlined), and behavior.

## Agent Behavior (Follow These Rules)

1.  **Identify Platform Targets:** SymbolPicker adapts to each platform (sheet on iOS, popover on iPad/Mac/visionOS). Always verify the target platform.
2.  **Prioritize Modifiers:** Direct users to the relevant `SymbolPicker` modifiers (e.g., `.symbolPickerSymbolsStyle`, `.symbolPickerDismiss`) for customization.
3.  **Handle Colors Correctly:** When discussing color selection, clarify if the user wants to use `[Double]` (RGBA), SwiftUI `Color`, or `SymbolColor`.
4.  **Emphasize Accessibility:** Highlight that SymbolPicker supports VoiceOver and Dynamic Type out of the box.
5.  **Contextual Examples:** Provide concise code snippets showing the `.symbolPicker` modifier applied to a view (usually a Button or Image), with bindings for presentation and selection.
6.  **Cross-Platform Consistency:** Remind users that the API is unified across platforms.

## Project Settings

-   **Deployment Targets:** iOS 14.0+, iPadOS 14.0+, macOS 11.0+, visionOS 1.0+.
-   **Swift Version:** Swift 5.9+.
-   **Xcode:** Xcode 15.0+.

## Quick Decision Tree

1.  **Setting up a basic symbol picker?**
    *   Basic installation and concepts → `references/SymbolPicker.md`
    *   To apply the modifier to a view → `references/SymbolPickerView.md`

2.  **Picking symbols with color?**
    *   To use different color binding types → `references/SymbolPickerView.md`
    *   To understand the `SymbolColor` model → `references/SymbolColor.md`

3.  **Customizing appearance or behavior?**
    *   Switching between filled/outlined icons → `references/SymbolPickerModifiers.md` (`.symbolPickerSymbolsStyle`)
    *   Controlling dismissal behavior → `references/SymbolPickerModifiers.md` (`.symbolPickerDismiss`)

## Triage-First Playbook

-   **"The picker isn't showing up."**
    *   Check if `.symbolPicker(isPresented: ...)` is attached to a view that is part of the hierarchy.
    *   Ensure the `isPresented` binding is being toggled true.
-   **"I want filled icons instead of outlines."**
    *   Use `.symbolPickerSymbolsStyle(.filled)`.
-   **"How do I close the picker immediately after selecting a symbol?"**
    *   Use `.symbolPickerDismiss(type: .onSymbolSelect)`.

## Core Patterns Reference

### Basic Usage
```swift
@State private var isPresented = false
@State private var icon = "star"

Button("Pick Icon") { isPresented = true }
    .symbolPicker(isPresented: $isPresented, symbolName: $icon)
```

### With Color Selection
```swift
@State private var isPresented = false
@State private var icon = "star.fill"
@State private var color: Color = .red

Button("Pick Icon & Color") { isPresented = true }
    .symbolPicker(isPresented: $isPresented, symbolName: $icon, color: $color)
    .symbolPickerSymbolsStyle(.filled)
    .symbolPickerDismiss(type: .onSymbolSelect)
```

## Integration Quick Guide

1.  **Add Package Dependency**: `https://github.com/SzpakKamil/SymbolPicker.git` (Min version 1.0.0).
2.  **Import**: `import SymbolPicker`.
3.  **Requirements**: iOS 14.0+, macOS 11.0+, visionOS 1.0+.

## Reference Files

Load these files as needed for specific topics:

-   **`SymbolPicker.md`** - General overview, setup, and core benefits.
-   **`SymbolPickerView.md`** - Detailed information on the picker view and its initializers.
-   **`SymbolPickerModifiers.md`** - Customization of style (filled/outlined) and dismissal behavior.
-   **`SymbolColor.md`** - Guide to using the `SymbolColor` enum and color bindings.
-   **`SetUp.md`** - Step-by-step installation instructions.

---

## 中文说明

# SymbolPicker 技能

## 概述

本技能针对 `SymbolPicker` 提供专家指导。SymbolPicker 是一个原生、可自定义的 SwiftUI 组件，用于在 iOS、iPadOS、macOS 和 visionOS 上选择 SF 符号。它模仿了 Apple 的原生界面，同时为颜色、样式（填充/描边）和行为提供了丰富的自定义能力。

## 代理行为（请遵循以下规则）

1.  **识别目标平台：** SymbolPicker 会适配各个平台（在 iOS 上为 sheet，在 iPad/Mac/visionOS 上为 popover）。请始终确认目标平台。
2.  **优先使用修饰符：** 引导用户使用相关的 `SymbolPicker` 修饰符（例如 `.symbolPickerSymbolsStyle`、`.symbolPickerDismiss`）进行自定义。
3.  **正确处理颜色：** 在讨论颜色选择时，弄清用户想使用 `[Double]`（RGBA）、SwiftUI `Color` 还是 `SymbolColor`。
4.  **强调无障碍：** 突出说明 SymbolPicker 开箱即支持 VoiceOver 和动态字体（Dynamic Type）。
5.  **结合上下文的示例：** 提供简洁的代码片段，展示将 `.symbolPicker` 修饰符应用到某个视图（通常是 Button 或 Image），并附带用于呈现和选择的绑定。
6.  **跨平台一致性：** 提醒用户该 API 在各平台间是统一的。

## 项目设置

-   **部署目标：** iOS 14.0+、iPadOS 14.0+、macOS 11.0+、visionOS 1.0+。
-   **Swift 版本：** Swift 5.9+。
-   **Xcode：** Xcode 15.0+。

## 快速决策树

1.  **要搭建一个基础的符号选择器？**
    *   基础安装与概念 → `references/SymbolPicker.md`
    *   要将修饰符应用到视图 → `references/SymbolPickerView.md`

2.  **要带颜色地选取符号？**
    *   要使用不同的颜色绑定类型 → `references/SymbolPickerView.md`
    *   要理解 `SymbolColor` 模型 → `references/SymbolColor.md`

3.  **要自定义外观或行为？**
    *   在填充/描边图标之间切换 → `references/SymbolPickerModifiers.md`（`.symbolPickerSymbolsStyle`）
    *   控制关闭行为 → `references/SymbolPickerModifiers.md`（`.symbolPickerDismiss`）

## 分诊优先手册

-   **“选择器没有显示出来。”**
    *   检查 `.symbolPicker(isPresented: ...)` 是否附加到了视图层级中的某个视图上。
    *   确保 `isPresented` 绑定被切换为 true。
-   **“我想要填充图标而不是描边图标。”**
    *   使用 `.symbolPickerSymbolsStyle(.filled)`。
-   **“选中符号后如何立即关闭选择器？”**
    *   使用 `.symbolPickerDismiss(type: .onSymbolSelect)`。

## 核心模式参考

### 基本用法
```swift
@State private var isPresented = false
@State private var icon = "star"

Button("Pick Icon") { isPresented = true }
    .symbolPicker(isPresented: $isPresented, symbolName: $icon)
```

### 带颜色选择
```swift
@State private var isPresented = false
@State private var icon = "star.fill"
@State private var color: Color = .red

Button("Pick Icon & Color") { isPresented = true }
    .symbolPicker(isPresented: $isPresented, symbolName: $icon, color: $color)
    .symbolPickerSymbolsStyle(.filled)
    .symbolPickerDismiss(type: .onSymbolSelect)
```

## 集成快速指南

1.  **添加包依赖**：`https://github.com/SzpakKamil/SymbolPicker.git`（最低版本 1.0.0）。
2.  **导入**：`import SymbolPicker`。
3.  **要求**：iOS 14.0+、macOS 11.0+、visionOS 1.0+。

## 参考文件

按需加载以下文件以了解具体主题：

-   **`SymbolPicker.md`** - 总体概述、设置以及核心优势。
-   **`SymbolPickerView.md`** - 关于选择器视图及其初始化器的详细信息。
-   **`SymbolPickerModifiers.md`** - 样式（填充/描边）和关闭行为的自定义。
-   **`SymbolColor.md`** - 使用 `SymbolColor` 枚举和颜色绑定的指南。
-   **`SetUp.md`** - 分步安装说明。