Barre de recherche

Utilisez une barre de recherche pour implémenter la fonctionnalité de recherche. Une barre de recherche est un champ de recherche persistant qui permet aux utilisateurs de saisir un mot clé ou une expression pour afficher des résultats pertinents dans votre application. Elle est recommandée lorsque la recherche est l'objectif principal de votre application.

Deux barres de recherche sont affichées. Celui de gauche ne comporte qu'un champ de texte. La barre de recherche à droite comporte un champ de texte et une suggestion de recherche en dessous.
Figure 1. Barre de recherche de base (1) et barre de recherche avec une suggestion (2).

Surface d'API

Utilisez le composable SearchBar pour implémenter des barres de recherche. Les paramètres clés de ce composable sont les suivants :

  • inputField : définit le champ de saisie de la barre de recherche. Il utilise généralement SearchBarDefaults.InputField, qui permet de personnaliser les éléments suivants :
    • query : texte de la requête à afficher dans le champ de saisie.
    • onQueryChange : lambda pour gérer les modifications de la chaîne de requête.
  • expanded : valeur booléenne indiquant si la barre de recherche est développée pour afficher des suggestions ou des résultats filtrés.

  • onExpandedChange : lambda pour gérer les modifications de l'état développé du menu déroulant.

  • content : contenu de cette barre de recherche pour afficher les résultats de recherche sous inputField.

Cet extrait montre une implémentation de base de SearchBar avec des suggestions :

@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()
                    )
                }
            }
        }
    }
}

Points clés concernant le code

  • rememberSaveable garantit que l'état développé ou réduit de la barre de recherche est conservé lors des modifications de configuration. Elle écrit la valeur mémorisée dans le bundle savedInstanceState de l'activité d'hébergement avant que l'activité ne soit détruite lors d'une modification de configuration.
  • Le modificateur semantics contrôle l'ordre de balayage de TalkBack.
    • isTraversalGroup est défini pour Box afin de regrouper tous ses composables enfants.
    • traversalIndex est défini pour spécifier l'ordre dans lequel TalkBack lit les informations d'accessibilité de chaque pair du groupe. TalkBack lit les informations d'accessibilité d'un pair ayant une valeur négative, comme -1, avant un pair ayant une valeur positive, comme 1. La valeur étant un float, vous pouvez spécifier un ordre personnalisé pour de nombreux pairs en définissant des valeurs comprises entre -1.0 et 1.0 sur chaque pair.
  • SearchBar contient un inputField pour la saisie utilisateur et un Column pour afficher les suggestions de recherche.
    • SearchBarDefaults.InputField crée le champ de saisie et gère les modifications apportées à la requête utilisateur.
    • onQueryChange gère la saisie de texte et met à jour l'état chaque fois que le texte du champ de saisie change.
    • L'état expanded contrôle la visibilité de la liste de suggestions.
  • searchResults.forEach { result -> … } effectue une itération dans la liste searchResults et crée un ListItem pour chaque résultat.
    • Lorsque l'utilisateur clique sur un ListItem, le textFieldState est mis à jour, la barre de recherche est réduite et le textField est rempli avec le résultat de recherche sélectionné.

Résultat

Une barre de recherche s'affiche avec la lettre &quot;a&quot; saisie à l'intérieur. Une liste contenant six suggestions de recherche s'affiche sous la barre de recherche.
Figure 2. Barre de recherche avec des suggestions affichées.

Barre de recherche avec liste filtrée

Cet exemple montre un SearchBar qui filtre une liste en fonction de la requête de recherche de l'utilisateur :

@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)
                    )
                }
            }
        }
    }
}

Points clés concernant le code

  • La fonction lambda onQueryChange est appelée chaque fois que l'utilisateur saisit ou supprime du texte dans la barre de recherche.
  • SearchBarDefaults.InputField contient un leadingIcon, qui ajoute une icône de recherche au début du champ de saisie, et un trailingIcon, qui ajoute une icône "Plus d'options" à la fin du champ de saisie. Ici, vous pouvez proposer des options de tri et de filtrage à l'utilisateur.
  • onSearch = { … } appelle le lambda onSearch et réduit la barre de recherche lorsque la recherche est envoyée.
  • Un LazyColumn gère efficacement un nombre potentiellement élevé de résultats de recherche. Il parcourt la liste searchResults et affiche chaque résultat sous la forme d'un ListItem.
  • Chaque composable ListItem affiche le texte de l'élément, un texte contenant des informations supplémentaires et une icône en forme d'étoile comme leadingContent de l'élément. Dans cet exemple, une option permettant d'ajouter l'élément aux favoris est présentée.
  • Pour connaître la logique de filtrage, consultez CustomizableSearchBarExample dans le code source complet sur GitHub.

Résultat

Une barre de recherche contenant les mots &quot;hinted text search&quot; s'affiche. Sous la barre de recherche, une liste de suggestions de recherche s'affiche, avec une icône en forme d'étoile à côté de chaque suggestion.
Figure 3. Une barre de recherche avec des suggestions pertinentes affichées.

Ressources supplémentaires