קומפוננטות מבוקרות מול לא מבוקרות ב-React

קומפוננטה מבוקרת (controlled) היא אלמנט טופס שהערך שלו חי ב-state של React: מעבירים value ומעדכנים את ה-state ב-onChange, כך ש-React מחליטה מה השדה מציג. קומפוננטה לא מבוקרת (uncontrolled) שומרת את הערך שלה ב-DOM, כמו HTML רגיל: מעבירים defaultValue התחלתי וקוראים את הערך הנוכחי אחר כך דרך ref או 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>
    );
}

הקלידו בשני השדות. הפסקה עוקבת אחרי הראשון בכל הקשה, כי כל שינוי קובע state ומרנדר שוב. השדה השני משתנה רק ב-DOM; React לא מרנדרת, ואת הערך שלו רואים רק כש-"Read both" מבקש אותו.

שדות מבוקרים

בשדה מבוקר, ה-state של React הוא מקור האמת היחיד. הזרימה בכל הקשה היא:

1. המשתמש מקליד, והדפדפן מפעיל אירוע input.
2. ה-handler של onChange קורא את e.target.value וקורא ל-setter.
3. React מרנדרת שוב וכותבת את ה-state החדש בחזרה לתוך ה-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>
    );
}

נסו להקליד אותיות: הן אף פעם לא מופיעות, כי ה-handler מסיר כל מה שאינו ספרה לפני שהוא קובע state. כפתור ה-Verify נשאר מושבת עד שיש בדיוק שש ספרות.

שדות מבוקרים הם מה שדוגמאות הטפסים ב-דף הטפסים משתמשות בו, וזו בחירת ברירת המחדל ברוב קוד ה-React.

שדות לא מבוקרים

שדה לא מבוקר עובד כמו HTML רגיל. React מרנדרת אותו פעם אחת עם defaultValue (או defaultChecked ב-checkboxes ורדיו) ואז עוזבת אותו. כדי לקרוא את הערך, או שמחזיקים ref לאלמנט או שקוראים את כל השדות בעלי שם מהטופס בשליחה עם 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>
    );
}

אין state לשדות ואין onChange. הערכים נאספים רק כשהטופס נשלח. בטלו את הסימון ב-checkbox ושלחו שוב: המפתח subscribe נעלם, כי checkbox לא מסומן לא נכלל ב-FormData בכלל.

שינוי של defaultValue אחרי הרינדור הראשון לא עושה כלום לשדה, כי React מחילה אותו רק כשהאלמנט נוצר. כדי לאפס טופס לא מבוקר, קראו ל-e.target.reset(), או תנו לטופס key חדש כדי ש-React תיצור שדות חדשים.

שדה שאי אפשר להקליד בו

אם מעבירים value אבל לא onChange, השדה מבוקר, אבל שום דבר אף פעם לא מעדכן את ה-state. 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>
    );
}

נסו להקליד בכל שדה. הראשון לא משתנה. השני הוא התיקון לשדה מבוקר, וכשמקלידים בו, השדה הראשון והאחרון עוקבים אחריו, כי שלושתם קוראים את אותו state. השלישי מקבל הקלדה כי הוא לא מבוקר. הרביעי אומר בכוונה שאי אפשר לערוך אותו.

בפיתוח, React רושמת אזהרה על השדה הראשון: "You provided a value prop to a form field without an onChange handler". התצוגה המקדימה רצה כמו build של פרודקשן, אז לא תראו כאן את האזהרה הזו, אבל תראו אותה בשרת הפיתוח שלכם.

מעבר מלא מבוקר למבוקר

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. השדה השני מתרוקן. הראשון שומר על הטקסט שלו: קביעת ה-state ל-undefined הפכה אותו ללא מבוקר, ולכן React כבר לא שולטת במה שהוא מציג.

המקור הרגיל של undefined הוא נתונים שעוד לא נטענו (value={user.name} לפני שהמשתמש הגיע) או שדה באובייקט שעוד לא קיים. שני תיקונים:

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

ב-checkboxes אותו כלל חל על checked: התחילו אותו ב-false, לא undefined.

שדות קבצים תמיד לא מבוקרים

<input type="file"> לא יכול להיות מבוקר, כי דפדפנים לא מאפשרים לדף לקבוע את הערך שלו (דף שיכול לבחור קבצים בדיסק שלכם היה פרצת אבטחה). קראו את הקבצים שנבחרו מ-e.target.files ב-onChange, או דרך ref כשהטופס נשלח.

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 מאפס אותו.

מתי לבחור במה

בחרו במבוקר כשהמסך צריך להגיב לערך תוך כדי הקלדה. בחרו בלא מבוקר כשצריך את הערכים רק בסוף, וכך גם עובדים form actions ב-React 19: <form action={fn}> מעביר לפונקציה שלכם FormData ומאפס אחר כך את השדות הלא מבוקרים.

רינדור בכל הקשה נשמע יקר, אבל בטופס רגיל זו לא בעיה. זה הופך לבעיה רק כשעץ גדול ואיטי מתרנדר מחדש יחד עם השדה; אז שמרו את ה-state קרוב לשדה, או העבירו את החלק האיטי לקומפוננטה משלו.

אותן שתי מילים מתארות גם את הקומפוננטות שלכם. קומפוננטה שמקבלת את הערך שלה ו-onChange מההורה דרך props נשלטת על ידי ההורה; קומפוננטה ששומרת state משלה היא לא מבוקרת. העברת state למעלה כדי להפוך קומפוננטה למבוקרת היא בדיוק הנושא של הרמת state למעלה.