Часть 1. TMA на KMP. Пишем кликер на Kotlin/JS20.07.2024 00:30

7ecf672eaaa094d93702b8c4a3a1b9cc.png

В этой статье рассмотрим старт проекта как обычное веб-приложение с минимальным функционалом. Остальные функции будут завязаны на Telegram API и веб-приложение сможет запускаться из Telegram.

Навигация по циклу статей

Часть 1. Пишем веб-приложение кликер на Kotlin — текущая статья

Раскрытые темы в цикле

  • Web приложение на Kotlin — часть 1

  • Интеграция приложения с Telegram Mini Apps — часть 2

  • Работа с элементами интерфейса TMA приложения. Тема,  MainButton,  BackButton — часть 2

  • Поделиться ссылкой на приложение через Telegram. Передача данных через ссылку — часть 2

  • Аутентификации через TMA приложение — часть 2 и 2.5

  • Telegram Payments API– часть 3

Техническое задание. Кратко

Разработать Telegram Mini Apps приложение-кликер с основными механиками:

  • Тапать на коин и увеличивать счётчик

  • Сохранять количество тапов для каждого пользователя

  • Приглашать друзей через ссылку из приложения

  • Просматривать список друзей.

  • Оплата премиум статуса через Telegram

  • В будущем перенести на Android/IOS

Зачем нужен Kotlin в Web. Ещё один .js фреймворк?

Kotlin Multiplaform анонсирован ещё в 2017 с поддержкой JVM, Native и JS таргетов. И именно JS тартет наиболее недооценён как самой JetBrains, так и компаниями, применяющими в разработке язык Kotlin.

Только в середине 2023 года JetBrains заявила о смене аббревиатуры с KMM (Kotlin Multiplatform Mobile) на KMP (Kotlin Multiplatform), что говорит о перспективах развития всех тартетов.

Зачем бизнесу нужен Kotlin Multiplatform, тем более в веб-разработке? В мобильные приложения уже давно интегрируют общий код между платформами, однако JS таргет, хоть и представлен давно, не все разработчики видят в его использовании смысл. Однако причина писать веб-приложения на Kotlin такая же как и для мобильных платформ — это шаринг кода между платформами. Уже имея приложение на KMP под две платформы — Android и iOS — можно третьей добавить браузер и разработать веб приложение, не переписывая бизнес логику, хотя конечно же доступа к системе у веб-приложений меньше, из-за чего придётся уменьшить количество поддерживаемых фичей.

Kotlin/JS тартет способен компилироваться в JavaScript код, вызывать методы из JS модулей или самим быть вызываем, что значительно расширяет возможности приложений на Kotlin/JS и даёт возможность писать на Kotlin с кодовой базовой уже существующих JS приложений.

Главная трудность — это написание UI. Сейчас есть выбор между четырьмя реализациями

  • Написать UI на HTML и CSS. И работать с DOM деревом как в старые добрые — получать элемент по id и изменять его

  • Использовать React in Kotlin (  kotlin-wrappers/kotlin-rea…  @GitHub) из модуля kotlin-wrappers. Однако такой подход выглядит неестественным для языка Kotlin. Повсеместное использование external для props, неоднородные стили с CSS in Kotlin

  • Использовать Compose for Web (пока статус Alpha) из Compose Multiplatform. Можно компилировать под WASM (который использует wasm gc, поддержки которого пока нет в Safari/WebKit) и JS, где уже встречаются баги взаимодействия со скроллом и нестабильной работой.

  • Наиболее перспективный вариант Compose HTML library.

Выбор на чем писать UI

Подробнее о Compose HTML library. Код компилируется в JS и использует compose runtime и html теги с css in kotlin стилями, по идеологии схож с JSX.

Доступен базовый функционал compose runtime: Composable аннотация, Side-effects, states и д.р. из пакета compose-runtime.

Не доступны другие пакеты, как compose-ui, compose-material, из-за чего нельзя использовать привычные Column,  Row,  Box,  Scaffold,  Button (composable ui функции),  MaterialTheme и д.р.

Для написания UI используются функции Div,  Button,  Span,  TextArea и д.р. браузерные теги, только вызываемые как функции с заглавной буквы. Стили применяются через СSS in Kotlin через отдельный StyleSheet или блок style в attrs любого тега.

Старт проекта

Для упрощения старта можно использовать шаблон, однако ещё разберём особенности настройки.

Файловая структура — типичная для проекта для kotlin multiplatform.

5eb445abd93700f9ea1281ffb34da766.png

В build.gradle.kts composeApp модуля подключим плагины (также нужно объявить в корневом модуле build.gradle.kts)

