רשימות ו-keys ב-React: map(), ה-prop key ו-index כ-key

כדי לרנדר רשימה ב-React, קראו ל-map() על מערך והחזירו קטע JSX לכל פריט. תנו לאלמנט החיצוני של כל פריט prop בשם key עם ערך שמזהה את הפריט, בדרך כלל ה-ID שלו, כדי ש-React תוכל להבחין בין הפריטים כשהרשימה משתנה.

const fruits = [
    { id: 'apl', name: 'Apple', price: 0.5 },
    { id: 'ban', name: 'Banana', price: 0.25 },
    { id: 'chr', name: 'Cherry', price: 3 },
];

export default function App() {
    return (
        <ul>
            {fruits.map((fruit) => (
                <li key={fruit.id}>
                    {fruit.name}: ${fruit.price.toFixed(2)}
                </li>
            ))}
        </ul>
    );
}

הוסיפו { id: 'dat', name: 'Date', price: 4 } למערך ותופיע שורה רביעית. ל-JSX אין תחביר לולאה משלו: map מחזיר מערך של אלמנטים, ו-React מרנדרת מערך על ידי רינדור כל אלמנט לפי הסדר.

רינדור מערכים עם map

map קורא לפונקציה שלכם פעם אחת לכל פריט ואוסף את התוצאות למערך חדש. בתוך סוגריים מסולסלים של JSX המערך הזה הוא סתם ערך, כך שאפשר לעשות map ישר בתוך ה-markup, כמו למעלה, או לבנות את המערך קודם:

const items = fruits.map((fruit) => <li key={fruit.id}>{fruit.name}</li>);
return <ul>{items}</ul>;

שני פרטים מכשילים אנשים. אם משתמשים בסוגריים מסולסלים בפונקציית החץ, צריך return: fruits.map((f) => { return <li key={f.id}>{f.name}</li>; }). בלעדיו הפונקציה מחזירה undefined והרשימה ריקה. ובנוסף, ה-key הולך על האלמנט שמוחזר מ-map, לא על אלמנט שבתוכו. אם הפריט הוא קומפוננטה, שימו את ה-key על הקומפוננטה: <FruitRow key={fruit.id} fruit={fruit} />.

filter, ואז map

כדי להציג חלק מהפריטים, סננו את המערך קודם ועשו map לתוצאה. כל מתודה עושה עבודה אחת, והשרשרת נקראת כמו המשפט "הפירות שמתאימים, כפריטי רשימה".

import { useState } from 'react';

const products = [
    { id: 1, name: 'Notebook', inStock: true },
    { id: 2, name: 'Pencil', inStock: false },
    { id: 3, name: 'Eraser', inStock: true },
    { id: 4, name: 'Ruler', inStock: false },
    { id: 5, name: 'Stapler', inStock: true },
];

export default function App() {
    const [query, setQuery] = useState('');
    const [onlyInStock, setOnlyInStock] = useState(false);

    const visible = products
        .filter((p) => p.name.toLowerCase().includes(query.toLowerCase()))
        .filter((p) => !onlyInStock || p.inStock);

    return (
        <div>
            <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="Search" />
            <label style={{ marginInlineStart: 8 }}>
                <input
                    type="checkbox"
                    checked={onlyInStock}
                    onChange={(e) => setOnlyInStock(e.target.checked)}
                />
                In stock only
            </label>
            {visible.length === 0 && <p>No products match.</p>}
            <ul>
                {visible.map((p) => (
                    <li key={p.id}>{p.name}</li>
                ))}
            </ul>
        </div>
    );
}

הקלידו er בתיבת החיפוש והרשימה מצטמצמת ל-Eraser, Ruler ו-Stapler; סמנו In stock only וגם Ruler נעלם. הרשימה המסוננת מחושבת בזמן הרינדור משני חלקי ה-state, כך שאין מערך שני ב-state שצריך לשמור מסונכרן. visible.length === 0 && הוא שימוש בטוח ב-&& כי ההשוואה היא בוליאני אמיתי (הדף על רינדור מותנה מראה מה קורה עם 0 חשוף).

מה keys עושים

כשרשימה מתרנדרת מחדש, React משווה את מערך האלמנטים החדש לקודם. keys הם הדרך שבה היא מתאימה ביניהם: האלמנט עם key 3 עכשיו הוא האלמנט עם key 3 מקודם, גם אם הוא זז. React שומרת את צומת ה-DOM של הפריט הזה ואת ה-state של הקומפוננטה שלו, ורק מזיזה או מעדכנת את מה שהשתנה. פריטים עם keys חדשים נוצרים, ו-keys שנעלמו מוסרים.

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

למה index כ-key נשבר

map מעביר את ה-index כארגומנט השני שלו, ולכן key={index} מפתה. ה-index מתאר מיקום, לא פריט. הוסיפו פריט בראש הרשימה וה-index של כל פריט זז באחד, כך ש-React חושבת שפריט 0 הוא עדיין פריט 0 ושומרת שם את ה-state הישן שלו.

הדמו שמתחת מרנדר את אותה רשימה פעמיים, פעם עם key לפי index ופעם לפי ID. לכל שורה יש שדה קלט ששומר טקסט משלו.

import { useState } from 'react';

let nextId = 3;

