Начало работы с FForm 🌟
Шаг 1: Установка
Прежде всего, давайте добавим пакет FForm в ваш проект Flutter. Добавьте FForm в файл pubspec.yaml
в разделе зависимостей:
dependencies: fform: ^latest_version
Не забудьте запустить flutter pub get
в вашем терминале, чтобы установить пакет.
Обзор
FForm — это высокоуровневый пакет Flutter, разработанный для упрощения создания и управления формами с упрощенной валидацией полей. Он предлагает два основных компонента: FFormField
и FFormBuilder
, которые вместе приносят легкость и гибкость в обработку форм в приложениях Flutter.
-
FFormField<T, E>
: Базовый класс для всех полей формы, поддерживающий значения, валидацию на лету и обработку изменений. -
FFormBuilder<F extends FForm>
: Виджет, который конструирует и управляет состоянием формы, используя потоки для динамического обновления интерфейса по мере изменения данных. -
FForm
: Базовый класс для создания пользовательских классов форм, позволяющий добавлять конкретные методы и свойства в ваши формы. -
FFormException
: Базовый класс для создания пользовательских исключений для полей формы, позволяющий определять пользовательские правила валидации и сообщения об ошибках. -
FFormProvider
: Виджет, который позволяет получить доступ к форме в дереве виджетов без передачи ее в качестве параметра.
Почему это круто 🎸
-
Упрощенное управление состоянием: Автоматически обрабатывает состояние как отдельных полей формы, так и формы в целом.
-
Встроенная валидация с изюминкой: Поддерживает валидацию на лету и обработку ошибок для каждого поля, обеспечивая плавный пользовательский опыт.
-
Максимальная гибкость: Поддерживает любой тип данных для значений полей и ошибок валидации благодаря дженерикам.
-
Реактивные формы для победы: Использует потоки для отслеживания изменений состояния формы, обеспечивая синхронизацию вашего интерфейса.
-
Множество форм? Нет проблем: Создавайте несколько форм с пользовательскими полями и правилами валидации, все это управляется FForm.
-
Пользовательские исключения для особых нужд: Определяйте пользовательские исключения для полей формы, чтобы с легкостью обрабатывать сложные правила валидации и сообщения об ошибках.
Примеры использования
FFormField
FFormField
— базовый класс для всех полей формы, поддерживающий значения, валидацию на лету и обработку изменений. Он предоставляет набор геттеров и методов для управления состоянием поля, включая проверку валидности поля, получение текущего значения и обработку исключений.
Пример
enum EmailError { empty, not; @override String toString() { switch (this) { case empty: return 'emailEmpty'; case not: return 'invalidFormatEmail'; default: return 'invalidFormatEmail'; } } } class EmailField extends FFormField<String, EmailError> { EmailField({required String value}) : super(value); @override EmailError? validator(value) { if (value.isEmpty) return EmailError.empty; return null; } }
API FFormField
Глобальный ключ key |
Уникальный ключ для идентификации виджета поля формы. Он используется для управления состоянием виджета и доступа к нему в дереве виджетов. |
---|---|
GlobalKey key |
|
Геттеры / Сеттеры |
Описание |
---|---|
T get value |
Получает текущее значение поля формы. |
set value(T newValue) |
Устанавливает новое значение для поля формы и вызывает слушателей, если значение изменилось. |
E? get exception |
Получает текущие исключения валидации поля формы, если они есть. |
bool get isValid |
Проверяет, валидно ли поле формы на основе текущего значения и правил валидации. |
bool get isInvalid |
Проверяет, является ли поле формы недействительным на основе текущего значения и правил валидации. |
Методы |
Описание |
---|---|
void addListener(FFormFieldListener<T, E> listener) |
Добавляет слушателя, который будет вызываться при изменении значения поля формы. |
void removeListener(FFormFieldListener<T, E> listener) |
Удаляет ранее добавленного слушателя из поля формы. |
E? validator(T value) |
Валидирует текущее значение поля формы и возвращает исключение, если значение недействительно. |
FForm
FForm
— базовый класс для создания пользовательских классов форм с конкретными полями и правилами валидации. Он предоставляет набор геттеров и методов для управления состоянием формы, включая проверку валидности формы, получение ответов и обработку исключений.
Пример
Это простой пример того, как создать форму с одним полем. Вы можете расширить класс FForm
, чтобы создать пользовательские формы с конкретными полями и правилами валидации.
class LoginForm extends FForm { EmailField email; LoginForm({ required this.email, }); @override List<FFormField> get fields => [email]; }
Это более сложный пример того, как создать форму с несколькими полями. Вы можете расширить класс FForm
, чтобы создать пользовательские формы с конкретными полями и правилами валидации.
class Form extends FForm { List<Form> forms; Form({ required this.forms, }); @override List<FFormField> get subForms => forms; }
allFieldUpdateCheck
— это свойство в FForm
, которое определяет, приводит ли каждое обновление поля к перестройке FFormBuilder
. Когда установлено в true
, форма будет перестраиваться при каждом обновлении поля, обеспечивая мгновенную обратную связь для пользователя. Когда установлено в false
, форма будет перестраиваться только при вызове геттеров isValid
или isInvalid
, уменьшая количество перестроек и повышая производительность.
class LoginForm extends FForm { EmailField email; LoginForm({ required this.email, }); @override bool get allFieldUpdateCheck => true; @override List<FFormField> get fields => [email]; }
API FForm
Геттеры |
Описание |
---|---|
bool get hasCheck |
Возвращает, есть ли у формы какие-либо проверки валидации. Этот геттер проверяет, применены ли какие-либо правила валидации к полям формы. |
bool get allFieldUpdateCheck |
Указывает, приводит ли каждое обновление поля к перестройке |
List get fields |
Получает список полей формы. Этот геттер используется для доступа ко всем полям, которые являются частью формы. |
List get subForms |
Получает список подформ в форме. Это используется, когда форма содержит вложенные формы, позволяя получить доступ к этим подформам. |
List get answers |
Получает список ответов из полей формы. Этот геттер собирает текущие значения всех полей формы. |
List get exceptions |
Получает список исключений валидации из полей формы. Это используется для сбора всех ошибок валидации, присутствующих в полях формы. |
bool get isValid |
Проверяет, валидна ли вся форма на основе текущих значений и правил валидации. Этот геттер оценивает валидность формы, проверяя состояние валидации каждого поля, и вызывает |
bool get isInvalid |
Проверяет, является ли вся форма недействительной на основе текущих значений и правил валидации. Это обратное от |
FFormField? get firstInvalidField |
Получает первое недействительное поле формы, если таковое имеется. Этот геттер используется для поиска первого поля, которое не прошло валидацию. |
FFormField? get lastInvalidField |
Получает последнее недействительное поле формы, если таковое имеется. Этот геттер используется для поиска последнего поля, которое не прошло валидацию. |
Методы |
Описание |
---|---|
void addListener(FFormListener listener) |
Добавляет слушателя, который будет вызываться при изменении состояния формы. Это полезно для обновления интерфейса или выполнения действий при изменении состояния формы. |
void removeListener(FFormListener listener) |
Удаляет ранее добавленного слушателя из формы. Это полезно для очистки слушателей, когда они больше не нужны. |
void notifyListeners() |
Уведомляет всех зарегистрированных слушателей об изменении состояния формы. Это используется для запуска обновлений в интерфейсе или других частях приложения, которые зависят от состояния формы. |
T get() |
Получает первое поле определенного типа из формы. Это полезно для доступа к конкретным полям без знания их точного положения в форме. |
FFormBuilder
FFormBuilder
— это виджет, который конструирует и управляет состоянием формы, используя потоки для динамического обновления интерфейса по мере изменения данных. Он предоставляет функцию построения, которая принимает форму и возвращает дерево виджетов на основе состояния формы.
Пример
Это пример того, как использовать FFormBuilder
для создания формы с одним полем. Функция построения принимает форму в качестве параметра и возвращает дерево виджетов на основе состояния формы.
void _submit() { if(_form.isValid) { // .isValid или .isInvalid запускают перестройку в FFormBuilder и возвращают boolean print('Форма валидна'); }; } @override Widget build(BuildContext context) { return FFormBuilder<LoginForm>( form: _form, builder: (context, form) { EmailField email = form.email; // или FFormProvider.of<LoginForm>(context).get<NameField>() return Column( children: [ TextField( key: email.key, controller: _emailController, decoration: InputDecoration( labelText: 'Email', errorText: email.exception.toString(), ), ), ElevatedButton( onPressed: _submit, child: const Text('Отправить'), ), ], ); }, ); }
FFormProvider
FFormProvider
— это виджет, который позволяет получить доступ к форме в дереве виджетов без передачи ее в качестве параметра.
Пример
FFormBuilder<LoginForm>( form: _form, builder: (context, form) { FFormProvider.of<LoginForm>(context).email; // или form.email; FFormProvider.of<LoginForm>(context).get<NameField>(); // или form.get<NameField>(); return YourForm(); }, )
FFormException
FFormException
— базовый класс для создания пользовательских исключений для полей формы. Он позволяет определять пользовательские правила валидации и сообщения об ошибках для полей формы, позволяя с легкостью обрабатывать сложные сценарии валидации.
Пример
Вы можете создать пользовательский класс исключения, который расширяет FFormException
, чтобы определить конкретные правила валидации и сообщения об ошибках для поля формы.
class PasswordValidationException extends FFormException { final bool isMinLengthValid; final bool isSpecialCharValid; final bool isNumberValid; PasswordValidationException({ required this.isMinLengthValid, required this.isSpecialCharValid, required this.isNumberValid, }); @override bool get isValid => isMinLengthValid && isSpecialCharValid && isNumberValid; } class PasswordField extends FFormField<String, PasswordValidationException> { PasswordField(String value) : super(value); @override PasswordValidationException? validator(String value) { final validator = FFormValidator(value); return PasswordValidationException( isMinLengthValid: validator.isMinLength(8), isSpecialCharValid: validator.isHaveSpecialChar, isNumberValid: validator.isHaveNumber, ); } }
API FFormException
Геттеры |
Описание |
---|---|
bool get isValid |
Возвращает |
Не стесняйтесь внести свой вклад в пакет или сообщить о любых проблемах в репозитории GitHub. Приятного кодирования! 🎉
ссылка на оригинал статьи https://habr.com/ru/articles/843778/
Добавить комментарий