Arama çubuğu

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

İki arama çubuğu gösterilir. Soldaki yalnızca bir metin alanına sahiptir. Soldaki arama çubuğunda bir metin alanı ve altında bir arama önerisi bulunur.
Şekil 1. Temel arama çubuğu (1) ve öneri içeren arama çubuğu (2).

API yüzeyi

Arama çubuklarını uygulamak için SearchBar bileşenini kullanın. Bu derlenebilir öğenin temel parametreleri şunlardır:

  • inputField: Arama çubuğunun giriş alanını tanımlar. Genellikle SearchBarDefaults.InputField'ü kullanır. Bu, aşağıdakilerin özelleştirilmesine olanak tanır:
    • query: Giriş alanında gösterilecek sorgu metni.
    • onQueryChange: Sorgu dizesindeki değişiklikleri işlemek için Lambda.
  • expanded: Arama çubuğunun önerileri mi yoksa filtrelenmiş sonuçları mı gösterecek şekilde genişletilip genişletilmediğini belirten bir boole değeri.

  • onExpandedChange: Açılır menünün genişletilmiş durumundaki değişiklikleri işleyen Lambda.

  • content: Arama sonuçlarını inputField'un altında görüntülemek için bu arama çubuğunun içeriği.

Bu snippet'te, önerilerle birlikte SearchBar'ün temel bir uygulaması gösterilmektedir:

@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

Kodla ilgili önemli noktalar

  • rememberSaveable, arama çubuğunun genişletilmiş veya daraltılmış olmasının yapılandırma değişikliklerinde korunmasını sağlar. Hatırlanan değeri, yapılandırma değişikliği sırasında etkinlik yok edilmeden önce barındıran etkinliğin savedInstanceState paketine yazar.
  • semantics değiştirici, TalkBack'in traversal sırasını kontrol eder.
    • isTraversalGroup, Box'un tüm alt bileşenlerini gruplandırması için ayarlanmıştır.
    • traversalIndex, TalkBack'in her grup eşinden erişilebilirlik bilgilerini okuduğu sırayı belirtecek şekilde ayarlanır. TalkBack, 1 gibi pozitif değere sahip bir eşlemeden önce -1 gibi negatif değere sahip bir eşle ilgili erişilebilirlik bilgilerini okur. Değer bir kayan nokta olduğundan, her eş için -1.0 ile 1.0 arasında değerler ayarlayarak birçok eş için özel bir sipariş 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ı sorgusunda yapılan değişiklikleri işler.
    • onQueryChange, metin girişini işler ve giriş alanındaki metin değiştiğinde durumu günceller.
    • The 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.
    • ListItem tıklandığında textFieldState güncellenir, arama çubuğu daraltılır ve textField seçili arama sonucuyla doldurulur.

Sonuç

İçinde &quot;a&quot; harfi bulunan bir arama çubuğu gösterilir. Arama çubuğunun altında altı arama önerisi içeren bir liste gösterilir.
Şekil 2. Önerileri gösteren bir arama çubuğu.

Filtrelenmiş liste içeren arama çubuğu

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

@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

Kodla ilgili önemli noktalar

  • onQueryChange lambda işlevi, kullanıcı arama çubuğuna metin yazdığında veya metin sildiğinde çağrılır.
  • SearchBarDefaults.InputField, giriş alanının başına bir arama simgesi ekleyen bir leadingIcon ve giriş alanının sonuna "diğer seçenekler" simgesi ekleyen bir trailingIcon içerir. Burada kullanıcıya sıralama ve filtreleme seçenekleri sunabilirsiniz.
  • onSearch = { … }, onSearch lambda işlevini çağırır ve arama gönderildiğinde 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 bileşeni, öğe metnini, ek bilgileri gösteren metni ve öğenin leadingContent olarak bir yıldız simgesi 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;İpucu verilen metin arama&quot; kelimelerini içeren bir arama çubuğu gösterilir. Arama çubuğunun altında, her önerinin yanında yıldız simgesi bulunan arama önerilerinin listesi gösterilir.
Şekil 3. Alakalı önerilerin gösterildiği bir arama çubuğu.

Ek kaynaklar