Tooltip

Gunakan tooltip untuk menambahkan konteks ke tombol atau elemen UI lainnya. Ada dua jenis tooltip:

• Tooltip biasa: Mendeskripsikan elemen atau tindakan tombol ikon.
• Tooltip kaya: Memberikan detail lebih lanjut, seperti mendeskripsikan nilai fitur. Juga dapat menyertakan judul, link, dan tombol opsional.

Gambar 1. Tooltip biasa (1) dan tooltip lengkap (2).

Platform API

Anda dapat menggunakan composable TooltipBox untuk menerapkan tooltip di aplikasi Anda. Anda mengontrol tampilan TooltipBox dengan parameter utama berikut:

• positionProvider: Menempatkan tooltip relatif terhadap konten penahan. Anda biasanya menggunakan penyedia posisi default dari TooltipDefaults, atau Anda dapat menyediakan penyedia posisi Anda sendiri jika memerlukan logika penempatan kustom.
• tooltip: Composable yang berisi konten tooltip. Anda biasanya menggunakan composable PlainTooltip atau RichTooltip.
  • Gunakan PlainTooltip untuk mendeskripsikan elemen atau tindakan tombol ikon.
  • Gunakan RichTooltip untuk memberikan detail selengkapnya, seperti mendeskripsikan nilai fitur. Tooltip kaya dapat menyertakan judul, link, dan tombol opsional.
• state: Holder status yang berisi logika UI dan status elemen untuk tooltip ini.
• content: Konten composable yang menjadi titik penjangkaran tooltip.

Menampilkan tooltip biasa

Gunakan tooltip biasa untuk menjelaskan elemen UI secara singkat. Cuplikan kode ini menampilkan tooltip biasa di atas tombol ikon, yang diberi label "Tambahkan ke favorit":

@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

Poin penting tentang kode

• TooltipBox menghasilkan tooltip dengan teks "Tambahkan ke favorit".
  • TooltipDefaults.rememberPlainTooltipPositionProvider() menyediakan pemosisian default untuk tooltip biasa.
  • tooltip adalah fungsi lambda yang menentukan konten tooltip menggunakan composable PlainTooltip.
  • Text(plainTooltipText) menampilkan teks dalam tooltip.
  • tooltipState mengontrol status tooltip.
• IconButton membuat tombol yang dapat diklik dengan ikon.
  • Icon(...) menampilkan ikon hati di dalam tombol.
  • Saat pengguna berinteraksi dengan IconButton, TooltipBox menampilkan tooltip dengan teks "Tambahkan ke favorit". Bergantung pada perangkat, pengguna dapat memicu tooltip dengan cara berikut:
  • Mengarahkan kursor ke ikon
  • Menekan lama ikon di perangkat seluler

Hasil

Contoh ini menghasilkan tooltip biasa di atas ikon:

Gambar 2. Tooltip biasa yang muncul saat pengguna mengarahkan kursor ke atau menekan lama ikon hati.

Menampilkan tooltip multimedia

Gunakan tooltip lengkap untuk memberikan konteks tambahan tentang elemen UI. Contoh ini membuat tooltip kaya multi-baris dengan judul yang ditambatkan ke 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

Poin penting tentang kode

• TooltipBox menangani pemroses peristiwa untuk interaksi pengguna dan memperbarui TooltipState dengan tepat. Saat TooltipState menunjukkan bahwa tooltip harus ditampilkan, lambda tooltip akan dieksekusi, dan TooltipBox akan menampilkan RichTooltip. TooltipBox berfungsi sebagai penampung dan anchor untuk konten dan tooltip.
  • Dalam hal ini, kontennya adalah komponen IconButton, yang menyediakan perilaku tindakan yang dapat diketuk. Saat ditekan lama (pada perangkat sentuh) atau diarahkan kursornya (seperti dengan pointer mouse) di mana saja dalam konten TooltipBox, tooltip akan ditampilkan untuk menunjukkan informasi selengkapnya.
• Composable RichTooltip menentukan konten tooltip, termasuk judul dan teks isi. TooltipDefaults.rememberRichTooltipPositionProvider() memberikan informasi penempatan untuk tooltip kaya.

Hasil

Contoh ini menghasilkan tooltip lengkap dengan judul yang dilampirkan ke ikon informasi:

Gambar 3. Tooltip lengkap dengan judul dan ikon informasi.

Menyesuaikan tooltip kaya

Cuplikan kode ini menampilkan tooltip kaya dengan judul, tindakan kustom, dan tanda sisipan (panah) kustom yang ditampilkan di atas tombol ikon kamera:

@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

Poin penting tentang kode

• RichToolTip menampilkan tooltip dengan judul dan tindakan tutup.
• Saat diaktifkan, baik dengan menekan lama atau mengarahkan kursor ke konten ToolTipBox, tooltip akan ditampilkan selama sekitar satu detik. Anda dapat menutup tooltip ini dengan mengetuk di tempat lain pada layar atau menggunakan tombol tindakan tutup.
• Saat tindakan menutup dijalankan, sistem akan meluncurkan coroutine untuk memanggil tooltipState.dismiss. Hal ini memverifikasi bahwa eksekusi tindakan tidak diblokir saat tooltip ditampilkan.
• onClick = coroutineScope.launch { tooltipState.show() } } meluncurkan coroutine untuk menampilkan tooltip secara manual menggunakan tooltipState.show.
• Parameter action memungkinkan penambahan elemen interaktif ke tooltip, seperti tombol.
• Parameter caretSize mengubah ukuran panah tooltip.

Hasil

Contoh ini menghasilkan output berikut:

Gambar 4. Tooltip lengkap kustom dengan tindakan tutup yang ditambatkan ke ikon kamera.

Referensi lainnya

• Desain Material: Tooltip