Flutter Web. Часть 2

Привет, меня зовут Максим, я Flutter-разработчик в компании Surf.

Мы продолжаем рассказывать про Flutter Web. И это вторая статья.

Разработка собственных библиотек

Межъязыковое взаимодействие JS-Dart устроено достаточно просто. Но вписать большой функционал только на Dart не всегда удобно. Как минимум, из-за отсутствия подсказок IDE о доступных методах в JS-объектах, а как максимум — из-за многословного преобразования комплексных объектов. 

Большие модули гораздо удобнее разрабатывать на нативном языке (JS) и оставлять несложный интерфейс для взаимодействия с Dart-частью.

Простой пример

Реализуем несколько простых функций. Для этого создадим файл simple.js в директории web/js .

/// web/js/simple.js /// Простая функция с входным параметром function customPrint(value) {     console.log(value); }  /// Асинхронная функция, /// возвращающая Promise, /// аналог Future в Dart async function future() {     await delay(1000);      return new Promise((resolve, reject) => {         // Здесь ваш асинхронный код         // Если всё прошло успешно, вызовите resolve(result)         // Если что-то пошло не так, вызовите reject(error)          resolve('success');     });  }  /// Вспомогательный метод, эмулирующий работу function delay(ms) {     return new Promise(resolve => setTimeout(resolve, ms)); }

Подключаем новую зависимость в файл web/index.html .

     <...>      <script src="./js/simple.js"></script> </head>

Проверяем с помощью консоли, что методы успешно импортированы

Теперь описываем интерфейсы уже знакомым нам способом:

// lib/main.dart @JS('customPrint') external void customPrint(String message);  @JS('future') external JSPromise<JSString> jsAsyncMethod();

Тут стоит обратить внимание, что JS Interop не умеет не явно преобразовывать Promise -> Future. По этой причине в описании интерфейса мы должны указать тип JSPromise c соответствующим дженерик типом, если это необходимо. И не забыть о приведении к системе типов Dart с помощью геттера toDart .

// lib/main.dart final message = await jsAsyncMethod().toDart; print(message);

Этих знаний будет достаточно, чтобы реализовать большую часть задач для Flutter Web. 

Но иногда нам нужно прописать сложную бизнес-логику или использовать сторонние библиотеки. Для закрытия этого пула задач есть огромное количество технологий и инструментов для нативной веб-разработки. Наиболее близкими и приятными нам показались Node.js, npm, TypeScript и webpack

Вы спросите: зачем нам столько всего? Объясним:

• Node.js — это не просто фреймворк, это среда выполнения JS-кода. Благодаря тому, что она не привязана к рантайму браузера, она позволяет использовать JS практически везде. Что, в свою очередь, очень популяризировало эту технологию за пределами веб-сайтов. У Node.js есть огромное комьюнити, которое реализовало множество библиотек. Они помогают не только взаимодействовать с браузером, но и, например, конвертировать видео, работать с документами, генерировать изображения и делать многое другое;

• npm — пакетный менеджер для Node.js, в репозиториях которого хранятся библиотеки;

• TypeScript — надстройка над языком JavaScript, которая позволяет удобно писать строго типизированный код и использовать подход ООП, что для нас более привычно;

• webpack — из-за особенностей веб-стандартов мы должны разрабатывать один модуль, в рамках одного файла. А это не всегда удобно. Webpack позволяет собирать модуль разбитый на части в один или несколько бандлов.

А теперь разработаем первый модуль, и на этот раз, он будет прикладным.

Модульная библиотека

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

Предлагаем реализовать простой плагин для обнаружения новых инстансов приложения. 

Создадим новую директорию для исходников плагина {root_project}/packages/instanse_detector 

Перейдём в эту директорию в терминале и инициализируем новый npm-модуль.

npm init -y

Подробную информацию об установке и настройке Node.js и npm в вашем окружении вы найдёте тут

В текущую директорию добавился файл package.json, который служит для конфигурации нашего проекта, управления зависимостями и сборки. Эдакий pubspec.yaml, только из мира Node.js.

Внесём правки:

// packages/instanse_detector/package.json {   "name": "instance_detector",   "version": "0.0.1",      "scripts": {     "tsc": "tsc",     /// добавим алиас для запуска TS     "build": "npm run tsc"   },   "devDependencies": {     // указываем, что используем TypeScript     // для разработки      "typescript": "^5.1.6"   } }

Теперь выполним команду npm install для установки необходимых зависимостей. 

Следующим этапом подготовим конфигурацию для компиляции TypeScript. 

Добавим файл tsconfig.json в корень нашего модуля.

