Создание кастомного тултипа Jetpack Compose

Привет, Хабр! Меня зовут Альберт Ханнанов, я Android-разработчик в команде интеграции рассрочки в приложении Wildberries.

В этой статье мы напишем простенькую реализацию тултипов на Jetpack Compose своими руками.

В мире мобильной разработки удобство и интуитивность интерфейса играют ключевую роль. Одним из способов улучшения пользовательского опыта является предоставление дополнительной информации в нужный момент, и для этого идеально подходят тултипы.

В этой статье мы разберём, как создать гибкую и удобную систему тултипов в Jetpack Compose, используя модифайры и специальный оборачивающий блок. Мы шаг за шагом рассмотрим создание необходимых компонентов, их взаимодействие и методы управления тултипом.

Что это вообще такое?

Тултип — это всплывающая подсказка, которая появляется поверх другого UI под/над конкретным элементом. Помогает улучшить UX.

Что мы хотим добиться?

Наш тултип должен уметь:

1. Показываться под якорным элементом в виде облачка

2. Скрываться согласно нашей кастомной логике

3. Добавляться в существующие экраны с минимальными затратами

4. Не блокировать взаимодействие с остальным 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 — элемент, над которым мы хотим показать тултип. Все бы ничего, данный подход не вызывает неудобств по добавлению тултипа на экран, но сильно ограничивает нас в использовании:

1. Когда показывается тултип, мы не можем взаимодействовать с экраном. Как только мы коснемся какой-то другой области, то тултип скроется, и только вторым касанием мы сможем взаимодействовать с экраном. Это блокирует нам скролл и любое другое взаимодействие с чем бы то ни было, кроме тултипа.

2. Под капотом тултип отрисовывается с помощью Popup. А этот элемент всегда отображается выше всех остальных элементов на экране. Что делает невозможным то, что, например, тултип будет скрываться под TopBar или под BottomBar.

Каких-то сторонних решений я нашел раз… и… всё. Последний раз эта либа обновлялась 4(!) года назад. К тому же, зачем искать что-то стороннее, если хочется разобраться самому и сделать свой велосипед?

Дисклеймер

В статье будет очень много кода, и в целях избежания еще большего количества кода, мы сделаем решение для показа только одного тултипа в рамках экрана. Это решение не будет работать на ленивых списках, также модифайр напишем через composed, а не Modifier.Node.

Если вам зайдет, то сделаю вторую часть, где вместе поддержим то, что не добрали в рамках этой статьи. Также объяснение каждой важной строчки кода написано комментарием сверху этой строки для большей очевидности.

Важное замечание: реализация, представленная в этой статье, не является единственно правильной. Это просто один из возможных вариантов, который первый пришел мне на ум я посчитал оптимальным для своих задач.

ХардКод

Итак, еще раз и более детально, что должен уметь делать наш тултип:

1. Показываться под якорным элементом

2. Быть изначально видимым

3. Исчезать по нажатию на него и по нажатию на какую-нибудь кнопку (считаем это нашей кастомной логикой)

4. Появляться по нажатию на какую-нибудь кнопку

5. Без сложностей добавляться в существующие экраны

6. Не блокировать взаимодействие с остальным UI

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

Давайте договоримся, что оборачивающий блок далее называем блок-обертка, а элемент, под которым мы хотим показать тултип — якорный элемент.

Всего нам понадобится создать 4 файла:

1. Tooltip.kt — здесь будет лежать Composable верстка тултипа.

2. TooltipWrapper.kt — блок-обертка.

3. TooltipModifier.kt — модифайр для добавления тултипа.

4. 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()    } }

Каждый из этих методов будет вызываться в момент изменении одного из лейаутов:

1. Блока-обертки TooltipWrapper (changeTooltipWrapperLayoutCoordinates)

2. Якорного элемента (changeAnchorLayoutCoordinates)

3. Самого тултипа (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 случая:

1. Блок-обертка — корневой элемент на экране

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 — начиная со структуры данных и заканчивая реализацией методов управления позиционированием и отображением. 

Теперь, добавив всего один модифайр к любому элементу, можно быстро предоставить пользователям полезные подсказки. Надеюсь, этот разбор поможет вам в создании более удобного и функционального интерфейса! Также буду рад обратной связи от вас.