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 multimedia 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. Anda mengontrol tampilan TooltipBox dengan parameter utama berikut:

  • positionProvider: Menempatkan tooltip relatif terhadap konten anchor. Biasanya, Anda menggunakan penyedia posisi default dari TooltipDefaults, atau Anda dapat menyediakan penyedia posisi sendiri jika memerlukan logika posisi kustom.
  • tooltip: Composable yang berisi konten tooltip. Biasanya, Anda menggunakan composable PlainTooltip atau RichTooltip.
    • Gunakan PlainTooltip untuk menjelaskan elemen atau tindakan tombol ikon.
    • Gunakan RichTooltip untuk memberikan detail selengkapnya, seperti menjelaskan nilai 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 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"
            )
        }
    }
}

Poin penting tentang kode

  • TooltipBox membuat 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 ke 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 menjadi anchor 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 bertindak sebagai anchor dan penampung untuk konten dan tooltip.
    • Dalam hal ini, kontennya adalah komponen IconButton, yang menyediakan perilaku tindakan yang dapat diketuk. Saat ditekan lama (di perangkat sentuh) atau diarahkan kursor (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 posisi untuk tooltip lengkap.

Hasil

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

Tooltip multi-baris dengan judul 'Tooltip Lengkap' dan satu 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 ke konten TooltipBox dengan kursor mouse, 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 dieksekusi, 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 hal berikut:

Tooltip multiline dengan judul 'Tooltip Multimedia Kustom' dan tombol tutup. Tooltip ditambatkan ke ikon kamera.
Gambar 4. Tooltip lengkap kustom dengan tindakan tutup yang menjadi anchor ke ikon kamera.

Referensi lainnya