Подсказка

Используйте подсказки, чтобы добавить контекст к кнопке или другому элементу интерфейса. Существует два типа подсказок:

• Простые подсказки описывают элементы или действия кнопок со значками.
• Расширенные подсказки содержат более подробную информацию, например описание преимуществ функции. Также может содержать заголовок, ссылку и кнопки.

API surface

Чтобы добавить подсказки в приложение, используйте composable-функцию TooltipBox. Внешний вид TooltipBox можно настроить с помощью следующих основных параметров:

• positionProvider: размещает подсказку относительно контента, к которому она привязана. Обычно используется поставщик позиций по умолчанию из TooltipDefaults, но вы можете указать собственный, если вам нужна особая логика позиционирования.
• tooltip: composable-функция, которая содержит контент подсказки. Обычно используются composable-функции PlainTooltip или RichTooltip.
  • Используйте PlainTooltip, чтобы описать элементы или действия кнопок со значками.
  • Используйте RichTooltip, чтобы предоставить больше информации, например описать ценность функции. В расширенных подсказках могут быть необязательные заголовок, ссылка и кнопки.
• state: хранилище состояния, которое содержит логику пользовательского интерфейса и состояние элемента для этой подсказки.
• content: составной контент, к которому привязана подсказка.

Показать простую подсказку

Используйте простую подсказку, чтобы кратко описать элемент интерфейса. Этот фрагмент кода показывает простую подсказку над кнопкой со значком и надписью "Добавить в избранное":

@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 – это лямбда-функция, которая определяет контент подсказки с помощью composable-функции PlainTooltip.
  • Text(plainTooltipText) – текст подсказки.
  • tooltipState управляет состоянием подсказки.
• IconButton создает интерактивную кнопку со значком.
  • Icon(...) – на кнопке показывается значок сердца.
  • Когда пользователь взаимодействует с IconButton, TooltipBox показывает подсказку с текстом "Добавить в избранное". В зависимости от устройства пользователи могут вызвать подсказку следующими способами:
  • Наведение курсора на значок
  • Нажмите и удерживайте значок на мобильном устройстве.

Результат

В этом примере показана простая подсказка над значком:

Показать расширенную подсказку

Используйте расширенную подсказку, чтобы предоставить дополнительный контекст об элементе интерфейса. В этом примере создается многострочная подсказка с заголовком, привязанная к 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 появляется подсказка с дополнительной информацией.
• Composable-функция RichTooltip определяет контент подсказки, включая заголовок и основной текст. TooltipDefaults.rememberRichTooltipPositionProvider() предоставляет информацию о расположении расширенных подсказок.

Результат

В этом примере создается расширенная подсказка с заголовком, прикрепленным к значку информации:

Как настроить расширенную подсказку

Этот фрагмент кода показывает расширенную подсказку с заголовком, настраиваемыми действиями и настраиваемой кареткой (стрелкой), которая отображается поверх кнопки со значком камеры:

@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) подсказка отображается примерно одну секунду. Чтобы закрыть подсказку, нажмите на любую другую область экрана или на кнопку закрытия.
• Когда выполняется действие закрытия, система запускает сопрограмму для вызова tooltipState.dismiss. Это гарантирует, что выполнение действия не будет заблокировано, пока показывается подсказка.
• onClick = coroutineScope.launch { tooltipState.show() } } запускает сопрограмму, чтобы вручную показать подсказку с помощью tooltipState.show.
• Параметр action позволяет добавлять в подсказку интерактивные элементы, например кнопку.
• Параметр caretSize изменяет размер стрелки подсказки.

Результат

В результате получится следующее:

Дополнительные ресурсы

• Material Design: подсказки