Barra di ricerca

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

Nota: il componibile SearchBar è sperimentale.

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 di 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 allo stato espanso del menu a discesa.

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

Barra di ricerca con suggerimenti

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 espanso o compresso 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 della configurazione.
• Il modificatore semantics controlla l'ordine di attraversamento di TalkBack.
  • isTraversalGroup è impostato su Box per raggruppare tutti i relativi elementi componibili secondari.
  • traversalIndex è impostato per specificare l'ordine in cui TalkBack legge le informazioni sull'accessibilità da ogni app peer del gruppo. TalkBack legge le informazioni di accessibilità su 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 ciascun 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 di suggerimenti.
• searchResults.forEach { result -> … } esegue l'iterazione dell'elenco searchResults e crea un ListItem per ogni risultato.
  • Quando si fa clic su un ListItem, viene aggiornato il textFieldState, viene compressa la barra di ricerca e viene compilato il textField con il risultato di ricerca selezionato.

Risultato

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)
                    )
                }
            }
        }
    }
}
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 funzione 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 dell'elenco searchResults e visualizza ogni risultato come ListItem.
• Ogni componibile 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

Figura 3. Una barra di ricerca con suggerimenti pertinenti.

Risorse aggiuntive

• Material Design: barra di ricerca