ツールチップ

ツールチップを使用して、ボタンや他の 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. カメラアイコンにアンカー設定された、閉じるアクション付きのカスタム リッチ ツールチップ。

参考情報