ツールチップ

ツールチップを使用して、ボタンやその他の 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 を操作すると、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"
            )
        }
    }
}
Tooltips.kt

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

  • TooltipBox は、ユーザー操作のイベント リスナーを処理し、それに応じて TooltipState を更新します。TooltipState がツールチップを表示する必要があることを示すと、ツールチップ ラムダが実行され、TooltipBox が 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)
                        }
                    }
                },
            ) {
                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.カメラ アイコンにアンカーされた閉じるアクションを含むカスタム リッチ ツールチップ。

参考情報