DivKit теперь и для Flutter. Рассказываем об особенностях BDUI-фреймворка Яндекса

Полтора года назад мы выпустили в опенсорс DivKit — фреймворк для отрисовки интерфейсов из ответа сервера. На тот момент он уже прошёл проверку временем внутри компании и применялся в приложении Яндекс, Алисе, Маркете, Едадиле и других сервисах. С тех пор инструмент прошёл длинный путь. И сегодня у нас по-настоящему важная новость: мы выпускаем в свободный доступ долгожданный клиент для Flutter. 

В статье расскажем об особенностях вёрстки в DivKit и нашей реализации UI. Вы узнаете, какие фичи и компоненты Flutter поддерживаются во фреймворке на текущий момент. Покажем, как начать пользоваться клиентом уже сейчас.

Что и как мы можем рисовать и делать

Рассмотрим фичи и компоненты детально. На всех схемах оранжевым будет обозначен presentation, зелёным — domain, а синим — data. Основные протоколы экспортированы и находятся в divkit/lib/src/core/protocol/…

Рендеринг

Рендеринг в DivKit имеет следующие особенности:

• Графический элемент разделён на две части: базовую (общую для всех компонентов) и специфическую.

• Графический компонент инициализирует модель на основе данных DTO и подписывается на её стрим обновления. Отрисовывает по полученным данным.

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

• Рисуем все компоненты асинхронно, по мере доступности данных. Реактивно перерисовываем компоненты только при изменении свойств.

Особенности вёрстки в DivKit и нашей реализации UI

Протокол DivKit позволяет клиентам собирать блоки UI любой сложности от простых текстовок до полноценных экранов. Вёрстка основана на вложенности элементов с помощью элемента container, реализацией которого во Flutter являются flex, wrap и stack в зависимости от свойств расположения потомков в контейнере. 

Свойства компонентов поддерживают три вида размеров — fixed, match-parent, wrap-content. Для Flutter эти категории оказались не самыми подходящими, однако для задания размеров компонентов  мы смогли обойтись стандартными виджетами: SizedBox, Flexible и Expanded. Для правильного позиционирования и изменяемых размеров (match-parent, wrap-content) стали оборачивать их в row, column и stack. 

Расширяя функциональность библиотеки и поддерживая всё новые и новые свойства, мы столкнулись с плохой совместимостью API коробочных виджетов и тем, что есть у DivKit на нативных платформах. Например, BorderSide во Flutter считается внутри размера компонента, а в нативе — снаружи. Далеко не все подобные моменты задокументированы и нашли своё решение, поэтому мы будем очень благодарны сторонним разработчикам, которые будут участвовать в жизни библиотеки и вносить свой вклад в исправление таких багов.

Стандартные компоненты

В самом DivKit есть достаточно обширный набор стандартных компонентов, позволяющий верстать практически всё. Сейчас доступны только самые базовые и основные:

Они не на 100% реализуют спецификацию DivKit. Чтобы узнать, что именно поддерживается, можно посмотреть в справочнике элементов в доке.

Работа с кастомными компонентами 

Если вам не хватает стандартных компонентов, можно добавить свои. Для этого в DivKit есть механизм кастомов.

Для обработки кастомных компонентов с помощью Flutter-клиента можно реализовать интерфейс DivCustomHandler:

