المكوّنات المتحكم بها وغير المتحكم بها في React

المكوّن المتحكم به عنصر نموذج تعيش قيمته في حالة React: تمرر value وتحدّث الحالة في onChange، فتقرر React ما يعرضه الحقل. والمكوّن غير المتحكم به يحتفظ بقيمته في DOM، مثل HTML العادية: تمرر defaultValue ابتدائية وتقرأ القيمة الحالية لاحقًا عبر مرجع أو FormData.

import { useRef, useState } from 'react';

export default function App() {
    const [controlled, setControlled] = useState('Ada');
    const uncontrolledRef = useRef(null);

    function readBoth() {
        console.log('controlled:', controlled);
        console.log('uncontrolled:', uncontrolledRef.current.value);
    }

    return (
        <div style={{ display: 'grid', gap: 8, maxWidth: 260 }}>
            <input
                value={controlled}
                onChange={(e) => setControlled(e.target.value)}
            />
            <input defaultValue="Linus" ref={uncontrolledRef} />
            <p>Controlled value in state: {controlled}</p>
            <button onClick={readBoth}>Read both</button>
        </div>
    );
}

اكتب في الحقلين. تتبع الفقرة الحقل الأول مع كل ضغطة مفتاح، لأن كل تغيير يضبط الحالة ويعيد العرض. أما الحقل الثاني فلا يتغير إلا في DOM؛ لا تعرض React شيئًا، ولا ترى قيمته إلا عندما يطلبها "Read both".

الحقول المتحكم بها

في الحقل المتحكم به، حالة React هي المصدر الوحيد للحقيقة. ويكون التدفق مع كل ضغطة مفتاح كالآتي:

1. يكتب المستخدم، فيطلق المتصفح حدث إدخال.
2. يقرأ معالج onChange القيمة e.target.value ويستدعي دالة الضبط.
3. تعيد React العرض وتكتب الحالة الجديدة في value الخاصة بالحقل.

لأن كودك يقع في منتصف هذه الحلقة، يمكنك فعل أشياء لا يستطيعها الحقل غير المتحكم به: رفض المحارف أو إعادة تشكيلها، أو عرض القيمة في مكان آخر، أو تعطيل زر حتى تصبح القيمة صالحة، أو ضبط القيمة من الكود (زر "Clear"، أو اقتراح ينقره المستخدم).

import { useState } from 'react';

export default function App() {
    const [code, setCode] = useState('');

    function handleChange(e) {
        const digits = e.target.value.replace(/\D/g, '').slice(0, 6);
        setCode(digits);
    }

    return (
        <div>
            <input
                value={code}
                onChange={handleChange}
                placeholder="6 digit code"
                style={{ letterSpacing: 6, fontSize: 18, width: 150 }}
            />{' '}
            <button disabled={code.length !== 6}>Verify</button>{' '}
            <button onClick={() => setCode('123456')}>Fill demo code</button>
        </div>
    );
}

جرّب كتابة أحرف: لا تظهر أبدًا، لأن المعالج يحذف كل ما ليس رقمًا قبل ضبط الحالة. ويبقى زر Verify معطّلًا حتى توجد ستة أرقام بالضبط.

الحقل المتحكم به هو ما تستخدمه أمثلة النماذج في صفحة النماذج، وهو الخيار الافتراضي في معظم كود React.

الحقول غير المتحكم بها

يعمل الحقل غير المتحكم به مثل HTML العادية. تعرضه React مرة واحدة بـ defaultValue (أو defaultChecked لمربعات الاختيار والأزرار الدائرية) ثم تتركه وشأنه. لقراءة القيمة، احتفظ بمرجع إلى العنصر أو اقرأ كل الحقول المسماة من النموذج عند الإرسال بـ FormData.

import { useState } from 'react';

export default function App() {
    const [result, setResult] = useState(null);

    function handleSubmit(e) {
        e.preventDefault();
        const data = new FormData(e.target);
        setResult(Object.fromEntries(data));
    }

    return (
        <form onSubmit={handleSubmit}>
            <input name="city" defaultValue="Oslo" />{' '}
            <label>
                <input name="subscribe" type="checkbox" defaultChecked />
                Subscribe
            </label>{' '}
            <button type="submit">Send</button>
            {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
        </form>
    );
}

لا توجد حالة للحقول ولا onChange. لا تُجمع القيم إلا عندما يُرسل النموذج. ألغِ تحديد مربع الاختيار وأرسل مرة أخرى: يختفي المفتاح subscribe، لأن مربع الاختيار غير المحدد ليس جزءًا من FormData إطلاقًا.

تغيير defaultValue بعد العرض الأول لا يفعل شيئًا للحقل، لأن React لا تطبقها إلا عند إنشاء العنصر. ولإعادة ضبط نموذج غير متحكم به، استدعِ e.target.reset()، أو أعطِ النموذج key جديدًا لتنشئ React حقولًا جديدة.

حقل لا تستطيع الكتابة فيه

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

import { useState } from 'react';

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

    return (
        <div style={{ display: 'grid', gap: 8, maxWidth: 260 }}>
            <input value={name} />
            <input value={name} onChange={(e) => setName(e.target.value)} />
            <input defaultValue={name} />
            <input value={name} readOnly />
        </div>
    );
}

