Communitygithub.com

ComeOnOliver/skillshub

À utiliser lors de l'implémentation d'une recherche SwiftUI — .searchable, isSearching, suggestions de recherche, portées, jetons, contrôle programmatique de la recherche (iOS 15-18). Pour les améliorations de recherche iOS 26 (alignée en bas, barre d'outils minimisée, rôle d'onglet de recherche), voir swiftui-26-ref.

Qu'est-ce que skillshub ?

Ce skill est une référence complète sur l'API de recherche SwiftUI, conçue pour les développeurs iOS, macOS, tvOS et watchOS. Il couvre l'utilisation du modificateur `.searchable()`, la gestion de l'état de recherche via les environnements `isSearching` et `dismissSearch`, l'ajout de suggestions avec `.searchCompletion()`, la soumission de recherche avec `.onSubmit(of: .search)`, les portées de recherche (`.searchScopes`) et les jetons de recherche (`.searchable(text:tokens:)`). Le skill explique en détail l'architecture basée sur l'environnement où le champ de recherche est rendu par un conteneur de navigation (NavigationStack, NavigationSplitView, TabView), ce qui est une source fréquente de bugs. Il fournit des exemples de code concrets pour chaque fonctionnalité, des modèles de bonnes pratiques, et des conseils de débogage pour les problèmes courants comme le champ de recherche qui n'apparaît pas ou les suggestions qui ne répondent pas au tap. Il est disponible sur les plateformes supportant SwiftUI (iOS 15+, macOS 12+), avec une couverture des améliorations jusqu'à iOS 18 (contrôle de focus programmatique avec `.searchFocused`) et une référence vers iOS 26. Le skill est utile pour tous les développeurs SwiftUI qui implémentent la recherche dans leurs applications, que ce soit pour des données locales (filtrage en temps réel) ou des requêtes réseau (recherche par soumission).

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/CharlesWiltgen/Axiom/axiom-swiftui-search-ref

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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

iOSAjouts clés
15.searchable(text:), isSearching, dismissSearch, suggestions, .searchCompletion(), onSubmit(of: .search)
16Portées de recherche (.searchScopes), jetons de recherche (.searchable(text:tokens:)), SearchScopeActivation
16.4Paramètre activation des portées de recherche (.onTextEntry, .onSearchPresentation)
17Paramètre isPresented, paramètre suggestedTokens
17.1.searchPresentationToolbarBehavior(.avoidHidingContent)
18.searchFocused($isFocused) pour le contrôle de focus programmatique
26Recherche 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

  1. Vous attachez .searchable(text: $query) à une vue
  2. Le conteneur de navigation le plus proche (NavigationStack, NavigationSplitView) affiche le champ de recherche
  3. La vue reçoit isSearching et dismissSearch par l'environnement
  4. 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

PlacementComportement
.automaticLe système décide (recommandé)
.navigationBarDrawerSous le titre de la barre de navigation (iOS)
.navigationBarDrawer(displayMode: .always)Toujours visible, non masqué au défilement
.sidebarDans la colonne de la barre latérale (NavigationSplitView)
.toolbarDans la zone de la barre d'outils
.toolbarPrincipalDans 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

PatternQuand l'utiliserExemple
Filtrage au fur et à mesureDonnées locales, filtrage rapideContacts, paramètres
Recherche par soumissionRequêtes réseau, requêtes coûteusesApp Store, recherche web
CombinéSuggestions filtrent localement, soumission déclenche le serveurMaps, 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)
    }
}
ActivationComportement
.automaticPar défaut du système
.onTextEntryLes portées apparaissent lorsque l'utilisateur tape du texte
.onSearchPresentationLes 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énarioApproche
Raccourcis clavierUtiliser un raccourci clavier (.keyboardShortcut) pour définir le focus sur true
Navigation profondeOuvrir la recherche lors de la navigation vers un écran qui en a besoin
Recherche en un clicBouton "Rechercher" qui active immédiatement le champ
Réinitialisation de la rechercheDé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 :

  1. Aucun conteneur de navigation : .searchable doit être un descendant d'un NavigationStack ou NavigationSplitView
  2. .searchable mal placé : Attacher .searchable à une vue hors de la hiérarchie de navigation
  3. Placement non pris en charge : Certains placements (.sidebar) nécessitent des configurations d'écran partagé spécifiques
  4. .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) ou Task.delayed pour la recherche asynchrone.
  • Transformations coûteuses : Mettez en cache les données filtrées avec @State ou @Binding au lieu de recalculer à chaque rendu.
  • Trop de suggestions : Limitez les suggestions à 5-10 éléments maximum.

Voir aussi

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

Skills associés