Referência da API de Busca do SwiftUI
Visão Geral
A busca no SwiftUI é baseada no ambiente e consumida pela navegação. Você anexa .searchable() a uma visão, mas um contêiner de navegação (NavigationStack, NavigationSplitView ou TabView) renderiza o campo de busca real. Essa indireção é a fonte da maioria dos bugs de busca.
Evolução da API
| iOS | Principais Adições |
|---|---|
| 15 | .searchable(text:), isSearching, dismissSearch, sugestões, .searchCompletion(), onSubmit(of: .search) |
| 16 | Escopos de busca (.searchScopes), tokens de busca (.searchable(text:tokens:)), SearchScopeActivation |
| 16.4 | Parâmetro de activation do escopo de busca (.onTextEntry, .onSearchPresentation) |
| 17 | Parâmetro isPresented, parâmetro suggestedTokens |
| 17.1 | .searchPresentationToolbarBehavior(.avoidHidingContent) |
| 18 | .searchFocused($isFocused) para controle de foco programático |
| 26 | Busca alinhada ao fundo, .searchToolbarBehavior(.minimize), Tab(role: .search), DefaultToolbarItem(kind: .search) — veja axiom-swiftui-26-ref |
Quando Usar Este Skill
- Adicionar busca a uma lista ou coleção SwiftUI
- Implementar filtragem enquanto digita ou busca por submissão
- Adicionar sugestões de busca com preenchimento automático
- Usar escopos de busca para restringir resultados por categoria
- Usar tokens de busca para consultas estruturadas
- Controlar o foco da busca programaticamente
- Depurar problemas de "o campo de busca não aparece"
Para recursos de busca do iOS 26 (alinhada ao fundo, barra de ferramentas minimizada, papel de busca em abas), veja axiom-swiftui-26-ref.
Parte 1: O Modificador searchable
API Principal
.searchable(
text: Binding<String>,
placement: SearchFieldPlacement = .automatic,
prompt: LocalizedStringKey
)
Disponibilidade: iOS 15+, macOS 12+, tvOS 15+, watchOS 8+
Como Funciona
- Você anexa
.searchable(text: $query)a uma visão - O contêiner de navegação mais próximo (NavigationStack, NavigationSplitView) renderiza o campo de busca
- A visão recebe
isSearchingedismissSearchatravés do ambiente - Sua visão filtra ou consulta com base no 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) }
}
}
Opções de Posicionamento
| Posicionamento | Comportamento |
|---|---|
.automatic | O sistema decide (recomendado) |
.navigationBarDrawer | Abaixo do título da barra de navegação (iOS) |
.navigationBarDrawer(displayMode: .always) | Sempre visível, não escondido ao rolar |
.sidebar | Na coluna da barra lateral (NavigationSplitView) |
.toolbar | Na área da barra de ferramentas |
.toolbarPrincipal | Na seção principal da barra de ferramentas |
Pega: O SwiftUI pode ignorar sua preferência de posicionamento se a hierarquia de visão não suportar. Sempre teste na plataforma de destino.
Associação de Coluna em NavigationSplitView
Onde você anexa .searchable determina qual coluna exibe o campo de busca:
NavigationSplitView {
SidebarView()
.searchable(text: $query) // Busca na barra lateral
} detail: {
DetailView()
}
// vs.
NavigationSplitView {
SidebarView()
} detail: {
DetailView()
.searchable(text: $query) // Busca no detalhe
}
// vs.
NavigationSplitView {
SidebarView()
} detail: {
DetailView()
}
.searchable(text: $query) // O sistema decide a coluna
Parte 2: Exibindo Resultados da Busca
Ambiente isSearching
@Environment(\.isSearching) private var isSearching
Disponibilidade: iOS 15+
Torna-se true quando o usuário ativa a busca (toca no campo), false quando ele cancela ou você chama dismissSearch.
Regra crítica: isSearching deve ser lido a partir de um filho da visão que possui .searchable. O SwiftUI define o valor no ambiente da visão pesquisável e não o propaga para cima.
// Padrão: Sobrepor resultados da busca ao pesquisar
struct WeatherCityList: View {
@State private var searchText = ""
var body: some View {
NavigationStack {
// SearchResultsOverlay lê 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 da busca
SearchResults(query: searchText)
} else {
content
}
}
}
Ambiente dismissSearch
@Environment(\.dismissSearch) private var dismissSearch
Disponibilidade: iOS 15+
Chamar dismissSearch() limpa o texto da busca, remove o foco e define isSearching como false. Deve ser chamado de dentro da hierarquia de visão pesquisável.
struct SearchResults: View {
@Environment(\.dismissSearch) private var dismissSearch
var body: some View {
List(results) { result in
Button(result.name) {
selectResult(result)
dismissSearch() // Fechar busca após seleção
}
}
}
}
Parte 3: Sugestões de Busca
Adicionando Sugestões
Passe um closure de suggestions para .searchable:
.searchable(text: $searchText) {
ForEach(suggestedResults) { suggestion in
Text(suggestion.name)
.searchCompletion(suggestion.name)
}
}
Disponibilidade: iOS 15+
As sugestões aparecem em uma lista abaixo do campo de busca quando o usuário está digitando.
Modificador searchCompletion
.searchCompletion(_:) vincula uma sugestão a um valor de conclusão. Quando o usuário toca na sugestão, o texto da busca é substituído pelo valor de conclusão.
.searchable(text: $searchText) {
ForEach(matchingColors) { color in
HStack {
Circle()
.fill(color.value)
.frame(width: 16, height: 16)
Text(color.name)
}
.searchCompletion(color.name) // Tocar preenche a busca com o nome da cor
}
}
Sem .searchCompletion(): As sugestões são exibidas, mas tocá-las não faz nada no campo de busca. Este é o erro mais comum com sugestões.
Padrão Completo de Sugestões
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 } // Converter ArraySlice em Array
}
var filteredColors: [NamedColor] {
if searchText.isEmpty { return allColors }
return allColors.filter {
$0.name.localizedCaseInsensitiveContains(searchText)
}
}
}
Parte 4: Submissão de Busca
onSubmit(of: .search)
Dispara quando o usuário pressiona Return/Enter no campo de busca:
.searchable(text: $searchText)
.onSubmit(of: .search) {
performSearch(searchText)
}
Disponibilidade: iOS 15+
Decisão entre Filtrar e Submeter
| Padrão | Quando Usar | Exemplo |
|---|---|---|
| Filtrar enquanto digita | Dados locais, filtragem rápida | Contatos, configurações |
| Busca por submissão | Requisições de rede, consultas caras | App Store, busca na web |
| Combinado | Sugestões filtram localmente, submissão dispara servidor | Mapas, compras |
Padrão Combinado Sugestões + Submissã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") {
// Sugestões locais de pesquisas recentes
ForEach(matchingRecent, id: \.self) { term in
Label(term, systemImage: "clock")
.searchCompletion(term)
}
}
.onSubmit(of: .search) {
// Busca no servidor ao submeter
Task {
searchResults = await ProductAPI.search(searchText)
}
}
}
}
var matchingRecent: [String] {
guard !searchText.isEmpty else { return recentSearches }
return recentSearches.filter {
$0.localizedCaseInsensitiveContains(searchText)
}
}
}
Parte 5: Escopos de Busca (iOS 16+)
Adicionando Escopos
Escopos adicionam um seletor segmentado abaixo do campo de busca para restringir resultados por categoria:
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)
}
}
}
}
}
Disponibilidade: iOS 16+, macOS 13+
Ativação de Escopo (iOS 16.4+)
Controle quando os escopos aparecem:
.searchScopes($searchScope, activation: .onTextEntry) {
// Escopos aparecem apenas quando o usuário começa a digitar
ForEach(SearchScope.allCases, id: \.self) { scope in
Text(scope.rawValue).tag(scope)
}
}
| Ativação | Comportamento |
|---|---|
.automatic | Padrão do sistema |
.onTextEntry | Escopos aparecem quando o usuário digita texto |
.onSearchPresentation | Escopos aparecem quando a busca é ativada |
Diferenças de plataforma:
- iOS/iPadOS: Escopos aparecem na entrada de texto por padrão, desaparecem ao cancelar
- macOS: Escopos aparecem quando a busca é apresentada, desaparecem ao cancelar
Parte 6: Tokens de Busca (iOS 16+)
Tokens são elementos de busca estruturados que aparecem como "pílulas" no campo de busca junto com texto livre.
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")
}
}
}
}
}
Disponibilidade: iOS 16+
Requisitos do modelo de token: Cada elemento de token deve estar em conformidade com Identifiable.
Tokens Sugeridos (iOS 17+)
.searchable(
text: $searchText,
tokens: $tokens,
suggestedTokens: $suggestedTokens,
prompt: "Search recipes"
) { token in
Label(token.displayName, systemImage: token.icon)
}
Disponibilidade: iOS 17+ adiciona os parâmetros suggestedTokens e isPresented.
Filtragem Combinada 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: Controle Programático de Busca (iOS 18+)
searchFocused
Vincule um FocusState<Bool> ao campo de busca para ativar ou dispensar a busca programaticamente:
struct ProgrammaticSearchView: View {
@State private var searchText = ""
@FocusState private var isSearchFocused: Bool
var body: some View {
NavigationStack {
VStack {
Button("Start Search") {
isSearchFocused = true // Ativar campo de busca
}
List(filteredItems) { item in
Text(item.name)
}
}
.navigationTitle("Items")
...
[truncated for translation]