Communitygithub.com

ComeOnOliver/skillshub

Úsalo al implementar búsqueda en SwiftUI — .searchable, isSearching, sugerencias de búsqueda, ámbitos, tokens, control programático de búsqueda (iOS 15-18). Para refinamientos de búsqueda de iOS 26 (alineado abajo, barra de herramientas minimizada, rol de pestaña de búsqueda), consulta swiftui-26-ref.

¿Qué es skillshub?

Este skill proporciona una referencia completa y detallada sobre la API de búsqueda de SwiftUI, cubriendo desde iOS 15 hasta iOS 18. Es esencial para cualquier desarrollador que necesite añadir funcionalidad de búsqueda a sus aplicaciones SwiftUI, ya que explica cómo funciona el sistema basado en entornos y cómo los contenedores de navegación (NavigationStack, NavigationSplitView, TabView) gestionan el campo de búsqueda. El skill aborda las características principales como el modificador `.searchable()`, el entorno `isSearching` para detectar cuándo el usuario está buscando, y `dismissSearch` para cerrar la búsqueda programáticamente. También cubre temas más avanzados como las sugerencias de búsqueda con `.searchCompletion()`, los ámbitos de búsqueda (`.searchScopes`) para filtrar por categorías, los tokens de búsqueda para consultas estructuradas, y el control programático del foco con `searchFocused` en iOS 18+. El objetivo es ayudar a los desarrolladores a evitar errores comunes, como el campo de búsqueda que no aparece, y a implementar patrones de búsqueda eficientes, ya sea filtrado local, búsqueda por envío o una combinación de ambos. Está orientado principalmente a plataformas Apple (iOS, macOS, tvOS, watchOS) y se basa en la documentación de SKILL.md para ofrecer ejemplos de código y patrones de uso.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Referencia de la API de Búsqueda en SwiftUI

Resumen

La búsqueda en SwiftUI está basada en el entorno y consumida por la navegación. Adjuntas .searchable() a una vista, pero un contenedor de navegación (NavigationStack, NavigationSplitView o TabView) renderiza el campo de búsqueda real. Esta indirección es la fuente de la mayoría de los errores de búsqueda.

Evolución de la API

iOSAdiciones Clave
15.searchable(text:), isSearching, dismissSearch, sugerencias, .searchCompletion(), onSubmit(of: .search)
16Ámbitos de búsqueda (.searchScopes), tokens de búsqueda (.searchable(text:tokens:)), SearchScopeActivation
16.4Parámetro activation del ámbito de búsqueda (.onTextEntry, .onSearchPresentation)
17Parámetro isPresented, parámetro suggestedTokens
17.1.searchPresentationToolbarBehavior(.avoidHidingContent)
18.searchFocused($isFocused) para control de foco programático
26Búsqueda alineada abajo, .searchToolbarBehavior(.minimize), Tab(role: .search), DefaultToolbarItem(kind: .search) — consulta axiom-swiftui-26-ref

Cuándo Usar Este Skill

  • Añadiendo búsqueda a una lista o colección de SwiftUI
  • Implementando filtrado mientras escribes o búsqueda basada en envío
  • Añadiendo sugerencias de búsqueda con autocompletado
  • Usando ámbitos de búsqueda para reducir resultados por categoría
  • Usando tokens de búsqueda para consultas estructuradas
  • Controlando el foco de búsqueda programáticamente
  • Depurando problemas donde "el campo de búsqueda no aparece"

Para funciones de búsqueda de iOS 26 (alineado abajo, barra de herramientas minimizada, rol de pestaña de búsqueda), consulta axiom-swiftui-26-ref.


Parte 1: El Modificador searchable

API Principal

.searchable(
    text: Binding<String>,
    placement: SearchFieldPlacement = .automatic,
    prompt: LocalizedStringKey
)

Disponibilidad: iOS 15+, macOS 12+, tvOS 15+, watchOS 8+

