Tooltip

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

  • Tooltip biasa: Menjelaskan elemen atau tindakan tombol ikon.
  • Tooltip lengkap: Memberikan detail selengkapnya, seperti menjelaskan nilai fitur. Dapat juga menyertakan judul, link, dan tombol opsional.
Tooltip biasa satu baris berlabel (1), dan tooltip lengkap multi-baris dengan judul dan blok informasi berlabel (2).
Gambar 1. Tooltip biasa (1) dan tooltip lengkap (2).

Platform API

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

  • positionProvider: Menempatkan tooltip relatif terhadap konten anchor. Anda biasanya menggunakan penyedia posisi default dari TooltipDefaults, atau Anda dapat menyediakan penyedia posisi Anda sendiri jika memerlukan logika pemosisian 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 menjelaskan nilai suatu fitur. Tooltip lengkap 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 anchor tooltip.

Menampilkan tooltip biasa

Gunakan tooltip biasa untuk mendeskripsikan elemen UI secara singkat. Cuplikan kode ini menampilkan tooltip biasa di atas tombol ikon, berlabel "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"
            )
        }
    }
}

Poin penting tentang kode

  • TooltipBox menghasilkan tooltip dengan teks "Tambahkan ke favorit".
  • IconButton membuat tombol yang dapat diklik dengan ikon.
    • Icon(...) menampilkan ikon hati di dalam tombol.
    • Saat pengguna berinteraksi dengan IconButton, TooltipBox akan 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:

Tooltip satu baris yang berisi teks 'Tambahkan ke favorit' ditampilkan di atas ikon hati. Tooltip muncul saat kursor diarahkan atau ditekan lama.
Gambar 2. Tooltip biasa yang muncul saat pengguna mengarahkan kursor atau menekan lama ikon hati.

Menampilkan tooltip lengkap

Gunakan tooltip lengkap untuk memberikan konteks tambahan tentang elemen UI. Contoh ini membuat tooltip lengkap 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"
            )
        }
    }
}

Poin penting tentang kode

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

Hasil

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

Tooltip multibaris dengan judul 'Tooltip Kaya' dan baris teks di atas ikon informasi.
Gambar 3. Tooltip lengkap dengan judul dan ikon informasi.

Menyesuaikan tooltip lengkap

Cuplikan kode ini menampilkan tooltip lengkap dengan judul, tindakan kustom, dan caret (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)
                        }
                    }
                },
            ) {
                Text(richTooltipText)
            }
        },
        state = tooltipState
    ) {
        IconButton(onClick = {
            coroutineScope.launch {
                tooltipState.show()
            }
        }) {
            Icon(
                imageVector = Icons.Filled.Camera,
                contentDescription = "Open camera"
            )
        }
    }
}

Poin penting tentang kode

  • RichTooltip menampilkan tooltip dengan judul dan tindakan tutup.
  • Saat diaktifkan, baik dengan menekan lama atau mengarahkan kursor mouse ke konten TooltipBox, tooltip akan ditampilkan selama sekitar satu detik. Anda dapat menutup tooltip ini dengan mengetuk di tempat lain di layar atau menggunakan tombol tindakan tutup.
  • Saat tindakan tutup dijalankan, sistem akan meluncurkan coroutine untuk memanggil tooltipState.dismiss. Tindakan 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 hal berikut:

Tooltip multibaris dengan judul 'Tooltip Kaya Kustom' dan tombol tutup. Tooltip ditambatkan ke ikon kamera.
Gambar 4. Tooltip lengkap kustom dengan tindakan tutup yang ditambatkan ke ikon kamera.

Referensi lainnya