ساخت فرم‌ها، دریافت ورودی و اعتبارسنجی (Form و TextFormField)

Build a form with validation

راهنمای رسمی ساخت فرم‌های تعاملی در Flutter با استفاده از Form، GlobalKey، TextFormField و TextEditingController

فهرست مطالب این صفحه

در اکثر اپلیکیشن‌ها، فرم‌ها ابزار اصلی دریافت اطلاعات از کاربر (مانند ورود، ثبت‌نام یا جست‌وجو) هستند. Flutter ویجت Form را برای گروه‌بندی چندین فیلد ورودی و اعتبارسنجی یکپارچه آن‌ها ارائه می‌دهد.

مراحل ساخت فرم دارای اعتبارسنجی

  1. ایجاد ویجت Form همراه با یک GlobalKey<FormState>: این کلید به شما امکان می‌دهد وضعیت فرم را در هر لحظه شناسایی و متد validate() را فراخوانی کنید.
  2. افزودن فیلدهای TextFormField با تابع validator: تابع validator متن واردشده توسط کاربر را دریافت می‌کند؛ اگر متن نامعتبر باشد یک رشته فارسی خطا برمی‌گرداند و اگر معتبر باشد مقدار null برمی‌گرداند.
  3. ایجاد دکمه ثبت (Submit) برای بررسی و ارسال فرم: با فشردن دکمه، متد _formKey.currentState!.validate() اجرا می‌شود و تمام پیام‌های خطا به‌صورت خودکار زیر فیلدهای نامعتبر نمایش داده می‌شوند.
Dart
import 'package:flutter/material.dart';

class LoginFormScreen extends StatefulWidget {
  const LoginFormScreen({super.key});

  @override
  State<LoginFormScreen> createState() => _LoginFormScreenState();
}

class _LoginFormScreenState extends State<LoginFormScreen> {
  final _formKey = GlobalKey<FormState>();
  final _emailController = TextEditingController();
  final _passwordController = TextEditingController();

  @override
  void dispose() {
    _emailController.dispose();
    _passwordController.dispose();
    super.dispose();
  }

  void _submitForm() {
    if (_formKey.currentState!.validate()) {
      final email = _emailController.text.trim();
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text('اطلاعات معتبر است. خوش آمدید: $email')),
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    return Form(
      key: _formKey,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        children: [
          TextFormField(
            controller: _emailController,
            keyboardType: TextInputType.emailAddress,
            decoration: const InputDecoration(
              labelText: 'ایمیل',
              hintText: 'example@domain.com',
              border: OutlineInputBorder(),
            ),
            validator: (value) {
              if (value == null || value.trim().isEmpty) {
                return 'لطفاً آدرس ایمیل را وارد کنید';
              }
              if (!value.contains('@')) {
                return 'فرمت ایمیل واردشده معتبر نیست';
              }
              return null;
            },
          ),
          const SizedBox(height: 16),
          TextFormField(
            controller: _passwordController,
            obscureText: true,
            decoration: const InputDecoration(
              labelText: 'رمز عبور',
              border: OutlineInputBorder(),
            ),
            validator: (value) {
              if (value == null || value.length < 8) {
                return 'رمز عبور باید حداقل ۸ کاراکتر باشد';
              }
              return null;
            },
          ),
          const SizedBox(height: 20),
          ElevatedButton(
            onPressed: _submitForm,
            child: const Text('ورود به حساب'),
          ),
        ],
      ),
    );
  }
}

نکته: همیشه TextEditingController را در متد dispose() آزاد کنید تا از مصرف بیهوده حافظه جلوگیری شود.