Cómo Funciona

  1. Adjuntas .searchable(text: $query) a una vista
  2. El contenedor de navegación más cercano (NavigationStack, NavigationSplitView) renderiza el campo de búsqueda
  3. La vista recibe isSearching y dismissSearch a través del entorno
  4. Tu vista filtra o consulta basándose en el texto vinculado
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) }
    }
}

Opciones de Ubicación

UbicaciónComportamiento
.automaticEl sistema decide (recomendado)
.navigationBarDrawerDebajo del título de la barra de navegación (iOS)
.navigationBarDrawer(displayMode: .always)Siempre visible, no se oculta al desplazar
.sidebarEn la columna de la barra lateral (NavigationSplitView)
.toolbarEn el área de la barra de herramientas
.toolbarPrincipalEn la sección principal de la barra de herramientas

Trampa: SwiftUI puede ignorar tu preferencia de ubicación si la jerarquía de vistas no lo soporta. Siempre prueba en la plataforma objetivo.

Asociación de Columnas en NavigationSplitView

Donde adjuntas .searchable determina qué columna muestra el campo de búsqueda:

NavigationSplitView {
    SidebarView()
        .searchable(text: $query)  // Búsqueda en la barra lateral
} detail: {
    DetailView()
}

// vs.

NavigationSplitView {
    SidebarView()
} detail: {
    DetailView()
        .searchable(text: $query)  // Búsqueda en el detalle
}

// vs.

NavigationSplitView {
    SidebarView()
} detail: {
    DetailView()
}
.searchable(text: $query)  // El sistema decide la columna

Parte 2: Mostrando Resultados de Búsqueda

Entorno isSearching

@Environment(\.isSearching) private var isSearching

Disponibilidad: iOS 15+

Se vuelve true cuando el usuario activa la búsqueda (toca el campo), false cuando cancelan o llamas a dismissSearch.

Regla crítica: isSearching debe leerse desde un hijo de la vista que tiene .searchable. SwiftUI establece el valor en el entorno de la vista buscable y no lo propaga hacia arriba.

// Patrón: Superponer resultados de búsqueda al buscar
struct WeatherCityList: View {
    @State private var searchText = ""

    var body: some View {
        NavigationStack {
            // SearchResultsOverlay lee 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 {
            // Mostrar resultados de búsqueda
            SearchResults(query: searchText)
        } else {
            content
        }
    }
}

Entorno dismissSearch

@Environment(\.dismissSearch) private var dismissSearch

Disponibilidad: iOS 15+

Llamar a dismissSearch() limpia el texto de búsqueda, elimina el foco y establece isSearching a false. Debe llamarse desde dentro de la jerarquía de vistas de la búsqueda.

struct SearchResults: View {
    @Environment(\.dismissSearch) private var dismissSearch

    var body: some View {
        List(results) { result in
            Button(result.name) {
                selectResult(result)
                dismissSearch()  // Cerrar búsqueda después de la selección
            }
        }
    }
}

Parte 3: Sugerencias de Búsqueda

Añadiendo Sugerencias

Pasa un closure de suggestions a .searchable:

.searchable(text: $searchText) {
    ForEach(suggestedResults) { suggestion in
        Text(suggestion.name)
            .searchCompletion(suggestion.name)
    }
}

Disponibilidad: iOS 15+

Las sugerencias aparecen en una lista debajo del campo de búsqueda cuando el usuario está escribiendo.

Modificador searchCompletion

.searchCompletion(_:) vincula una sugerencia a un valor de completado. Cuando el usuario toca la sugerencia, el texto de búsqueda se reemplaza con el valor de completado.

.searchable(text: $searchText) {
    ForEach(matchingColors) { color in
        HStack {
            Circle()
                .fill(color.value)
                .frame(width: 16, height: 16)
            Text(color.name)
        }
        .searchCompletion(color.name)  // Tocar llena la búsqueda con el nombre del color
    }
}

