SwiftUI Search API Referenz
Übersicht
Die SwiftUI-Suche ist umgebungsbasiert und navigationskonsumiert. Du hängst .searchable() an eine View an, aber ein Navigationscontainer (NavigationStack, NavigationSplitView oder TabView) rendert das eigentliche Suchfeld. Diese Indirektion ist die Quelle der meisten Suchfehler.
API-Entwicklung
| iOS | Wichtige Neuerungen |
|---|---|
| 15 | .searchable(text:), isSearching, dismissSearch, Vorschläge, .searchCompletion(), onSubmit(of: .search) |
| 16 | Suchbereiche (.searchScopes), Such-Token (.searchable(text:tokens:)), SearchScopeActivation |
| 16.4 | Suchbereich activation-Parameter (.onTextEntry, .onSearchPresentation) |
| 17 | isPresented-Parameter, suggestedTokens-Parameter |
| 17.1 | .searchPresentationToolbarBehavior(.avoidHidingContent) |
| 18 | .searchFocused($isFocused) für programmatische Fokussteuerung |
| 26 | Unten ausgerichtete Suche, .searchToolbarBehavior(.minimize), Tab(role: .search), DefaultToolbarItem(kind: .search) — siehe axiom-swiftui-26-ref |
Wann dieses Skill verwenden
- Hinzufügen einer Suche zu einer SwiftUI-Liste oder Sammlung
- Implementieren von Filter-beim-Tippen oder eingabebasierter Suche
- Hinzufügen von Suchvorschlägen mit Autovervollständigung
- Verwenden von Suchbereichen, um Ergebnisse nach Kategorie einzugrenzen
- Verwenden von Such-Token für strukturierte Abfragen
- Programmatisches Steuern des Suchfokus
- Debuggen von Problemen, wenn das Suchfeld nicht angezeigt wird
Für iOS 26 Suchfunktionen (unten ausgerichtet, minimierte Symbolleiste, Such-Tab-Rolle), siehe axiom-swiftui-26-ref.
Teil 1: Der searchable-Modifier
Kern-API
.searchable(
text: Binding<String>,
placement: SearchFieldPlacement = .automatic,
prompt: LocalizedStringKey
)
Verfügbarkeit: iOS 15+, macOS 12+, tvOS 15+, watchOS 8+
Funktionsweise
- Du hängst
.searchable(text: $query)an eine View an - Der nächstgelegene Navigationscontainer (NavigationStack, NavigationSplitView) rendert das Suchfeld
- Die View erhält
isSearchingunddismissSearchüber die Umgebung - Deine View filtert oder fragt basierend auf dem gebundenen Text ab
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("Rezepte")
.searchable(text: $searchText, prompt: "Ein Rezept finden")
}
}
var filteredRecipes: [Recipe] {
if searchText.isEmpty { return recipes }
return recipes.filter { $0.name.localizedCaseInsensitiveContains(searchText) }
}
}
Platzierungsoptionen
| Platzierung | Verhalten |
|---|---|
.automatic | System entscheidet (empfohlen) |
.navigationBarDrawer | Unter dem Navigationstitel (iOS) |
.navigationBarDrawer(displayMode: .always) | Immer sichtbar, nicht beim Scrollen versteckt |
.sidebar | In der Seitenleiste (NavigationSplitView) |
.toolbar | Im Symbolleistenbereich |
.toolbarPrincipal | Im Hauptbereich der Symbolleiste |
Warnung: SwiftUI ignoriert möglicherweise deine Platzierungspräferenz, wenn die View-Hierarchie sie nicht unterstützt. Teste immer auf der Zielplattform.
Spaltenzuordnung in NavigationSplitView
Wo du .searchable anbringst, bestimmt, welche Spalte das Suchfeld anzeigt:
NavigationSplitView {
SidebarView()
.searchable(text: $query) // Suche in der Seitenleiste
} detail: {
DetailView()
}
// vs.
NavigationSplitView {
SidebarView()
} detail: {
DetailView()
.searchable(text: $query) // Suche im Detailbereich
}
// vs.
NavigationSplitView {
SidebarView()
} detail: {
DetailView()
}
.searchable(text: $query) // System entscheidet über die Spalte
Teil 2: Anzeigen von Suchergebnissen
isSearching-Umgebung
@Environment(\.isSearching) private var isSearching
Verfügbarkeit: iOS 15+
Wird true, wenn der Benutzer die Suche aktiviert (auf das Feld tippt), false, wenn er abbricht oder du dismissSearch aufrufst.
Wichtige Regel: isSearching muss von einem Kind der View gelesen werden, die .searchable hat. SwiftUI setzt den Wert in der Umgebung der searchable-View und gibt ihn nicht nach oben weiter.
// Muster: Suchergebnisse bei Suche überlagern
struct WeatherCityList: View {
@State private var searchText = ""
var body: some View {
NavigationStack {
// SearchResultsOverlay liest isSearching
SearchResultsOverlay(searchText: searchText) {
List(favoriteCities) { city in
CityRow(city: city)
}
}
.searchable(text: $searchText)
.navigationTitle("Wetter")
}
}
}
struct SearchResultsOverlay<Content: View>: View {
let searchText: String
@ViewBuilder let content: Content
@Environment(\.isSearching) private var isSearching
var body: some View {
if isSearching {
// Suchergebnisse anzeigen
SearchResults(query: searchText)
} else {
content
}
}
}
dismissSearch-Umgebung
@Environment(\.dismissSearch) private var dismissSearch
Verfügbarkeit: iOS 15+
Der Aufruf von dismissSearch() löscht den Suchtext, entfernt den Fokus und setzt isSearching auf false. Muss innerhalb der searchable-View-Hierarchie aufgerufen werden.
struct SearchResults: View {
@Environment(\.dismissSearch) private var dismissSearch
var body: some View {
List(results) { result in
Button(result.name) {
selectResult(result)
dismissSearch() // Suche nach Auswahl schließen
}
}
}
}
Teil 3: Suchvorschläge
Hinzufügen von Vorschlägen
Übergib einen suggestions-Closure an .searchable:
.searchable(text: $searchText) {
ForEach(suggestedResults) { suggestion in
Text(suggestion.name)
.searchCompletion(suggestion.name)
}
}
Verfügbarkeit: iOS 15+
Vorschläge erscheinen in einer Liste unterhalb des Suchfelds, während der Benutzer tippt.
searchCompletion-Modifier
.searchCompletion(_:) bindet einen Vorschlag an einen Vervollständigungswert. Wenn der Benutzer auf den Vorschlag tippt, wird der Suchtext durch den Vervollständigungswert ersetzt.
.searchable(text: $searchText) {
ForEach(matchingColors) { color in
HStack {
Circle()
.fill(color.value)
.frame(width: 16, height: 16)
Text(color.name)
}
.searchCompletion(color.name) // Tippen füllt die Suche mit dem Farbnamen
}
}
Ohne .searchCompletion(): Vorschläge werden angezeigt, aber durch Antippen passiert nichts mit dem Suchfeld. Dies ist der häufigste Fehler bei Vorschlägen.
Vollständiges Vorschlagsmuster
struct ColorSearchView: View {
@State private var searchText = ""
let allColors: [NamedColor]
var body: some View {
NavigationStack {
List(filteredColors) { color in
ColorRow(color: color)
}
.navigationTitle("Farben")
.searchable(text: $searchText, prompt: "Farben suchen") {
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 in Array konvertieren
}
var filteredColors: [NamedColor] {
if searchText.isEmpty { return allColors }
return allColors.filter {
$0.name.localizedCaseInsensitiveContains(searchText)
}
}
}
Teil 4: Suche absenden
onSubmit(of: .search)
Wird ausgelöst, wenn der Benutzer die Eingabetaste im Suchfeld drückt:
.searchable(text: $searchText)
.onSubmit(of: .search) {
performSearch(searchText)
}
Verfügbarkeit: iOS 15+
Entscheidung: Filtern vs. Absenden
| Muster | Verwende, wenn | Beispiel |
|---|---|---|
| Filter-beim-Tippen | Lokale Daten, schnelles Filtern | Kontakte, Einstellungen |
| Eingabebasierte Suche | Netzwerkanfragen, teure Abfragen | App Store, Websuche |
| Kombiniert | Vorschläge filtern lokal, Absenden löst Server aus | Karten, Shopping |
Kombiniertes Muster: Vorschläge + Absenden
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("Geschäft")
.searchable(text: $searchText, prompt: "Produkte suchen") {
// Lokale Vorschläge aus letzten Suchen
ForEach(matchingRecent, id: \.self) { term in
Label(term, systemImage: "clock")
.searchCompletion(term)
}
}
.onSubmit(of: .search) {
// Serversuche beim Absenden
Task {
searchResults = await ProductAPI.search(searchText)
}
}
}
}
var matchingRecent: [String] {
guard !searchText.isEmpty else { return recentSearches }
return recentSearches.filter {
$0.localizedCaseInsensitiveContains(searchText)
}
}
}
Teil 5: Suchbereiche (iOS 16+)
Hinzufügen von Bereichen
Bereiche fügen einen segmentierten Picker unterhalb des Suchfelds hinzu, um Ergebnisse nach Kategorie einzugrenzen:
enum SearchScope: String, CaseIterable {
case all = "Alle"
case recipes = "Rezepte"
case ingredients = "Zutaten"
}
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("Kochbuch")
.searchable(text: $searchText)
.searchScopes($searchScope) {
ForEach(SearchScope.allCases, id: \.self) { scope in
Text(scope.rawValue).tag(scope)
}
}
}
}
}
Verfügbarkeit: iOS 16+, macOS 13+
Bereichsaktivierung (iOS 16.4+)
Steuere, wann Bereiche angezeigt werden:
.searchScopes($searchScope, activation: .onTextEntry) {
// Bereiche erscheinen nur, wenn der Benutzer zu tippen beginnt
ForEach(SearchScope.allCases, id: \.self) { scope in
Text(scope.rawValue).tag(scope)
}
}
| Aktivierung | Verhalten |
|---|---|
.automatic | Systemstandard |
.onTextEntry | Bereiche erscheinen, wenn der Benutzer Text eingibt |
.onSearchPresentation | Bereiche erscheinen, wenn die Suche aktiviert wird |
Plattformunterschiede:
- iOS/iPadOS: Bereiche erscheinen standardmäßig bei Texteingabe, verschwinden bei Abbrechen
- macOS: Bereiche erscheinen, wenn die Suche dargestellt wird, verschwinden bei Abbrechen
Teil 6: Such-Token (iOS 16+)
Token sind strukturierte Suchelemente, die als „Pillen" im Suchfeld neben dem Freitext erscheinen.
Basis-Token
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("Rezepte")
.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")
}
}
}
}
}
Verfügbarkeit: iOS 16+
Token-Modellanforderungen: Jedes Token-Element muss dem Protokoll Identifiable entsprechen.
Vorgeschlagene Token (iOS 17+)
.searchable(
text: $searchText,
tokens: $tokens,
suggestedTokens: $suggestedTokens,
prompt: "Rezepte durchsuchen"
) { token in
Label(token.displayName, systemImage: token.icon)
}
Verfügbarkeit: iOS 17+ fügt die Parameter suggestedTokens und isPresented hinzu.
Kombinierte Token + Textfilterung
var filteredRecipes: [Recipe] {
var results = allRecipes
// Token-Filter anwenden
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 }
}
}
// Textfilter anwenden
if !searchText.isEmpty {
results = results.filter {
$0.name.localizedCaseInsensitiveContains(searchText)
}
}
return results
}
Teil 7: Programmatische Suchsteuerung (iOS 18+)
searchFocused
Binde einen FocusState<Bool> an das Suchfeld, um die Suche programmatisch zu aktivieren oder zu beenden:
struct ProgrammaticSearchView: View {
@State private var searchText = ""
@FocusState private var isSearchFocused: Bool
var body: some View {
NavigationStack {
VStack {
Button("Suche starten") {
isSearchFocused = true // Suchfeld aktivieren
}
List(filteredItems) { item in
Text(item.name)
}
}
.navigationTitle("Elemente")
.searchable(text: $searchText)
.searchFocused($isSearchFocused) // iOS 18+
}
}
}
Verfügbarkeit: iOS 18+, macOS 15+
Wichtig: searchFocused muss auf dieselbe View wie .searchable oder auf eine untergeordnete View angewendet werden. Wird es auf eine übergeordnete View angewendet, hat es keine Wirkung.
Fehlerbehebung
Suchfeld erscheint nicht
| Ursache | Lösung |
|---|---|
| Kein umschließender Navigationscontainer | In NavigationStack oder NavigationSplitView einbetten |
.searchable an der falschen View | .searchable an ein Kind der Navigationscontainer-View anhängen |
isSearching in der falschen View gelesen | isSearching nur in einer untergeordneten View der .searchable-View lesen |
.searchCompletion() fehlt | .searchCompletion() zu jedem Vorschlagselement hinzufügen |
searchFocused an der falschen View | searchFocused auf dieselbe View wie .searchable oder auf eine untergeordnete View anwenden |
Vorschläge sind interaktiv, tun aber nichts
Problem: Die Vorschlagsliste zeigt Elemente an, aber durch Tippen wird das Suchfeld nicht ausgefüllt.
Ursache: Dem Vorschlagselement fehlt der Modifier .searchCompletion(SOME_VALUE).
Behebung:
.searchable(text: $searchText) {
ForEach(suggestions) { item in
Text(item.name)
.searchCompletion(item.name) // 👈 Wichtig
}
}
Suchtaste auf der Tastatur
Standardmäßig zeigt die Tastatur „Suchen" an. Um dies zu ändern, verwende .submitLabel():
.searchable(text: $searchText)
.submitLabel(.search) // Werte: .done, .go, .send, .join, .route, .search, .continue