النماذج في React: الحقول ومربعات الاختيار وselect والتحقق

يحتفظ نموذج React بقيمة كل حقل في الحالة: يعرض الحقل value={state} ويحدّثها بـ onChange. وعندما يرسل المستخدم، يستدعي معالج onSubmit الدالة e.preventDefault() لمنع إعادة تحميل الصفحة ثم يستخدم القيم الموجودة أصلًا في الحالة.

import { useState } from 'react';

export default function App() {
    const [name, setName] = useState('');
    const [greeting, setGreeting] = useState('');

    function handleSubmit(e) {
        e.preventDefault();
        setGreeting(`Hello, ${name || 'stranger'}!`);
    }

    return (
        <form onSubmit={handleSubmit}>
            <label>
                Name{' '}
                <input name="name" value={name} onChange={(e) => setName(e.target.value)} />
            </label>{' '}
            <button type="submit">Say hello</button>
            <p>{greeting}</p>
        </form>
    );
}

اكتب اسمًا واضغط Enter أو انقر الزر. ثم احذف السطر e.preventDefault();: تعرض المعاينة الحقول التي كان المتصفح سيرسلها في إرسال أصلي، وهو ما كان سيعيد تحميل الصفحة أيضًا في صفحة حقيقية.

الحقل الذي تأتي قيمته من الحالة يُسمى حقلًا متحكمًا به. أما البديل، أي ترك DOM يحتفظ بالقيمة وقراءتها لاحقًا، فتتناوله صفحة المكوّنات المتحكم بها وغير المتحكم بها.

الحقول النصية وtextarea

يعمل كل حقل نصي بالطريقة نفسها: value من الحالة، وonChange يقرأ e.target.value. ويتبع <textarea> النمط نفسه. في HTML يوضع نصه بين الوسمين، أما في React فتمرره على أنه value.

import { useState } from 'react';

export default function App() {
    const [title, setTitle] = useState('');
    const [body, setBody] = useState('');

    return (
        <div style={{ display: 'grid', gap: 8, maxWidth: 320 }}>
            <input
                value={title}
                onChange={(e) => setTitle(e.target.value.toUpperCase())}
                placeholder="Title (shouts)"
            />
            <textarea
                value={body}
                onChange={(e) => setBody(e.target.value)}
                rows={4}
                maxLength={140}
                placeholder="Up to 140 characters"
            />
            <small>{140 - body.length} characters left</small>
        </div>
    );
}

لأنك تضبط القيمة بنفسك، يمكنك تغيير ما كتبه المستخدم قبل أن يظهر: يحوّل حقل العنوان كل حرف إلى حرف كبير. ويتحدث عدّاد المحارف مع كل ضغطة مفتاح لأن body حالة وكل تغيير يعيد العرض.

Select

يأخذ <select> القيمة value على عنصر select نفسه، لا selected على أحد الخيارات. وe.target.value هي value الخيار المحدد.

import { useState } from 'react';

export default function App() {
    const [plan, setPlan] = useState('monthly');
    const prices = { monthly: '$12 a month', yearly: '$99 a year', free: '$0' };

    return (
        <div>
            <select value={plan} onChange={(e) => setPlan(e.target.value)}>
                <option value="free">Free</option>
                <option value="monthly">Monthly</option>
                <option value="yearly">Yearly</option>
            </select>
            <p>You pay {prices[plan]}.</p>
        </div>
    );
}

ولقائمة اختيار متعدد، أضف multiple ومرّر مصفوفة على أنها value. واقرأ الاختيارات بـ Array.from(e.target.selectedOptions, (o) => o.value).

مربع الاختيار والأزرار الدائرية

يُتحكم في مربع الاختيار بـ checked لا value، ويقرأ معالجه e.target.checked، وهي true أو false. وتتشارك الأزرار الدائرية في مجموعة واحدة الاسم name؛ ويكون كل منها محددًا عندما تساوي الحالة قيمته.

import { useState } from 'react';

export default function App() {
    const [newsletter, setNewsletter] = useState(false);
    const [size, setSize] = useState('m');

    return (
        <div>
            <label>
                <input
                    type="checkbox"
                    checked={newsletter}
                    onChange={(e) => setNewsletter(e.target.checked)}
                />
                Send me the newsletter
            </label>

            <p>Shirt size:</p>
            {['s', 'm', 'l'].map((s) => (
                <label key={s} style={{ marginInlineEnd: 12 }}>
                    <input
                        type="radio"
                        name="size"
                        value={s}
                        checked={size === s}
                        onChange={(e) => setSize(e.target.value)}
                    />
                    {s.toUpperCase()}
                </label>
            ))}

            <p>
                Size {size.toUpperCase()}, newsletter {newsletter ? 'on' : 'off'}.
            </p>
        </div>
    );
}

