SwiftUI 搜尋 API 參考指南
概述
SwiftUI 搜尋是以環境為基礎並由導航容器消耗的。您將 .searchable() 附加到一個視圖上,但實際的搜尋欄是由導航容器(NavigationStack、NavigationSplitView 或 TabView)來呈現的。這種間接性是大多數搜尋錯誤的根源。
API 演進
| iOS | 關鍵新增功能 |
|---|---|
| 15 | .searchable(text:)、isSearching、dismissSearch、建議、.searchCompletion()、onSubmit(of: .search) |
| 16 | 搜尋範圍 (.searchScopes)、搜尋 Token (.searchable(text:tokens:))、SearchScopeActivation |
| 16.4 | 搜尋範圍的 activation 參數 (.onTextEntry、.onSearchPresentation) |
| 17 | isPresented 參數、suggestedTokens 參數 |
| 17.1 | .searchPresentationToolbarBehavior(.avoidHidingContent) |
| 18 | 用於程式化焦點控制的 .searchFocused($isFocused) |
| 26 | 底部對齊搜尋、.searchToolbarBehavior(.minimize)、Tab(role: .search)、DefaultToolbarItem(kind: .search) — 請參閱 axiom-swiftui-26-ref |
何時使用此技能
- 為 SwiftUI 列表或集合新增搜尋功能
- 實作輸入即過濾或基於提交的搜尋
- 新增附自動完成功能的搜尋建議
- 使用搜尋範圍按類別縮小結果範圍
- 使用搜尋 Token 進行結構化查詢
- 程式化控制搜尋焦點
- 除錯「搜尋欄未出現」的問題
如需 iOS 26 搜尋功能(底部對齊、最小化工具列、搜尋標籤角色),請參閱 axiom-swiftui-26-ref。
第一部分:searchable 修飾器
核心 API
.searchable(
text: Binding<String>,
placement: SearchFieldPlacement = .automatic,
prompt: LocalizedStringKey
)
可用性:iOS 15+、macOS 12+、tvOS 15+、watchOS 8+
運作方式
- 您將
.searchable(text: $query)附加到一個視圖上 - 最近的導航容器(NavigationStack、NavigationSplitView)會呈現搜尋欄
- 該視圖透過環境接收
isSearching和dismissSearch - 您的視圖根據綁定的文字進行過濾或查詢
struct RecipeListView: View {
@State private var searchText = ""
let recipes: [Recipe]
var body: some View {
NavigationStack {
List(filteredRecipes) { recipe in
NavigationLink(recipe.name, value: recipe)
}
.navigationTitle("食譜")
.searchable(text: $searchText, prompt: "尋找食譜")
}
}
var filteredRecipes: [Recipe] {
if searchText.isEmpty { return recipes }
return recipes.filter { $0.name.localizedCaseInsensitiveContains(searchText) }
}
}
放置選項
| 放置方式 | 行為 |
|---|---|
.automatic | 系統決定(建議使用) |
.navigationBarDrawer | 導航列標題下方 (iOS) |
.navigationBarDrawer(displayMode: .always) | 始終可見,滾動時不隱藏 |
.sidebar | 側邊欄中 (NavigationSplitView) |
.toolbar | 工具列區域 |
.toolbarPrincipal | 工具列的主要區域 |
陷阱:如果視圖層級不支援,SwiftUI 可能會忽略您的放置偏好。請務必在目標平台上進行測試。
NavigationSplitView 中的欄位關聯
您附加 .searchable 的位置決定了哪個欄位會顯示搜尋欄:
NavigationSplitView {
SidebarView()
.searchable(text: $query) // 在側邊欄中搜尋
} detail: {
DetailView()
}
// 相較於
NavigationSplitView {
SidebarView()
} detail: {
DetailView()
.searchable(text: $query) // 在詳細欄位中搜尋
}
// 相較於
NavigationSplitView {
SidebarView()
} detail: {
DetailView()
}
.searchable(text: $query) // 系統決定欄位
第二部分:顯示搜尋結果
isSearching 環境變數
@Environment(\.isSearching) private var isSearching
可用性:iOS 15+
當使用者啟動搜尋(點擊欄位)時變為 true,當他們取消或您呼叫 dismissSearch 時變為 false。
關鍵規則:isSearching 必須從具有 .searchable 的視圖的子視圖中讀取。SwiftUI 在可搜尋視圖的環境中設定該值,但不會向上傳播。
// 模式:搜尋時覆蓋搜尋結果
struct WeatherCityList: View {
@State private var searchText = ""
var body: some View {
NavigationStack {
// SearchResultsOverlay 會讀取 isSearching
SearchResultsOverlay(searchText: searchText) {
List(favoriteCities) { city in
CityRow(city: city)
}
}
.searchable(text: $searchText)
.navigationTitle("天氣")
}
}
}
struct SearchResultsOverlay<Content: View>: View {
let searchText: String
@ViewBuilder let content: Content
@Environment(\.isSearching) private var isSearching
var body: some View {
if isSearching {
// 顯示搜尋結果
SearchResults(query: searchText)
} else {
content
}
}
}
dismissSearch 環境變數
@Environment(\.dismissSearch) private var dismissSearch
可用性:iOS 15+
呼叫 dismissSearch() 會清除搜尋文字、移除焦點,並將 isSearching 設為 false。必須從可搜尋視圖的層級內部呼叫。
struct SearchResults: View {
@Environment(\.dismissSearch) private var dismissSearch
var body: some View {
List(results) { result in
Button(result.name) {
selectResult(result)
dismissSearch() // 選取後關閉搜尋
}
}
}
}
第三部分:搜尋建議
新增建議
將 suggestions 閉包傳遞給 .searchable:
.searchable(text: $searchText) {
ForEach(suggestedResults) { suggestion in
Text(suggestion.name)
.searchCompletion(suggestion.name)
}
}
可用性:iOS 15+
當使用者正在輸入時,建議會顯示在搜尋欄下方的一個列表中。
searchCompletion 修飾器
.searchCompletion(_:) 將一個建議綁定到一個完成值。當使用者點擊建議時,搜尋文字會被替換為該完成值。
.searchable(text: $searchText) {
ForEach(matchingColors) { color in
HStack {
Circle()
.fill(color.value)
.frame(width: 16, height: 16)
Text(color.name)
}
.searchCompletion(color.name) // 點擊後將搜尋文字填入顏色名稱
}
}
沒有 .searchCompletion():建議會顯示,但點擊它們對搜尋欄沒有任何作用。這是最常見的建議錯誤。
完整建議模式
struct ColorSearchView: View {
@State private var searchText = ""
let allColors: [NamedColor]
var body: some View {
NavigationStack {
List(filteredColors) { color in
ColorRow(color: color)
}
.navigationTitle("顏色")
.searchable(text: $searchText, prompt: "搜尋顏色") {
ForEach(suggestedColors) { color in
Label(color.name, systemImage: "paintpalette")
.searchCompletion(color.name)
}
}
}
}
var suggestedColors: [NamedColor] {
guard !searchText.isEmpty else { return [] }
return allColors.filter {
$0.name.localizedCaseInsensitiveContains(searchText)
}
.prefix(5)
.map { $0 } // 將 ArraySlice 轉換為 Array
}
var filteredColors: [NamedColor] {
if searchText.isEmpty { return allColors }
return allColors.filter {
$0.name.localizedCaseInsensitiveContains(searchText)
}
}
}
第四部分:搜尋提交
onSubmit(of: .search)
當使用者在搜尋欄中按下 Return/Enter 時觸發:
.searchable(text: $searchText)
.onSubmit(of: .search) {
performSearch(searchText)
}
可用性:iOS 15+
過濾 vs 提交決策
| 模式 | 使用時機 | 範例 |
|---|---|---|
| 輸入即過濾 | 本地資料、快速過濾 | 聯絡人、設定 |
| 基於提交的搜尋 | 網路請求、昂貴的查詢 | App Store、網頁搜尋 |
| 組合模式 | 建議在本地過濾,提交觸發伺服器 | 地圖、購物 |
組合建議 + 提交模式
struct StoreSearchView: View {
@State private var searchText = ""
@State private var searchResults: [Product] = []
let recentSearches: [String]
var body: some View {
NavigationStack {
List(searchResults) { product in
ProductRow(product: product)
}
.navigationTitle(\