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

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

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