ใช้แถบค้นหาเพื่อใช้ฟังก์ชันการค้นหา แถบค้นหาคือช่องค้นหาแบบถาวรที่อนุญาตให้ผู้ใช้ป้อนคีย์เวิร์ดหรือวลีเพื่อแสดงผลการค้นหาที่เกี่ยวข้องภายในแอป และแนะนำให้ใช้เมื่อการค้นหาเป็นแกนหลักของแอป

แพลตฟอร์ม 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
ช่วยให้มั่นใจว่าแถบค้นหาจะขยายหรือยุบอยู่เสมอไม่ว่าจะมีการเปลี่ยนแปลงการกําหนดค่าอย่างไร โดยจะเขียนค่าที่จดจำไว้ในแพ็กเกจsavedInstanceState
ของกิจกรรมโฮสติ้งก่อนที่ระบบจะทำลายกิจกรรมระหว่างการเปลี่ยนแปลงการกําหนดค่า- ตัวแก้ไข
semantics
จะควบคุมลําดับการไปยังส่วนต่างๆ ของ TalkBackisTraversalGroup
ได้รับการตั้งค่าสำหรับBox
เพื่อจัดกลุ่มคอมโพสิเบิลย่อยทั้งหมดtraversalIndex
มีการตั้งค่าเพื่อระบุลำดับที่ TalkBack จะอ่านข้อมูลการช่วยเหลือพิเศษจากอุปกรณ์ของบุคคลในอีกกลุ่มหนึ่ง TalkBack จะอ่านข้อมูลการช่วยเหลือพิเศษของอุปกรณ์ที่เชื่อมต่อที่มีค่าเป็นลบ เช่น-1
ก่อนอุปกรณ์ที่เชื่อมต่อที่มีค่าเป็นบวก เช่น1
เนื่องจากค่านี้เป็นประเภท float คุณจึงระบุลําดับที่กำหนดเองของ Peer หลายรายการได้โดยการตั้งค่าระหว่าง-1.0
กับ1.0
ใน Peer แต่ละรายการ
SearchBar
มีinputField
สําหรับอินพุตของผู้ใช้ และColumn
เพื่อแสดงคําแนะนําการค้นหาSearchBarDefaults.InputField
สร้างช่องป้อนข้อมูลและจัดการการเปลี่ยนแปลงในข้อความค้นหาของผู้ใช้onQueryChange
จัดการการป้อนข้อความและอัปเดตสถานะทุกครั้งที่มีการเปลี่ยนแปลงข้อความในช่องป้อนข้อมูล- สถานะ
The expanded
ควบคุมระดับการมองเห็นรายการคำแนะนำ
searchResults.forEach { result -> … }
จะวนผ่านsearchResults
รายการและสร้างListItem
สําหรับผลลัพธ์แต่ละรายการ- เมื่อคลิก
ListItem
ระบบจะอัปเดตtextFieldState
ยุบแถบค้นหา และป้อนผลการค้นหาที่เลือกลงในtextField
- เมื่อคลิก
ผลลัพธ์

แถบค้นหาที่มีรายการที่กรอง
ตัวอย่างนี้แสดง SearchBar
ที่กรองรายการตามข้อความค้นหาของผู้ใช้
@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) ) } } } } }
ประเด็นสำคัญเกี่ยวกับรหัส
- ระบบจะเรียกใช้ฟังก์ชัน LAMBDA
onQueryChange
ทุกครั้งที่ผู้ใช้พิมพ์หรือลบข้อความในแถบค้นหา SearchBarDefaults.InputField
มีleadingIcon
ซึ่งจะเพิ่มไอคอนการค้นหาไว้ที่จุดเริ่มต้นของช่องป้อนข้อมูล และtrailingIcon
ซึ่งจะเพิ่มไอคอน "ตัวเลือกเพิ่มเติม" ไว้ที่จุดสิ้นสุดของช่องป้อนข้อมูล ในส่วนนี้ คุณสามารถระบุตัวเลือกการจัดเรียงและการกรองให้กับผู้ใช้onSearch = { … }
จะเรียก Lambda ของonSearch
และยุบแถบค้นหาเมื่อส่งการค้นหาLazyColumn
จัดการผลการค้นหาจํานวนมากได้อย่างมีประสิทธิภาพ โดยระบบจะวนผ่านรายการsearchResults
และแสดงผลลัพธ์แต่ละรายการเป็นListItem
- Composable
ListItem
แต่ละรายการจะแสดงข้อความของรายการ ข้อความที่แสดงข้อมูลเพิ่มเติม และไอคอนดาวเป็นleadingContent
ของรายการ ในตัวอย่างนี้ ระบบจะแสดงตัวเลือกให้ตั้งค่ารายการเป็นรายการโปรด - ดูตรรกะการกรองได้ที่
CustomizableSearchBarExample
ในซอร์สโค้ดแบบเต็มใน GitHub
ผลลัพธ์

แหล่งข้อมูลเพิ่มเติม
- Material Design: แถบค้นหา