Sin .searchCompletion(): Las sugerencias se muestran pero tocarlas no hace nada en el campo de búsqueda. Este es el error más común con sugerencias.

Patrón Completo de Sugerencias

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 a Array
    }

    var filteredColors: [NamedColor] {
        if searchText.isEmpty { return allColors }
        return allColors.filter {
            $0.name.localizedCaseInsensitiveContains(searchText)
        }
    }
}

Parte 4: Envío de Búsqueda

onSubmit(of: .search)

Se activa cuando el usuario presiona Return/Enter en el campo de búsqueda:

.searchable(text: $searchText)
.onSubmit(of: .search) {
    performSearch(searchText)
}

Disponibilidad: iOS 15+

Decisión entre Filtro y Envío

PatrónCuándo UsarEjemplo
Filtrar mientras escribesDatos locales, filtrado rápidoContactos, ajustes
Búsqueda basada en envíoSolicitudes de red, consultas costosasApp Store, búsqueda web
CombinadoLas sugerencias filtran localmente, el envío activa el servidorMapas, compras

Patrón Combinado de Sugerencias + Envío

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") {
                // Sugerencias locales de búsquedas recientes
                ForEach(matchingRecent, id: \.self) { term in
                    Label(term, systemImage: "clock")
                        .searchCompletion(term)
                }
            }
            .onSubmit(of: .search) {
                // Búsqueda en servidor al enviar
                Task {
                    searchResults = await ProductAPI.search(searchText)
                }
            }
        }
    }

    var matchingRecent: [String] {
        guard !searchText.isEmpty else { return recentSearches }
        return recentSearches.filter {
            $0.localizedCaseInsensitiveContains(searchText)
        }
    }
}

Parte 5: Ámbitos de Búsqueda (iOS 16+)

Añadiendo Ámbitos

Los ámbitos añaden un selector segmentado debajo del campo de búsqueda para reducir resultados por categoría:

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)
                }
            }
        }
    }
}

Disponibilidad: iOS 16+, macOS 13+

Activación de Ámbitos (iOS 16.4+)

Controla cuándo aparecen los ámbitos:

.searchScopes($searchScope, activation: .onTextEntry) {
    // Los ámbitos aparecen solo cuando el usuario comienza a escribir
    ForEach(SearchScope.allCases, id: \.self) { scope in
        Text(scope.rawValue).tag(scope)
    }
}
ActivaciónComportamiento
.automaticValor predeterminado del sistema
.onTextEntryLos ámbitos aparecen cuando el usuario escribe texto
.onSearchPresentationLos ámbitos aparecen cuando se activa la búsqueda

Diferencias de plataforma:

  • iOS/iPadOS: Los ámbitos aparecen al escribir texto de forma predeterminada, se descartan al cancelar
  • macOS: Los ámbitos aparecen cuando se presenta la búsqueda, se descartan al cancelar

Parte 6: Tokens de Búsqueda (iOS 16+)

Los tokens son elementos de búsqueda estructurados que aparecen como "píldoras" en el campo de búsqueda junto al texto libre.

Tokens Básicos

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")
                }
            }
        }
    }
}

Disponibilidad: iOS 16+

Requisitos del modelo de token: Cada elemento del token debe cumplir con Identifiable.

Tokens Sugeridos (iOS 17+)

.searchable(
    text: $searchText,
    tokens: $tokens,
    suggestedTokens: $suggestedTokens,
    prompt: "Search recipes"
) { token in
    Label(token.displayName, systemImage: token.icon)
}

Disponibilidad: iOS 17+ añade los parámetros suggestedTokens e isPresented.

Filtrado Combinado de Tokens + Texto

var filteredRecipes: [Recipe] {
    var results = allRecipes

    // Aplicar filtros de token
    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 }
        }
    }

    // Aplicar filtro de texto
    if !searchText.isEmpty {
        results = results.filter {
            $0.name.localizedCaseInsensitiveContains(searchText)
        }
    }

    return results
}