export default function App() {
    const [people, setPeople] = useState([
        { id: 1, name: 'Ada' },
        { id: 2, name: 'Linus' },
    ]);

    function addToTop() {
        setPeople([{ id: nextId, name: 'New person ' + nextId }, ...people]);
        nextId++;
    }

    return (
        <div style={{ display: 'flex', gap: 24, flexWrap: 'wrap' }}>
            <div>
                <b>key=&#123;index&#125;</b>
                {people.map((p, index) => (
                    <p key={index}>
                        {p.name}: <input placeholder="note" size={10} />
                    </p>
                ))}
            </div>
            <div>
                <b>key=&#123;p.id&#125;</b>
                {people.map((p) => (
                    <p key={p.id}>
                        {p.name}: <input placeholder="note" size={10} />
                    </p>
                ))}
            </div>
            <button onClick={addToTop} style={{ alignSelf: 'start' }}>Add to top</button>
        </div>
    );
}

הקלידו math ליד Ada בשתי הרשימות, ואז לחצו על Add to top. ברשימת ה-ID ההערה נשארת עם Ada. ברשימת ה-index ההערה קופצת לאדם החדש, כי שדה הקלט הראשון הוא עדיין השדה במיקום 0, ומיקום 0 הוא עכשיו מישהו אחר. השמות נכונים בשתי הרשימות, כי הם מגיעים מהנתונים; רק ה-state שחי ב-DOM ובקומפוננטות משתבש. אפליקציות אמיתיות נתקלות בזה עם checkboxes, פוקוס, אנימציות וכל קומפוננטה שמחזיקה useState.

key מבוסס index בטוח רק כשכל התנאים האלה מתקיימים: הרשימה אף פעם לא משנה סדר או מסוננת, פריטים אף פעם לא מוכנסים או מוסרים חוץ מבסוף, ולפריטים אין state משלהם. רשימה סטטית של קישורים בפוטר עומדת בזה. כל דבר שמשתמש יכול לערוך בדרך כלל לא.

מאיפה keys מגיעים

ה-key הכי טוב הוא מזהה שכבר נמצא בנתונים: מזהה ממסד נתונים, מק"ט של מוצר, slug, שם משתמש. לנתונים שמגיעים משרת כמעט תמיד יש אחד כזה.

לפריטים שנוצרים בדפדפן, תנו לכל פריט מזהה כשאתם יוצרים אותו ושמרו אותו עם הפריט: מונה, כמו בדמו שלמעלה, או crypto.randomUUID(). אף פעם אל תייצרו את ה-key בזמן הרינדור:

// Wrong: a new key on every render, so React remounts every item every time
{todos.map((todo) => <Todo key={Math.random()} todo={todo} />)}

// Right: the ID is created once, in the event that adds the item
function addTodo(text) {
    setTodos([...todos, { id: crypto.randomUUID(), text }]);
}

key שמשתנה בכל רינדור גרוע יותר מ-index: כל פריט נהרס ונוצר מחדש בכל פעם, שדות קלט מאבדים פוקוס תוך כדי הקלדה, ושום דבר לא שומר את ה-state שלו. אותו טריק שימושי כשעושים אותו בכוונה: שינוי ה-key של קומפוננטה מאפס אותה, והדף על useState משתמש בזה כדי לנקות טופס.

keys ייחודיים רק בין אחים

key צריך להיות ייחודי בתוך רשימה אחת, לא בכל האפליקציה. שתי רשימות נפרדות יכולות להשתמש שוב באותם מזהים, כי React משווה keys רק בין הילדים של אותו הורה.

const menu = [
    { id: 1, section: 'Breakfast', dishes: [{ id: 1, name: 'Pancakes' }, { id: 2, name: 'Omelette' }] },
    { id: 2, section: 'Lunch', dishes: [{ id: 1, name: 'Soup' }, { id: 2, name: 'Salad' }] },
];

export default function App() {
    return (
        <div>
            {menu.map((part) => (
                <section key={part.id}>
                    <h4 style={{ marginBottom: 4 }}>{part.section}</h4>
                    <ul style={{ marginTop: 0 }}>
                        {part.dishes.map((dish) => (
                            <li key={dish.id}>{dish.name}</li>
                        ))}
                    </ul>
                </section>
            ))}
        </div>
    );
}

בשני החלקים יש מנות עם keys 1 ו-2, וזה נכון: כל ul הוא רשימה משלו. keys כפולים בתוך רשימה אחת הם הבעיה: React לא יכולה להבחין בין הפריטים המתנגשים, וכשהרשימה מתעדכנת היא עלולה לשכפל או להשמיט אותם.

כשפריט אחד מרנדר כמה אלמנטים אחים, כמו <dt> ו-<dd>, עטפו אותם ב-<Fragment key={item.id}>. התחביר הקצר <> לא יכול לקבל key.

אזהרת ה-"unique key prop"

אם משמיטים את ה-key, React מדפיסה את זה בקונסול של הדפדפן בזמן פיתוח:

Each child in a list should have a unique "key" prop.

Check the render method of `App`.

השורה השנייה מציינת את הקומפוננטה שהרינדור שלה יצר את הרשימה, וכך יודעים איזה map לתקן. שני אחים עם אותו key מקבלים הודעה אחרת, שמתחילה ב-"Encountered two children with the same key". התצוגה המקדימה בדף הזה רצה כמו build של פרודקשן, שמדלג על הבדיקה הזו, אז לא תראו כאן את האזהרה גם אם תמחקו key. מחקו אחד בכל זאת בדוגמה הראשונה: הרשימה עדיין מתרנדרת, כי key חסר הוא סיכון לנכונות, לא קריסה. כדי לתקן את האזהרה, הוסיפו key יציב לאלמנט שמוחזר מ-map; הוספת key={index} משתיקה אותה אבל מחזירה את הבאג שמוצג למעלה.

שימו לב גם ש-key לא מועבר לקומפוננטה שלכם. בתוך FruitRow, props.key הוא undefined. אם הקומפוננטה צריכה את המזהה, העבירו אותו פעם שנייה כ-prop רגיל: <FruitRow key={f.id} id={f.id} />.