plugins {
    id("org.jetbrains.kotlin.multiplatform")
    id("org.jetbrains.kotlin.plugin.compose") // компилятор, необходимый для сборки модуля с compose на Kotlin 2.X
    id("org.jetbrains.compose") // работа с compose multiplatform
}

Зададим JS таргет и зависимости в блоке kotlin{} модуля composeApp

kotlin {
    js(IR) {
        browser()
        binaries.executable()
    }
    sourceSets {
        jsMain.dependencies {
            implementation(compose.runtime)
            implementation(compose.html.core)
        }
    }
}

Создаём директории для наших исходников commonMain и jsMain

36331e757dda5235dc58be28f35308fc.png

В resources jsMain нужно создать index.html




    
    
    EllowBurgerBot

Далее определим точку входа в приложение. Создаём main.kt с функцией main, которая и будет точкой входа в наше приложение

fun main() {
    renderComposable(rootElementId = "app") {
       /* Весь интерфейс здесь */
    }
}

Напишем простой экран, который будет сообщать, что это веб-приложение, написанное на Kotlin

Важно: UI находится в jsMain, поскольку это нативный для браузера способа отображения

@Composable
fun App() {
    Div {
        H2 {
            Text("This is my Kotlin web application")
        }
    }
}

Вызовем функцию с нашим приложением в блоке renderComposable

renderComposable(rootElementId = "app") {
    App()
}

Первоначальная настройка закончена, теперь можно запустить приложение и проверить, что всё работает как надо

./gradlew composeApp:jsRun

Но страница выглядит просто как текст, Compose HTML library может инжектить в браузер свои стили, которые пишутся на Kotlin. Добавим таблицу стилей в наше приложение

object AppStyles: StyleSheet() {
    val MainContainer by style {
        display(DisplayStyle.Flex)
        width(100.vw)
        height(100.vh)
        textAlign("center")
        alignItems(AlignItems.Center)
        justifyContent(JustifyContent.Center)
    }
}

Важно, что каждый StyleSheet должен быть явно определён, именно в этот момент он инжектится в браузерную страницу. Применяем таблицу стилей.

renderComposable(rootElementId = "app") {
    Style(AppStyles)
    App()
}

Далее через поля из AppStyles применим стиль к нашему Div.

@Composable
fun App() {
    Div(
        attrs = {
            classes(AppStyles.MainContainer)
        }
    ) {
        H2 {
            Text("This is my Kotlin web application")
        }
    }
}

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

Добавляем ресурсы

Теперь переходим к созданию полноценного веб-приложения. Каждый этап описан не будет, однако основные моменты будут описаны. Некоторые из доступных, хоть и ограниченных, возможностей Compose runtime и Compose HTML library, при работе с KMP

Для этого используем библиотеку moko-resources. Подключается вместе с gradle плагином в build.gradle.kts модуля composeApp

plugins {
    // ...
    id("dev.icerock.mobile.multiplatform-resources")
}
kotlin {
//...
sourceSets {
commonMain.dependencies {
implementation("dev.icerock.moko:resources:0.24.1")
}
//...
}
}
multiplatformResources {
resourcesPackage.set("your.package.name")
resourcesClassName.set("Res")
}

Добавим нашу картинку, по которой будем тапать в commonMain модуль.

8a8c9c391f4c78457842523152f2b9ad.png

И получим url до картинки через сгенерированный класс Res и поле Res.images.click_item.

@Composable
fun App() {
    Div(
        attrs = {
            classes(AppStyles.MainContainer)
        }
    ) {
        Img(
            src = Res.images.click_item.fileUrl,
            attrs = {
                classes(AppStyles.MainImage) // стиль с указанием размера картинки
            }
        )
    }
}

Создаём UI нашего кликера

Поскольку это кликер, обязательно нужно добавить счётчик нажатий на наш «подставить на кого будем кликать».

Создадим состояние, значение которого будем увеличивать по клику на картинку.

@Composable
fun App() {
    var score by remember { mutableStateOf(0) }
    Div(
        attrs = {
            classes(AppStyles.MainContainer)
        }
    ) {
        H2 {
            Text("Score: \$score")
        }
        Img(
            src = Res.images.click_item.fileUrl,
            attrs = {
                classes(AppStyles.ClickImage)
                onClick {
                    score++
                }
            }
        )
    }
}

Итоги

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

Список используемых библиотек на данный момент:

  • Compose Runtime

  • Moko-resources

Дальше — больше, в следующих статьях это просто веб-приложение с одной кнопкой станет полноценным Telegram-кликером со своей реферальной системой.

© Habrahabr.ru