Barra di ricerca

Utilizza una barra di ricerca per implementare la funzionalità di ricerca. Una barra di ricerca è un campo di ricerca persistente che consente agli utenti di inserire una parola chiave o una frase per visualizzare i risultati pertinenti all'interno dell'app ed è consigliata quando la ricerca è l'obiettivo principale dell'app.

Vengono mostrate due barre di ricerca. Quello a sinistra ha solo un campo di testo. La barra di ricerca a sinistra ha un campo di testo e un suggerimento di ricerca sotto.
Figura 1. Una barra di ricerca di base (1) e una barra di ricerca con a suggerimento (2).

Piattaforma API

Utilizza il SearchBar composable per implementare le barre di ricerca. I parametri chiave per questo composable includono:

  • inputField: definisce il campo di immissione della barra di ricerca. In genere utilizza SearchBarDefaults.InputField, che consente la personalizzazione di:
    • query: il testo della query da mostrare nel campo di immissione.
    • onQueryChange: lambda per gestire le modifiche alla stringa di query.
  • expanded: un valore booleano che indica se la barra di ricerca è espansa per mostrare i suggerimenti o i risultati filtrati.

  • onExpandedChange: lambda per gestire le modifiche allo stato espanso dell'elenco a discesa.

  • content: il contenuto di questa barra di ricerca per visualizzare i risultati di ricerca sotto inputField.

Questo snippet mostra un'implementazione di base di SearchBar con suggerimenti:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun SimpleSearchBar(
    textFieldState: TextFieldState,
    onSearch: (String) -> Unit,
    searchResults: List<String>,
    modifier: Modifier = Modifier
) {
    // Controls expansion state of the search bar
    var expanded by rememberSaveable { mutableStateOf(false) }

    Box(
        modifier
            .fillMaxSize()
            .semantics { isTraversalGroup = true }
    ) {
        SearchBar(
            modifier = Modifier
                .align(Alignment.TopCenter)
                .semantics { traversalIndex = 0f },
            inputField = {
                SearchBarDefaults.InputField(
                    query = textFieldState.text.toString(),
                    onQueryChange = { textFieldState.edit { replace(0, length, it) } },
                    onSearch = {
                        onSearch(textFieldState.text.toString())
                        expanded = false
                    },
                    expanded = expanded,
                    onExpandedChange = { expanded = it },
                    placeholder = { Text("Search") }
                )
            },
            expanded = expanded,
            onExpandedChange = { expanded = it },
        ) {
            // Display search results in a scrollable column
            Column(Modifier.verticalScroll(rememberScrollState())) {
                searchResults.forEach { result ->
                    ListItem(
                        headlineContent = { Text(result) },
                        modifier = Modifier
                            .clickable {
                                textFieldState.edit { replace(0, length, result) }
                                expanded = false
                            }
                            .fillMaxWidth()
                    )
                }
            }
        }
    }
}
SearchBar.kt

Punti chiave sul codice

  • rememberSaveable garantisce che lo stato di espansione o riduzione della barra di ricerca venga mantenuto durante le modifiche alla configurazione. Scrive il valore memorizzato nel bundle savedInstanceState dell'attività di hosting prima che l'attività venga eliminata durante una modifica alla configurazione.
  • Il modificatore semantics controlla l'ordine di attraversamento di TalkBack.
    • isTraversalGroup è impostato per Box per raggruppare tutti i composable secondari.
    • traversalIndex è impostato per specificare l'ordine in cui TalkBack legge le informazioni sull'accessibilità da ogni peer di gruppo. TalkBack reads accessibility information on a peer with a negative value, such as -1, before a peer with a positive value, such as 1. Poiché il valore è un float, puoi specificare un ordine personalizzato di molti peer impostando valori compresi tra -1.0 e 1.0 su ogni peer.
  • Il SearchBar contiene un inputField per l'input dell'utente e un Column per visualizzare i suggerimenti di ricerca.
    • SearchBarDefaults.InputField crea il campo di immissione e gestisce le modifiche alla query dell'utente.
    • onQueryChange gestisce l'input di testo e aggiorna lo stato ogni volta che il testo nel campo di immissione cambia.
    • The expanded state controlla la visibilità dell'elenco dei suggerimenti.
  • searchResults.forEach { result -> … } scorre l'searchResults elenco e crea un ListItem per ogni risultato.
    • Quando si fa clic su un ListItem, viene aggiornato textFieldState, la barra di ricerca viene compressa e textField viene compilato con il risultato di ricerca selezionato.