قراءة e.target.value على مربع اختيار خطأ شائع: لمربع اختيار بلا سمة value تُرجع النص "on" سواء أكان المربع محددًا أم لا.

كائن حالة واحد لحقول كثيرة

النموذج الذي فيه عشرة حقول لا يحتاج إلى عشرة استدعاءات لـ useState وعشرة معالجات. احتفظ بكائن واحد، وأعطِ كل حقل name يطابق مفتاحًا، واكتب معالجًا واحدًا يستخدم الاسم كمفتاح محسوب: [e.target.name].

import { useState } from 'react';

export default function App() {
    const [form, setForm] = useState({
        email: '',
        country: 'NO',
        terms: false,
    });

    function handleChange(e) {
        const { name, type, value, checked } = e.target;
        setForm({ ...form, [name]: type === 'checkbox' ? checked : value });
    }

    return (
        <div style={{ display: 'grid', gap: 8, maxWidth: 280 }}>
            <input name="email" value={form.email} onChange={handleChange} placeholder="Email" />
            <select name="country" value={form.country} onChange={handleChange}>
                <option value="NO">Norway</option>
                <option value="JP">Japan</option>
                <option value="BR">Brazil</option>
            </select>
            <label>
                <input name="terms" type="checkbox" checked={form.terms} onChange={handleChange} />
                I accept the terms
            </label>
            <pre>{JSON.stringify(form, null, 2)}</pre>
        </div>
    );
}

يفحص المعالج نوع الحقل ليخزّن مربع الاختيار قيمة منطقية وتخزّن البقية نصًا. أضف حقلًا بإضافة مفتاح إلى الكائن الابتدائي وحقل بالاسم name نفسه؛ ولا يحتاج المعالج إلى أي تغيير. يُبقي النشر كل حقل آخر (راجع تحديث المصفوفات والكائنات).

إرسال نموذج

ضع منطق الإرسال على onSubmit الخاص بالنموذج، لا على onClick الخاص بالزر. يُطلق onSubmit أيضًا عندما يضغط المستخدم Enter في حقل نصي، وهو ما سيفوت معالج النقر. الزر <button> داخل نموذج زر إرسال افتراضيًا؛ أعطِ الأزرار الأخرى type="button" حتى لا ترسل.

import { useState } from 'react';

export default function App() {
    const [form, setForm] = useState({ user: 'ada', password: '' });

    function handleChange(e) {
        setForm({ ...form, [e.target.name]: e.target.value });
    }

    function handleSubmit(e) {
        e.preventDefault();
        console.log('submitting', form);
    }

    return (
        <form onSubmit={handleSubmit}>
            <input name="user" value={form.user} onChange={handleChange} />{' '}
            <input name="password" type="password" value={form.password} onChange={handleChange} />{' '}
            <button type="button" onClick={() => setForm({ user: '', password: '' })}>
                Clear
            </button>{' '}
            <button type="submit">Log in</button>
        </form>
    );
}

افتح وحدة التحكم، واكتب كلمة مرور واضغط Enter: يسجّل النموذج الكائن كله. النقر على "Clear" لا يسجّل شيئًا، لأنه type="button". احذف تلك السمة فيبدأ Clear بالإرسال أيضًا.

التحقق وعرض الأخطاء

التحقق البسيط دالة تأخذ القيم وتُرجع كائنًا من الرسائل. شغّلها عند الإرسال، وخزّن النتيجة في الحالة، واعرض كل رسالة تحت حقلها. عطّل زر الإرسال أثناء تنفيذ طلب حتى لا يرسل النقر المزدوج النموذج مرتين.

import { useState } from 'react';

function validate({ email, age }) {
    const errors = {};
    if (!email.includes('@')) errors.email = 'Enter a valid email.';
    if (!age || Number(age) < 13) errors.age = 'You must be 13 or older.';
    return errors;
}

function saveProfile(data) {
    return new Promise((resolve) => setTimeout(() => resolve(data), 800));
}

