Communitygithub.com

SwiftUI Search API リファレンス

SwiftUI の .searchable、isSearching、検索候補、スコープ、トークン、プログラムによる検索制御(iOS 15~18)を実装する際に使用します。iOS 26 の検索改善(下部配置、最小化ツールバー、検索タブロール)については swiftui-26-ref を参照してください。

SwiftUI Search API リファレンス とは?

このスキルは、SwiftUI アプリケーションに検索機能を実装するための包括的なガイドと API リファレンスを提供します。検索の動作は環境ベースであり、NavigationStack や NavigationSplitView などのナビゲーションコンテナによって制御されるため、この間接性が原因で多くのバグが発生します。iOS 15 から 18 までの主要な API 進化を網羅しており、.searchable 修飾子の基本的な使い方から、プログラムによる検索フォーカス制御(iOS 18 の searchFocused)までをカバーしています。具体的には、isSearching 環境値の正しい読み取り方、dismissSearch による検索終了、searchCompletion を使った検索候補の実装、検索スコープとトークンによる高度な絞り込み、onSubmit との組み合わせ方など、実践的なパターンと落とし穴を詳細に解説します。このリファレンスは Claude Code、Cursor、Codex などの AI エージェントが SwiftUI 検索機能の実装を支援する際に参照することを想定しており、各 API の利用可能な iOS バージョンやプラットフォームごとの動作の違いも明記しています。

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

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

SwiftUI Search 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()
}

// 対

NavigationSplitView {
    SidebarView()
} detail: {
    DetailView()
        .searchable(text: $query)  // 詳細で検索
}

// 対

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 サブミットの判断

パターン使用するタイミング例
入力に応じたフィルターローカルデータ、高速フィルタリング連絡先、設定
サブミットベースの検索ネットワークリクエスト、高コストなクエリApp Store、ウェブ検索
組み合わせサジェスチョンはローカルでフィルター、サブミットでサーバー処理マップ、ショッピング

サジェスチョン + サブミットの組み合わせパターン

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 と同じビューにアタッチする必要があります。FocusState の値が true に設定されると、ユーザーがタップしたかのように検索フィールドがアクティブになります。

searchFocused の一般的な問題

問題: アラートやシート内からフォーカスを設定できない

回避策: フォーカスは、searchable 修飾子を含むビューと同じウィンドウ/シーンの一部である必要があります。

// ✅ 動作する: 同じビュー階層
NavigationStack {
    content
        .searchable(text: $query)
        .searchFocused($isFocused)
}

// ❌ 動作しない: 別のシーンまたはモーダル
.sheet(isPresented: $showSheet) {
    SheetView()
        .searchable(text: $query)
        .searchFocused($isFocused)  // 予想通りに動作しない可能性がある
}

一般的な問題のトラブルシューティング

「検索フィールドが表示されない」

原因: .searchable がナビゲーションコンテナの外にある。

// ❌ 間違い: ナビゲーションコンテナがない
VStack {
    List { ... }
}
.searchable(text: $query)

// ✅ 正しい: NavigationStack 内
NavigationStack {
    List { ... }
        .searchable(text: $query)
}

「サジェスチョンが表示されない」

原因: searchCompletion が必要。閉じられた suggestions クロージャにテキストまたはサジェスチョンがある。

// ❌ 間違い: searchCompletion がない
.searchable(text: $query) {
    ForEach(suggestions) { Text($0.name) }
}

// ✅ 正しい
.searchable(text: $query) {
    ForEach(suggestions) {
        Text($0.name).searchCompletion($0.name)
    }
}

「環境値が機能しない」

原因: isSearching または dismissSearch が間違ったビューで読み取られている。

// ❌ 間違い: searchable と同じビュー
struct MyView: View {
    @Environment(\.isSearching) private var isSearching

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

// ✅ 正しい: searchable を持つビューの子
struct MyView: View {
    var body: some View {
        NavigationStack {
            SearchConsumer()  // ここで isSearching を読み取る
                .searchable(text: $query)
        }
    }
}

クイックリファレンス

最小限の実装

struct MinimalSearch: View {
    @State private var query = ""

    var body: some View {
        NavigationStack {
            List(filteredItems) { item in
                Text(item.name)
            }
            .searchable(text: $query)
        }
    }

    var filteredItems: [Item] {
        if query.isEmpty { return allItems }
        return allItems.filter { $0.name.localizedCaseInsensitiveContains(query) }
    }
}

サジェスチョンあり

NavigationStack {
    List(filteredItems) { ... }
        .searchable(text: $query) {
            ForEach(suggestions) {
                Label($0.name, systemImage: $0.icon)
                    .searchCompletion($0.name)
            }
        }
}

スコープあり

NavigationStack {
    List(filteredItems) { ... }
        .searchable(text: $query)
        .searchScopes($scope) {
            ForEach(Scope.allCases, id: \.self) {
                Text($0.rawValue).tag($0)
            }
        }
}

トークンあり

NavigationStack {
    List(filteredItems) { ... }
        .searchable(text: $query, tokens: $tokens) { token in
            Label(token.label, systemImage: token.icon)
        }
}

プログラムフォーカス制御あり

@FocusState private var focused: Bool

NavigationStack {
    List(filteredItems) { ... }
        .searchable(text: $query)
        .searchFocused($focused)
}
// focused = true で検索をアクティブ化

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

関連スキル