Подсказка

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

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

Поверхность API

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

• positionProvider – размещает подсказку относительно основного контента. Обычно используется поставщик позиций по умолчанию из TooltipDefaults, но при необходимости можно указать собственного поставщика, если вам нужна специальная логика позиционирования.
• tooltip: 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: всплывающие подсказки