SearchBar Skill

Overview

This skill provides expert guidance on SearchBar, a powerful and highly customizable SwiftUI component for creating native-feeling search experiences across iOS, iPadOS, macOS, and visionOS. It bridges the gap between UISearchBar (iOS/visionOS) and native SwiftUI views (macOS), offering a unified API for styling, behavior, and advanced features like search tokens and dynamic suggestions.

Agent Behavior (Follow These Rules)

1. Identify Platform Targets: SearchBar behaves slightly differently on iOS/visionOS (wraps UISearchBar) vs. macOS (custom SwiftUI). Always check or ask for the target platform to provide accurate advice (e.g., specific material effects or token behaviors).
Prioritize Modifiers: Direct users to the relevant SearchBar modifiers (e.g., .searchBarStyle, .searchBarSuggestions) rather than suggesting they build custom views from scratch.
Clarify Availability: Explicitly mention version requirements (iOS 14+, iOS 16+ for tokens/suggestions) when discussing advanced features.
Emphasize Localization: Remind users that SearchBar is fully localized and adapts to system languages automatically.
Contextual Examples: Provide concise code snippets that illustrate the recommended usage within a View, often with a binding to @State for text and tokens.
Highlight Cross-Platform: When possible, remind users of SearchBar's cross-platform consistency and how to handle platform-specific differences using #if os(...) directives if necessary (though the library handles most internally).

Project Settings

- Deployment Targets: iOS 14.0+, iPadOS 14.0+, macOS 11.0+, visionOS 1.0+.
Advanced Features: Tokens and Suggestions require iOS 16.0+, iPadOS 16.0+, visionOS 1.0+. (Suggestions also on macOS 15.0+).
Swift Version: Swift 5.9+.

Quick Decision Tree

1. Setting up a basic search bar?

* Basic init and setup → INLINECODE9

2. Customizing appearance?

* Changing colors, shape (capsule/rounded) → references/SearchBarStyle.md * Using "Glass" or "Solid" materials → references/SearchBarStyle.md * Changing the size/scale → references/SearchBarStyle.md * Custom icon → references/SearchBarModifiers.md (.searchBarIconView)

3. Configuring behavior?

* Showing/Hiding Cancel or Clear buttons → references/SearchBarDisplayModes.md * Handling events (begin/end editing, clear, cancel) → references/SearchBarModifiers.md * Focus management → references/SearchBarModifiers.md (.searchBarIsFocused)

4. Using advanced search features (iOS 16+/visionOS)?

* Adding filter tokens (capsules) → references/SearchBarData.md * Showing search suggestions → references/SearchBarData.md * Enabling automatic suggestion filtering → INLINECODE21

Triage-First Playbook

- "My search bar looks different on macOS."

* Explain that macOS uses a pure SwiftUI implementation while iOS uses UISearchBar. Styling is consistent but underlying implementation differs.

- "Tokens/Suggestions are not showing up."

* Verify the deployment target is iOS 16.0+ or visionOS 1.0+. * Ensure the binding to tokens/suggestions is active and populated.

- "How do I change the background color?"

* Use .searchBarStyle(..., backgroundColor: .red). See references/SearchBarStyle.md.

- "I want to hide the cancel button."

* Use .searchBarCancelButtonDisplayMode(.never). See references/SearchBarDisplayModes.md.

- "How do I make the search bar glass/transparent?"

* Use .searchBarMaterial(.glass). Note platform/version restrictions (iOS 26+). See references/SearchBarStyle.md.

Core Patterns Reference

Basic Setup

CODEBLOCK0

Advanced Styling

CODEBLOCK1

Tokens & Suggestions

CODEBLOCK2

Event Handling

CODEBLOCK3

Integration Quick Guide

SearchBar is integrated via Swift Package Manager.

1. Add Package Dependency: In Xcode, go to File > Add Package Dependency and enter https://github.com/SzpakKamil/SearchBar.git.
Import: import SearchBar in your Swift files.
Deployment Targets: Ensure your project targets iOS 14.0+, macOS 11.0+, visionOS 1.0+.

For detailed setup, see references/SearchBar.md.

Reference Files

- SearchBar.md - General overview, setup, and initialization.
SearchBarModifiers.md - Comprehensive list of all modifiers.
SearchBarStyle.md - Styling, materials, corner styles, and scale.
SearchBarDisplayModes.md - Cancel and Clear button behaviors.
SearchBarData.md - Search Tokens and Suggestions.
_index.md - Index of all topics.

SearchBar 技能

概述

本技能提供关于 SearchBar 的专业指导，这是一个功能强大且高度可定制的 SwiftUI 组件，用于在 iOS、iPadOS、macOS 和 visionOS 上创建原生体验的搜索功能。它弥合了 UISearchBar（iOS/visionOS）与原生 SwiftUI 视图（macOS）之间的差距，为样式、行为以及搜索令牌和动态建议等高级功能提供了统一的 API。

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

