Communitygithub.com

ComeOnOliver/skillshub

Use ao implementar busca em SwiftUI — .searchable, isSearching, sugestões de busca, escopos, tokens e controle programático de busca (iOS 15-18). Para refinamentos de busca do iOS 26 (alinhada ao fundo, barra minimizada, papel de busca em abas), veja swiftui-26-ref.

O que é skillshub?

Este skill fornece uma referência abrangente para implementar funcionalidades de busca em SwiftUI, desde iOS 15 até as mudanças drásticas do iOS 26. Ele explica como o modificador `.searchable()` funciona, destacando a indireção crucial: ele deve ser anexado a uma visão, mas a renderização real do campo de busca é feita por um contêiner de navegação (NavigationStack, NavigationSplitView ou TabView). O resumo da API por versão do iOS ajuda a identificar rapidamente quais recursos estão disponíveis, como escopos de busca (a partir do iOS 16) e tokens de busca (iOS 16+), sugestões de tokens e parâmetros de apresentação (iOS 17+), e o controle programático de foco com `searchFocused` (iOS 18+). Para o iOS 26, o skill referencia um documento separado (`swiftui-26-ref`) que cobre a busca alinhada ao fundo, a barra de ferramentas minimizada (`searchToolbarBehavior(.minimize)`), e o uso de `Tab(role: .search)` e `DefaultToolbarItem(kind: .search)`. Este skill é suportado em todas as plataformas SwiftUI (iOS, macOS, tvOS, watchOS) e é útil para depurar problemas comuns como "o campo de busca não aparece" ou "as sugestões não funcionam". Ele cobre padrões completos: filtragem enquanto digita, busca por submissão, sugestões de busca, escopos de busca, tokens de busca e controle programático, com exemplos de código e orientações sobre práticas recomendadas.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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

iOSPrincipais Adições
15.searchable(text:), isSearching, dismissSearch, sugestões, .searchCompletion(), onSubmit(of: .search)
16Escopos de busca (.searchScopes), tokens de busca (.searchable(text:tokens:)), SearchScopeActivation
16.4Parâmetro de activation do escopo de busca (.onTextEntry, .onSearchPresentation)
17Parâmetro isPresented, parâmetro suggestedTokens
17.1.searchPresentationToolbarBehavior(.avoidHidingContent)
18.searchFocused($isFocused) para controle de foco programático
26Busca 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

  1. Você anexa .searchable(text: $query) a uma visão
  2. O contêiner de navegação mais próximo (NavigationStack, NavigationSplitView) renderiza o campo de busca
  3. A visão recebe isSearching e dismissSearch através do ambiente
  4. 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

PosicionamentoComportamento
.automaticO sistema decide (recomendado)
.navigationBarDrawerAbaixo do título da barra de navegação (iOS)
.navigationBarDrawer(displayMode: .always)Sempre visível, não escondido ao rolar
.sidebarNa coluna da barra lateral (NavigationSplitView)
.toolbarNa área da barra de ferramentas
.toolbarPrincipalNa 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ãoQuando UsarExemplo
Filtrar enquanto digitaDados locais, filtragem rápidaContatos, configurações
Busca por submissãoRequisições de rede, consultas carasApp Store, busca na web
CombinadoSugestões filtram localmente, submissão dispara servidorMapas, 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çãoComportamento
.automaticPadrão do sistema
.onTextEntryEscopos aparecem quando o usuário digita texto
.onSearchPresentationEscopos 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]

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

Habilidades Relacionadas