Kotak penelusuran

Gunakan kotak penelusuran untuk menerapkan fungsi penelusuran. Kotak penelusuran adalah kolom penelusuran persisten yang memungkinkan pengguna memasukkan kata kunci atau frasa untuk menampilkan hasil yang relevan dalam aplikasi Anda, dan direkomendasikan saat penelusuran menjadi fokus utama aplikasi Anda.

Catatan: Composable SearchBar bersifat eksperimental.

Gambar 1. Kotak penelusuran dasar (1) dan kotak penelusuran dengan saran (2).

Platform API

Gunakan composable SearchBar untuk menerapkan kotak penelusuran. Parameter utama untuk composable ini meliputi:

• inputField: Menentukan kolom input kotak penelusuran. Biasanya menggunakan SearchBarDefaults.InputField, yang memungkinkan penyesuaian:
  • query: Teks kueri yang akan ditampilkan di kolom input.
  • onQueryChange: Lambda untuk menangani perubahan pada string kueri.
• expanded: Boolean yang menunjukkan apakah kotak penelusuran diperluas untuk menampilkan saran atau hasil yang difilter.

• onExpandedChange: Lambda untuk menangani perubahan status dropdown yang diperluas.

• content: Konten kolom penelusuran ini untuk menampilkan hasil penelusuran di bawah inputField.

Kotak penelusuran dengan saran

Cuplikan ini menunjukkan penerapan dasar SearchBar dengan saran:

@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

Poin penting tentang kode

• rememberSaveable memastikan bahwa apakah kolom penelusuran diperluas atau diciutkan dipertahankan di seluruh perubahan konfigurasi. Fungsi ini menulis nilai yang diingat ke dalam paket savedInstanceState Aktivitas hosting sebelum Aktivitas dimusnahkan selama perubahan konfigurasi.
• Pengubah semantics mengontrol urutan traversal TalkBack.
  • isTraversalGroup ditetapkan untuk Box guna mengelompokkan semua composable turunannya.
  • traversalIndex ditetapkan untuk menentukan urutan TalkBack membaca informasi aksesibilitas dari setiap peer grup. TalkBack membaca informasi aksesibilitas pada peer dengan nilai negatif, seperti -1, sebelum peer dengan nilai positif, seperti 1. Karena nilainya adalah float, Anda dapat menentukan urutan kustom banyak peer dengan menetapkan nilai di antara -1.0 dan 1.0 pada setiap peer.
• SearchBar berisi inputField untuk input pengguna dan Column untuk menampilkan saran penelusuran.
  • SearchBarDefaults.InputField membuat kolom input dan menangani perubahan pada kueri pengguna.
  • onQueryChange menangani input teks dan memperbarui status setiap kali teks di kolom input berubah.
  • Status The expanded mengontrol visibilitas daftar saran.
• searchResults.forEach { result -> … } melakukan iterasi melalui daftar searchResults dan membuat ListItem untuk setiap hasil.
  • Saat ListItem diklik, ListItem akan diperbarui, kotak penelusuran akan diciutkan, dan textField akan diisi dengan hasil penelusuran yang dipilih.textFieldState

Hasil

Gambar 2. Kotak penelusuran dengan saran ditampilkan.

Kotak penelusuran dengan daftar yang difilter

Contoh ini menampilkan SearchBar yang memfilter daftar berdasarkan kueri penelusuran pengguna:

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun CustomizableSearchBar(
    query: String,
    onQueryChange: (String) -> Unit,
    onSearch: (String) -> Unit,
    searchResults: List<String>,
    onResultClick: (String) -> Unit,
    // 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,
    modifier: Modifier = Modifier
) {
    // 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

Poin penting tentang kode

• Fungsi lambda onQueryChange dipanggil setiap kali pengguna mengetik atau menghapus teks di kotak penelusuran.
• SearchBarDefaults.InputField berisi leadingIcon, yang menambahkan ikon penelusuran di awal kolom input, dan trailingIcon, yang menambahkan ikon "opsi lainnya" di akhir kolom input. Di sini, Anda dapat memberikan opsi pengurutan dan pemfilteran kepada pengguna.
• onSearch = { … } memanggil lambda onSearch dan menciutkan kotak penelusuran saat penelusuran dikirimkan.
• LazyColumn menangani sejumlah besar hasil penelusuran secara efisien. Fungsi ini melakukan iterasi melalui daftar searchResults dan menampilkan setiap hasil sebagai ListItem.
• Setiap composable ListItem menampilkan teks item, teks yang menampilkan informasi tambahan, dan ikon bintang sebagai leadingContent item. Dalam contoh ini, opsi untuk menandai item sebagai favorit ditampilkan.
• Untuk logika pemfilteran, lihat CustomizableSearchBarExample dalam kode sumber lengkap di GitHub.

Hasil

Gambar 3. Kotak penelusuran dengan saran yang relevan ditampilkan.

Referensi lainnya

• Desain Material: Kotak penelusuran