Risultato

Viene mostrata una barra di ricerca con la lettera &quot;a&quot; digitata all&#39;interno. Sotto la barra di ricerca viene visualizzato un elenco contenente sei suggerimenti di ricerca.
Figura 2. Una barra di ricerca con i suggerimenti visualizzati.

Barra di ricerca con elenco filtrato

Questo esempio mostra una SearchBar che filtra un elenco in base alla query di ricerca dell'utente:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun CustomizableSearchBar(
    query: String,
    onQueryChange: (String) -> Unit,
    onSearch: (String) -> Unit,
    searchResults: List<String>,
    onResultClick: (String) -> Unit,
    modifier: Modifier = Modifier,
    // Customization options
    placeholder: @Composable () -> Unit = { Text("Search") },
    leadingIcon: @Composable (() -> Unit)? = { Icon(Icons.Default.Search, contentDescription = "Search") },
    trailingIcon: @Composable (() -> Unit)? = null,
    supportingContent: (@Composable (String) -> Unit)? = null,
    leadingContent: (@Composable () -> Unit)? = null,
) {
    // Track expanded state of search bar
    var expanded by rememberSaveable { mutableStateOf(false) }

    Box(
        modifier
            .fillMaxSize()
            .semantics { isTraversalGroup = true }
    ) {
        SearchBar(
            modifier = Modifier
                .align(Alignment.TopCenter)
                .semantics { traversalIndex = 0f },
            inputField = {
                // Customizable input field implementation
                SearchBarDefaults.InputField(
                    query = query,
                    onQueryChange = onQueryChange,
                    onSearch = {
                        onSearch(query)
                        expanded = false
                    },
                    expanded = expanded,
                    onExpandedChange = { expanded = it },
                    placeholder = placeholder,
                    leadingIcon = leadingIcon,
                    trailingIcon = trailingIcon
                )
            },
            expanded = expanded,
            onExpandedChange = { expanded = it },
        ) {
            // Show search results in a lazy column for better performance
            LazyColumn {
                items(count = searchResults.size) { index ->
                    val resultText = searchResults[index]
                    ListItem(
                        headlineContent = { Text(resultText) },
                        supportingContent = supportingContent?.let { { it(resultText) } },
                        leadingContent = leadingContent,
                        colors = ListItemDefaults.colors(containerColor = Color.Transparent),
                        modifier = Modifier
                            .clickable {
                                onResultClick(resultText)
                                expanded = false
                            }
                            .fillMaxWidth()
                            .padding(horizontal = 16.dp, vertical = 4.dp)
                    )
                }
            }
        }
    }
}
SearchBar.kt

Punti chiave sul codice

  • La funzione lambda onQueryChange viene chiamata ogni volta che l'utente digita o elimina testo nella barra di ricerca.
  • SearchBarDefaults.InputField contiene un leadingIcon, che aggiunge un'icona di ricerca all'inizio del campo di immissione, e un trailingIcon, che aggiunge un'icona "Altre opzioni" alla fine del campo di immissione. Qui puoi fornire all'utente opzioni di ordinamento e filtro.
  • onSearch = { … } chiama la lambda onSearch e comprime la barra di ricerca quando la ricerca viene inviata.
  • Un LazyColumn gestisce in modo efficiente un numero potenzialmente elevato di risultati di ricerca. Scorre l'elenco searchResults e visualizza ogni risultato come ListItem.
  • Ogni composable ListItem mostra il testo dell'elemento, il testo che mostra informazioni aggiuntive e un'icona a forma di stella come leadingContent dell'elemento. In questo esempio, viene presentata un'opzione per aggiungere l'elemento ai preferiti.
  • Per la logica di filtro, consulta CustomizableSearchBarExample nel codice sorgente completo su GitHub.

Risultato

Viene visualizzata una barra di ricerca contenente le parole Ricerca di testo suggerita all&#39;interno. Sotto la barra di ricerca viene visualizzato un elenco di suggerimenti di ricerca, con un&#39;icona a forma di stella accanto a ogni suggerimento.
Figura 3. Una barra di ricerca con i suggerimenti pertinenti visualizzati.

Risorse aggiuntive