جرّب الكتابة في كل حقل. الأول لا يتغير. والثاني هو الإصلاح لحقل متحكم به، وأثناء الكتابة فيه يتبعه الحقلان الأول والأخير، لأن الثلاثة تقرأ الحالة نفسها. والثالث يقبل الكتابة لأنه غير متحكم به. والرابع يقول عمدًا إنه لا يمكن تعديله.

في التطوير، تسجّل React تحذيرًا للحقل الأول: "You provided a value prop to a form field without an onChange handler". تعمل المعاينة مثل بناء الإنتاج، فلن ترى هذا التحذير هنا، لكنك ستراه في خادم التطوير الخاص بك.

التحول من غير متحكم به إلى متحكم به

تقرر React ما إذا كان الحقل متحكمًا به بالنظر إلى value. إذا كانت value هي undefined أو null، فالحقل غير متحكم به. لذا فإن حقلًا تبدأ value الخاصة به على أنها undefined ثم تصبح نصًا يتحول من غير متحكم به إلى متحكم به أثناء حياته، وتحذّر React في التطوير: "A component is changing an uncontrolled input to be controlled".

يشير التحذير إلى خطأ حقيقي. فالعودة في الاتجاه المعاكس، من نص إلى undefined، تجعل الحقل غير متحكم به من جديد، فتتوقف React عن الكتابة فيه.

import { useState } from 'react';

export default function App() {
    const [buggy, setBuggy] = useState(undefined);
    const [fixed, setFixed] = useState('');

    return (
        <div style={{ display: 'grid', gap: 8, maxWidth: 300 }}>
            <input
                value={buggy}
                onChange={(e) => setBuggy(e.target.value)}
                placeholder="Starts as undefined"
            />
            <button onClick={() => setBuggy(undefined)}>Clear first</button>
            <input
                value={fixed}
                onChange={(e) => setFixed(e.target.value)}
                placeholder="Starts as an empty string"
            />
            <button onClick={() => setFixed('')}>Clear second</button>
        </div>
    );
}

اكتب شيئًا في الحقلين واضغط كل زر Clear. يُفرَّغ الحقل الثاني. أما الأول فيحتفظ بنصه: ضبط الحالة على undefined جعله غير متحكم به، فلم تعد React تتحكم في ما يعرضه.

المصدر المعتاد لـ undefined هو بيانات لم تُحمَّل بعد (value={user.name} قبل وصول المستخدم) أو حقل في كائن لم يوجد بعد. وهناك إصلاحان:

const [name, setName] = useState('');   // start with a string
<input value={user?.name ?? ''} />       // or fall back to one

وفي مربعات الاختيار تنطبق القاعدة نفسها على checked: ابدأها بـ false، لا undefined.

حقول الملفات غير متحكم بها دائمًا

لا يمكن التحكم في <input type="file">، لأن المتصفحات لا تسمح للصفحة بضبط قيمته (فالصفحة التي تستطيع اختيار ملفات من قرصك ستكون ثغرة أمنية). اقرأ الملفات المختارة من e.target.files في onChange، أو عبر مرجع عندما يُرسل النموذج.

import { useRef, useState } from 'react';

export default function App() {
    const inputRef = useRef(null);
    const [files, setFiles] = useState([]);

    function handleChange(e) {
        setFiles(Array.from(e.target.files, (f) => `${f.name} (${f.size} bytes)`));
    }

    function clear() {
        inputRef.current.value = '';
        setFiles([]);
    }

    return (
        <div>
            <input type="file" multiple ref={inputRef} onChange={handleChange} />
            <button onClick={clear}>Clear</button>
            <ul>
                {files.map((f) => (
                    <li key={f}>{f}</li>
                ))}
            </ul>
            {files.length === 0 && <p>No files chosen.</p>}
        </div>
    );
}

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

متى تختار أيًا منهما

اختر المتحكم به عندما يجب أن تتفاعل الشاشة مع القيمة أثناء الكتابة. واختر غير المتحكم به عندما لا تحتاج إلى القيم إلا في النهاية، وهذه أيضًا طريقة عمل إجراءات النماذج في React 19: يسلّم <form action={fn}> دالتك FormData ويعيد ضبط الحقول غير المتحكم بها بعد ذلك.

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

تصف الكلمتان نفسهما مكوّناتك الخاصة أيضًا. المكوّن الذي يأخذ قيمته وonChange من أبيه عبر props متحكم به من الأب؛ والذي يحتفظ بحالته الخاصة غير متحكم به. ونقل الحالة إلى الأعلى لجعل مكوّن متحكمًا به هو موضوع رفع الحالة.