เคล็ดลับเครื่องมือ

ใช้เคล็ดลับเครื่องมือเพื่อเพิ่มบริบทให้กับปุ่มหรือองค์ประกอบ UI อื่นๆ เคล็ดลับเครื่องมือมี 2 ประเภท ได้แก่

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

แพลตฟอร์ม API

คุณสามารถใช้ TooltipBox Composable เพื่อใช้เคล็ดลับเครื่องมือในแอปได้ โดยควบคุมลักษณะที่ปรากฏของ TooltipBox ด้วยพารามิเตอร์หลักต่อไปนี้

• positionProvider: วางเคล็ดลับเครื่องมือเทียบกับเนื้อหา Anchor โดยปกติแล้วคุณจะใช้ Position Provider เริ่มต้นจาก TooltipDefaults หรือจะระบุ Position Provider ของคุณเองก็ได้หากต้องการตรรกะการวางตำแหน่งที่กำหนดเอง
• tooltip: Composable ที่มีเนื้อหาของเคล็ดลับเครื่องมือ โดยปกติแล้วคุณจะใช้ Composable PlainTooltip หรือ RichTooltip
  • ใช้ PlainTooltip เพื่ออธิบายองค์ประกอบหรือการทำงานของปุ่มไอคอน
  • ใช้ RichTooltip เพื่อให้รายละเอียดเพิ่มเติม เช่น อธิบายคุณค่าของฟีเจอร์ เคล็ดลับเครื่องมือแบบละเอียดสามารถใส่ชื่อ ลิงก์ และปุ่มที่ไม่บังคับได้
• state: ตัวเก็บสถานะที่มีตรรกะ UI และสถานะองค์ประกอบสำหรับเคล็ดลับเครื่องมือนี้
• content: เนื้อหา Composable ที่เคล็ดลับเครื่องมือยึดอยู่

แสดงเคล็ดลับเครื่องมือแบบธรรมดา

ใช้เคล็ดลับเครื่องมือแบบธรรมดาเพื่ออธิบายองค์ประกอบ UI สั้นๆ ข้อมูลโค้ดนี้จะแสดงเคล็ดลับเครื่องมือแบบธรรมดาที่ด้านบนของปุ่มไอคอนที่มีป้ายกำกับว่า "เพิ่มลงในรายการโปรด"

@Composable
fun PlainTooltipExample(
    modifier: Modifier = Modifier,
    plainTooltipText: String = "Add to favorites"
) {
    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberPlainTooltipPositionProvider(),
        tooltip = {
            PlainTooltip { Text(plainTooltipText) }
        },
        state = rememberTooltipState()
    ) {
        IconButton(onClick = { /* Do something... */ }) {
            Icon(
                imageVector = Icons.Filled.Favorite,
                contentDescription = "Add to favorites"
            )
        }
    }
}
Tooltips.kt

ประเด็นสำคัญเกี่ยวกับโค้ด

• TooltipBox จะสร้างเคล็ดลับเครื่องมือที่มีข้อความว่า "เพิ่มลงในรายการโปรด"
  • TooltipDefaults.rememberPlainTooltipPositionProvider() จะให้การวางตำแหน่งเริ่มต้นสำหรับเคล็ดลับเครื่องมือแบบธรรมดา
  • tooltip เป็นฟังก์ชัน Lambda ที่กำหนดเนื้อหาของเคล็ดลับเครื่องมือโดยใช้ Composable PlainTooltip
  • Text(plainTooltipText) จะแสดงข้อความภายในเคล็ดลับเครื่องมือ
  • tooltipState จะควบคุมสถานะของเคล็ดลับเครื่องมือ
• IconButton จะสร้างปุ่มที่คลิกได้พร้อมไอคอน
  • Icon(...) จะแสดงไอคอนรูปหัวใจภายในปุ่ม
  • เมื่อผู้ใช้โต้ตอบกับ IconButton แล้ว TooltipBox จะแสดงเคล็ดลับเครื่องมือที่มีข้อความว่า "เพิ่มลงในรายการโปรด" ผู้ใช้สามารถทริกเกอร์เคล็ดลับเครื่องมือได้ด้วยวิธีต่อไปนี้ ทั้งนี้ขึ้นอยู่กับอุปกรณ์ที่ใช้
  • วางเมาส์เหนือไอคอน
  • กดไอคอนค้างไว้ในอุปกรณ์เคลื่อนที่

ผลลัพธ์

ตัวอย่างนี้จะสร้างเคล็ดลับเครื่องมือแบบธรรมดาที่ด้านบนของไอคอน

แสดงเคล็ดลับเครื่องมือแบบละเอียด

ใช้เคล็ดลับเครื่องมือแบบละเอียดเพื่อเพิ่มบริบทเกี่ยวกับองค์ประกอบ UI ตัวอย่างนี้จะสร้างเคล็ดลับเครื่องมือแบบละเอียดหลายบรรทัดที่มีชื่อซึ่งยึดกับ Icon

