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

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

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

แพลตฟอร์ม API

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

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

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

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

ผลลัพธ์

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

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

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