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
| iOS | Adiciones 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.4 | Parámetro activation del ámbito de búsqueda (.onTextEntry, .onSearchPresentation) |
| 17 | Parámetro isPresented, parámetro suggestedTokens |
| 17.1 | .searchPresentationToolbarBehavior(.avoidHidingContent) |
| 18 | .searchFocused($isFocused) para control de foco programático |
| 26 | Bú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
- Adjuntas
.searchable(text: $query)a una vista - El contenedor de navegación más cercano (NavigationStack, NavigationSplitView) renderiza el campo de búsqueda
- La vista recibe
isSearchingydismissSearcha través del entorno - 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ón | Comportamiento |
|---|---|
.automatic | El sistema decide (recomendado) |
.navigationBarDrawer | Debajo del título de la barra de navegación (iOS) |
.navigationBarDrawer(displayMode: .always) | Siempre visible, no se oculta al desplazar |
.sidebar | En la columna de la barra lateral (NavigationSplitView) |
.toolbar | En el área de la barra de herramientas |
.toolbarPrincipal | En 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ón | Cuándo Usar | Ejemplo |
|---|---|---|
| Filtrar mientras escribes | Datos locales, filtrado rápido | Contactos, ajustes |
| Búsqueda basada en envío | Solicitudes de red, consultas costosas | App Store, búsqueda web |
| Combinado | Las sugerencias filtran localmente, el envío activa el servidor | Mapas, 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ón | Comportamiento |
|---|---|
.automatic | Valor predeterminado del sistema |
.onTextEntry | Los ámbitos aparecen cuando el usuario escribe texto |
.onSearchPresentation | Los á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ística | iOS | Modificador/Entorno |
|---|---|---|
| Búsqueda básica | 15+ | .searchable(text:) |
| Estado de búsqueda | 15+ | @Environment(\.isSearching) |
| Cerrar búsqueda | 15+ | @Environment(\.dismissSearch) |
| Sugerencias | 15+ | Closure de sugerencias + .searchCompletion() |
| Envío de búsqueda | 15+ | .onSubmit(of: .search) |
| Ámbitos | 16+ | .searchScopes() |
| Tokens | 16+ | .searchable(text:tokens:) |
| Tokens sugeridos | 17+ | Parámetro suggestedTokens |
| Foco programático | 18+ | .searchFocused() |
| Búsqueda alineada abajo | 26 | Consulta 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.