/// Handles specific div-custom. Creates Flutter Widget from custom model abstract class DivCustomHandler { /// Returns TRUE if custom widget can be handled. /// [type] — DivCustom.customType, custom alias to handle. Bool isCustomTypeSupported(String type);  /// Returns Widget to use for div-custom. /// [div] — div-custom model. Widget createCustom(DivCustom div);  factory DivCustomHandler.none() => _DefaultDivCustomHandler(); }  class PlaygroundAppCustomHandler implements DivCustomHandler {  late final factories = {    'new_custom_card_1': _createCustomCard,    'new_custom_card_2': _createCustomCard,    'new_custom_container_1': _createCustomContainer,  };   @override  Widget createCustom(DivCustom div) {    final child = factories[div.customType]?.call(div) ??        (throw Exception(            'Unsupported DivCustom with custom_type: ${div.customType}'));     return child;  }   @override  bool isCustomTypeSupported(String type) => factories.containsKey(type);   Widget _createCustomCard(DivCustom div) {    const gradientColors = [      -0xFF0000,      -0xFF7F00,      -0xF00F00,      -0x00FF00,      -0x0000FF,      -0x2E2B5F,      -0x8B00FF,    ];     return Material(      child: Container(        width: double.infinity,        decoration: BoxDecoration(          gradient: LinearGradient(            begin: Alignment.bottomLeft,            end: Alignment.topRight,            colors: gradientColors.map((item) => Color(item)).toList(),          ),        ),        alignment: Alignment.centerLeft,        padding: const EdgeInsets.only(          left: 12,          top: 12,          right: 12,          bottom: 12,        ),        child: _ChronographWidget(),      ),    );  }   Widget _createCustomContainer(DivCustom div) {    return Column(      children: _createItems(div.items ?? []),    );  }   List<Widget> _createItems(List<Div> items) {    return items.map((item) => DivWidget(item)).toList();  } }  class _ChronographWidget extends StatefulWidget {  @override  State<StatefulWidget> createState() => _ChronographState(); }  class _ChronographState extends State<_ChronographWidget> {  late final timer = Timer.periodic(    const Duration(      seconds: 1,    ),    (timer) {      if (mounted) {        setState(() {});      } else {        timer.cancel();      }    },  );   @override  Widget build(BuildContext context) => Text(        '${(timer.tick ~/ 60).toString().padLeft(2, '0')}:${(timer.tick % 60).toString().padLeft(2, '0')}',        style: const TextStyle(          fontSize: 20,          color: Colors.black,          backgroundColor: Colors.transparent,        ),      ); }

Собственную реализацию CustomHandler к DivKitView можно подключить так:

DivKitView(      data: data,      customHandler: MyCustomHandler(),    )

isCustomTypeSupported и createCustom будут вызываться последовательно во время отрисовки UI, а если компонент оказывается неподдерживаемым — библиотека по умолчанию ничего не нарисует, но можно включить placeholder с помощью флага showUnsupportedDivs у DivKitView.

Модели как прослойка между DTO и Flutter 

Сейчас JSON парсится в DTO-дерево сущностей, свойства которого — вычисляемые выражения или константы. Выражения решаются асинхронно, и сами параметры представляют сырые данные, которые нужно преобразовать в сущности стандартной вёрстки фреймворка Flutter. Этой задачей занимается модель виджета. 

Разберём на примере div-text:

