Communitygithub.com

ComeOnOliver/skillshub

SwiftUI 검색 구현 시 사용합니다 — .searchable, isSearching, 검색 제안, 범위, 토큰, 프로그래매틱 검색 제어(iOS 15-18). iOS 26 검색 개선 사항(하단 정렬, 최소화된 툴바, 검색 탭 역할)은 swiftui-26-ref를 참조하세요.

skillshub란 무엇인가요?

이 스킬은 SwiftUI에서 검색 기능을 구현할 때 필요한 완전한 API 참조를 제공합니다. `.searchable()` 수정자의 작동 방식과 환경 기반 검색의 특성을 상세히 설명하며, iOS 15부터 18까지의 검색 API 진화를 다룹니다. 주요 주제로는 기본 검색 필드 연결, 검색 결과 표시를 위한 `isSearching` 및 `dismissSearch` 환경 값 사용, 검색 제안 추가, `onSubmit(of: .search)`를 통한 제출 기반 검색, 검색 범위(Search Scopes)와 검색 토큰(Search Tokens)을 사용한 고급 필터링, 그리고 iOS 18에서 도입된 `searchFocused`를 통한 프로그래매틱 검색 제어가 포함됩니다. 개발자는 이 스킬을 통해 SwiftUI 검색 필드가 나타나지 않는 버그를 진단하고, 올바른 계층 구조에서 환경 값을 읽는 방법, 그리고 다양한 iOS 버전에서의 동작 차이를 이해할 수 있습니다. iOS 26의 새로운 검색 기능(하단 정렬, 최소화된 툴바, 검색 탭 역할)은 별도 참조(swiftui-26-ref)를 통해 확인해야 합니다.

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

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

SwiftUI 검색 API 참조

개요

SwiftUI 검색은 환경 기반이며 내비게이션에 의해 소비됩니다. 뷰에 .searchable()을 첨부하지만, 내비게이션 컨테이너(NavigationStack, NavigationSplitView 또는 TabView)가 실제 검색 필드를 렌더링합니다. 이러한 간접성은 대부분의 검색 버그의 원인입니다.

API 진화

iOS주요 추가 사항
15.searchable(text:), isSearching, dismissSearch, 제안, .searchCompletion(), onSubmit(of: .search)
16검색 범옆(.searchScopes), 검색 토큰(.searchable(text:tokens:)), SearchScopeActivation
16.4검색 범위 activation 매개변수(.onTextEntry, .onSearchPresentation)
17isPresented 매개변수, suggestedTokens 매개변수
17.1.searchPresentationToolbarBehavior(.avoidHidingContent)
18프로그래매틱 포커스 제어를 위한 .searchFocused($isFocused)
26하단 정렬 검색, .searchToolbarBehavior(.minimize), Tab(role: .search), DefaultToolbarItem(kind: .search) — axiom-swiftui-26-ref 참조

이 스킬을 사용해야 하는 경우

  • SwiftUI 목록 또는 컬렉션에 검색 추가
  • 입력 시 필터링(타이핑할 때) 또는 제출 기반 검색 구현
  • 자동 완성 기능이 있는 검색 제안 추가
  • 검색 범위를 사용하여 카테고리별로 결과 범위 좁히기
  • 검색 토큰을 사용한 구조화된 쿼리
  • 프로그래매틱하게 검색 포커스 제어
  • "검색 필드가 나타나지 않음" 문제 디버깅

iOS 26 검색 기능(하단 정렬, 최소화된 툴바, 검색 탭 역할)은 axiom-swiftui-26-ref를 참조하세요.


파트 1: searchable 수정자

핵심 API

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

사용 가능: iOS 15+, macOS 12+, tvOS 15+, watchOS 8+

작동 방식

  1. 뷰에 .searchable(text: $query)를 첨부합니다.
  2. 가장 가까운 내비게이션 컨테이너(NavigationStack, NavigationSplitView)가 검색 필드를 렌더링합니다.
  3. 뷰는 환경을 통해 isSearching과 dismissSearch를 받습니다.
  4. 뷰는 바인딩된 텍스트를 기반으로 필터링하거나 쿼리합니다.
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) }
    }
}

배치 옵션

배치동작
.automatic시스템이 결정(권장)
.navigationBarDrawer내비게이션 바 제목 아래(iOS)
.navigationBarDrawer(displayMode: .always)항상 표시, 스크롤 시 숨기지 않음
.sidebar사이드바 열(NavigationSplitView)
.toolbar툴바 영역
.toolbarPrincipal툴바의 주요 섹션

주의 사항: 뷰 계층이 지원하지 않는 경우 SwiftUI가 배치 설정을 무시할 수 있습니다. 항상 대상 플랫폼에서 테스트하세요.

NavigationSplitView에서 열 연결

.searchable을 첨부하는 위치에 따라 검색 필드를 표시할 열이 결정됩니다.

