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) |
| 17 | isPresented 매개변수, 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+
작동 방식
- 뷰에
.searchable(text: $query)를 첨부합니다. - 가장 가까운 내비게이션 컨테이너(NavigationStack, NavigationSplitView)가 검색 필드를 렌더링합니다.
- 뷰는 환경을 통해
isSearching과dismissSearch를 받습니다. - 뷰는 바인딩된 텍스트를 기반으로 필터링하거나 쿼리합니다.
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을 올바른 자식 뷰에 첨부하세요.
핵심 규칙 요약
.searchable은 내비게이션 컨테이너 내부에 있어야 합니다(NavigationStack, NavigationSplitView, TabView).isSearching과dismissSearch는 자식 뷰에서만 읽을 수 있습니다.- 제안에는 항상
.searchCompletion()이 필요합니다. - 검색 범위는
.searchScopes()수정자를 사용합니다(iOS 16+). - 검색 토큰에는
Identifiable모델이 필요합니다(iOS 16+). - 프로그래매틱 포커스는
searchFocused를 사용합니다(iOS 18+). - iOS 26 기능은 별도 참조를 참조하세요.