class DivTextModel with EquatableMixin {     final String text;     final int? maxLines;      const DivTextModel(this.text, this.maxLines);      static Stream<DivTextModel> from(BuildContext context, DivText data) {         final variables = DivKitProvider.watch<DivContext>(context)!.variableManager;         return variables.watch<DivTextModel>((context) async {             return DivTextModel(                 await data.text.resolveValue(context: context),                 await data.maxLines?.resolveValue(context: context),             );         }).distinct(); // The widget is redrawn when the model changes.     }      @override      List<Object?> get props => [text, maxLines]; }

Главная задача модели — хранить свойства, которые будут использоваться в виджете, и быть сравнимой, для правильного контроля перерисовок. Также нужно уметь собирать её из DTO и зависеть от изменений переменных. Текущая реализация — это временное решение, выполняющее свою задачу.

Поддерживаемые фичи и примеры их использования

Мы считаем, что все фичи нужно разбирать на практике. Увидев возможности клиента, гораздо проще оценить потенциальные выгоды для своих проектов.

Счётчик

Начнём с примера реализации счётчика с двумя кнопками. Для него нам понадобятся шаблоны, переменные, вычисляемые выражения. 

Вот есть задача сверстать такой экран, с чего можно начать?

Темплейтинг и шаблоны

Шаблоны нужны для удобства и сокращения объёма пересылаемых по сети данных. В идеале они версионируются и хранятся в закэшированном виде в клиенте, используются и обновляются по мере необходимости.

Для использования нужно определить список шаблонов в блоке templates или передать его отдельно, если отходить от схемы.

Можно делать именованные наборы свойств, наследоваться и делать композици. Стоит заметить, что родительские свойства шаблона переопределяются значениями из дочерних. В вёрстке раздела card же определяются максимально приоритетные свойства.

В примере, который мы разбираем, всего две кнопки, но очень похожих компонентов может быть и больше. Тогда описание вёрстки раздувается на ровном месте и всё будет долго грузиться. Чтобы этого избежать, можно вынести общие свойства в шаблон, например в нашем случае напрашивается circle_button:

Как видим, шаблон существенно сократил объём самой вёрстки. Но можно сделать ещё лучше — переименовать названия полей, используя синтаксис:

«$real_prop_name»: «new_prop_name»

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

Кнопка у нас всегда имеет полную заливку цветом, так что можно определить color в background новым именем bg_color (значение просто подставляется).

Ну с этим разобрались. Более детально можно почитать в разделе Шаблоны. А мы пойдём дальше.

Переменные

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

Чтобы использовать переменные, нужно объявить их в отдельном блоке variables в «card«-секции JSON-файла вёрстки:

{    "card": {         "log_id": "main_screen",         "variables": [             {                 "type": "integer",                 "name": "count",                 "value": 0             },             {                 "type": "number",                 "name": "alpha",                 "value": 0.5             }         ]    } }

Вернёмся к примеру, объявим непосредственно count = 0, а как дополнительное свойство пусть будет alpha = 0.5.

Переменные также можно создать программно. Это позволяет внедрять в DivKitView значения из хостовой среды. Делается всё согласно протоколу DivVariableStorage:

abstract class DivVariableStorage {  /// The parent storage. There is full access to it.  DivVariableStorage? get inheritedStorage;   /// A list of variable names under the control of the current storage.  Set<String> get names;   /// Update an existing variable.  /// If successful, it will return true  bool update(DivVariable variable);   /// Update if it exists and will create otherwise.  void put(DivVariable variable);   /// The current snapshot of the raw representation of the storage.  Map<String, DivVariable> get value;   /// The raw data stream of storage changes.  Stream<Map<String, DivVariable>> get stream;   /// Safely destroy storage.  Future<void> dispose(); }

В составе библиотеки есть default-реализация. Она сеансовая, так как не сохраняет значения на устройство. Начальные значения можно передать двумя способами: списком и методом put. Хранилища можно вложить друг в друга, изменение родительского хранилища обновляет дочерние. При этом имена уже существующих переменных заменяются новыми (разрывается связность). Круто, что изменения переменных в таких хранилищах влияют на DivKitView.

Ниже пример наследования хранилищ, идёт разделение данных на уровни. View-хранилище можно передать уже в DivKitView и использовать все объявленные переменные:

final system = DefaultDivVariableStorage(  variables: [    DivVariable(name: 'isDark', value: false),  ], );  final page = DefaultDivVariableStorage(  inheritedStorage: system,  variables: [    DivVariable(name: 'token', value: "..."),  ], );  final view = DefaultDivVariableStorage(  inheritedStorage: page,  variables: [    DivVariable(name: 'id', value: '...'),  ], );

Выражения

Выражения добавляют интерактивности и позволяют творить чудеса, особенно если учитывать, что большинство полей в схеме вёрстки их поддерживают. Они объявляются с помощью включений вида «@{…}». Далее, чтобы вычислить значение, они должны пройти через «Вычислитель выражений». Это сейчас достаточно дорого, поэтому мы сразу разделяем параметры на выражения и константы на этапе построения DTO-моделей. 

В DivKit поддерживается вся базовая математика, также есть встроенные функции.

Немного стоит сказать про использование переменных в выражениях. Всё просто, обращение идёт по имени:

•  «@{isDark ? 1 : 0}» → 0 

•  «url?token=@{token}» → url?token=…

• «set_state?state_id=@{id}» → set_state?state_id=…

В нашем случае выведем на экран значение счётчика (count) с помощью текста и будем менять его прозрачность (alpha):

{   "type": "text",   "font_size": 100,   "alpha": "@{min(1.0, max(alpha, 0.0))}",   "width": {"type": "wrap_content", "constrained": true},   "text_alignment_horizontal": "center",   "alignment_horizontal": "center",   "alignment_vertical": "center",   "text": "@{count}" }

Более детально можно посмотреть в документации, раздел Вычисляемые выражения.

Обработчик экшенов

Обработчик экшенов позволяет выполнять прописанные в вёрстке экшены (ивенты с данными). Экшены есть двух видов: «диплинк» и типизированный. Первые хранят в себе всю нужную информацию для обработки, например из реализованных set_state,  set_variable, timer. У вторых есть дополнительный объект с информацией, например из реализованных — DivActionFocusElement и DivActionSetVariable.

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

/// Handles any div-action abstract class DivActionHandler {  const DivActionHandler();   /// Returns TRUE if action can be handled.  /// [action] — Action to handle. Maybe typed or contain a non-null url  /// [context] — DivContext to use variables and access stateManager  bool canHandle(DivContext context, DivAction action);   /// Returns TRUE if action was handled.  /// [action] — Action to handle. Maybe typed or contain a non-null url  /// [context] — DivContext to use variables and access stateManager  FutureOr<bool> handleAction(DivContext context, DivAction action); }

Переопределяется на уровне DivKitView: 

DivKitView(        data: DefaultDivKitData.fromJson(data),        actionHandler: CustomDivActionHandler(navigator: navigatorKey), )

Более детально можно посмотреть в доке — раздел Действия с элементами.

Для обновления значения переменных из вёрстки можно воспользоваться стандартным диплинком. В нём указываются имя и новое значение, которое должно быть того же типа, что и переменная. Можно указать и выражение:

"actions": [     {         "log_id": "action_id",         "url": "div-action://set_variable?name=count&value=@{count - 1}"     },     {         "log_id": "action_id",         "url": "div-action://set_variable?name=alpha&value=@{alpha - 0.1}"     } ]

Более детально об этом написано в документации в разделе Изменение значений переменных.

Карточка

Карточки умеют переключаться при тапе на кнопку. Тут мы познакомимся со стейтами и триггерами. 

Стейты

Стейты отвечают за отрисовку соответствующего div (из предопределённого в вёрстке набора) по stateId. Предположим, у нас есть главный стейт DivKitView, который индексируется числом, и стейты, созданные с помощью компонента div-state.

На практике они позволяют программно менять контент в определённом месте дерева вёрстки.

Для примера нам потребуется два стейта, группу назовём sample, и будет только два варианта divkit или flutter. Таким нехитрым образом мы добавили интерактивности на уровне компонентов. 

Для переключения стейта используется стандартный action: 

div-action://set_state?state_id=0/sample/flutter

На изменения состояния подписываются только card и div-state. По мере построения дерева компонентов в менеджер регистрируются стейты и выбранные значения сохраняются в хранилище.

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

Более детально можно посмотреть в доке — раздел Наборы состояний.

Триггеры переменных

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

"card": {         "variables": [             {                 "name": "change_state",                 "type": "string",                 "value": "none"             },             {                 "name": "block_state",                 "type": "string",                 "value": "divkit"             }         ],         "variable_triggers": [             {                 "condition": "@{change_state == 'block' && block_state == 'divkit'}",                 "mode": "on_variable",                 "actions": [                     {                         "log_id": "update change_state",                         "url": "div-action://set_variable?name=change_state&value=none"                     },                     {                         "log_id": "update block_state",                         "url": "div-action://set_variable?name=block_state&value=flutter"                     },                     {                         "log_id": "update state",                         "url": "div-action://set_state?state_id=0/sample/flutter"                     }                 ]             },             {                 "condition": "@{change_state == 'block' && block_state == 'flutter'}",                 "mode": "on_variable",                 "actions": [                     {                         "log_id": "update change_state",                         "url": "div-action://set_variable?name=change_state&value=none"                     },                     {                         "log_id": "update block_state",                         "url": "div-action://set_variable?name=block_state&value=divkit"                     },                     {                         "log_id": "update state",                         "url": "div-action://set_state?state_id=0/sample/divkit"                     }                 ]             }         ] }

У триггера указывается само условие срабатывания и режим (на каждое обновление переменной on_variable или на смену результата условия on_condition).

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

Как видно из схемы, мы не застрахованы от рекурсивного срабатывания триггера (когда мы обновляем переменную и триггеримся на её обновление снова). С этим нужно быть осторожным, в рассматриваемом примере для избежания данной ситуации значение стейта не меняется напрямую, и кнопка отправляет именованный ивент.

Более детально можно узнать в разделе Выполнение действий при изменении значений переменных.

Таймер

Таймеры достаточно сложные, поэтому разберём пример, использующий возможности таймера по максимуму, — тикающий таймер.

По своей сути он позволяет выполнять действия отложено, периодически (бесконечно или конечно). Для этого добавьте описание триггера в блоке timers:

{      "timers": [             {                 "id": "ticker",                 "duration": "@{timer_duration}",                 "tick_interval": "@{timer_interval}",                 "value_variable": "timer_value",                 "tick_actions": [                     {                         "log_id": "tick",                         "url": "div-action://set_variable?name=timer_state&value=ticking"                     },                     {                         "log_id": "tick",                         "url": "div-action://set_variable?name=tick_count_value&value=@{tick_count_value+1}"                     }                 ],                 "end_actions": [                     {                         "log_id": "end",                         "url": "div-action://set_variable?name=timer_state&value=ended"                     }                 ]             }         ] }

Таймеру задаётся длительность и интервал. Может работать в трёх режимах:

• duration — один вызов end_action;

• duration и tick_interval — tick_action  на каждый интервал до конца duration и один вызов end_action;

• tick_interval — tick_action на каждый интервал без конца.

Таймеры управляются по id с помощью экшена:

div-action://timer?id=ticker&action=start/stop/reset/pause/resume/cancel

У механизма есть три основные сущности. TimerManager — прослойка для инициализации таймеров, обработки внешних экшенов и взаимодействия с Scheduler, который хранит набор Timers (DTO) и может управлять их Clockworks по id. Сам Clockwork нужен для вызова колбэков в определённые моменты — отложено или периодически. 

Если подробнее, то Clockwork позволяет вызывать onEnd, отложенный на duration, а также позволяет задать промежуточный interval, на который будет вызываться onTick до истечения основного duration. Сам по себе Clockwork — это простейшая стейт-машина с тремя состояниями: started/stopped/paused.

Что осталось

Контекст DivKitView

Связующая сущность, которая ссылается на все публичные внутренние механизмы. Используется в кастомных экшенах и onInit-колбэке DivKitView. У главного контекста есть доступ к хранилищу переменных, стейтам, таймерам. Также здесь можно запустить выполнение экшена с помощью ActionHandler. Наконец, можно менять фокусы FocusNode.

Вычислитель выражений и контекст переменных

Вычислитель выражения — это продвинутый калькулятор (отвечает за получение значения из выражения). Для своей работы он требует контекст переменных (буквально значения и имена переменных в момент вычисления), также он помогает выделить изменение в данных. Само выражение в момент создания анализирует строку и ищет все имена используемых переменных. Комбинируя оба значения, вычислитель считает новое только при изменении и возвращает предыдущее значение в противном случае. Это помогает сократить количество вычислений, которые происходят достаточно долго.

На данный момент в клиенте используются нативные реализации вычислителей — плагин div_expressions_resolver (основанный на Platform Channel). Практически всё работает в рамках спецификации, но производительность не потрясающая. 

Для iOS вычислитель пока не может сам вывести тип результата, поэтому гоняем строки, из-за чего есть проблемки в типах внутри коллекций:

Для Android, на момент написания, полный интероп типов без промежуточного представления. Последняя версия вычислителя не опубликована, поэтому падают новые тесты:

Самая большая текущая проблема в том, что идёт жёсткое ограничение полноценно поддерживаемых платформ — только iOS и Android, на других не будут работать выражения. В ближайших планах плавно переписать его на Dart/C++ (Rust).

Первый запуск Flutter-клиента

dependencies:      divkit: any

import 'package:divkit/divkit.dart';

final data = DefaultDivKitData.fromJson(json); // Map<String, dynamic>

 final data = DefaultDivKitData.fromScheme(        card: json['card'], // Map<String, dynamic>        templates: json['templates'], // Map<String, dynamic>?    );

 DivKitView(        data: data,    )

DivKitView(      data: data,      customHandler: MyCustomHandler(), // DivCustomHandler?      actionHandler: MyCustomActionHandler(), // DivActionHandler?      variableStorage: MyOwnVariableStorage(), // DivVariableStorage?    )

Заключение

Это первая версия релиза, над которой мы продолжаем работать. Наша цель — сделать решение более удобным, стабильным и быстрым. Пробуйте, внедряйте, предлагайте. Мы также будем рады вкладу в технологию со стороны сообщества, ведь впереди у нас ещё много работы — анимации, переходы, триггеры видимости, оставшиеся компоненты и прочее. Продолжим развивать проект вместе!