แถบค้นหา

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

แถบค้นหา 2 แถบจะปรากฏขึ้น รายการทางด้านซ้ายมีเพียงช่องข้อความ
  แถบค้นหาทางด้านซ้ายจะมีช่องข้อความและการแนะนำการค้นหาด้านล่าง
รูปที่ 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 ช่วยให้มั่นใจว่าแถบค้นหาจะขยายหรือยุบอยู่เสมอไม่ว่าจะมีการเปลี่ยนแปลงการกําหนดค่าอย่างไร โดยจะเขียนค่าที่จดจำไว้ในแพ็กเกจ savedInstanceState ของกิจกรรมโฮสติ้งก่อนที่ระบบจะทำลายกิจกรรมระหว่างการเปลี่ยนแปลงการกําหนดค่า
  • ตัวแก้ไข semantics จะควบคุมลําดับการไปยังส่วนต่างๆ ของ TalkBack
    • isTraversalGroup ได้รับการตั้งค่าสำหรับ 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

ผลลัพธ์

แถบค้นหาจะแสดงขึ้นพร้อมตัวอักษร &quot;a&quot; ที่พิมพ์อยู่ในแถบ รายการที่มีคำแนะนำการค้นหา 6 รายการจะแสดงใต้แถบค้นหา
รูปที่ 2 แถบค้นหาที่แสดงคำแนะนำ

แถบค้นหาที่มีรายการที่กรอง

ตัวอย่างนี้แสดง 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

ผลลัพธ์

แถบค้นหาที่มีคำว่า &quot;การค้นหาข้อความที่แนะนำ&quot; จะปรากฏขึ้น รายการคำแนะนำการค้นหาจะแสดงใต้แถบค้นหา โดยมีไอคอนดาวข้างคำแนะนำแต่ละรายการ
รูปที่ 3 แถบค้นหาที่แสดงคําแนะนําที่เกี่ยวข้อง

แหล่งข้อมูลเพิ่มเติม