SearchBar 技能

概述

本技能提供关于 SearchBar 的专家级指导——这是一个功能强大且高度可定制的 SwiftUI 组件，用于在 iOS、iPadOS、macOS 和 visionOS 上构建原生体验的搜索界面。它弥合了 UISearchBar（iOS/visionOS）与原生 SwiftUI 视图（macOS）之间的差异，为样式设置、行为控制以及高级功能（如搜索标记 token 和动态建议 suggestions）提供了统一的 API。

智能体行为（请严格遵守以下规则）

1. 识别目标平台：SearchBar 在 iOS/visionOS（封装 UISearchBar）与 macOS（纯 SwiftUI 自定义实现）上的行为略有不同。务必确认或主动询问用户的目标平台，以提供准确建议（例如特定材质效果或标记行为）。
2. 优先使用修饰符（Modifiers）：引导用户使用对应的 SearchBar 修饰符（例如 .searchBarStyle、.searchBarSuggestions），而非建议其从零开始构建自定义视图。
3. 明确可用性要求：讨论高级功能（如标记和建议）时，需明确指出版本要求（例如：iOS 14+ 基础支持；iOS 16+ / iPadOS 16+ / visionOS 1.0+ 支持标记与建议）。
4. 强调本地化支持：提醒用户 SearchBar 具备完整本地化能力，可自动适配系统语言。
5. 提供上下文化示例：给出简洁的代码片段，展示如何在 View 中推荐使用该组件，通常包含绑定至 @State 的文本与标记变量。
6. 突出跨平台一致性：尽可能强调 SearchBar 的跨平台一致性，并说明必要时如何通过 #if os(...) 指令处理平台特异性差异（尽管该库已在内部处理了大部分兼容逻辑）。

项目设置

• 部署目标：iOS 14.0+、iPadOS 14.0+、macOS 11.0+、visionOS 1.0+。
• 高级功能支持：标记（Tokens）与建议（Suggestions）需 iOS 16.0+、iPadOS 16.0+、visionOS 1.0+；建议功能亦支持 macOS 15.0+。
• Swift 版本：Swift 5.9+。

快速决策树

1. 搭建基础搜索栏？

   • 基础初始化与配置 → references/SearchBar.md

2. 自定义外观？

   • 修改颜色、形状（胶囊形/capsule 或圆角/rounded）→ references/SearchBarStyle.md
   • 使用 “Glass” 或 “Solid” 材质 → references/SearchBarStyle.md
   • 调整尺寸/缩放比例 → references/SearchBarStyle.md
   • 自定义图标 → references/SearchBarModifiers.md（使用 .searchBarIconView）

3. 配置行为？

   • 显示/隐藏取消（Cancel）或清除（Clear）按钮 → references/SearchBarDisplayModes.md
   • 响应事件（开始/结束编辑、清除、取消）→ references/SearchBarModifiers.md
   • 焦点管理 → references/SearchBarModifiers.md（使用 .searchBarIsFocused）

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

   • 添加筛选标记（capsule 形式）→ references/SearchBarData.md
   • 显示搜索建议 → references/SearchBarData.md
   • 启用自动建议过滤 → references/SearchBarData.md

问题分诊优先操作手册（Triage-First Playbook）

• “我的搜索栏在 macOS 上显示效果不同。”
  • 解释：macOS 使用纯 SwiftUI 实现，而 iOS 基于 UISearchBar 封装；样式表现一致，但底层实现不同。
• “标记（Tokens）/建议（Suggestions）未显示。”
  • 确认部署目标是否为 iOS 16.0+ 或 visionOS 1.0+。
  • 确保绑定至 tokens/suggestions 的状态变量已激活且已填充数据。
• “如何更改背景色？”
  • 使用 .searchBarStyle(..., backgroundColor: .red)。详见 references/SearchBarStyle.md。
• “我想隐藏取消按钮。”
  • 使用 .searchBarCancelButtonDisplayMode(.never)。详见 references/SearchBarDisplayModes.md。
• “如何让搜索栏呈现玻璃质感/透明效果？”
  • 使用 .searchBarMaterial(.glass)。注意平台与版本限制（仅限 iOS 26+，当前为实验性/未来特性）。详见 references/SearchBarStyle.md。

核心模式参考

基础配置

SearchBar(text: $text, prompt: "Search...")
    .searchBarStyle(.rounded)

高级样式设置

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

标记与建议

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

事件处理

SearchBar(text: $text)
    .searchBarBeginEditingAction { print("Started") }
    .searchBarEndEditingAction { print("Ended") }
    .searchBarCancelButtonAction { print("Cancelled") }

集成快速指南

SearchBar 通过 Swift Package Manager 集成。

1. 添加包依赖：在 Xcode 中，依次选择 File > Add Package Dependency，然后输入 https://github.com/SzpakKamil/SearchBar.git。
2. 导入模块：在 Swift 文件中添加 import SearchBar。
3. 部署目标：确保项目部署目标为 iOS 14.0+、macOS 11.0+、visionOS 1.0+。

详细配置说明请参阅 references/SearchBar.md。

参考文档列表

• SearchBar.md —— 总览、基础配置与初始化说明。
• SearchBarModifiers.md —— 所有修饰符的完整列表。
• SearchBarStyle.md —— 样式、材质、圆角样式与缩放比例设置。
• SearchBarDisplayModes.md —— 取消按钮与清除按钮的行为控制。
• SearchBarData.md —— 搜索标记（Tokens）与建议（Suggestions）相关功能。
• _index.md —— 全部主题索引。