@Composable
fun RichTooltipExample(
    modifier: Modifier = Modifier,
    richTooltipSubheadText: String = "Rich Tooltip",
    richTooltipText: String = "Rich tooltips support multiple lines of informational text."
) {
    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),
        tooltip = {
            RichTooltip(
                title = { Text(richTooltipSubheadText) }
            ) {
                Text(richTooltipText)
            }
        },
        state = rememberTooltipState()
    ) {
        IconButton(onClick = { /* Icon button's click event */ }) {
            Icon(
                imageVector = Icons.Filled.Info,
                contentDescription = "Show more information"
            )
        }
    }
}
Tooltips.kt

ประเด็นสำคัญเกี่ยวกับโค้ด

• TooltipBox จะจัดการ Listener เหตุการณ์สำหรับการโต้ตอบของผู้ใช้และอัปเดต TooltipState ตามนั้น เมื่อ TooltipState ระบุว่าควรแสดงเคล็ดลับเครื่องมือ ฟังก์ชัน Lambda ของเคล็ดลับเครื่องมือจะทำงาน และ TooltipBox จะแสดง RichTooltip TooltipBox จะทำหน้าที่เป็น Anchor และ Container สำหรับทั้งเนื้อหาและเคล็ดลับเครื่องมือ
  • ในกรณีนี้ เนื้อหาคือคอมโพเนนต์ IconButton ซึ่งมีลักษณะการทำงานที่แตะได้ เมื่อกดค้างไว้ (ในอุปกรณ์ระบบสัมผัส) หรือวางเมาส์เหนือ (เช่นเดียวกับเคอร์เซอร์เมาส์) ที่ใดก็ได้ในเนื้อหาของ TooltipBox เคล็ดลับเครื่องมือจะแสดงขึ้นเพื่อแสดงข้อมูลเพิ่มเติม
• Composable RichTooltip จะกำหนดเนื้อหาของเคล็ดลับเครื่องมือ ซึ่งรวมถึงชื่อและข้อความเนื้อหา TooltipDefaults.rememberRichTooltipPositionProvider() จะให้ข้อมูลการวางตำแหน่งสำหรับเคล็ดลับเครื่องมือแบบละเอียด

ผลลัพธ์

ตัวอย่างนี้จะสร้างเคล็ดลับเครื่องมือแบบละเอียดที่มีชื่อแนบอยู่กับไอคอนข้อมูล

ปรับแต่งเคล็ดลับเครื่องมือแบบละเอียด

ข้อมูลโค้ดนี้จะแสดงเคล็ดลับเครื่องมือแบบละเอียดที่มีชื่อ การกระทำที่กำหนดเอง และแคเร็ต (ลูกศร) ที่กำหนดเองซึ่งแสดงที่ด้านบนของปุ่มไอคอนกล้อง

@Composable
fun AdvancedRichTooltipExample(
    modifier: Modifier = Modifier,
    richTooltipSubheadText: String = "Custom Rich Tooltip",
    richTooltipText: String = "Rich tooltips support multiple lines of informational text.",
    richTooltipActionText: String = "Dismiss"
) {
    val tooltipState = rememberTooltipState()
    val coroutineScope = rememberCoroutineScope()

    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),
        tooltip = {
            RichTooltip(
                title = { Text(richTooltipSubheadText) },
                action = {
                    Row {
                        TextButton(onClick = {
                            coroutineScope.launch {
                                tooltipState.dismiss()
                            }
                        }) {
                            Text(richTooltipActionText)
                        }
                    }
                },
            ) {
                Text(richTooltipText)
            }
        },
        state = tooltipState
    ) {
        IconButton(onClick = {
            coroutineScope.launch {
                tooltipState.show()
            }
        }) {
            Icon(
                imageVector = Icons.Filled.Camera,
                contentDescription = "Open camera"
            )
        }
    }
}
Tooltips.kt

ประเด็นสำคัญเกี่ยวกับโค้ด

• RichTooltip จะแสดงเคล็ดลับเครื่องมือที่มีชื่อและการทำงานเพื่อปิด
• เมื่อเปิดใช้งาน ไม่ว่าจะโดยการกดค้างไว้หรือวางเมาส์เหนือเนื้อหา TooltipBox ด้วยเคอร์เซอร์เมาส์ เคล็ดลับเครื่องมือจะแสดงขึ้นประมาณ 1 วินาที คุณสามารถปิดเคล็ดลับเครื่องมือนี้ได้โดยแตะที่อื่นบนหน้าจอหรือใช้ปุ่มดำเนินการเพื่อปิด
• เมื่อการทำงานเพื่อปิดทำงาน ระบบจะเปิดใช้ Coroutine เพื่อเรียก tooltipState.dismiss ซึ่งจะยืนยันว่าการทำงานจะไม่ถูกบล็อกขณะที่เคล็ดลับเครื่องมือแสดงอยู่
• onClick = coroutineScope.launch { tooltipState.show() } } จะเปิดใช้ โครูทีน เพื่อแสดงเคล็ดลับเครื่องมือด้วยตนเองโดยใช้ tooltipState.show
• พารามิเตอร์ action ช่วยให้เพิ่มองค์ประกอบแบบโต้ตอบลงในเคล็ดลับเครื่องมือได้ เช่น ปุ่ม
• พารามิเตอร์ caretSize จะปรับเปลี่ยนขนาดของลูกศรของเคล็ดลับเครื่องมือ

ผลลัพธ์

ตัวอย่างนี้จะสร้างผลลัพธ์ต่อไปนี้

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

• Material Design: เคล็ดลับเครื่องมือ