搜尋列

使用搜尋列實作搜尋功能。搜尋列是永久顯示的搜尋欄位，可讓使用者輸入關鍵字或詞組，在應用程式中顯示相關結果。如果搜尋是應用程式的主要功能，建議使用搜尋列。

畫面顯示兩個搜尋列，左側的只有文字欄位。右側的搜尋列有一個文字欄位，下方有搜尋建議。
圖 1. 基本搜尋列 (1) 和含有建議的搜尋列 (2)。

API 介面

使用 SearchBar 可組合函式實作搜尋列。這個可組合函式的重要參數包括：

  • inputField：定義搜尋列的輸入欄位。通常會使用 SearchBarDefaults.InputField，可自訂：
    • query：要在輸入欄位中顯示的查詢文字。
    • onQueryChange：用於處理查詢字串變更的 Lambda。
  • expanded：布林值，指出搜尋列是否展開，以顯示建議或篩選結果。

  • onExpandedChange：用於處理下拉式選單展開狀態變更的 Lambda。

  • content：這個搜尋列的內容，用於在 inputField 下方顯示搜尋結果。

下列程式碼片段顯示 SearchBar 的基本實作，並提供建議：

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

程式碼重點

  • rememberSaveable 可確保在設定變更時，搜尋列的展開或收合狀態會保留。在設定變更期間，系統會先將記住的值寫入代管 Activity 的 savedInstanceState 套件，再刪除 Activity。
  • semantics 修飾符可控制 TalkBack 遍歷順序。
    • isTraversalGroup 設為 Box，用於將所有子項可組合項分組。
    • traversalIndex 的設定會指定 TalkBack 讀取各個群組對等項目的無障礙資訊順序。TalkBack 會先讀取負值 (例如 -1) 對等項目的無障礙資訊，再讀取正值 (例如 1) 對等項目的無障礙資訊。由於值是浮點數，因此您可以在每個對等點上設定介於 -1.0 和 1.0 之間的值，指定多個對等點的自訂順序。
  • SearchBar 包含用於使用者輸入內容的 inputField，以及用於顯示搜尋建議的 Column。
    • SearchBarDefaults.InputField 會建立輸入欄位，並處理使用者查詢的變更。
    • onQueryChange 會處理文字輸入，並在輸入欄位中的文字變更時更新狀態。
    • expanded 狀態會控制建議清單的顯示設定。
  • searchResults.forEach { result -> … } 會疊代 searchResults 清單，並為每個結果建立 ListItem。
    • 使用者點選 ListItem 時，系統會更新 textFieldState、收合搜尋列，並在 textField 中填入所選搜尋結果。

結果

搜尋列中輸入了字母「a」。搜尋列下方會顯示包含六項搜尋建議的清單。
圖 2. 顯示建議的搜尋列。

含有篩選清單的搜尋列

以下範例顯示 SearchBar 根據使用者的搜尋查詢篩選清單：

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

程式碼重點

  • 每當使用者在搜尋列中輸入或刪除文字時，系統就會呼叫 onQueryChange lambda 函式。
  • SearchBarDefaults.InputField 包含 leadingIcon，可在輸入欄位開頭新增搜尋圖示，以及 trailingIcon，可在輸入欄位結尾新增「更多選項」圖示。您可以在這裡為使用者提供排序和篩選選項。
  • onSearch = { … } 會呼叫 onSearch lambda，並在提交搜尋時收合搜尋列。
  • LazyColumn 可有效率地處理可能數量龐大的搜尋結果。它會疊代 searchResults 清單，並將每個結果顯示為 ListItem。
  • 每個 ListItem 可組合項都會顯示項目文字、顯示其他資訊的文字，以及做為項目 leadingContent 的星號圖示。在這個範例中，系統會顯示將項目加入收藏的選項。
  • 如要瞭解篩選邏輯，請參閱 GitHub 完整原始碼中的 CustomizableSearchBarExample。

結果

搜尋列中顯示「hinted text search」字樣。搜尋列下方會顯示搜尋建議清單，每項建議旁都有星號圖示。
圖 3. 搜尋列，顯示相關建議。

其他資源