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

จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ

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

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

แพลตฟอร์ม API

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

• positionProvider: วางเคล็ดลับเครื่องมือโดยสัมพันธ์กับเนื้อหาของส่วนหัว โดยปกติแล้ว คุณจะใช้ผู้ให้บริการตำแหน่งเริ่มต้นจาก TooltipDefaults หรือจะระบุผู้ให้บริการตำแหน่งของคุณเองก็ได้หากต้องการใช้ตรรกะการจัดตำแหน่งที่กำหนดเอง
• tooltip: คอมโพสิชันที่มีเนื้อหาของเคล็ดลับเครื่องมือ โดยปกติแล้วคุณจะใช้คอมโพสิเบิล 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 ที่กําหนดเนื้อหาของเคล็ดลับเครื่องมือโดยใช้คอมโพสิเบิล PlainTooltip
  • Text(plainTooltipText) แสดงข้อความภายในเคล็ดลับเครื่องมือ
  • tooltipState ควบคุมสถานะของเคล็ดลับเครื่องมือ
• IconButton สร้างปุ่มที่คลิกได้พร้อมไอคอน
  • Icon(...) แสดงไอคอนหัวใจภายในปุ่ม
  • เมื่อผู้ใช้โต้ตอบกับ IconButton เคล็ดลับเครื่องมือจะแสดงพร้อมข้อความ "เพิ่มลงในรายการโปรด" ผู้ใช้สามารถเรียกใช้เคล็ดลับเครื่องมือได้ดังนี้ ทั้งนี้ขึ้นอยู่กับอุปกรณ์ที่ใช้
  • วางเคอร์เซอร์เหนือไอคอน
  • การกดไอคอนบนอุปกรณ์เคลื่อนที่ค้างไว้

ผลลัพธ์

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

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

ใช้เคล็ดลับเครื่องมือแบบริชมีเดียเพื่อระบุบริบทเพิ่มเติมเกี่ยวกับองค์ประกอบ 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 ระบุว่าควรแสดงเคล็ดลับเครื่องมือ ลามเดลเคล็ดลับเครื่องมือจะทำงาน และ RichTooltip จะแสดง TooltipBox จะทำหน้าที่เป็นแฮนเดิลและคอนเทนเนอร์สำหรับทั้งเนื้อหาและเคล็ดลับเครื่องมือ
  • ในกรณีนี้ เนื้อหาคือคอมโพเนนต์ 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)
                        }
                    }
                },
                caretSize = DpSize(32.dp, 16.dp)
            ) {
                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: เคล็ดลับเครื่องมือ