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 destra 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 un suggerimento (2).

Piattaforma API

Utilizza il componibile SearchBar per implementare le barre di ricerca. I parametri chiave per questo componibile 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 nella stringa di query.
  • expanded: un valore booleano che indica se la barra di ricerca è espansa per mostrare suggerimenti o risultati filtrati.

  • onExpandedChange: Lambda per gestire le modifiche nello stato espanso del menu 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()
                    )
                }
            }
        }
    }
}

Punti chiave sul codice

  • rememberSaveable garantisce che lo stato della barra di ricerca (espansa o compressa) venga mantenuto dopo le modifiche alla configurazione. Scrive il valore memorizzato nel bundle savedInstanceState dell'attività di hosting prima che l'attività venga eliminata durante una modifica della configurazione.
  • Il modificatore semantics controlla l'ordine di attraversamento di TalkBack.
    • isTraversalGroup è impostato per Box per raggruppare tutti i relativi componenti componibili secondari.
    • traversalIndex è impostato per specificare l'ordine in cui TalkBack legge le informazioni sull'accessibilità di ogni peer del gruppo. TalkBack legge le informazioni sull'accessibilità di un peer con un valore negativo, ad esempio -1, prima di un peer con un valore positivo, ad esempio 1. Poiché il valore è un numero in virgola mobile, puoi specificare un ordine personalizzato di molti peer impostando valori compresi tra -1.0 e 1.0 su ogni peer.
  • 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.
    • Lo stato di expanded controlla la visibilità dell'elenco dei suggerimenti.
  • searchResults.forEach { result -> … } esegue l'iterazione nell'searchResults elenco e crea un ListItem per ogni risultato.
    • Quando si fa clic su un ListItem, viene aggiornato il textFieldState, la barra di ricerca viene compressa e il textField viene compilato con il risultato di ricerca selezionato.

Risultato

Viene mostrata una barra di ricerca con la lettera &quot;a&quot; digitata all'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 un 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)
                    )
                }
            }
        }
    }
}

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 opzioni di ordinamento e filtro all'utente.
  • onSearch = { … } chiama la lambda onSearch e comprime la barra di ricerca quando viene inviata la ricerca.
  • Un LazyColumn gestisce in modo efficiente un numero potenzialmente elevato di risultati di ricerca. Esegue l'iterazione nell'elenco searchResults e mostra 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 visualizzata un'opzione per aggiungere l'elemento ai preferiti.
  • Per la logica di filtraggio, consulta CustomizableSearchBarExample nel codice sorgente completo su GitHub.

Risultato

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

Risorse aggiuntive