Упрощение управления формами во Flutter с помощью пакета FForm

Начало работы с 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	Указывает, приводит ли каждое обновление поля к перестройке FFormBuilder. Это используется для определения необходимости перестраивать форму при каждом обновлении поля.
List get fields	Получает список полей формы. Этот геттер используется для доступа ко всем полям, которые являются частью формы.
List get subForms	Получает список подформ в форме. Это используется, когда форма содержит вложенные формы, позволяя получить доступ к этим подформам.
List get answers	Получает список ответов из полей формы. Этот геттер собирает текущие значения всех полей формы.
List get exceptions	Получает список исключений валидации из полей формы. Это используется для сбора всех ошибок валидации, присутствующих в полях формы.
bool get isValid	Проверяет, валидна ли вся форма на основе текущих значений и правил валидации. Этот геттер оценивает валидность формы, проверяя состояние валидации каждого поля, и вызывает notifyListeners().
bool get isInvalid	Проверяет, является ли вся форма недействительной на основе текущих значений и правил валидации. Это обратное от isValid и используется для быстрого определения, есть ли в форме недействительные поля.
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	Возвращает true, если поле формы валидно на основе текущего значения и правил валидации.

Не стесняйтесь внести свой вклад в пакет или сообщить о любых проблемах в репозитории GitHub. Приятного кодирования! 🎉