export default function App() {
    const [form, setForm] = useState({ email: '', age: '' });
    const [errors, setErrors] = useState({});
    const [status, setStatus] = useState('idle');

    async function handleSubmit(e) {
        e.preventDefault();
        const found = validate(form);
        setErrors(found);
        if (Object.keys(found).length > 0) return;
        setStatus('saving');
        await saveProfile(form);
        setStatus('saved');
    }

    const change = (e) => setForm({ ...form, [e.target.name]: e.target.value });
    const error = { color: 'crimson', margin: '4px 0 8px', fontSize: 13 };

    return (
        <form onSubmit={handleSubmit} noValidate>
            <input name="email" value={form.email} onChange={change} placeholder="Email" />
            {errors.email && <p style={error}>{errors.email}</p>}
            <input name="age" type="number" value={form.age} onChange={change} placeholder="Age" />
            {errors.age && <p style={error}>{errors.age}</p>}
            <div style={{ marginTop: 8 }}>
                <button disabled={status === 'saving'}>
                    {status === 'saving' ? 'Saving...' : 'Save'}
                </button>
                {status === 'saved' && ' Saved.'}
            </div>
        </form>
    );
}

انقر Save والحقول فارغة لترى الرسالتين، ثم املأها. saveProfile بديل عن طلب حقيقي: ينتظر 800 جزء من الثانية ثم يُحل. تُطفئ السمة noValidate فقاعات التحقق الخاصة بالمتصفح فلا تظهر إلا رسائلك؛ احذفها وأضف required إلى حقل لتقارن.

يمكن أيضًا حساب الأخطاء أثناء العرض بدلًا من تخزينها، مثل const emailError = form.email && !form.email.includes('@')، الذي يعرض الرسالة أثناء الكتابة. اختر التوقيت الذي يناسب النموذج: عند الإرسال أهدأ، وأثناء الكتابة يعطي ملاحظات أسرع.

إجراءات النماذج في React 19

تضيف React 19 طريقة أخرى للتعامل مع النموذج. مرّر دالة إلى الـ prop المسماة action في النموذج. تمنع React إعادة تحميل الصفحة نيابة عنك وتستدعي الدالة مع كائن FormData يحمل كل حقل له name. لا تحتاج الحقول إلى حالة على الإطلاق: فهي غير متحكم بها، وتفرّغها React بعد انتهاء الإجراء.

import { useState } from 'react';

function addComment(text) {
    return new Promise((resolve) => setTimeout(() => resolve(text), 500));
}

export default function App() {
    const [comments, setComments] = useState([]);

    async function postComment(formData) {
        const text = formData.get('comment');
        console.log('action received', text);
        const saved = await addComment(text);
        setComments((list) => [...list, saved]);
    }

    return (
        <form action={postComment}>
            <input name="comment" defaultValue="Nice docs" />{' '}
            <button type="submit">Post</button>
            <ul>
                {comments.map((c, i) => (
                    <li key={i}>{c}</li>
                ))}
            </ul>
        </form>
    );
}

اكتب تعليقك وانشره. تعرض القائمة نصك، ويعود الحقل إلى Nice docs: بعد أن يُحل الإجراء، تعيد React ضبط الحقول غير المتحكم بها إلى defaultValue الخاصة بها. يمكن للإجراء أن يكون غير متزامن، وأثناء تنفيذه تعامل React التحديث كانتقال.

لعرض حالة انتظار أو خطأ من الإجراء، غلّفه بـ useActionState، الذي يُرجع أحدث نتيجة، وإجراءً مغلّفًا للنموذج، وعلامة isPending. ويمكن لزر في عمق النموذج أيضًا قراءة حالة الانتظار بـ useFormStatus من react-dom:

import { useFormStatus } from 'react-dom';

function SubmitButton() {
    const { pending } = useFormStatus();
    return <button disabled={pending}>{pending ? 'Posting...' : 'Post'}</button>;
}

لا يُحمَّل useFormStatus في المحررات هنا، فلا يظهر إلا في هذه الكتلة الثابتة. يجب أن يُستدعى من مكوّن يُعرض داخل <form>، لا في المكوّن الذي يعرض النموذج.

كل من الحالة المتحكم بها مع onSubmit وإجراءات النماذج مع FormData يعمل في React 19. تناسب الحقول المتحكم بها النماذج التي تتفاعل أثناء الكتابة (التحقق المباشر، أو عدّاد المحارف، أو حقول يعتمد بعضها على بعض). وتناسب الإجراءات النماذج التي لا تحتاج فيها إلى القيم إلا عندما يرسل المستخدم.