SwiftUI Search API リファレンス は何をしますか?
概要
SwiftUI の検索は環境ベースで、ナビゲーションによって消費されます。.searchable() をビューにアタッチしますが、実際の検索フィールドをレンダリングするのはナビゲーションコンテナ(NavigationStack、NavigationSplitView、または TabView)です。この間接性が、ほとんどの検索バグの原因です。
API の進化
| iOS | 主な追加機能 |
|---|---|
| 15 | .searchable(text:)、isSearching、dismissSearch、サジェスチョン、.searchCompletion()、onSubmit(of: .search) |
| 16 | 検索スコープ(.searchScopes)、検索トークン(.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 のリストまたはコレクションに検索を追加する場合
- 入力に応じたフィルターや送信ベースの検索を実装する場合
- オートコンプリート付きの検索候補を追加する場合
- カテゴリごとに結果を絞り込む検索スコープを使用する場合
- 構造化クエリに検索トークンを使用する場合
- プログラムで検索フォーカスを制御する場合
- 「検索フィールドが表示されない」問題をデバッグする場合
iOS 26 の検索機能(下部配置、最小化ツールバー、検索タブロール)については、axiom-swiftui-26-ref を参照してください。
パート 1: 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("Recipes")
.searchable(text: $searchText, prompt: "Find a recipe")
}
}
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) // システムが列を決定
パート 2: 検索結果の表示
isSearching 環境
@Environment(\.isSearching) private var isSearching
利用可能性: iOS 15+
ユーザーが検索をアクティブにすると(フィールドをタップ)true になり、キャンセルするか dismissSearch を呼び出すと false になります。
重要なルール: isSearching は、.searchable を持つビューの子から読み取る必要があります。SwiftUI はこの値を searchable ビューの環境に設定し、上方向には伝播しません。
// パターン: 検索中に検索結果をオーバーレイ表示
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("Weather")
}
}
}
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 に設定されます。searchable ビュー階層の内部から呼び出す必要があります。
struct SearchResults: View {
@Environment(\.dismissSearch) private var dismissSearch
var body: some View {
List(results) { result in
Button(result.name) {
selectResult(result)
dismissSearch() // 選択後に検索を閉じる
}
}
}
}
パート 3: 検索候補 (サジェスチョン)
サジェスチョンの追加
.searchable に suggestions クロージャを渡します。
.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("Colors")
.searchable(text: $searchText, prompt: "Search colors") {
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)
}
}
}
パート 4: 検索送信 (サブミット)
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("Store")
.searchable(text: $searchText, prompt: "Search products") {
// 最近の検索からのローカルサジェスチョン
ForEach(matchingRecent, id: \.self) { term in
Label(term, systemImage: "clock")
.searchCompletion(term)
}
}
.onSubmit(of: .search) {
// サブミット時にサーバー検索
Task {
searchResults = await ProductAPI.search(searchText)
}
}
}
}
var matchingRecent: [String] {
guard !searchText.isEmpty else { return recentSearches }
return recentSearches.filter {
$0.localizedCaseInsensitiveContains(searchText)
}
}
}
パート 5: 検索スコープ (iOS 16+)
スコープの追加
スコープは、検索フィールドの下にセグメント化されたピッカーを追加して、結果をカテゴリごとに絞り込みます。
enum SearchScope: String, CaseIterable {
case all = "All"
case recipes = "Recipes"
case ingredients = "Ingredients"
}
struct ScopedSearchView: View {
@State private var searchText = ""
@State private var searchScope: SearchScope = .all
var body: some View {
NavigationStack {
List(filteredResults) { result in
ResultRow(result: result)
}
.navigationTitle("Cookbook")
.searchable(text: $searchText)
.searchScopes($searchScope) {
ForEach(SearchScope.allCases, id: \.self) { scope in
Text(scope.rawValue).tag(scope)
}
}
}
}
}
利用可能性: iOS 16+、macOS 13+
スコープのアクティベーション (iOS 16.4+)
スコープが表示されるタイミングを制御します。
.searchScopes($searchScope, activation: .onTextEntry) {
// スコープはユーザーが入力を開始したときにのみ表示される
ForEach(SearchScope.allCases, id: \.self) { scope in
Text(scope.rawValue).tag(scope)
}
}
| アクティベーション | 動作 |
|---|---|
.automatic | システムのデフォルト |
.onTextEntry | ユーザーがテキストを入力するとスコープが表示される |
.onSearchPresentation | 検索がアクティブになるとスコープが表示される |
プラットフォームの違い:
- iOS/iPadOS: デフォルトでテキスト入力時にスコープが表示され、キャンセル時に非表示になる
- macOS: 検索が表示されるとスコープが表示され、キャンセル時に非表示になる
パート 6: 検索トークン (iOS 16+)
トークンは、フリーテキストと一緒に検索フィールドに「ピル」として表示される構造化された検索要素です。
基本的なトークン
enum RecipeToken: Identifiable, Hashable {
case cuisine(String)
case difficulty(String)
var id: Self { self }
}
struct TokenSearchView: View {
@State private var searchText = ""
@State private var tokens: [RecipeToken] = []
var body: some View {
NavigationStack {
List(filteredRecipes) { recipe in
RecipeRow(recipe: recipe)
}
.navigationTitle("Recipes")
.searchable(text: $searchText, tokens: $tokens) { token in
switch token {
case .cuisine(let name):
Label(name, systemImage: "globe")
case .difficulty(let name):
Label(name, systemImage: "star")
}
}
}
}
}
利用可能性: iOS 16+
トークンモデルの要件: 各トークン要素は Identifiable に準拠する必要があります。
サジェストされたトークン (iOS 17+)
.searchable(
text: $searchText,
tokens: $tokens,
suggestedTokens: $suggestedTokens,
prompt: "Search recipes"
) { token in
Label(token.displayName, systemImage: token.icon)
}
利用可能性: iOS 17+ で suggestedTokens と isPresented パラメータが追加されました。
トークンとテキストフィルタリングの組み合わせ
var filteredRecipes: [Recipe] {
var results = allRecipes
// トークンフィルターを適用
for token in tokens {
switch token {
case .cuisine(let cuisine):
results = results.filter { $0.cuisine == cuisine }
case .difficulty(let difficulty):
results = results.filter { $0.difficulty == difficulty }
}
}
// テキストフィルターを適用
if !searchText.isEmpty {
results = results.filter {
$0.name.localizedCaseInsensitiveContains(searchText)
}
}
return results
}
パート 7: プログラムによる検索制御 (iOS 18+)
searchFocused
FocusState<Bool> を検索フィールドにバインドして、プログラムで検索をアクティブ化または解除します。
struct ProgrammaticSearchView: View {
@State private var searchText = ""
@FocusState private var isSearchFocused: Bool
var body: some View {
NavigationStack {
VStack {
Button("Start Search") {
isSearchFocused = true // 検索フィールドをアクティブ化
}
List(filteredItems) { item in
Text(item.name)
}
}
.navigationTitle("Items")
.searchable(text: $searchText)
.searchFocused($isSearchFocused)
}
}
}
利用可能性: iOS 18+
searchFocused は .searchable と同じビューにアタッチする必要があります。FocusState の値が true に設定されると、ユーザーがタップしたかのように検索フィールドがアクティブになります。
searchFocused の一般的な問題
問題: アラートやシート内からフォーカスを設定できない
回避策: フォーカスは、searchable 修飾子を含むビューと同じウィンドウ/シーンの一部である必要があります。
// ✅ 動作する: 同じビュー階層
NavigationStack {
content
.searchable(text: $query)
.searchFocused($isFocused)
}
// ❌ 動作しない: 別のシーンまたはモーダル
.sheet(isPresented: $showSheet) {
SheetView()
.searchable(text: $query)
.searchFocused($isFocused) // 予想通りに動作しない可能性がある
}
一般的な問題のトラブルシューティング
「検索フィールドが表示されない」
原因: .searchable がナビゲーションコンテナの外にある。
// ❌ 間違い: ナビゲーションコンテナがない
VStack {
List { ... }
}
.searchable(text: $query)
// ✅ 正しい: NavigationStack 内
NavigationStack {
List { ... }
.searchable(text: $query)
}
「サジェスチョンが表示されない」
原因: searchCompletion が必要。閉じられた suggestions クロージャにテキストまたはサジェスチョンがある。
// ❌ 間違い: searchCompletion がない
.searchable(text: $query) {
ForEach(suggestions) { Text($0.name) }
}
// ✅ 正しい
.searchable(text: $query) {
ForEach(suggestions) {
Text($0.name).searchCompletion($0.name)
}
}
「環境値が機能しない」
原因: isSearching または dismissSearch が間違ったビューで読み取られている。
// ❌ 間違い: searchable と同じビュー
struct MyView: View {
@Environment(\.isSearching) private var isSearching
var body: some View {
NavigationStack {
List { ... }
}
.searchable(text: $query)
}
}
// ✅ 正しい: searchable を持つビューの子
struct MyView: View {
var body: some View {
NavigationStack {
SearchConsumer() // ここで isSearching を読み取る
.searchable(text: $query)
}
}
}
クイックリファレンス
最小限の実装
struct MinimalSearch: View {
@State private var query = ""
var body: some View {
NavigationStack {
List(filteredItems) { item in
Text(item.name)
}
.searchable(text: $query)
}
}
var filteredItems: [Item] {
if query.isEmpty { return allItems }
return allItems.filter { $0.name.localizedCaseInsensitiveContains(query) }
}
}
サジェスチョンあり
NavigationStack {
List(filteredItems) { ... }
.searchable(text: $query) {
ForEach(suggestions) {
Label($0.name, systemImage: $0.icon)
.searchCompletion($0.name)
}
}
}
スコープあり
NavigationStack {
List(filteredItems) { ... }
.searchable(text: $query)
.searchScopes($scope) {
ForEach(Scope.allCases, id: \.self) {
Text($0.rawValue).tag($0)
}
}
}
トークンあり
NavigationStack {
List(filteredItems) { ... }
.searchable(text: $query, tokens: $tokens) { token in
Label(token.label, systemImage: token.icon)
}
}
プログラムフォーカス制御あり
@FocusState private var focused: Bool
NavigationStack {
List(filteredItems) { ... }
.searchable(text: $query)
.searchFocused($focused)
}
// focused = true で検索をアクティブ化