Библиотеки
Библиотека — это целый проект FlutterFlow, подключённый к другому проекту как зависимость. Так приложение разбирается на части: компоненты, вызовы API, кастомный код живут отдельно и переиспользуются там, где нужны.
Зависимость — внешняя библиотека или ресурс, без которого проект не работает. Часть зависимостей добавляется в новый проект автоматически, ещё часть появляется, когда вы используете кастомный виджет. Библиотеки развивают ту же идею: зависимостью становится целый проект FlutterFlow.
Представьте магазин, над которым работает несколько команд. Одна из них делает платежи. Опубликовав платёжную часть как библиотеку, она избавляет остальные команды от необходимости собирать то же самое заново.
Зачем это нужно
Раньше ресурсы между проектами делили иначе: командные библиотеки кода, дизайн-системы, библиотеки API, товары маркетплейса. У всех этих способов были ограничения — нельзя было передать собственные типы данных или функции вместе с компонентами и вызовами API, не было версий.
Библиотека снимает это ограничение: публикуется весь проект целиком и подключается к другим как зависимость.
- Модульная разработка: большое приложение разбивается на самостоятельные проекты — библиотека интерфейса, интеграции с бэкендом и так далее.
- Работа в команде: общие компоненты, функции и интеграции переиспользуются во всех приложениях команды.
- Обмен с сообществом: библиотеку можно опубликовать так, чтобы её подключали другие разработчики FlutterFlow.
Публикация библиотеки
Чтобы ресурсы проекта стали доступны другим, опубликуйте проект как библиотеку.
После публикации проект становится библиотечным, и часть возможностей в нём отключается.
Отменить публикацию нельзя. Вернуть обычный проект можно только клонированием, но настройки деплоя и Firestore при этом обнулятся. Хотите сохранить проект в нынешнем виде — сначала склонируйте его, а публикуйте копию.
Порядок действий: создайте проект как обычно, а затем —
- Публикация доступна тем, у кого есть ветки, то есть на тарифе Growth и выше.
- Публиковать можно только из главной ветки, и каждая версия привязана к конкретному коммиту — версии получаются воспроизводимыми.
- Перед публикацией новой версии изменения нужно зафиксировать.
- В описание версии стоит написать, что в ней изменилось: это единственное, что увидят пользователи библиотеки.
Проект можно опубликовать как библиотеку, если он удовлетворяет условиям:
- Не публиковался в магазины: проект не выкладывался в Google Play или App Store.
- Нет неудавшихся деплоев: кнопка Publish остаётся неактивной, если деплой запускался и завершился ошибкой.
- Нет ошибок и предупреждений: их нужно устранить заранее.
- Только главная ветка.
- Платный тариф.
- Не копия товара с маркетплейса.
Что отключается в библиотеке
После превращения проекта в библиотеку становятся недоступны:
- настройки приложения
- Supabase
- окружения разработки
- аутентификация
- push-уведомления
- публикация мобильного приложения
- публикация веб-версии
- Stripe
- Braintree
- Razorpay
- Google Analytics
- OneSignal
- Mux
Подключение библиотеки
Откройте Settings and Integrations > Project Setup > Project Dependencies и укажите библиотеку и её версию.
- Выбрать библиотеку можно, если у вас есть хотя бы доступ на чтение к её проекту.
- Чтобы библиотека появилась в списке, вы должны быть её участником, а у самой библиотеки должна быть опубликованная версия.
- Публично доступную библиотеку можно подключить по идентификатору проекта — введите его в поле при добавлении зависимости.
- По умолчанию подключается последняя опубликованная версия, но можно выбрать и более раннюю.
- Есть вариант подключить версию
current— текущее состояние главной ветки; так делать не стоит. - Версия подключаемой библиотеки не должна быть
currentи должна быть не выше версии FlutterFlow того проекта, куда её подключают. Подробнее — управление версией FlutterFlow в библиотеке.
Конфликты зависимостей
Конфликт возникает, когда две подключённые библиотеки требуют разные версии одной и той же зависимости. Проект не может выбрать между ними — и выдаёт ошибку.
Скажем, в магазине подключены две библиотеки:
- User Auth Library — авторизация;
- Payment Gateway Library — платёжный шлюз.
Обе зависят от общей библиотеки Components Library, но от разных её версий:
- User Auth Library — от
Components Library v1.5.0; - Payment Gateway Library — от
Components Library v2.0.0.
Проект магазина не может подключить обе версии сразу, поэтому сообщает о конфликте.
Как разрешить конфликт
- Обновите обе библиотеки. Свежие версии обычно рассчитаны на актуальную Components Library — часто этого достаточно.
- Поправьте сами библиотеки. Если проекты библиотек доступны вам, приведите их зависимости к одной версии Components Library.
- Напишите авторам. Если библиотека чужая, обратитесь к её сопровождающим: они подскажут обходной путь или выпустят согласованную версию.
Что даёт подключённая библиотека
После подключения становятся доступны:
- компоненты;
- типы данных и перечисления;
- переменные App State;
- константы;
- вызовы API;
- блоки действий;
- кастомные функции, действия и виджеты;
- ресурсы приложения — они не версионируются;
- файлы кода.
- Страницы, коллекции Firestore и облачные функции ещё в работе и появятся в следующих обновлениях.
- Создавать ИИ-агентов в библиотечном проекте пока нельзя.
Ресурсы появляются там, где они применяются:
- компоненты — в палитре виджетов;
- вызовы API — при добавлении запроса в редакторе действий;
- кастомные функции — при настройке действий и функций;
- файлы кода (Dart-классы и перечисления) — при создании экземпляров, а также в редакторе действий при добавлении действий со своим классом.
Так в каждом месте видно только то, что там уместно.
Из кастомного кода тоже доступны ресурсы подключённой библиотеки — её App State, значения библиотеки, файлы кода. Примеры собраны в разделе Частые примеры кастомного кода.
Версии библиотеки
Версии позволяют развивать библиотеку, не ломая тех, кто её уже подключил: каждый проект сам решает, на какой версии оставаться.
- Совместимость: старые версии продолжают работать, пока в новых появляются возможности.
- Откат: если в свежей версии обнаружилась проблема, можно вернуться к прежней.
- Контроль обновлений: обновляется тот, кто к этому готов, а не все сразу.
Публикация новой версии
Зафиксируйте изменения в главной ветке проекта библиотеки и опубликуйте её так же, как в первый раз.
- Опишите, что изменилось в версии.
- Номер версии увеличивается автоматически при каждой публикации.
Подключение конкретной версии
При подключении библиотеки версию выбираете вы; по умолчанию предлагается последняя.
Обновление до свежей версии
Библиотеки обновляются в пару кликов, как только выходят новые версии.
- Если обновление сломало работу приложения, всегда можно вернуться к прежней версии.
- После обновления проверьте приложение — совместимость лучше выяснять сразу, а не на пользователях.
Страницы библиотеки
Все страницы опубликованной библиотеки доступны в проекте, который её подключил, и ведут себя как обычные: поддерживают навигацию, параметры, состояние и переходы.
Это и есть модульная разработка: онбординг или оплату достаточно собрать один раз в библиотеке и дальше подключать куда нужно.
- Супераппы вроде Gojek или Uber, где такси, магазин и платежи — разные модули. Каждый собирается отдельной библиотекой и подключается в главный проект.
- Корпоративные приложения с разными сценариями для ролей: интерфейс администратора и интерфейс клиента живут в своих библиотеках.
- White-label приложения с общим онбордингом: он делается один раз и переиспользуется во всех фирменных версиях.
При подключении или обновлении библиотеки имена маршрутов можно переопределить, чтобы они не конфликтовали с маршрутами проекта. Дальше страницы библиотеки видны в действиях навигации наравне с обычными.
Страницы библиотеки в NavBar
Страницы библиотеки можно вывести в панель навигации. В супераппе так собирают нижнее меню из модулей: такси, доставка, платежи — каждый из своей библиотеки.
Подробный разбор модульной архитектуры супераппов — в статье блога FlutterFlow.
Откройте Project Dependencies > FlutterFlow Libraries, нажмите Pages у нужной библиотеки, найдите страницу в списке и выберите Nav Bar Settings, затем включите Show on NavBar. Там же задаются подпись и иконка.
Проверить результат можно в разделе Nav Bar & App Bar — страница библиотеки появится среди пунктов панели.
У обычных страниц настройки панели навигации находятся в свойствах самой страницы, а у страниц библиотеки — в диалоге с подробностями библиотеки.
Значения библиотеки
Library values — переменные, которые объявляет автор библиотеки, а задаёт тот, кто её подключает. Через них настраивают библиотеку под конкретный проект: публичные ключи API, региональные параметры, общие настройки.
Скажем, у платёжной библиотеки это могут быть:
- валюта по умолчанию: USD;
- регион: US;
- способ оплаты по умолчанию: карта.
Пользователь библиотеки задаёт свои значения, не залезая внутрь неё.
В значениях библиотеки нельзя хранить секреты — приватные ключи API и учётные данные. Они для этого не предназначены и не защищены.
Публичные (клиентские) ключи допустимы: у них ограниченные права и лимиты, они и рассчитаны на открытое использование. Например, библиотека, которая ходит в публичный API погоды, может принимать ключ значением библиотеки — каждый подставит свой.
Любому ключу стоит выставить ограничения, чтобы им нельзя было воспользоваться где попало. Как это делается — на примере ключа Google Maps в Google Cloud Console.
Создание значений (для автора)
Автор задаёт имя переменной, тип данных (строка, перечисление и другие), допустимость null и, при желании, значение по умолчанию.
Откройте Settings and Integrations > App Settings > Publish as Library > Library Values и нажмите + Add Value.
Использование значений
Дальше значения библиотеки работают как обычные переменные: их привязывают к компонентам, действиям, вызовам API и любым свойствам через меню Set from Variable.
Значения библиотеки используются внутри самой библиотеки. В проекте, который её подключил, они недоступны — там их можно только задать.
Задание значений (для пользователя)
Откройте Settings and Integrations > Project Setup > Project Dependencies. При подключении библиотеки FlutterFlow сам попросит заполнить обязательные значения; если библиотека уже подключена, нажмите View Details и введите значение в открывшемся окне.
Для разных окружений разработки значения библиотеки можно связать со значениями окружения. Скажем, завести DEV_OPENAI_API_KEY и PROD_OPENAI_API_KEY и привязать их к тестовому и рабочему окружениям — тогда и расход по API будет виден раздельно.
Библиотеки и Firebase
В библиотечном проекте можно создавать коллекции и включать возможности Firebase, не подключая отдельный проект Firebase.
Поля для привязки к Firebase в библиотеке нет: подключением занимается тот проект, который библиотеку импортирует.
Индексы и правила безопасности, описанные в библиотеке, подхватываются проектом и разворачиваются вместе с ним.
Firebase Auth и Firebase Storage в библиотечных проектах пока не поддерживаются напрямую. Если библиотеке нужна такая функциональность, вынесите её в колбэк и передавайте действие снаружи.
Если несколько проектов команды используют один и тот же кусок работы с Firebase, из него стоит сделать библиотеку: логика останется единой и будет ходить в тот же проект Firestore.
Что удобно собирать библиотекой:
- Аналитика и события: запись событий в Firestore, чтобы собирать данные об использовании со всех приложений.
- Конфигурация: общие настройки приложения — флаги функциональности, темы, варианты раскладки — через Firebase Remote Config.
Частые вопросы
Что будет с существующими командными библиотеками?
Командные библиотеки кода и API переедут в библиотечные проекты и подключатся как библиотеки последней версии. Компоненты из командных дизайн-систем переедут в собственные проекты, а сами дизайн-системы останутся, но только с настройками темы.
Работают ли библиотеки с маркетплейсом?
Да, проект с маркетплейса можно добавить и подключить как библиотеку.
Как библиотеки уживаются с дизайн-системами?
По умолчанию дизайн-система основного проекта важнее, чем дизайн-система подключённой библиотеки. Чтобы использовать библиотечную, её нужно выбрать на странице Design System.
Как передаются ключи API?
Для этого есть значения библиотеки: тот, кто подключает библиотеку, задаёт свои значения при импорте.
Как работают вложенные зависимости?
Проект может подключать библиотеки, которые сами зависят от других библиотек. Но если проект и библиотека зависят от одного и того же, версии должны совпадать точно — иначе конфликт.
Почему при подключении копии проекта возникают ошибки коллизий?
Когда проект дублируют и публикуют как библиотеку, уникальные ключи компонентов и других ресурсов остаются прежними. При подключении такой библиотеки обратно в исходный проект ключи оригиналов и копий сталкиваются.
FlutterFlow предложит удалить оригинальные ресурсы в базовом проекте и перевести все ссылки на библиотечные версии. Если разбираться вручную, продублируйте нужные компоненты внутри библиотеки после подключения — у копий появятся новые ключи, и коллизия исчезнет.