Библиотеки

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

к сведению

Зависимость — это внешняя библиотека или ресурс, от которого зависит правильная работа вашего проекта. При создании нового проекта FlutterFlow некоторые зависимости добавляются автоматически для поддержки генерируемого кода. Кроме того, при использовании Custom Widget вы по сути добавляете зависимости в свой проект. Библиотеки развивают эту концепцию, позволяя добавлять целые проекты FlutterFlow в качестве зависимостей.

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

Важность библиотек

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

С библиотеками вы можете опубликовать полный проект FlutterFlow как библиотеку и импортировать его как зависимость в другие проекты.

возможные сценарии использования

• Модульная разработка: Строите крупномасштабные приложения, разделяя их на меньшие, независимо управляемые проекты (например, библиотека UI, интеграции с бэкендом и т. д.).
• Сотрудничество в команде: Делитесь повторно используемыми компонентами UI, пользовательскими функциями или интеграциями API в нескольких приложениях внутри команды.
• Обмен в сообществе: Публикуйте библиотеки, которые могут импортировать и повторно использовать более широкое сообщество FlutterFlow.

Публикация библиотеки

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

При публикации проекта как библиотеки он станет проектом-библиотекой, и некоторые функции больше не будут доступны.

примечание

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

Чтобы опубликовать проект FlutterFlow как библиотеку, начните с создания проекта FlutterFlow как обычно, а затем следуйте этим шагам:

к сведению

• Вы можете публиковать библиотеки только если у вас есть доступ к ветвлению, которое доступно пользователям на плане Growth и выше.
• Библиотеки можно публиковать только из основной ветки, и каждая опубликованная версия связана с конкретным коммитом, что обеспечивает надежный контроль версий.
• Перед публикацией новой версии библиотеки вы должны закоммитить изменения.
• Рекомендуется включить сообщение, которое расскажет пользователям, что изменилось в версии, которую вы публикуете.

warning

Чтобы опубликовать проект как библиотеку, он должен соответствовать следующим требованиям:

• Отсутствие предыдущего развертывания в магазин: Проект не должен быть развернут в Google Play Store или Apple App Store.
• Отсутствие неудачных развертываний: Кнопка Publish остается отключенной, если процесс развертывания был запущен и завершился неудачей.
• Отсутствие ошибок или предупреждений: Все ошибки или предупреждения проекта должны быть устранены заранее.
• Только основная ветка: Вы можете публиковать только из основной ветки.
• Платный план: Для публикации проекта как библиотеки требуется подписка на один из платных планов.
• Не клонирован из маркетплейса: Проект не может быть клоном элемента маркетплейса.

Отключенные функции в библиотеке

При преобразовании проекта в библиотеку следующие функции отключаются для обеспечения совместимости и ограничений функциональности:

• Настройки приложения
  • Supabase
  • Среды разработки
  • Аутентификация
  • Push-уведомления
  • Развертывание для мобильных устройств
  • Развертывание для веба
  • Stripe
  • Braintree
  • Razorpay
  • Google Analytics
  • OneSignal
  • Mux

Импорт библиотеки

Чтобы импортировать проект-библиотеку в другой проект FlutterFlow, перейдите в Settings and Integrations > Project Setup > Project Dependencies. Здесь вы можете указать проект-библиотеку и версию, которую импортируете.

к сведению

• Вы можете выбрать библиотеку только если у вас есть как минимум права на чтение в проекте-библиотеке.
• Чтобы проект-библиотека отображался в выпадающем списке, вы должны быть добавлены как соавтор в проект, и проект-библиотека должен иметь опубликованную версию.
• Вы можете импортировать общедоступные библиотеки, указав ID проекта в текстовом поле при добавлении зависимости библиотеки.
• По умолчанию импортируется последняя опубликованная версия библиотеки, но вы можете выбрать зависимость от более ранней версии, если это необходимо.
• Вы также можете импортировать версию 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.

В этом сценарии проект электронной коммерции обнаружит конфликт зависимостей, поскольку не сможет добавить одновременно v1.5.0 и v2.0.0 библиотеки Components Library.

Устранение конфликтов зависимостей

Следуйте этим шагам, чтобы обе библиотеки зависели от одной и той же версии Components Library:

1. Обновите обе библиотеки: Если доступны обновления, начните с обновления как библиотеки User Auth Library, так и Payment Gateway Library до их последних версий. Часто новые версии библиотек предназначены для использования последней версии Components Library, что может помочь устранить конфликты.
2. Измените библиотеки: Если у вас есть доступ к проектам-библиотекам, настройте зависимости либо User Auth Library, либо Payment Gateway Library (или обеих), чтобы они использовали одну и ту же версию Components Library.
3. Свяжитесь с maintainer'ами библиотек: Если вы не владеете библиотекой сами, обратитесь к maintainer'ам проектов-библиотек. Они могут предоставить рекомендации, предложить обходные пути или выпустить версию, которая устраняет конфликт.

Доступ к ресурсам библиотеки

После импорта библиотеки следующие ресурсы становятся доступными для использования:

• Компоненты
• Типы данных и перечисления
• Переменные состояния приложения
• Константы
• Вызовы API
• Блоки действий
• Custom Functions, Actions и Widgets
• Активы (Примечание: Они не версионированы)
• Файлы кода

к сведению

• Страницы, Коллекции Firestore и Cloud Functions все еще разрабатываются и могут появиться в будущих обновлениях.
• Создание AI Agents пока не поддерживается в проекте-библиотеке

Важно отметить, что эти ресурсы отображаются там, где они инстанцируются. Например:

• Компоненты появляются в палитре виджетов.
• Вызовы API появляются при создании вызовов API в редакторе потоков действий.
• Custom Functions доступны при настройке действий или функций внутри приложения.
• Файлы кода (Dart-файлы, содержащие классы или перечисления) становятся доступными при создании экземпляров, что позволяет обращаться к их полям и методам. Они также появляются в редакторе потоков действий при добавлении действий пользовательского класса.

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

Доступ к компонентам библиотеки в пользовательском коде

Когда ваш проект включает зависимость от библиотеки, вы можете использовать ее компоненты — такие как состояние приложения библиотеки, значения библиотеки, ресурсы пользовательского кода библиотеки и т. д. — в своем пользовательском коде. Ознакомьтесь с каталогом Common Custom Code Examples для справки.

Версионирование библиотек

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

Важность версионирования библиотек

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

Публикация новой версии

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

подсказка

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

Импорт конкретной версии

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

Обновление до последней версии

Вы можете легко обновляться до новых версий библиотек по мере их появления.

подсказка

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

Страницы библиотек

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

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

Возможные сценарии использования

• Суперприложения вроде Gojek и Uber с отдельными модулями, такими как бронирование поездок, шопинг и платежи. Каждый модуль может быть разработан как отдельная библиотека и импортирован в единый основной проект.
• Корпоративные приложения с изолированными пользовательскими путями для разных ролей, таких как администратор и клиент. Каждый поток на основе роли может быть построен как своя библиотека и интегрирован в основное приложение по мере необходимости.
• White-labeled приложения, которые делят общие потоки онбординга, могут извлечь пользу из библиотек. Процесс онбординга можно построить один раз как библиотеку и повторно использовать во всех брендированных версиях приложения.

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

Страницы библиотек в NavBar

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

подсказка

Хотите узнать больше о построении модульных суперприложений с использованием библиотек? Ознакомьтесь с нашим постом в блоге.

Чтобы отобразить страницу библиотеки в NavBar, перейдите в Project Dependencies > FlutterFlow Libraries, затем нажмите Pages для соответствующей библиотеки, чтобы открыть ее детали. В списке страниц найдите нужную страницу и нажмите Nav Bar Settings, затем включите Show on NavBar. Вы также можете настроить дополнительные параметры, такие как метка и иконка, по необходимости.

Для подтверждения перейдите в раздел Nav Bar & App Bar, где вы увидите страницу библиотеки, перечисленную как часть элементов NavBar.

к сведению

Настройки NavBar для обычных страниц доступны напрямую в панели настроек страницы в билдере. Однако для страниц библиотек эти настройки управляются через диалог деталей библиотеки.

Значения библиотек

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

Например, если кто-то строит библиотеку платежного шлюза, они могут определить значения библиотек для настроек конфигурации, таких как:

• Валюта по умолчанию: USD
• Регион: US
• Метод оплаты по умолчанию: Card

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

осторожно

Значения библиотек не следует использовать для хранения приватных или чувствительных данных, таких как секретные API-ключи или учетные данные. Эти значения в настоящее время не предназначены для безопасного хранения или обработки чувствительной информации.

Использование client-side или publishable API-ключа в целом приемлемо, поскольку ключи часто имеют ограниченные разрешения, лимиты скорости или предназначены для публичного использования. Например, если кто-то создает библиотеку, которая подключается к публичному API погоды, они могут определить значение библиотеки для API-ключа. Пользователи этой библиотеки затем могут ввести свой собственный API-ключ, чтобы она заработала.

подсказка

Чтобы избежать неправильного использования любого типа учетных данных, убедитесь, что применены соответствующие ограничения для ограничения его использования. Например, см. как ограничить API-ключ Google Maps в консоли Google Cloud.

Создание значений библиотек как автор

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

Чтобы создать значения библиотек, перейдите в Settings and Integrations > App Settings > Publish as Library > Library Values и нажмите + Add Value.

Использование значений библиотек

После установки значений библиотек они функционируют так же, как любые другие переменные в FlutterFlow. Вы можете привязывать их к компонентам, действиям, вызовам API или любому свойству, которое позволяет настраивать динамические значения по всему проекту-библиотеке. Вы можете обращаться к значениям библиотек через меню Set from Variable.

подсказка

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

Установка значений библиотек как пользователь

Чтобы установить значения библиотек, перейдите на страницу Settings and Integrations > Project Setup > Project Dependencies. При импорте библиотеки вас попросят установить значения для обязательных значений библиотек. Если библиотека уже добавлена, нажмите View Details, что откроет диалог, и затем вы можете ввести значение.

подсказка

Для разных сред разработки (например, разработка против продакшена) вы можете привязывать значения библиотек к значениям среды. Например, вы можете иметь два разных значения библиотек для API-ключа, таких как DEV_OPENAI_API_KEY и PROD_OPENAI_API_KEY, и привязать их к средам разработки и продакшена, чтобы отслеживать использование API отдельно.

Библиотеки с Firebase

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

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

Любые индексы или правила безопасности, определенные в библиотеке, распознаются импортирующим проектом и развертываются соответственно.

Ограничения

Библиотеки работают с Firebase, но имеют некоторые ограничения. Firebase Auth и Firebase Storage пока не поддерживаются напрямую в проектах-библиотеках. Если вам нужны эти функции в функциональности вашей библиотеки, вы можете включить действие, которое выполняет эту задачу, как callback.

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

Вот несколько примеров проектов-библиотек, которые вы можете построить с Firebase:

• Базовая аналитика или отслеживание: Библиотека, которая логирует события в Firestore; полезна для агрегации данных использования на уровне приложения.
• Конфигурация или настройки: Библиотека, которая обслуживает конфигурации на уровне всего приложения (например, флаги функций, темы UI или выбор макетов), обрабатывается в Firebase Remote Config.

Часто задаваемые вопросы

Что произойдет с существующими библиотеками команд?

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

Работают ли библиотеки с маркетплейсом?

Да, вы можете добавлять и импортировать проект маркетплейса как библиотеку.

Как библиотеки работают с темами (системами дизайна)?

По умолчанию система дизайна родительского проекта имеет приоритет над импортированной системой дизайна библиотеки. Если вы хотите использовать систему дизайна библиотеки, вы должны выбрать или установить библиотеку на странице Design System.

Как делятся API-ключи?

Мы работаем над значениями библиотек, которые позволят пользователям устанавливать конкретные значения при импорте библиотеки. Эта функция станет доступна в ближайшее время.

Как работают вложенные зависимости?

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

Почему я получаю ошибки коллизий при импорте дублированного проекта как библиотеки?

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

Чтобы помочь с этим, FlutterFlow показывает диалог, который предлагает автоматически удалить исходные ресурсы в вашем базовом проекте и обновить все ссылки, чтобы они указывали на версии библиотеки.

Если вы предпочитаете решать это вручную, вы можете дублировать отдельные компоненты внутри библиотеки после импорта; это сгенерирует новые ключи и избежит коллизии.