ツールチップ

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

  • プレーン ツールチップ: アイコンボタンの要素やアクションを説明します。
  • リッチ ツールチップ: 機能の価値を説明するなど、より詳細な情報を提供します。オプションでタイトル、リンク、ボタンを含めることもできます。
（1）ラベル付きの 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"
            )
        }
    }
}

コードに関する主なポイント

  • TooltipBox は、「お気に入りに追加」というテキストを含むツールチップを生成します。
    • TooltipDefaults.rememberPlainTooltipPositionProvider() は、プレーン ツールチップのデフォルトの位置を提供します。
    • tooltip は、PlainTooltip コンポーザブルを使用してツールチップのコンテンツを定義するラムダ関数です。
    • Text(plainTooltipText) は、ツールチップ内にテキストを表示します。
    • tooltipState は、ツールチップの状態を制御します。
  • IconButton は、アイコン付きのクリック可能なボタンを作成します。
    • Icon(...) は、ボタン内にハートアイコンを表示します。
    • ユーザーが IconButton を操作すると、TooltipBox は「お気に入りに追加」というテキストを含むツールチップを表示します。デバイスに応じて、ユーザーは次の方法でツールチップをトリガーできます。
    • カーソルをアイコンに合わせる
    • モバイル デバイスでアイコンを長押しする

結果

次の例では、アイコンの上にプレーン ツールチップを生成しています。

ハートアイコンの上に表示された「お気に入りに追加」というテキストを含む 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"
            )
        }
    }
}

コードに関する主なポイント

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

結果

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

「リッチ ツールチップ」というタイトルと、情報アイコンの上に 1 行のテキストが表示された複数行のツールチップ。
図 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)
                        }
                    }
                },
            ) {
                Text(richTooltipText)
            }
        },
        state = tooltipState
    ) {
        IconButton(onClick = {
            coroutineScope.launch {
                tooltipState.show()
            }
        }) {
            Icon(
                imageVector = Icons.Filled.Camera,
                contentDescription = "Open camera"
            )
        }
    }
}

コードに関する主なポイント

  • RichTooltip は、タイトルと閉じるアクションを含むツールチップを表示します。
  • 長押しするか、マウスポインタを TooltipBox コンテンツに合わせると、ツールチップが約 1 秒間表示されます。このツールチップを閉じるには、画面の他の場所をタップするか、閉じる操作ボタンを使用します。
  • 閉じられたときのアクションが実行されると、システムはコルーチンを起動して tooltipState.dismiss を呼び出します。これにより、ツールチップが表示されている間、アクションの実行がブロックされないことを確認します。
  • onClick = coroutineScope.launch { tooltipState.show() } } は、tooltipState.show を使用してツールチップを手動で表示するコルーチンを起動します。
  • action パラメータを使用すると、ボタンなどのインタラクティブ要素をツールチップに追加できます。
  • caretSize パラメータは、ツールチップの矢印のサイズを変更します。

結果

この例では、次の出力が生成されます。

「カスタム リッチ ツールチップ」というタイトルと閉じるボタンが付いた複数行のツールチップ。ツールチップはカメラアイコンに固定されています。
図 4. カメラアイコンに固定された、閉じるアクションを含むカスタムのリッチ ツールチップ。

参考情報