Instance Method インスタンスメソッド

searchable(text:placement:prompt:suggestions:)

Marks this view as searchable, which configures the display of a search field.

Declaration 宣言

func searchable<S>(text: Binding<String>, placement: SearchFieldPlacement = .automatic, prompt: Text? = nil, suggestions: () -> S) -> some View where S : View

Parameters パラメータ

text: The text to display and edit in the search field.
placement: Where the search field should attempt to be placed based on the containing view hierarchy.
prompt: A Text representing the prompt of the search field which provides users with guidance on what to search for.
suggestions: A view builder that produces content that populates a list of suggestions.

Discussion 議論

Use this modifier to create a user interface appropriate for searching.

Wrapping a navigation view results in a column of the navigation view displaying a search field. On iOS and iPadOS, the first or second column displays the search field in a double, or triple column navigation view respectively. On macOS, the search field is placed in the trailing-most position of the toolbar.

var body: some View {
    NavigationView {
        PrimaryView()
        SecondaryView()
        Text("Select a primary and secondary item")
    }
    .searchable(text: $text)
}

On iOS, iPadOS, or watchOS, wrapping a specific column of a navigation view results in that column displaying a search field.

struct DestinationPageView: View {
    @State private var text = ""
    var body: some View {
        Text("Destination Page")
            .searchable(text: $text)
    }
}


var body: some View {
    NavigationView {
        List {
            NavigationLink(
                "Destination Page",
                destination: DestinationPageView()
            )
        }
        Text("Select a destination")
    }
}

You can query the isSearching property to adjust the view hierarchy within the searchable modifier. You can also provide search suggestions using the suggestions parameter of searchable modifiers.

Use the searchCompletion(_:) modifier to associate strings to the views provided to the suggestions view. The system uses these strings to replace the partial text being currently edited of the associated search field. If a view has no completion modifier, it’s displayed as is.

SearchPlaceholderView()
    .searchable(text: $text) {
        Text("🍎").searchCompletion("apple")
        Text("🍐").searchCompletion("pear")
        Text("🍌").searchCompletion("banana")
    }

The presentation of the suggestions depends on whether any content is provided to the suggestions parameter.

SearchPlaceholderView()
    .searchable(text: $text) {
        ForEach(viewModel.suggestedSearches) { suggestion in
            Label(suggestion.title,  image: suggestion.image)
                .searchCompletion(suggestion.text)
        }
    }

If viewModel.suggestedSearches begins as an empty array, then the suggestions aren’t initially displayed. When the array becomes populated, the suggestions are presented. Note that the suggestions may be dismissed based on a user’s action, like moving the window of the app on macOS for example.

You can associate an action to be invoked upon submission of the current search query by using an onSubmit(of:_:) modifier in conjunction with the a searchable modifier.

@StateObject private var viewModel = ViewModel()


NavigationView {
    SidebarView()
    DetailView()
}
.searchable(
    text: $viewModel.searchText,
    placement: .sidebar
) {
    SuggestionsView()
}
.onSubmit(of: .search) {
    viewModel.submitCurrentSearchQuery()
}