1. 识别平台目标： SearchBar 在 iOS/visionOS（封装 UISearchBar）和 macOS（自定义 SwiftUI）上的行为略有不同。始终检查或询问目标平台，以提供准确的建议（例如，特定的材质效果或令牌行为）。
优先使用修饰符： 引导用户使用相关的 SearchBar 修饰符（例如 .searchBarStyle、.searchBarSuggestions），而不是建议他们从头开始构建自定义视图。
明确可用性： 在讨论高级功能时，明确提及版本要求（iOS 14+，令牌/建议需要 iOS 16+）。
强调本地化： 提醒用户 SearchBar 已完全本地化，并会自动适应系统语言。
上下文示例： 提供简洁的代码片段，说明在 View 中的推荐用法，通常使用 @State 绑定文本和令牌。
突出跨平台： 在可能的情况下，提醒用户 SearchBar 的跨平台一致性，以及如何在必要时使用 #if os(...) 指令处理特定于平台的差异（尽管该库在内部处理了大部分）。

项目设置

- 部署目标： iOS 14.0+、iPadOS 14.0+、macOS 11.0+、visionOS 1.0+。
高级功能： 令牌和建议需要 iOS 16.0+、iPadOS 16.0+、visionOS 1.0+。（macOS 15.0+ 也支持建议）。
Swift 版本： Swift 5.9+。

快速决策树

1. 设置基本搜索栏？

* 基本初始化和设置 → references/SearchBar.md

2. 自定义外观？

* 更改颜色、形状（胶囊/圆角） → references/SearchBarStyle.md * 使用“玻璃”或“实心”材质 → references/SearchBarStyle.md * 更改大小/缩放 → references/SearchBarStyle.md * 自定义图标 → references/SearchBarModifiers.md (.searchBarIconView)

3. 配置行为？

* 显示/隐藏取消或清除按钮 → references/SearchBarDisplayModes.md * 处理事件（开始/结束编辑、清除、取消） → references/SearchBarModifiers.md * 焦点管理 → references/SearchBarModifiers.md (.searchBarIsFocused)

4. 使用高级搜索功能（iOS 16+/visionOS）？

* 添加过滤令牌（胶囊） → references/SearchBarData.md * 显示搜索建议 → references/SearchBarData.md * 启用自动建议过滤 → references/SearchBarData.md

分类优先手册

- “我的搜索栏在 macOS 上看起来不同。”

* 解释 macOS 使用纯 SwiftUI 实现，而 iOS 使用 UISearchBar。样式是一致的，但底层实现不同。

- “令牌/建议没有显示。”

* 验证部署目标是否为 iOS 16.0+ 或 visionOS 1.0+。 * 确保令牌/建议的绑定处于活动状态并已填充。

- “如何更改背景颜色？”

* 使用 .searchBarStyle(..., backgroundColor: .red)。请参阅 references/SearchBarStyle.md。

- “我想隐藏取消按钮。”

* 使用 .searchBarCancelButtonDisplayMode(.never)。请参阅 references/SearchBarDisplayModes.md。

- “如何让搜索栏变成玻璃/透明？”

* 使用 .searchBarMaterial(.glass)。注意平台/版本限制（iOS 26+）。请参阅 references/SearchBarStyle.md。

核心模式参考

基本设置

swift SearchBar(text: $text, prompt: 搜索...) .searchBarStyle(.rounded)

高级样式

swift SearchBar(text: $text) .searchBarStyle(.capsule, textColor: .white, tint: .blue, backgroundColor: .black.opacity(0.8)) .searchBarMaterial(.glass) // iOS 26+（实验性/未来）

令牌和建议

swift SearchBar(text: $text) .searchBarCurrentTokens($tokens) .searchBarSuggestions($suggestions) .searchBarEnableAutomaticSuggestionsFiltering(true)

事件处理

swift SearchBar(text: $text) .searchBarBeginEditingAction { print(开始编辑) } .searchBarEndEditingAction { print(结束编辑) } .searchBarCancelButtonAction { print(已取消) }

集成快速指南

SearchBar 通过 Swift Package Manager 集成。

1. 添加包依赖： 在 Xcode 中，转到 文件 > 添加包依赖，然后输入 https://github.com/SzpakKamil/SearchBar.git。
导入： 在你的 Swift 文件中 import SearchBar。
部署目标： 确保你的项目目标为 iOS 14.0+、macOS 11.0+、visionOS 1.0+。

有关详细设置，请参阅 references/SearchBar.md。

参考文件

- SearchBar.md - 一般概述、设置和初始化。
SearchBarModifiers.md - 所有修饰符的完整列表。
SearchBarStyle.md - 样式、材质、圆角样式和缩放。
SearchBarDisplayModes.md - 取消和清除按钮行为。
SearchBarData.md - 搜索令牌和建议。
_index.md - 所有主题的索引。