Parte 7: Control Programático de Búsqueda (iOS 18+)

searchFocused

Vincula un FocusState<Bool> al campo de búsqueda para activar o cerrar la búsqueda programáticamente:

struct ProgrammaticSearchView: View {
    @State private var searchText = ""
    @FocusState private var isSearchFocused: Bool

    var body: some View {
        NavigationStack {
            VStack {
                Button("Start Search") {
                    isSearchFocused = true  // Activar campo de búsqueda
                }

                List(filteredItems) { item in
                    Text(item.name)
                }
            }
            .navigationTitle("Items")
            .searchable(text: $searchText)
            .searchFocused($isSearchFocused)
        }
    }
}

Disponibilidad: iOS 18+, macOS 15+, tvOS 18+, watchOS 11+


Parte 8: Problemas Comunes y Depuración

El Campo de Búsqueda No Aparece

Causa raíz: .searchable() debe ser un descendiente de un contenedor de navegación. Sin NavigationStack o NavigationSplitView, no aparece ningún campo.

// ❌ Incorrecto: Sin contenedor de navegación
VStack {
    List(items) { item in
        Text(item.name)
    }
    .searchable(text: $query)
}

// ✅ Correcto: NavigationStack como contenedor
NavigationStack {
    List(items) { item in
        Text(item.name)
    }
    .searchable(text: $query)
}

isSearching Siempre es false

Causa raíz: Leer isSearching en la misma vista que tiene .searchable(). Debe leerse en una vista hija.

// ❌ Incorrecto: isSearching en la vista que tiene .searchable
struct ContentView: View {
    @Environment(\.isSearching) private var isSearching  // Siempre false

    var body: some View {
        NavigationStack {
            List { ... }
                .searchable(text: $query)
        }
    }
}

// ✅ Correcto: isSearching en una vista hija
struct SearchChildView: View {
    @Environment(\.isSearching) private var isSearching  // Funciona
    // ...
}

Las Sugerencias Se Muestran Pero No Hacen Nada al Tocar

Causa raíz: Olvidar .searchCompletion() en las sugerencias.

// ❌ Incorrecto: Sin searchCompletion
.searchable(text: $searchText) {
    ForEach(suggestions) { s in
        Text(s.name)  // Tocar no hace nada
    }
}

// ✅ Correcto: Con searchCompletion
.searchable(text: $searchText) {
    ForEach(suggestions) { s in
        Text(s.name)
            .searchCompletion(s.name)  // Tocar llena el campo de búsqueda
    }
}

Los Ámbitos No Aparecen

Causa raíz: Los ámbitos solo se muestran cuando el campo de búsqueda está activo. En iOS 16+, es posible que necesites escribir algo primero para verlos.

Compilación Lenta con Búsqueda

Si tu aplicación compila lentamente, separa la lógica de filtrado en un método calculado en lugar de en línea:

// Más rápido de compilar
var body: some View {
    List(filteredItems, id: \.id) { item in
        ItemRow(item: item)
    }
    .searchable(text: $searchText)
}

private var filteredItems: [Item] {
    items.filter { ... }
}

Resumen Rápido

CaracterísticaiOSModificador/Entorno
Búsqueda básica15+.searchable(text:)
Estado de búsqueda15+@Environment(\.isSearching)
Cerrar búsqueda15+@Environment(\.dismissSearch)
Sugerencias15+Closure de sugerencias + .searchCompletion()
Envío de búsqueda15+.onSubmit(of: .search)
Ámbitos16+.searchScopes()
Tokens16+.searchable(text:tokens:)
Tokens sugeridos17+Parámetro suggestedTokens
Foco programático18+.searchFocused()
Búsqueda alineada abajo26Consulta axiom-swiftui-26-ref

Para características de búsqueda de iOS 26 (búsqueda alineada abajo, barra de herramientas minimizada, rol de pestaña de búsqueda), consulta el skill axiom-swiftui-26-ref.

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 relacionados