ツールチップ

ツールチップを使用して、ボタンなどの UI 要素にコンテキストを追加します。ツールチップには次の 2 種類があります。

  • シンプルなツールチップ: アイコンボタンの要素やアクションを説明します。
  • 詳細なツールチップ: 特徴の値の説明など、より詳細な情報を提供します。必要に応じて、タイトル、リンク、ボタンを含めることもできます。
ラベル付きの単一行のシンプルなツールチップ（1）と、タイトルと情報ブロックがラベル付きの複数行のリッチ ツールチップ（2）。
図 1. プレーン ツールチップ（1）とリッチ ツールチップ（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 は、PlainTooltip コンポーザブルを使用してツールチップのコンテンツを定義するラムダ関数です。
    • Text(plainTooltipText) は、ツールチップ内にテキストを表示します。
    • tooltipState はツールチップの状態を制御します。
  • IconButton は、アイコン付きのクリック可能なボタンを作成します。
    • Icon(...) は、ボタン内にハートのアイコンを表示します。
    • ユーザーが IconButton を操作すると、ツールチップに「お気に入りに追加」というテキストが表示されます。デバイスに応じて、ユーザーは次の方法でツールチップをトリガーできます。
    • カーソルをアイコンにホバーする
    • モバイル デバイスでアイコンを長押しする

結果

この例では、アイコンの上にシンプルなツールチップを表示します。

テキストを含む 1 行のツールチップ
図 2. ユーザーがハートアイコンにカーソルを合わせたり、長押ししたりしたときに表示されるシンプルなツールチップ。

リッチなツールチップを表示する

リッチ ツールチップを使用して、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 は、ユーザー操作のイベント リスナーを処理し、それに応じて TooltipState を更新します。TooltipState がツールチップを表示する必要があることを示すと、ツールチップ ラムダが実行され、RichTooltip が表示されます。TooltipBox は、コンテンツとツールチップの両方のアンカーとコンテナとして機能します。
    • この場合、コンテンツはタップ可能なアクション ビヘイビアを提供する IconButton コンポーネントです。TooltipBox のコンテンツの任意の場所を長押し（タップデバイスの場合）またはホバー（マウス ポインタの場合）すると、ツールチップが表示され、詳細情報が表示されます。
  • RichTooltip コンポーザブルは、タイトルや本文のテキストなど、ツールチップのコンテンツを定義します。TooltipDefaults.rememberRichTooltipPositionProvider() は、リッチ ツールチップの配置情報を提供します。

結果

この例では、情報アイコンにタイトルが付いたリッチなツールチップを生成します。

タイトルが
図 3. タイトルと情報アイコン付きの詳細なツールチップ。

リッチ ツールチップをカスタマイズする

このコード スニペットは、カメラ アイコンボタンの上にタイトル、カスタム アクション、カスタム カーレット（矢印）を表示するリッチなツールチップを表示します。

@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() } } はコルーチンを起動して、tooltipState.show を使用してツールチップを手動で表示します。
  • action パラメータを使用すると、ボタンなどのインタラクティブな要素をツールチップに追加できます。
  • caretSize パラメータは、ツールチップの矢印のサイズを変更します。

結果

この例では、次のようになります。

タイトルが
図 4. カメラアイコンに固定された閉じるアクションを含むカスタム リッチ ツールチップ。

参考情報