Подсказка

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

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

Рисунок 1. Простая всплывающая подсказка (1) и расширенная всплывающая подсказка (2).

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

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

• positionProvider : Размещает всплывающую подсказку относительно содержимого привязки. Обычно используется поставщик позиционирования по умолчанию из TooltipDefaults , или вы можете предоставить свой собственный, если вам нужна пользовательская логика позиционирования.
• tooltip : Составной объект, содержащий содержимое всплывающей подсказки. Обычно используются либо составные объекты 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 — это лямбда-функция, которая определяет содержимое всплывающей подсказки с помощью составного объекта PlainTooltip .
  • Text(plainTooltipText) отображает текст во всплывающей подсказке.
  • tooltipState управляет состоянием всплывающей подсказки.
• IconButton создает кликабельную кнопку с иконкой.
  • Icon(...) отображает значок сердца внутри кнопки.
  • Когда пользователь взаимодействует с IconButton , TooltipBox отображает всплывающую подсказку с текстом «Добавить в избранное». В зависимости от устройства, пользователи могут активировать всплывающую подсказку следующими способами:
  • Наведите курсор на значок.
  • Длительное нажатие на значок на мобильном устройстве

Результат

В этом примере поверх значка отображается простая всплывающая подсказка:

Рисунок 2. Простая всплывающая подсказка, которая появляется, когда пользователь наводит курсор на значок сердца или удерживает его.

Отобразить всплывающую подсказку с расширенными возможностями.

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

Результат

В результате выполнения этого примера получается следующее:

Рисунок 4. Настраиваемая всплывающая подсказка с возможностью закрытия, привязанная к значку камеры.

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

• Материальный дизайн: всплывающие подсказки