Подсказка

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

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

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

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

• positionProvider : размещает подсказку относительно содержимого якоря. Обычно вы используете поставщика позиции по умолчанию из TooltipDefaults , или вы можете предоставить свой собственный, если вам нужна пользовательская логика позиционирования.
• tooltip : Компонуемый элемент, содержащий содержимое подсказки. Обычно используются компонуемые элементы PlainTooltip или RichTooltip .
  • Используйте PlainTooltip для описания элементов или действий кнопок-значков.
  • Используйте RichTooltip , чтобы предоставить больше подробностей, например, описать ценность функции. Rich-подсказки могут включать необязательный заголовок, ссылку и кнопки.
• 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 показывает подсказку с текстом «Добавить в избранное». В зависимости от устройства пользователи могут вызывать подсказку следующими способами:
  • Наведение курсора на иконку
  • Длительное нажатие на иконку на мобильном устройстве

Результат

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

Отображение подробной подсказки

Используйте расширенную подсказку для предоставления дополнительного контекста об элементе пользовательского интерфейса. Этот пример создает многострочную расширенную подсказку с заголовком, который привязан к 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 composable определяет содержимое подсказки, включая заголовок и основной текст. 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)
                        }
                    }
                },
                caretSize = DpSize(32.dp, 16.dp)
            ) {
                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: Подсказки