← ライブラリ一覧に戻る

Form Builder Validators

Flutter Form Builder用の包括的な検証ライブラリ。一般的なバリデータセットとカスタムバリデータの作成方法を提供

Form Builder Validators {#form-builder-validators}

Form Builder Validatorsは、FormFieldウィジェットまたはFormFieldクラスを拡張するウィジェット（TextFormField、DropdownFormFieldなど）用のバリデータセットです。標準的な既製の検証ルールと、カスタムルールを含む複数のルールを組み合わせて新しい検証ルールを作成する方法を提供します。

また、エラーテキストメッセージの多言語対応（l10n/i18n）も含まれています。

主な特徴 {#features}

  • 既製の検証ルール
  • 複数の再利用可能な検証ルールの組み合わせ
  • 多言語でのデフォルトエラーメッセージ
  • Flutter Form Builderエコシステムとのシームレスな統合

インストール {#installation}

pubspec.yamlに以下を追加：

dependencies:
  form_builder_validators: ^11.2.0

セットアップ {#setup}

デフォルトのエラーメッセージは英語です。アプリ内でデフォルトエラーメッセージのローカライゼーションを可能にするには、アプリのlocalizationsDelegatesリストにFormBuilderLocalizations.delegateを追加します：

return MaterialApp(
  supportedLocales: [
    Locale('ja'),
    Locale('en'),
    Locale('es'),
    Locale('fr'),
    // その他のロケール
  ],
  localizationsDelegates: [
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    FormBuilderLocalizations.delegate,
  ],
  // ...
);

基本的な使用方法 {#basic-usage}

TextFormField(
  decoration: InputDecoration(labelText: '名前'),
  autovalidateMode: AutovalidateMode.always,
  validator: FormBuilderValidators.required(),
),

利用可能なバリデータ {#available-validators}

Boolバリデータ {#bool-validators}

  • FormBuilderValidators.hasLowercaseChars() - 指定数の小文字を含むことを要求
  • FormBuilderValidators.hasNumericChars() - 指定数の数字を含むことを要求
  • FormBuilderValidators.hasSpecialChars() - 指定数の特殊文字を含むことを要求
  • FormBuilderValidators.hasUppercaseChars() - 指定数の大文字を含むことを要求
  • FormBuilderValidators.isFalse() - 値がfalseであることを要求
  • FormBuilderValidators.isTrue() - 値がtrueであることを要求

コレクションバリデータ {#collection-validators}

  • FormBuilderValidators.containsElement() - 値が提供されたリストに含まれることを要求
  • FormBuilderValidators.equalLength() - 値の長さが指定された長さと等しいことを要求
  • FormBuilderValidators.maxLength() - 値の長さが最大値以下であることを要求
  • FormBuilderValidators.minLength() - 値の長さが最小値以上であることを要求
  • FormBuilderValidators.range() - 値が範囲内にあることを要求
  • FormBuilderValidators.unique() - 値がリスト内で一意であることを要求

コアバリデータ {#core-validators}

  • FormBuilderValidators.aggregate() - バリデータを並列実行し、すべてのエラーを収集
  • FormBuilderValidators.compose() - 複数のバリデータを組み合わせて実行
  • FormBuilderValidators.conditional() - 条件付きでバリデータを実行
  • FormBuilderValidators.defaultValue() - 値がnullの場合にデフォルト値を使用してバリデータを実行
  • FormBuilderValidators.equal() - 値が指定されたオブジェクトと等しいことを要求
  • FormBuilderValidators.log() - 検証チェーンの特定のポイントで値をログ出力
  • FormBuilderValidators.notEqual() - 値が指定されたオブジェクトと等しくないことを要求
  • FormBuilderValidators.or() - いずれかのバリデータが成功すれば合格
  • FormBuilderValidators.required() - 必須フィールド検証
  • FormBuilderValidators.skipWhen() - 特定の条件が満たされた場合に検証をスキップ
  • FormBuilderValidators.transform() - バリデータ実行前に値を変換

日時バリデータ {#datetime-validators}

  • FormBuilderValidators.dateFuture() - 値が未来の日付であることを要求
  • FormBuilderValidators.datePast() - 値が過去の日付であることを要求
  • FormBuilderValidators.dateRange() - 値が日付範囲内にあることを要求
  • FormBuilderValidators.dateTime() - 有効な日時であることを要求
  • FormBuilderValidators.date() - 有効な日付文字列であることを要求
  • FormBuilderValidators.time() - 有効な時刻文字列であることを要求
  • FormBuilderValidators.timeZone() - 有効なタイムゾーンであることを要求

ファイルバリデータ {#file-validators}

  • FormBuilderValidators.fileExtension() - 有効なファイル拡張子であることを要求
  • FormBuilderValidators.fileName() - 有効なファイル名であることを要求
  • FormBuilderValidators.fileSize() - ファイルサイズが最大値以下であることを要求
  • FormBuilderValidators.mimeType() - 有効なMIMEタイプであることを要求
  • FormBuilderValidators.path() - 有効なファイルまたはフォルダパスであることを要求

金融バリデータ {#finance-validators}

  • FormBuilderValidators.bic() - 有効なBICであることを要求
  • FormBuilderValidators.creditCardCVC() - 有効なクレジットカードCVC番号であることを要求
  • FormBuilderValidators.creditCardExpirationDate() - 有効なクレジットカード有効期限であることを要求
  • FormBuilderValidators.creditCard() - 有効なクレジットカード番号であることを要求
  • FormBuilderValidators.iban() - 有効なIBANであることを要求

個人情報バリデータ {#identity-validators}

  • FormBuilderValidators.city() - 有効な都市名であることを要求
  • FormBuilderValidators.country() - 有効な国名であることを要求
  • FormBuilderValidators.firstName() - 有効な名前であることを要求
  • FormBuilderValidators.lastName() - 有効な姓であることを要求
  • FormBuilderValidators.passportNumber() - 有効なパスポート番号であることを要求
  • FormBuilderValidators.password() - 必要な条件を満たすパスワードであることを要求
  • FormBuilderValidators.ssn() - 有効なSSN（社会保障番号）であることを要求
  • FormBuilderValidators.state() - 有効な州名であることを要求
  • FormBuilderValidators.street() - 有効な通り名であることを要求
  • FormBuilderValidators.username() - 必要な条件を満たすユーザー名であることを要求
  • FormBuilderValidators.zipCode() - 有効な郵便番号であることを要求

ネットワークバリデータ {#network-validators}

  • FormBuilderValidators.email() - 有効なメールアドレスであることを要求
  • FormBuilderValidators.ip() - 有効なIPアドレスであることを要求
  • FormBuilderValidators.latitude() - 有効な緯度であることを要求
  • FormBuilderValidators.longitude() - 有効な経度であることを要求
  • FormBuilderValidators.macAddress() - 有効なMACアドレスであることを要求
  • FormBuilderValidators.phoneNumber() - 有効な電話番号であることを要求
  • FormBuilderValidators.portNumber() - 有効なポート番号であることを要求
  • FormBuilderValidators.url() - 有効なURLであることを要求

数値バリデータ {#numeric-validators}

  • FormBuilderValidators.between() - 値が2つの数値の間にあることを要求
  • FormBuilderValidators.evenNumber() - 偶数であることを要求
  • FormBuilderValidators.integer() - 整数であることを要求
  • FormBuilderValidators.max() - 値が最大値以下であることを要求
  • FormBuilderValidators.min() - 値が最小値以上であることを要求
  • FormBuilderValidators.negativeNumber() - 負の数であることを要求
  • FormBuilderValidators.notZeroNumber() - ゼロでないことを要求
  • FormBuilderValidators.numeric() - 有効な数値であることを要求
  • FormBuilderValidators.oddNumber() - 奇数であることを要求
  • FormBuilderValidators.positiveNumber() - 正の数であることを要求
  • FormBuilderValidators.prime() - 素数であることを要求

文字列バリデータ {#string-validators}

  • FormBuilderValidators.alphabetical() - アルファベット文字のみを含むことを要求
  • FormBuilderValidators.contains() - 部分文字列を含むことを要求
  • FormBuilderValidators.endsWith() - 指定された文字列で終わることを要求
  • FormBuilderValidators.lowercase() - 小文字であることを要求
  • FormBuilderValidators.matchNot() - 正規表現パターンと一致しないことを要求
  • FormBuilderValidators.match() - 正規表現パターンと一致することを要求
  • FormBuilderValidators.maxWordsCount() - 単語数が最大値以下であることを要求
  • FormBuilderValidators.minWordsCount() - 単語数が最小値以上であることを要求
  • FormBuilderValidators.singleLine() - 単一行のテキストであることを要求
  • FormBuilderValidators.startsWith() - 指定された文字列で始まることを要求
  • FormBuilderValidators.uppercase() - 大文字であることを要求

ユースケースバリデータ {#use-case-validators}

  • FormBuilderValidators.base64() - 有効なbase64文字列であることを要求
  • FormBuilderValidators.colorCode() - 有効なカラーコードであることを要求
  • FormBuilderValidators.duns() - 有効なDUNS番号であることを要求
  • FormBuilderValidators.isbn() - 有効なISBNであることを要求
  • FormBuilderValidators.json() - 有効なJSON文字列であることを要求
  • FormBuilderValidators.languageCode() - 有効な言語コードであることを要求
  • FormBuilderValidators.licensePlate() - 有効なナンバープレートであることを要求
  • FormBuilderValidators.uuid() - 有効なUUIDであることを要求
  • FormBuilderValidators.vin() - 有効なVIN番号であることを要求

高度な使用方法 {#advanced-usage}

複数のバリデータの組み合わせ {#composing-validators}

FormBuilderValidators.compose()を使用して、複数のバリデータを組み合わせることができます：

TextFormField(
  decoration: InputDecoration(labelText: '年齢'),
  keyboardType: TextInputType.number,
  autovalidateMode: AutovalidateMode.always,
  validator: FormBuilderValidators.compose([
    // 必須フィールドにする
    FormBuilderValidators.required(),
    
    // 数値入力を確保（カスタムエラーメッセージ付き）
    FormBuilderValidators.numeric(errorText: '年齢は数値である必要があります'),
    
    // 最大値を70に設定
    FormBuilderValidators.max(70),
    
    // カスタムバリデータ関数を含める
    (val) {
      final number = int.tryParse(val ?? '');
      if (number == null) return null;
      if (number < 0) return '年齢は負の値にできません';
      return null;
    },
  ]),
),

拡張メソッドバリデータ {#extension-validators}

バリデータの連鎖と組み合わせのための拡張メソッド：

// AND演算子でバリデータを組み合わせる
final validator = FormBuilderValidators.required()
    .and(FormBuilderValidators.email());

// OR演算子でバリデータを組み合わせる
final validator = FormBuilderValidators.email()
    .or(FormBuilderValidators.phoneNumber());

// 条件付きバリデータ
final validator = FormBuilderValidators.required()
    .when((value) => someCondition);

// エラーメッセージのオーバーライド
final validator = FormBuilderValidators.email()
    .withErrorMessage('有効なメールアドレスを入力してください');

カスタムバリデータの作成 {#custom-validators}

BaseValidatorまたはTranslatedValidatorクラスを使用してカスタムバリデータを実装できます：

class CustomValidator extends BaseValidator<String> {
  CustomValidator({String? errorText, bool checkNullOrEmpty = true})
      : super(errorText: errorText, checkNullOrEmpty: checkNullOrEmpty);

  @override
  String? validateValue(String? value, FormFieldState<String> field) {
    // カスタム検証ロジックをここに実装
    if (value != null && !isValidCustomFormat(value)) {
      return errorText ?? 'カスタム形式が無効です';
    }
    return null;
  }
  
  bool isValidCustomFormat(String value) {
    // カスタム検証ロジック
    return true;
  }
}

Flutter Form Builderとの統合 {#flutter-form-builder-integration}

Form Builder Validatorsは、Flutter Form Builderとシームレスに動作します：

import 'package:flutter_form_builder/flutter_form_builder.dart';
import 'package:form_builder_validators/form_builder_validators.dart';

FormBuilder(
  key: _formKey,
  child: Column(
    children: [
      FormBuilderTextField(
        name: 'email',
        decoration: InputDecoration(labelText: 'メールアドレス'),
        validator: FormBuilderValidators.compose([
          FormBuilderValidators.required(),
          FormBuilderValidators.email(),
        ]),
      ),
      FormBuilderTextField(
        name: 'password',
        decoration: InputDecoration(labelText: 'パスワード'),
        obscureText: true,
        validator: FormBuilderValidators.compose([
          FormBuilderValidators.required(),
          FormBuilderValidators.minLength(8),
          FormBuilderValidators.hasUppercaseChars(
            atLeast: 1,
            errorText: '少なくとも1つの大文字を含む必要があります',
          ),
          FormBuilderValidators.hasNumericChars(
            atLeast: 1,
            errorText: '少なくとも1つの数字を含む必要があります',
          ),
        ]),
      ),
    ],
  ),
),

サポート言語 {#supported-languages}

Form Builder Validatorsは、日本語を含む40以上の言語でデフォルトのエラーメッセージをサポートしています。サポートされている言語の完全なリストには以下が含まれます：

  • 日本語 (ja)
  • 英語 (en)
  • 中国語簡体字 (zh_Hans)
  • 中国語繁体字 (zh_Hant)
  • 韓国語 (ko)
  • その他多数

パフォーマンスの最適化 {#performance-optimization}

  • autovalidateModeを適切に設定して、不要な検証を避ける
  • 複雑な検証ロジックにはskipWhenを使用して条件付き検証を実装
  • 大量のフィールドがある場合は、FormBuilderValidators.aggregate()を使用して並列検証を実行

まとめ {#conclusion}

Form Builder Validatorsは、Flutterアプリケーションでフォーム検証を実装するための包括的で使いやすいソリューションを提供します。豊富な組み込みバリデータ、多言語サポート、カスタムバリデータの作成機能により、あらゆる検証ニーズに対応できます。