Arama çubuğu

Arama işlevini uygulamak için arama çubuğu kullanın. Arama çubuğu, kullanıcıların uygulamanızda alakalı sonuçları görüntülemek için bir anahtar kelime veya kelime öbeği girmesine olanak tanıyan kalıcı bir arama alanıdır. Uygulamanızın birincil odağı arama olduğunda kullanılması önerilir.

İki arama çubuğu gösteriliyor. Soldakinde yalnızca bir metin alanı var. Sağdaki arama çubuğunda bir metin alanı ve altında bir arama önerisi var.
Şekil 1. Temel arama çubuğu (1) ve öneri içeren arama çubuğu (2).

API yüzeyi

Arama çubukları uygulamak için SearchBar composable'ını kullanın. Bu composable'ın temel parametreleri şunlardır:

  • inputField: Arama çubuğunun giriş alanını tanımlar. Genellikle SearchBarDefaults.InputField kullanılır. Bu sayede şunlar özelleştirilebilir:
    • query: Giriş alanında gösterilecek sorgu metni.
    • onQueryChange: Sorgu dizesindeki değişiklikleri işlemek için Lambda.
  • expanded: Arama çubuğunun, önerileri veya filtrelenmiş sonuçları göstermek için genişletilip genişletilmediğini belirten bir boole değeri.

  • onExpandedChange: Açılır listenin genişletilmiş durumundaki değişiklikleri işlemek için lambda.

  • content: Bu arama çubuğunun içeriği, arama sonuçlarını inputField altında gösterir.

Bu snippet, önerilerle birlikte SearchBar'nin temel bir uygulamasını gösterir:

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

Kodla ilgili önemli noktalar

  • rememberSaveable, arama çubuğunun genişletilmiş veya daraltılmış durumunun yapılandırma değişiklikleri boyunca korunmasını sağlar. Hatırlanan değeri, yapılandırma değişikliği sırasında etkinlik yok edilmeden önce barındırma etkinliğinin savedInstanceState paketine yazar.
  • semantics değiştiricisi, TalkBack gezinme sırasını kontrol eder.
    • isTraversalGroup, tüm alt bileşenlerini gruplandırmak için Box olarak ayarlanır.
    • traversalIndex, TalkBack'in her bir grup eşinden erişilebilirlik bilgilerini okuma sırasını belirtmek için ayarlanır. TalkBack, -1 gibi negatif değere sahip bir eşle ilgili erişilebilirlik bilgilerini, 1 gibi pozitif değere sahip bir eşten önce okur. Değer bir kayan nokta olduğundan, her bir eş üzerinde -1.0 ile 1.0 arasında değerler ayarlayarak birçok eş için özel bir sıra belirtebilirsiniz.
  • SearchBar, kullanıcı girişi için bir inputField ve arama önerilerini görüntülemek için bir Column içerir.
    • SearchBarDefaults.InputField, giriş alanını oluşturur ve kullanıcı sorgusundaki değişiklikleri işler.
    • onQueryChange, metin girişini işler ve giriş alanındaki metin her değiştiğinde durumu günceller.
    • expanded durumu, öneri listesinin görünürlüğünü kontrol eder.
  • searchResults.forEach { result -> … }, searchResults listesinde iterasyon yapar ve her sonuç için bir ListItem oluşturur.
    • Bir ListItem tıklandığında textFieldState güncellenir, arama çubuğu daraltılır ve textField seçilen arama sonucuyla doldurulur.

Sonuç

İçinde &quot;a&quot; harfi yazılı bir arama çubuğu gösteriliyor. Arama çubuğunun altında altı arama önerisi içeren bir liste gösteriliyor.
Şekil 2. Önerilerin gösterildiği bir arama çubuğu.

Filtrelenmiş liste içeren arama çubuğu

Bu örnekte, kullanıcının arama sorgusuna göre bir listeyi filtreleyen SearchBar gösterilmektedir:

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

Kodla ilgili önemli noktalar

  • Kullanıcı, arama çubuğuna metin yazdığında veya metin sildiğinde onQueryChange lambda işlevi çağrılır.
  • SearchBarDefaults.InputField, giriş alanının başına bir arama simgesi ekleyen leadingIcon ve giriş alanının sonuna "diğer seçenekler" simgesi ekleyen trailingIcon içerir. Burada kullanıcıya sıralama ve filtreleme seçenekleri sunabilirsiniz.
  • onSearch = { … }, arama gönderildiğinde onSearch lambda'yı çağırır ve arama çubuğunu daraltır.
  • LazyColumn, çok sayıda arama sonucunu verimli bir şekilde işler. searchResults listesinde iterasyon yapar ve her sonucu ListItem olarak gösterir.
  • Her ListItem composable, öğe metnini, ek bilgileri gösteren metni ve öğenin leadingContent olarak bir yıldız simgesini gösterir. Bu örnekte, öğeyi favorilere ekleme seçeneği sunulmaktadır.
  • Filtreleme mantığı için GitHub'daki tam kaynak kodunda CustomizableSearchBarExample bölümüne bakın.

Sonuç

İçinde &quot;metin arama&quot; ifadesi bulunan bir arama çubuğu gösteriliyor. Arama çubuğunun altında, her önerinin yanında yıldız simgesi bulunan bir arama önerisi listesi gösteriliyor.
Şekil 3. Alakalı önerilerin gösterildiği bir arama çubuğu.

Ek kaynaklar