NavigationSplitView {
    SidebarView()
        .searchable(text: $query)  // 사이드바에서 검색
} detail: {
    DetailView()
}

// vs.

NavigationSplitView {
    SidebarView()
} detail: {
    DetailView()
        .searchable(text: $query)  // 세부 정보에서 검색
}

// vs.

NavigationSplitView {
    SidebarView()
} detail: {
    DetailView()
}
.searchable(text: $query)  // 시스템이 열 결정

파트 2: 검색 결과 표시

isSearching 환경

@Environment(\.isSearching) private var isSearching

사용 가능: iOS 15+

사용자가 검색을 활성화(필드를 탭)하면 true가 되고, 취소하거나 dismissSearch를 호출하면 false가 됩니다.

중요 규칙: isSearching은 .searchable이 있는 뷰의 자식에서 읽어야 합니다. SwiftUI는 searchable 뷰의 환경에 값을 설정하고 위쪽으로 전파하지 않습니다.

// 패턴: 검색 중에 검색 결과 오버레이
struct WeatherCityList: View {
    @State private var searchText = ""

    var body: some View {
        NavigationStack {
            // SearchResultsOverlay가 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 {
            // 검색 결과 표시
            SearchResults(query: searchText)
        } else {
            content
        }
    }
}

dismissSearch 환경

@Environment(\.dismissSearch) private var dismissSearch

사용 가능: iOS 15+

dismissSearch()를 호출하면 검색 텍스트가 지워지고 포커스가 제거되며 isSearching이 false로 설정됩니다. searchable 뷰 계층 내부에서 호출해야 합니다.

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

    var body: some View {
        List(results) { result in
            Button(result.name) {
                selectResult(result)
                dismissSearch()  // 선택 후 검색 종료
            }
        }
    }
}

파트 3: 검색 제안

제안 추가

.searchable에 suggestions 클로저를 전달합니다.

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

사용 가능: iOS 15+

사용자가 입력하는 동안 검색 필드 아래에 제안 목록이 나타납니다.

searchCompletion 수정자

.searchCompletion(_:)는 제안을 완료 값에 바인딩합니다. 사용자가 제안을 탭하면 검색 텍스트가 완료 값으로 대체됩니다.

.searchable(text: $searchText) {
    ForEach(matchingColors) { color in
        HStack {
            Circle()
                .fill(color.value)
                .frame(width: 16, height: 16)
            Text(color.name)
        }
        .searchCompletion(color.name)  // 탭하면 검색 필드가 색상 이름으로 채워짐
    }
}

.searchCompletion() 없음: 제안이 표시되지만 탭해도 검색 필드에 아무런 영향이 없습니다. 이것이 가장 흔한 제안 버그입니다.

완전한 제안 패턴

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 }  // ArraySlice를 Array로 변환
    }

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

파트 4: 검색 제출

onSubmit(of: .search)

사용자가 검색 필드에서 Return/Enter를 누를 때 트리거됩니다.

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

사용 가능: iOS 15+

필터 vs 제출 결정

패턴사용 시기예시
입력 시 필터링로컬 데이터, 빠른 필터링연락처, 설정
제출 기반 검색네트워크 요청, 비용이 큰 쿼리앱 스토어, 웹 검색
결합제안은 로컬 필터링, 제출은 서버 트리거지도, 쇼핑

결합된 제안 + 제출 패턴

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") {
                // 최근 검색어에서 로컬 제안
                ForEach(matchingRecent, id: \.self) { term in
                    Label(term, systemImage: "clock")
                        .searchCompletion(term)
                }
            }
            .onSubmit(of: .search) {
                // 제출 시 서버 검색
                Task {
                    searchResults = await ProductAPI.search(searchText)
                }
            }
        }
    }

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

파트 5: 검색 범위(iOS 16+)

범위 추가

범위는 검색 필드 아래에 카테고리별로 결과 범위를 좁히기 위한 세그먼트화된 피커를 추가합니다.

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

사용 가능: iOS 16+, macOS 13+

범위 활성화(iOS 16.4+)

범위가 나타나는 시기를 제어합니다.

.searchScopes($searchScope, activation: .onTextEntry) {
    // 사용자가 입력을 시작할 때만 범위가 나타남
    ForEach(SearchScope.allCases, id: \.self) { scope in
        Text(scope.rawValue).tag(scope)
    }
}
활성화동작
.automatic시스템 기본값
.onTextEntry사용자가 텍스트를 입력할 때 범위가 나타남
.onSearchPresentation검색이 활성화될 때 범위가 나타남

플랫폼 차이:

  • iOS/iPadOS: 기본적으로 텍스트 입력 시 범위가 나타나고, 취소 시 사라짐
  • macOS: 검색이 표시될 때 범위가 나타나고, 취소 시 사라짐

파트 6: 검색 토큰(iOS 16+)

토큰은 자유 텍스트와 함께 검색 필드에 "알약"으로 표시되는 구조화된 검색 요소입니다.

기본 토큰

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

