Привет, Хабр! Меня зовут Альберт Ханнанов, я Android-разработчик в команде интеграции рассрочки в приложении Wildberries.
В этой статье мы напишем простенькую реализацию тултипов на Jetpack Compose своими руками.
В мире мобильной разработки удобство и интуитивность интерфейса играют ключевую роль. Одним из способов улучшения пользовательского опыта является предоставление дополнительной информации в нужный момент, и для этого идеально подходят тултипы.
В этой статье мы разберём, как создать гибкую и удобную систему тултипов в Jetpack Compose, используя модифайры и специальный оборачивающий блок. Мы шаг за шагом рассмотрим создание необходимых компонентов, их взаимодействие и методы управления тултипом.
Что это вообще такое?
Тултип — это всплывающая подсказка, которая появляется поверх другого UI под/над конкретным элементом. Помогает улучшить UX.
Что мы хотим добиться?
Наш тултип должен уметь:
Показываться под якорным элементом в виде облачка
Скрываться согласно нашей кастомной логике
Добавляться в существующие экраны с минимальными затратами
Не блокировать взаимодействие с остальным UI
Выглядеть должно следующим образом
Почему существующие решения нам не подойдут?
Material 3 предоставляет нам Composable виджет TooltipBox:
fun TooltipBox(
positionProvider: PopupPositionProvider,
tooltip: @Composable TooltipScope.() -> Unit,
state: TooltipState,
modifier: Modifier = Modifier,
focusable: Boolean = true,
enableUserInput: Boolean = true,
content: @Composable () -> Unit,
)В целом, использование данного виджета заключается в том, что вместо элемента, под которым мы хотим показать тулип, мы внедряем этот TooltipBox, передаем в аргумент tooltip верстку для тултипа, в аргумент content — элемент, над которым мы хотим показать тултип. Все бы ничего, данный подход не вызывает неудобств по добавлению тултипа на экран, но сильно ограничивает нас в использовании:
Когда показывается тултип, мы не можем взаимодействовать с экраном. Как только мы коснемся какой-то другой области, то тултип скроется, и только вторым касанием мы сможем взаимодействовать с экраном. Это блокирует нам скролл и любое другое взаимодействие с чем бы то ни было, кроме тултипа.
Под капотом тултип отрисовывается с помощью Popup. А этот элемент всегда отображается выше всех остальных элементов на экране. Что делает невозможным то, что, например, тултип будет скрываться под TopBar или под BottomBar.
Каких-то сторонних решений я нашел раз… и… всё. Последний раз эта либа обновлялась 4(!) года назад. К тому же, зачем искать что-то стороннее, если хочется разобраться самому и сделать свой велосипед?
Дисклеймер
В статье будет очень много кода, и в целях избежания еще большего количества кода, мы сделаем решение для показа только одного тултипа в рамках экрана. Это решение не будет работать на ленивых списках, также модифайр напишем через composed, а не Modifier.Node.
Если вам зайдет, то сделаю вторую часть, где вместе поддержим то, что не добрали в рамках этой статьи. Также объяснение каждой важной строчки кода написано комментарием сверху этой строки для большей очевидности.
Важное замечание: реализация, представленная в этой статье, не является единственно правильной. Это просто один из возможных вариантов, который первый пришел мне на ум я посчитал оптимальным для своих задач.
ХардКод
Итак, еще раз и более детально, что должен уметь делать наш тултип:
Показываться под якорным элементом
Быть изначально видимым
Исчезать по нажатию на него и по нажатию на какую-нибудь кнопку (считаем это нашей кастомной логикой)
Появляться по нажатию на какую-нибудь кнопку
Без сложностей добавляться в существующие экраны
Не блокировать взаимодействие с остальным UI
Вся задумка заключается в том, что у нас будет блок-обертка, внутри которого мы у любого элемента сможем отрисовывать тултип с помощью простого добавления к нему модифайра.
Давайте договоримся, что оборачивающий блок далее называем блок-обертка, а элемент, под которым мы хотим показать тултип — якорный элемент.
Всего нам понадобится создать 4 файла:
Tooltip.kt— здесь будет лежать Composable верстка тултипа.TooltipWrapper.kt— блок-обертка.TooltipModifier.kt— модифайр для добавления тултипа.TooltipState.kt— сущность, которая будет хранить всю информацию о тултипе и управлять его характеристиками.
Первым делом давайте определимся с TooltipState, а именно — какие поля нам нужны, чтобы это все работало.
@Composable
fun rememberTooltipState(): TooltipState = remember { TooltipState() }
@Stable
class TooltipState internal constructor() {
// параметры блока-обертки
// длина оборачивающего блока. Нужна для того, чтобы определить максимальную ширину тултипа
internal var tooltipWrapperWidth: Int by mutableIntStateOf(0)
// информация о лейауте для оборачивающего блока. Понадобится нам, когда будем считать смещение тултипа
private var tooltipWrapperLayoutCoordinated: LayoutCoordinates? = null
// параметры тултипа
// данные для отображения в тултипе: заголовок, сабтайтл
internal var data: TooltipData? by mutableStateOf(null)
// видим ли тултип в данный момент
internal var isVisible: Boolean by mutableStateOf(false)
// итоговое смещение тултипа
internal var tooltipOffset: IntOffset by mutableStateOf(IntOffset.Zero)
// информация о лейауте тултипа. Понадобится нам, когда будем считать смещение тултипа
private var tooltipLayoutCoordinates: LayoutCoordinates? = null
// смещение пипочки тултипа
private var triangleXOffset: Int = 0
// параметры якорного блока
// информация о лейауте якорного элемента. Понадобится нам, когда будем считать смещение
internal var anchorLayoutCoordinates: LayoutCoordinates? by mutableStateOf(null) тултипа
}
@Stable
data class TooltipData(
val title: String?,
val subtitle: String,
)Теперь перейдем в написанию блока-обертки:
@Composable
fun TooltipWrapper(
modifier: Modifier = Modifier,
content: @Composable BoxScope.(tooltipState: TooltipState) -> Unit,
) {
val tooltipState = rememberTooltipState()
Box(
modifier = modifier
// Скрываем элементы, которые выходят за границы Box
.clipToBounds()
// отправляем информацию о лейауте в стейт
.onGloballyPositioned { tooltipState.changeTooltipWrapperLayoutCoordinates(it) },
) {
content(tooltipState)
Tooltip(state = tooltipState)
}
}
Перейдем к написанию модифайра. В созданном модифайре мы должны уметь отправлять данные для тултипа (заголовок, подпись) и информацию об якорном элементе.
@Stable
private fun Modifier.tooltipInternal(
state: TooltipState,
subtitle: String,
@DrawableRes dismissIconResource: Int? = null,
title: String? = null,
initialVisibility: Boolean = false,
): Modifier = composed {
LaunchedEffect(Unit) {
state.initialize(
data = TooltipData(
title = title,
subtitle = subtitle,
dismissIconResource = dismissIconResource,
),
initialVisibility = initialVisibility,
)
}
this.onGloballyPositioned {
state.changeAnchorLayoutCoordinates(layoutCoordinates = it)
}
}С помощью LaunchedEffect вызываем init единожды и передаем данные в стейт. Также реагируем на изменение позиции якорного элемента c помощью onGloballyPositioned. Важное замечание: так не будет работать с ленивыми списками. В случае с ними LaunchedEffect будет вызываться довольно часто из-за того, что виджет будет открепляться и прикрепляться к верстки в процессе скролла.
Теперь перейдем к верстке самого тултипа:
@Composable
internal fun Tooltip(state: TooltipState) {
val data = state.data
val animatedTriangleVisibility by animateFloatAsState(
targetValue = if (state.isVisible) 1f else 0f,
animationSpec = tween(300)
)
// Если тултип не виден или для него нет данных или якорного элемента, то ничего не рисуем
if (animatedTriangleVisibility == 0f || data == null || state.anchorLayoutCoordinates == null) return
// высчитываем максимальную ширину тултипа. В данном случае будет 70% от ширины блока для тултипов
val maxTooltipWidth = LocalDensity.current.run {
(state.tooltipWrapperWidth * .7f).toDp()
}
Column(
modifier = Modifier
.widthIn(max = maxTooltipWidth)
// смещаем тултип на расчитанное в стейте значение
.offset { state.tooltipOffset }
// передаем информацию о лейауте тултипа
.onGloballyPositioned { state.changeTooltipLayoutCoordinates(it) }
// рисуем пипочку сверху тултипа
.drawBehind {
val path = state.getTrianglePath()
drawPath(
path = path,
alpha = animatedTriangleVisibility,
color = Color(0xFF18181B),
)
}
// управляем прозрачностью тултипа для плавных действий над ним
.graphicsLayer { alpha = animatedTriangleVisibility }
// скрываем тултип по нажатию на него
.clickable(onClick = state::hide)
.clip(RoundedCornerShape(16.dp))
.background(Color(0xFF18181B))
.padding(vertical = 12.dp, horizontal = 16.dp),
) {
Row {
if (data.title != null) {
Text(
text = data.title,
fontSize = 20.sp,
fontWeight = FontWeight.Bold,
color = MaterialTheme.colorScheme.onPrimary
)
}
if (data.dismissIconResource != null) {
Icon(
modifier = Modifier.clickable(onClick = state::hide),
painter = painterResource(data.dismissIconResource),
contentDescription = "",
tint = Color.White,
)
}
}
Text(
text = data.subtitle,
color = MaterialTheme.colorScheme.onPrimary
)
}
}Самое интересное только впереди. Теперь нам надо научиться всем этим управлять. Перейдем к реализации методов стейта. Первым делом напишем публичные методы стейта.
@Stable
class TooltipState internal constructor() {
//...
fun hide() {
isVisible = false
}
fun show() {
isVisible = true
}
}Данные методы просто меняют поле isVisible, на который подписывается UI и управляет видимостью тултипа.
Не забудем про метод инициализации тултипа.
@Stable
class TooltipState internal constructor() {
//...
internal fun initialize(
data: TooltipData,
initialVisibility: Boolean,
) {
this.data = data
if (initialVisibility) {
show()
}
}
}Данный метод принимает на вход класс, который содержит данные для тултипа, и изначальную его видимость.
Теперь напишем методы, которые будут вызываться при изменении параметром всех зависимых лейаутов.
@Stable
class TooltipState internal constructor() {
//...
internal fun changeTooltipWrapperLayoutCoordinates(layoutCoordinates: LayoutCoordinates) {
tooltipWrapperLayoutCoordinated = layoutCoordinates
tooltipWrapperWidth = layoutCoordinates.size.width
syncTooltipOffset()
}
internal fun changeAnchorLayoutCoordinates(layoutCoordinates: LayoutCoordinates) {
anchorLayoutCoordinates = layoutCoordinates
syncTooltipOffset()
}
internal fun changeTooltipLayoutCoordinates(layoutCoordinates: LayoutCoordinates) {
tooltipLayoutCoordinates = layoutCoordinates
syncTooltipOffset()
}
}Каждый из этих методов будет вызываться в момент изменении одного из лейаутов:
Блока-обертки TooltipWrapper (
changeTooltipWrapperLayoutCoordinates)Якорного элемента (
changeAnchorLayoutCoordinates)Самого тултипа (
changeTooltipLayoutCoordinates)
При изменении любого из них будет происходить пересчет позиции тултипа — метод syncTooltipOffset(). Перейдем к его реализации:
@Stable
class TooltipState internal constructor() {
//...
private fun syncTooltipOffset() {
val tooltipWrapperLC = tooltipWrapperLayoutCoordinated ?: return
// смещение тултипа посередине якорного
val anchorWidgetDisplacement = anchorLayoutCoordinates?.let { anchorLC ->
// позиция опорного элемента в координатах блока TooltipWrapper. Объяснение ниже
val parent = tooltipWrapperLC.localPositionOf(anchorLC, Offset.Zero)
val size = it.size
val x = parent.x + size.width / 2f
val y = parent.y + size.height
IntOffset(
x = x.toInt(),
y = y.toInt() + TRIANGLE_HEIGHT.toInt(),
)
} ?: IntOffset.Zero
// собственное смещение тултипа на половину ширины тултипа
val properDisplacement = tooltipLayoutCoordinates?.let {
IntOffset(it.size.center.x, 0)
} ?: IntOffset.Zero
val tooltipWidth = tooltipLayoutCoordinates?.size?.width ?: 0
// левая верхняя точка тултипа
val newTopLeftOffset = anchorWidgetDisplacement - properDisplacement
// правая верхняя точка тултипа
val newTopRightOffset = newTopLeftOffset + IntOffset(tooltipSize.width, 0)
// Нужно учесть кейсы, если наш тултип вышел за пределы блока и смещать тултип таким образом, чтобы он помещался
val resultDependWindowBoundaries = when {
// кейс, когда тултип выходит за левую границу
newTopLeftOffset.x < 0 -> {
triangleXOffset = newTopLeftOffset.x
IntOffset(0, newTopLeftOffset.y)
}
// Кейс, когда тултип выходит за правую границу
newTopRightOffset.x > tooltipWrapperWidth -> {
triangleXOffset = newTopRightOffset.x - tooltipWrapperWidth
IntOffset(tooltipWrapperWidth - tooltipSize.width, newTopRightOffset.y)
}
// Кейс, когда тултип не выходит за границы
else -> {
triangleXOffset = 0
newTopLeftOffset
}
}
tooltipOffset = resultDependWindowBoundaries
}
}Давайте рассмотрим подробнее строчку номер 11 tooltipWrapperLC.localPositionOf(anchorLC, Offset.Zero)
Всего у нас может быть 2 случая:
Блок-обертка — корневой элемент на экране
Блок-обертка — не корневой элемент на экране
В первом случае мы можем говорить о том, что обертка занимает полностью весь экран, и мы можем считать координаты любого элемента внутри, используя систему отсчета, которая опирается на сам экран.
Во втором случае мы не можем таким образом рассчитывать позицию элементов внутри блока-обертки, потому что, например, на одном уровне иерархии с оберткой может быть топбар или же боттомбар. В этом случае мы должны рассчитывать позицию элемента опираясь на систему отчета, которая относится к самому блоку обертки. Здесь мы так и делаем. У нас есть anchorLC— информация о лейауте якорного элемента, tooltipWrapperLC — информация о лейауте блока обертки. Мы точно знаем, что якорный элемент находится внутри нашего блока-обертки, поэтому мы можем перейти с системы отсчета от якорного элемента к системе отсчета блока-обертки и вычислить позицию якорного элемента относительно блока обертки. С помощью метода localPositionOf мы так и делаем.
Теперь напишем метод, который отвечает за получение координат пипочки для тултипа:
@Stable
class TooltipState internal constructor() {
//...
internal fun getTrianglePath(): Path = Path().apply {
val triangleHeight = TRIANGLE_HEIGHT
val triangleWidth = TRIANGLE_WIDTH
val tooltipLayoutCoordinates = tooltipLayoutCoordinates ?: return@apply
val widgetSize = tooltipLayoutCoordinates.size
val offsetToCenterX = widgetSize.center.x.toFloat() + triangleXOffset
val offsetToCenterY = 0f
moveTo(offsetToCenterX, offsetToCenterY - triangleHeight)
lineTo(offsetToCenterX - triangleWidth / 2f, offsetToCenterY)
lineTo(offsetToCenterX + triangleWidth / 2f, offsetToCenterY)
close()
}
private companion object {
const val TRIANGLE_WIDTH = 40f
const val TRIANGLE_HEIGHT = 40f
}
}Поздравляю всех тех, кто дотерпел до этого момента и смог осознать все, что здесь происходит. Теперь у нас все должно работать.
Пример для проверки результата
@Composable
fun TooltipExampleScreen() {
Column {
Box(
modifier = Modifier
.fillMaxWidth()
.height(97.dp)
.shadow(10.dp)
.background(Color.White),
contentAlignment = Alignment.Center,
) {
Text("Top Bar")
}
TooltipWrapper(
modifier = Modifier.fillMaxWidth(),
) { tooltipState: TooltipState ->
Column(
modifier = Modifier
.fillMaxWidth()
.verticalScroll(rememberScrollState())
) {
Button(onClick = tooltipState::show) {
Text("Show tooltips")
}
(0..20).forEach {
ScreenItem(
itemNumber = it,
tooltipState = tooltipState,
)
}
}
}
}
}
@Composable
private fun ScreenItem(
tooltipState: TooltipState,
itemNumber: Int,
) {
Column(
modifier = Modifier
.fillMaxWidth()
.height(120.dp),
) {
Row(
modifier = Modifier.weight(1f),
verticalAlignment = Alignment.CenterVertically,
) {
Spacer(Modifier.weight(1f))
if (itemNumber == 1) {
Text(
modifier = Modifier.tooltip(
state = tooltipState,
title = "Some title",
subtitle = "Some tooltip content",
initialVisibility = true,
),
text = "item with tooltip $itemNumber"
)
} else {
Text(text = "item $itemNumber")
}
Spacer(Modifier.weight(1f))
}
Spacer(modifier = Modifier.fillMaxWidth().height(1.dp).background(Color.Black))
}
}Теперь о моментах, которых мы не коснулись
Во-первых, что касается возможности добавления нескольких тултипов на экран. Для решения этой задачи требуется просто текущий стейт размножить. В TooltipsState создать поле типа SnapshotStateMap<String, TooltipState>. Внутри этой структуры будут лежать все тултипы, которые есть на экране. Ключом можно сделать, например UUID. Методы TooltipsState также нужно будет адаптировать к работе с этой мапой.
Во-вторых, что более сложно, — ленивые списки. Как известно, айтемы ленивых списков переиспользуются, чтобы не вываливать сразу все данные списка на экран. В момент, когда какой-то элемент списка уходит за область видимости, он открепляется от композиции и далее может прикрепиться для нового элемента, который только собирается появиться на экране. Нам это все нужно учитывать — не рисовать тултип для айтема, который открепился от верстки и корректно различать тултипы между собой, например, по ключу. Но это уже тема для будущей статьи.
Заключение
Поздравляю! Мы создали свой велосипед разобрали процесс создания кастомного тултипа в Jetpack Compose — начиная со структуры данных и заканчивая реализацией методов управления позиционированием и отображением.
Теперь, добавив всего один модифайр к любому элементу, можно быстро предоставить пользователям полезные подсказки. Надеюсь, этот разбор поможет вам в создании более удобного и функционального интерфейса! Также буду рад обратной связи от вас.