packages/instanse_detector/tsconfig.json {   "compilerOptions": {       /// указываем стандарты       /// ES5 - максимальный для взаимодействия с Flutter web       "target": "ES5",       "module": "system",       "moduleResolution": "node",       /// директория, куда будет сохранен скомпилированный JS       "outDir": "../../web/js/",   },    "exclude": [       "node_modules",       "build"   ] }

Более подробную информацию о tsconfig вы найдёте тут

Пора переходить к реализации нашего модуля. Для этого создадим поддиректорию src и добавим туда файл с расширением ts .

// packages/instanse_detector/src/instanse_detector.ts /// Вспомогательное перечисление, для определения инстанса приложения enum Message {     First,     Second, }  /// Для удобства определим тип метода с булевым параметром type OnInstanceEvent = (e: boolean) => void;  class InstanceDetector {     onEvent?: OnInstanceEvent;     channel: BroadcastChannel;          constructor() {         /// Вкладки браузера могут общаться между собой          /// при помощи каналов         this.channel = new BroadcastChannel("simpl-instanse-detector");                  this.channel.onmessage = (event) => {             /// Если в канал поступило сообщение с типом First              /// значит запущен новый инстанс приложения             if (event.data === Message.First) {                 /// сообщаем в ответ что есть другой инстанс                 this.channel.postMessage(Message.Second);                 /// оповещаем Dart                 this.onEvent(true);             }             /// Если в получили событие Second             /// Это означает, что мы главный инстанс             if (event.data === Message.Second) {                 /// оповещаем Dart                 this.onEvent(false);             }         };         /// При инициализации сообщаем всем, что         /// мы главный инстанс         this.channel.postMessage(Message.First);     }      /// Метод установки коллбека на изменения состояния     init(onEvent: OnInstanceEvent) {         this.onEvent = onEvent;         onEvent(false);     } }

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

Итоговая структура нашего проекта может выглядеть так:

📁root_project_folder/    └──📁packages/       ├──📁instance_detector/       │  └──📁src/       │     └──📄instance_detector.ts       ├──📄package.json       └──📄tsconfig.json

Итак, мы запустили команду npm run build в папке /web/js. У нас появился скомпилированный JS-файл, который нужно подключить и использовать.

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

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

Рассмотрим этот подход подробнее.

Обеспечение кросскомпиляции для разных платформ

В директории packages генерируем плагин командой:

flutter create --template=package {name} 

Разделим реализацию плагина для каждой из платформ. Объявим общий интерфейс.

class INativeInstanceDetector {}

Здесь мы обойдёмся пустым контрактом — нам не потребуются ни методы, ни параметры. 

Создадим структуру для плагина:

📁project_foler └──📁lib_folder     ├──📁lib     │  ├──📁src     │  │  ├──📁impl     │  │  │  ├──📁io     │  │  │  │  └──📄io.dart     │  │  │  └──📁web     │  │  │     ├──📄bindings.dart     │  │  │     └──📄web.dart     │  │  └──📄i_instance_detector.dart     │  └──📄export.dart     └──📁packages        └──📁js_source           ├──📁src          │  └──📄instanse_detector.ts          ├──📄package.json           └──📄tsconfig.json

На этом этапе работа с io нам не очень важна — просто реализуем интерфейс, чтобы избежать ошибок сборки.

// lib_folder/lib/src/i_instance_detector.dart class NativeInstanceDetector extends INativeInstanceDetector {   NativeInstanceDetector(Function(bool event) onInstanceAdded); }

Теперь реализуем веб-часть.

Опишем интерфейсы для работы с JS в файле bindings.dart .

// lib_folder/lib/src/impl/web/bindings.dart @JS() library instance_detect.js;  import 'dart:js_interop';  typedef OnInstanceAdded = void Function(bool event);  @JS('InstanceDetector') extension type InstanceDetector._(JSObject _) implements JSObject {   external InstanceDetector();   external JSFunction? get onEvent;   external void init(JSFunction onEvent); }

Обратим внимание на расширение типа JSObject. До этого момента мы вызывали либо простые методы, либо статичные — в них достаточно просто добавить аннотации @JS @staticInterop. 

Здесь нам необходимо создать расширение типа JSObject. Такой подход применяется для описания JS-объекта на стороне Dart, когда необходимо создать инстанс этого объекта и обращаться к его полям или методам.

После — реализуем INativeInstanceDetector для web в файле web.dart .

// lib_folder/lib/src/impl/web/web.dart class NativeInstanceDetector extends INativeInstanceDetector {   final InstanceDetector detector;   /// В конструкторе примим коллбэк,   /// который будет передан в JS-слой   NativeInstanceDetector(OnInstanceAdded onInstanceAdded) : detector = InstanceDetector() {     /// Заводим инстанс обертки над JS-объектом InstanceDetector     final detector = InstanceDetector();     /// Производим инициализацию, передавая коллбек,     /// который будет вызван при запуски нового инстанса     /// нашего приложения      detector.init(onInstanceAdded.toJS);   } }

Завершающим этапом подготовки будет export.dart файл, в котором мы экспортируем нужную реализацию в зависимости от окружения:

// lib_folder/lib/export.dart library detector;  export 'src/impl/io/io.dart' // по умолчанию    if (dart.library.js) 'src/impl/web/web.dart' // web    if (dart.library.io) 'src/impl/io/io.dart'; // io

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

Добавляем плагин в pubspeck.yaml :

dependencies:   flutter:     sdk: flutter   detector:     path: './packages/detector'

Использование плагина ничем не отличается от того, что мы стягиваем с pub.dev.

// lib/main.dart /// Заводим инстанс детектора и передаем туда коллбэк, /// который сработает на изменение состояния вкладки NativeInstanceDetector((event) {       setState(() {         if (event) {           _isSecondary = event;         }       });     });

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

Что в итоге

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

Но это не всё. В следующих статьях мы расскажем о компиляции веб-приложения в wasm.

Этот метод стал доступен не так давно, общую информацию и наше мнение о нём вы найдёте в нашем материале. 

Мы поговорим о разработке и использовании wasm-модулей, о публикации веб-приложений, настройке ci/cd, оптимизации загрузки и оценим прирост производительности. До встречи!

Больше полезного про Flutter — в Telegram-канале Surf Flutter Team. 

Кейсы, лучшие практики, новости и вакансии в команду Flutter Surf в одном месте. Присоединяйтесь!