사용 가능: iOS 16+

토큰 모델 요구 사항: 각 토큰 요소는 Identifiable을 준수해야 합니다.

제안된 토큰(iOS 17+)

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

사용 가능: iOS 17+에서 suggestedTokens 및 isPresented 매개변수 추가.

토큰 + 텍스트 필터링 결합

var filteredRecipes: [Recipe] {
    var results = allRecipes

    // 토큰 필터 적용
    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 }
        }
    }

    // 텍스트 필터 적용
    if !searchText.isEmpty {
        results = results.filter {
            $0.name.localizedCaseInsensitiveContains(searchText)
        }
    }

    return results
}

파트 7: 프로그래매틱 검색 제어(iOS 18+)

searchFocused

FocusState<Bool>을 검색 필드에 바인딩하여 프로그래매틱하게 검색을 활성화하거나 해제합니다.

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

    var body: some View {
        NavigationStack {
            VStack {
                Button("Start Search") {
                    isSearchFocused = true  // 검색 필드 활성화
                }

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

사용 가능: iOS 18+

중요한 고려 사항:

  • searchFocused가 작동하려면 보기 가능한 searchable 뷰가 필요합니다.
  • NavigationStack이 푸시된 후에는 작동하지 않습니다.
  • SwiftUI 5.0(iOS 17+)은 @FocusState 및 @Binding과 함께 isPresented 매개변수를 제공합니다.

파트 8: 일반적인 문제 해결

문제: 검색 필드가 나타나지 않음

// 잘못됨: TabView 외부에서 접근
TabView {
    NavigationStack {
        ContentView()
    }
}
.searchable(text: $query)  // 아무 일도 일어나지 않음

// 올바름: 각 탭 내부
TabView {
    NavigationStack {
        ContentView()
            .searchable(text: $query)  // 작동
    }
    .tabItem { Label("Home", systemImage: "house") }
}

진단: .searchable을 적용한 뷰가 NavigationStack, NavigationSplitView 또는 TabView 내부에 있는지 확인하세요. SwiftUI는 이러한 컨테이너 외부에서는 검색 필드를 렌더링하지 않습니다.

문제: isSearching이 false 유지

// 잘못됨: searchable 뷰와 동일한 뷰에서 읽기
struct ContentView: View {
    @Environment(\.isSearching) private var isSearching
    @State private var query = ""

    var body: some View {
        NavigationStack {
            List { ... }
                .searchable(text: $query)
        }
        // isSearching이 여기서는 작동하지 않음
    }
}

// 올바름: searchable 뷰의 자식에서 읽기
struct ContentView: View {
    @State private var query = ""

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

struct ChildResultsView: View {
    let query: String
    @Environment(\.isSearching) private var isSearching  // 작동

    var body: some View {
        List { ... }
    }
}

진단: isSearching과 dismissSearch는 항상 자식 뷰에서 읽어야 합니다. 환경 값은 위쪽으로 전파되지 않습니다.

문제: 제안 탭이 아무것도 하지 않음

// 잘못됨: searchCompletion 누락
.searchable(text: $query) {
    ForEach(suggestions) { suggestion in
        Text(suggestion.name)  // 표시되지만 탭해도 아무 일도 일어나지 않음
    }
}

// 올바름: searchCompletion 포함
.searchable(text: $query) {
    ForEach(suggestions) { suggestion in
        Text(suggestion.name)
            .searchCompletion(suggestion.name)  // 탭하면 검색 필드 채움
    }
}

진단: 각 제안 항목에 .searchCompletion()을 잊지 마십시오. 이것이 없으면 제안이 탭에 응답하지 않습니다.

문제: NavigationSplitView의 잘못된 열

// 잘못됨: detail 열에 첨부될 것으로 예상했지만 사이드바에 나타남
NavigationSplitView {
    SidebarView()
        .searchable(text: $query)  // 여기에 첨부됨
} detail: {
    DetailView()
}

// 올바름: detail 열에 명시적으로 첨부
NavigationSplitView {
    SidebarView()
} detail: {
    DetailView()
        .searchable(text: $query)  // detail 열에 나타남
}

진단: 검색 필드가 원하는 열에 나타나도록 .searchable을 올바른 자식 뷰에 첨부하세요.


핵심 규칙 요약

  1. .searchable은 내비게이션 컨테이너 내부에 있어야 합니다(NavigationStack, NavigationSplitView, TabView).
  2. isSearching과 dismissSearch는 자식 뷰에서만 읽을 수 있습니다.
  3. 제안에는 항상 .searchCompletion()이 필요합니다.
  4. 검색 범위는 .searchScopes() 수정자를 사용합니다(iOS 16+).
  5. 검색 토큰에는 Identifiable 모델이 필요합니다(iOS 16+).
  6. 프로그래매틱 포커스는 searchFocused를 사용합니다(iOS 18+).
  7. iOS 26 기능은 별도 참조를 참조하세요.

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

관련 스킬