Référence de l'API de recherche SwiftUI
Vue d'ensemble
La recherche SwiftUI est basée sur l'environnement et consommée par la navigation. Vous attachez .searchable() à une vue, mais un conteneur de navigation (NavigationStack, NavigationSplitView ou TabView) affiche le champ de recherche réel. Cette indirection est la source de la plupart des bugs de recherche.
Évolution de l'API
| iOS | Ajouts clés |
|---|---|
| 15 | .searchable(text:), isSearching, dismissSearch, suggestions, .searchCompletion(), onSubmit(of: .search) |
| 16 | Portées de recherche (.searchScopes), jetons de recherche (.searchable(text:tokens:)), SearchScopeActivation |
| 16.4 | Paramètre activation des portées de recherche (.onTextEntry, .onSearchPresentation) |
| 17 | Paramètre isPresented, paramètre suggestedTokens |
| 17.1 | .searchPresentationToolbarBehavior(.avoidHidingContent) |
| 18 | .searchFocused($isFocused) pour le contrôle de focus programmatique |
| 26 | Recherche alignée en bas, .searchToolbarBehavior(.minimize), Tab(role: .search), DefaultToolbarItem(kind: .search) — voir axiom-swiftui-26-ref |
Quand utiliser ce skill
- Ajout d'une recherche à une liste ou collection SwiftUI
- Implémentation d'un filtrage au fur et à mesure de la frappe ou d'une recherche basée sur la soumission
- Ajout de suggestions de recherche avec auto-complétion
- Utilisation de portées de recherche pour affiner les résultats par catégorie
- Utilisation de jetons de recherche pour des requêtes structurées
- Contrôle du focus de recherche par programmation
- Débogage des problèmes "le champ de recherche n'apparaît pas"
Pour les fonctionnalités de recherche iOS 26 (alignée en bas, barre d'outils minimisée, rôle d'onglet de recherche), voir axiom-swiftui-26-ref.
Partie 1 : Le modificateur searchable
API de base
.searchable(
text: Binding<String>,
placement: SearchFieldPlacement = .automatic,
prompt: LocalizedStringKey
)
Disponibilité : iOS 15+, macOS 12+, tvOS 15+, watchOS 8+
Comment ça marche
- Vous attachez
.searchable(text: $query)à une vue - Le conteneur de navigation le plus proche (NavigationStack, NavigationSplitView) affiche le champ de recherche
- La vue reçoit
isSearchingetdismissSearchpar l'environnement - Votre vue filtre ou interroge en fonction du texte lié
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) }
}
}
Options de placement
| Placement | Comportement |
|---|---|
.automatic | Le système décide (recommandé) |
.navigationBarDrawer | Sous le titre de la barre de navigation (iOS) |
.navigationBarDrawer(displayMode: .always) | Toujours visible, non masqué au défilement |
.sidebar | Dans la colonne de la barre latérale (NavigationSplitView) |
.toolbar | Dans la zone de la barre d'outils |
.toolbarPrincipal | Dans la section principale de la barre d'outils |
Piège : SwiftUI peut ignorer votre préférence de placement si la hiérarchie de vues ne la prend pas en charge. Testez toujours sur la plateforme cible.
Association de colonne dans NavigationSplitView
L'endroit où vous attachez .searchable détermine quelle colonne affiche le champ de recherche :
NavigationSplitView {
SidebarView()
.searchable(text: $query) // Recherche dans la barre latérale
} detail: {
DetailView()
}
// vs.
NavigationSplitView {
SidebarView()
} detail: {
DetailView()
.searchable(text: $query) // Recherche dans le détail
}
// vs.
NavigationSplitView {
SidebarView()
} detail: {
DetailView()
}
.searchable(text: $query) // Le système décide de la colonne
Partie 2 : Affichage des résultats de recherche
Environnement isSearching
@Environment(\.isSearching) private var isSearching
Disponibilité : iOS 15+
Devient true lorsque l'utilisateur active la recherche (tape dans le champ), false lorsqu'il annule ou que vous appelez dismissSearch.
Règle critique : isSearching doit être lu depuis un enfant de la vue qui a .searchable. SwiftUI définit la valeur dans l'environnement de la vue searchable et ne la propage pas vers le haut.
// Pattern : Superposer les résultats de recherche lors de la recherche
struct WeatherCityList: View {
@State private var searchText = ""
var body: some View {
NavigationStack {
// SearchResultsOverlay lit 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 {
// Afficher les résultats de recherche
SearchResults(query: searchText)
} else {
content
}
}
}
Environnement dismissSearch
@Environment(\.dismissSearch) private var dismissSearch
Disponibilité : iOS 15+
Appeler dismissSearch() efface le texte de recherche, supprime le focus et définit isSearching à false. Doit être appelé depuis l'intérieur de la hiérarchie de la vue searchable.
struct SearchResults: View {
@Environment(\.dismissSearch) private var dismissSearch
var body: some View {
List(results) { result in
Button(result.name) {
selectResult(result)
dismissSearch() // Fermer la recherche après la sélection
}
}
}
}
Partie 3 : Suggestions de recherche
Ajout de suggestions
Passez une fermeture suggestions à .searchable :
.searchable(text: $searchText) {
ForEach(suggestedResults) { suggestion in
Text(suggestion.name)
.searchCompletion(suggestion.name)
}
}
Disponibilité : iOS 15+
Les suggestions apparaissent dans une liste sous le champ de recherche lorsque l'utilisateur tape.
Modificateur searchCompletion
.searchCompletion(_:) lie une suggestion à une valeur de complétion. Lorsque l'utilisateur tape sur la suggestion, le texte de recherche est remplacé par la valeur de complétion.
.searchable(text: $searchText) {
ForEach(matchingColors) { color in
HStack {
Circle()
.fill(color.value)
.frame(width: 16, height: 16)
Text(color.name)
}
.searchCompletion(color.name) // Taper remplit la recherche avec le nom de la couleur
}
}
Sans .searchCompletion() : Les suggestions s'affichent mais taper dessus ne fait rien pour le champ de recherche. C'est le bug de suggestions le plus courant.
Pattern de suggestion complet
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 } // Convertir ArraySlice en Array
}
var filteredColors: [NamedColor] {
if searchText.isEmpty { return allColors }
return allColors.filter {
$0.name.localizedCaseInsensitiveContains(searchText)
}
}
}
Partie 4 : Soumission de recherche
onSubmit(of: .search)
Se déclenche lorsque l'utilisateur appuie sur Retour/Entrée dans le champ de recherche :
.searchable(text: $searchText)
.onSubmit(of: .search) {
performSearch(searchText)
}
Disponibilité : iOS 15+
Décision Filtre vs Soumission
| Pattern | Quand l'utiliser | Exemple |
|---|---|---|
| Filtrage au fur et à mesure | Données locales, filtrage rapide | Contacts, paramètres |
| Recherche par soumission | Requêtes réseau, requêtes coûteuses | App Store, recherche web |
| Combiné | Suggestions filtrent localement, soumission déclenche le serveur | Maps, shopping |
Pattern combiné Suggestions + Soumission
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") {
// Suggestions locales issues des recherches récentes
ForEach(matchingRecent, id: \.self) { term in
Label(term, systemImage: "clock")
.searchCompletion(term)
}
}
.onSubmit(of: .search) {
// Recherche serveur lors de la soumission
Task {
searchResults = await ProductAPI.search(searchText)
}
}
}
}
var matchingRecent: [String] {
guard !searchText.isEmpty else { return recentSearches }
return recentSearches.filter {
$0.localizedCaseInsensitiveContains(searchText)
}
}
}
Partie 5 : Portées de recherche (iOS 16+)
Ajout de portées
Les portées ajoutent un sélecteur segmenté sous le champ de recherche pour affiner les résultats par catégorie :
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)
}
}
}
}
}
Disponibilité : iOS 16+, macOS 13+
Activation de portée (iOS 16.4+)
Contrôlez quand les portées apparaissent :
.searchScopes($searchScope, activation: .onTextEntry) {
// Les portées apparaissent uniquement lorsque l'utilisateur commence à taper
ForEach(SearchScope.allCases, id: \.self) { scope in
Text(scope.rawValue).tag(scope)
}
}
| Activation | Comportement |
|---|---|
.automatic | Par défaut du système |
.onTextEntry | Les portées apparaissent lorsque l'utilisateur tape du texte |
.onSearchPresentation | Les portées apparaissent lorsque la recherche est activée |
Différences de plateforme :
- iOS/iPadOS : Les portées apparaissent sur la saisie de texte par défaut, se ferment sur l'annulation
- macOS : Les portées apparaissent lorsque la recherche est présentée, se ferment sur l'annulation
Partie 6 : Jetons de recherche (iOS 16+)
Les jetons sont des éléments de recherche structurés qui apparaissent sous forme de "pilules" dans le champ de recherche à côté du texte libre.
Jetons de base
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")
}
}
}
}
}
Disponibilité : iOS 16+
Exigences du modèle de jeton : Chaque élément de jeton doit se conformer à Identifiable.
Jetons suggérés (iOS 17+)
.searchable(
text: $searchText,
tokens: $tokens,
suggestedTokens: $suggestedTokens,
prompt: "Search recipes"
) { token in
Label(token.displayName, systemImage: token.icon)
}
Disponibilité : iOS 17+ ajoute les paramètres suggestedTokens et isPresented.
Filtrage combiné Jetons + Texte
var filteredRecipes: [Recipe] {
var results = allRecipes
// Appliquer les filtres de jetons
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 }
}
}
// Appliquer le filtre de texte
if !searchText.isEmpty {
results = results.filter {
$0.name.localizedCaseInsensitiveContains(searchText)
}
}
return results
}
Partie 7 : Contrôle programmatique de la recherche (iOS 18+)
searchFocused
Liez un FocusState<Bool> au champ de recherche pour activer ou fermer la recherche par programmation :
struct ProgrammaticSearchView: View {
@State private var searchText = ""
@FocusState private var isSearchFocused: Bool
var body: some View {
NavigationStack {
VStack {
Button("Start Search") {
isSearchFocused = true // Activer le champ de recherche
}
List(filteredItems) { item in
Text(item.name)
}
}
.navigationTitle("Items")
.searchable(text: $searchText)
.searchFocused($isSearchFocused)
}
}
}
Disponibilité : iOS 18+, macOS 15+
Piège : Vous devez attacher .searchFocused à la même vue que .searchable. Les attacher à des vues différentes ne fonctionne pas.
Cas d'utilisation
| Scénario | Approche |
|---|---|
| Raccourcis clavier | Utiliser un raccourci clavier (.keyboardShortcut) pour définir le focus sur true |
| Navigation profonde | Ouvrir la recherche lors de la navigation vers un écran qui en a besoin |
| Recherche en un clic | Bouton "Rechercher" qui active immédiatement le champ |
| Réinitialisation de la recherche | Définir le focus sur false après avoir effacé le texte |
Partie 8 : Dépannage
Le champ de recherche n'apparaît pas
Causes courantes :
- Aucun conteneur de navigation :
.searchabledoit être un descendant d'un NavigationStack ou NavigationSplitView - .searchable mal placé : Attacher
.searchableà une vue hors de la hiérarchie de navigation - Placement non pris en charge : Certains placements (
.sidebar) nécessitent des configurations d'écran partagé spécifiques - .searchable sur une feuille modale : Les feuilles dans NavigationStack peuvent perdre le champ de recherche ; ajoutez
.searchableà l'intérieur de la feuille, pas à l'extérieur
Solution de débogage : Placez temporairement .searchable directement sur une vue List dans un NavigationStack. S'il apparaît, le problème est lié au placement.
Les suggestions ne fonctionnent pas
Cause la plus fréquente : Oubli de .searchCompletion(_:) sur les vues de suggestion. Sans cela, les suggestions s'affichent mais ne répondent pas.
Solution : Assurez-vous que chaque élément de suggestion a .searchCompletion(_:) avec une valeur String appropriée.
isSearching toujours faux
Règle : @Environment(\.isSearching) doit être utilisé dans un enfant de la vue qui a .searchable. Le lire dans la même vue qui a .searchable ne fonctionne pas.
// NE FONCTIONNE PAS : isSearching lu dans la même vue
struct ContentView: View {
@State private var query = ""
@Environment(\.isSearching) private var isSearching // Toujours faux
var body: some View {
NavigationStack {
List {...}
.searchable(text: $query)
}
}
}
// FONCTIONNE : isSearching lu dans une vue enfant
struct ContentView: View {
@State private var query = ""
var body: some View {
NavigationStack {
SearchContent(query: $query)
.searchable(text: $query)
}
}
}
struct SearchContent: View {
@Binding var query: String
@Environment(\.isSearching) private var isSearching // Correct
var body: some View {
List {...}
}
}
Pertes de performance
- Filtrage coûteux : Évitez les filtres synchrones coûteux sur l'ensemble de données à chaque frappe. Utilisez
.onSubmit(of: .search)ouTask.delayedpour la recherche asynchrone. - Transformations coûteuses : Mettez en cache les données filtrées avec
@Stateou@Bindingau lieu de recalculer à chaque rendu. - Trop de suggestions : Limitez les suggestions à 5-10 éléments maximum.
Voir aussi
- Documentation officielle Apple : Adding search to your app
- [Documentation du modificateur .searchable](https://developer.apple.com/documentation/swiftui/view/searchable(text:placement:prompt:)
- [Documentation des portées de recherche](https://developer.apple.com/documentation/swiftui/view/searchScopes(_:activation:)
- Documentation de la gestion de focus
- Voir
axiom-swiftui-26-refpour les fonctionnalités de recherche iOS 26 (alignée en bas, barre d'outils minimisée, rôle d'onglet de recherche)