{"id":"l-rf-3-3","courseId":"react-fundamentals","lang":"ar","kind":"lesson","summary":"ابنِ نموذج إضافة الأفلام في Watchlist باستخدام الـ controlled inputs، وتعامل مع الإرسال والتحقّق من المدخلات، واعرف متى تكون الـ form actions وuseActionState في React 19 الخيار الأنسب.","html":"

كل تطبيق مفيد يستقبل مدخلات. في Watchlist يعني ذلك نموذجًا: اكتب عنوانًا، وسنة إن أردت، واضغط Enter أو انقر Add، فيظهر الفيلم في القائمة. النماذج هي المكان الذي يلتقي فيه الـ state بالأحداث، وفيها يعيش معظم أخطاء المبتدئين: حقول ترفض الكتابة، وصفحات يُعاد تحميلها عند الإرسال، وأرقام تُلصق ببعضها كالنصوص. ولكل واحد منها سبب واضح.

\n

الـ controlled input

\n

في HTML العادي يملك الحقل قيمته، وأنت تقرؤها حين تحتاجها. أمّا في React فالأسلوب المعتاد يقلب ذلك: الـ state يملك القيمة، والحقل يعرضها.

\n
src/components/AddMovieForm.jsx
import { useState } from 'react';\n\nexport default function AddMovieForm() {\n  const [title, setTitle] = useState('');\n\n  return (\n    <form>\n      <label htmlFor=\"title\">Title</label>\n      <input\n        id=\"title\"\n        value={title}\n        onChange={(e) => setTitle(e.target.value)}\n      />\n      <p>{title.length}/80 characters</p>\n    </form>\n  );\n}
\n

هذا هو الـ controlled input (الحقل المتحكَّم به). كل ضغطة مفتاح تُطلق onChange، فيخزّن المعالج النص الجديد في الـ state، وتعيد React الـ render، ويعرض الحقل الـ state. يبدو هذا التفافًا، لكن النص الحالي صار الآن متغيّرًا عاديًا. يمكنك عرض عدد الحروف، والتحقّق أثناء الكتابة، وتعطيل زر، أو مسح الحقل بضبط الـ state على ''.

\n

لاحظ أن onChange في React يعمل مع كل ضغطة مفتاح، مثل حدث input في الـ DOM، لا فقط حين يفقد الحقل التركيز.

\n\n

الإرسال

\n

تعامل مع الإرسال على النموذج، لا على نقرة الزر:

\n
src/components/AddMovieForm.jsx
export default function AddMovieForm({ onAdd }) {\n  const [title, setTitle] = useState('');\n  const trimmed = title.trim();\n\n  function handleSubmit(e) {\n    e.preventDefault();\n    if (!trimmed) return;\n    onAdd(trimmed);\n    setTitle('');\n  }\n\n  return (\n    <form onSubmit={handleSubmit}>\n      <label htmlFor=\"title\">Title</label>\n      <input id=\"title\" value={title} onChange={(e) => setTitle(e.target.value)} />\n      <button type=\"submit\" disabled={!trimmed}>Add</button>\n    </form>\n  );\n}
\n

وجود onSubmit على النموذج يعني أن الضغط على Enter داخل الحقل يعمل، والزر يعمل، والتقنيات المساعدة تفهم النموذج، كل ذلك من دون كود إضافي. وتوقف e.preventDefault() السلوك الافتراضي للمتصفّح، وهو إرسال النموذج إلى رابط وإعادة تحميل الصفحة. ويبلّغ الـ component عن العنوان الجديد عبر onAdd، ويمسح الحقل بإعادة ضبط الـ state.

\n

والتحقّق يأتي من الـ state أيضًا. تُشتقّ trimmed في كل render، فيكون الزر معطّلًا بالضبط ما دام العنوان فارغًا، بما في ذلك العنوان المكوّن من مسافات فقط. أمّا if (!trimmed) return; داخل المعالج فحارس ثانٍ تحسّبًا لإرسال النموذج بطريقة أخرى.

\n\n

أنواع أخرى من الحقول

\n

كل أنواع الحقول تتبع النمط نفسه مع فروق صغيرة:

\n
JSX
// Numbers arrive as strings. Keep the string in state, convert on use.\n<input type=\"number\" value={year} onChange={(e) => setYear(e.target.value)} />\nconst yearNumber = year === '' ? null : Number(year);\n\n// Checkboxes use checked, not value.\n<input type=\"checkbox\" checked={watched} onChange={(e) => setWatched(e.target.checked)} />\n\n// A select is controlled through value on the <select>.\n<select value={genre} onChange={(e) => setGenre(e.target.value)}>\n  <option value=\"drama\">Drama</option>\n  <option value=\"sci-fi\">Sci-fi</option>\n</select>
\n

حالة الأرقام توقع الجميع مرة على الأقل: e.target.value نص دائمًا، حتى مع type="number"، فيعطي year + 1 النتيجة “20161”. والاحتفاظ بالنص الخام في الـ state يعني أيضًا أن الحقل الفارغ يبقى فارغًا بدل أن يتحوّل إلى 0.

\n

React 19: الـ form actions

\n

الـ controlled inputs هي الأفضل حين تتفاعل مع كل ضغطة مفتاح. لكن نماذج كثيرة لا تهمّ إلا لحظة الإرسال، وقد أضاف React 19 دعمًا مباشرًا لها: مرّر دالة إلى الخاصية action في النموذج.

\n
JSX
function QuickAdd({ onAdd }) {\n  function addAction(formData) {\n    onAdd(formData.get('title').trim());\n  }\n\n  return (\n    <form action={addAction}>\n      <input name=\"title\" required />\n      <button type=\"submit\">Add</button>\n    </form>\n  );\n}
\n

تمنع React إعادة تحميل الصفحة نيابةً عنك، وتستدعي دالتك مع كائن FormData مبني من خصائص name في الحقول، وتعيد ضبط الحقول غير المتحكَّم بها حين تنتهي الـ action. فالحقول ليست متحكَّمًا بها أصلًا.

\n

وحين تحتاج إلى نتيجة من الإرسال، مثل رسالة خطأ، أو إلى حالة انتظار أثناء عمل غير متزامن، أضف useActionState:

\n
JSX
import { useActionState } from 'react';\n\nfunction QuickAdd({ onAdd }) {\n  const [error, formAction, isPending] = useActionState(async (prevError, formData) => {\n    const title = formData.get('title').trim();\n    if (!title) return 'Title is required';\n    await onAdd(title); // could be a request to a server\n    return null;\n  }, null);\n\n  return (\n    <form action={formAction}>\n      <input name=\"title\" aria-invalid={error ? true : undefined} />\n      <button type=\"submit\" disabled={isPending}>{isPending ? 'Adding…' : 'Add'}</button>\n      {error && <p role=\"alert\">{error}</p>}\n    </form>\n  );\n}
\n

تستقبل الـ action الـ state السابق وبيانات النموذج، وتُرجع الـ state التالي. وتكون isPending قيمتها true أثناء تنفيذها. ويستطيع أي component ابن داخل النموذج أيضًا قراءة حالة الانتظار باستخدام useFormStatus من react-dom.

\n

أيّهما تستخدم؟ خيار افتراضي معقول: الـ controlled inputs حين تتفاعل الواجهة أثناء الكتابة (العدّ، والتحقّق المباشر، والحقول المعتمدة على بعضها)؛ والـ actions حين يحدث العمل عند الإرسال، خصوصًا إن كان غير متزامن. نموذج الإضافة في Watchlist يعطّل زرّه ما دام العنوان فارغًا، لذا يستخدم controlled input، وهذا ما ستبنيه في التمرين.

\n\n

في الدرس التالي تربط هذا النموذج بالقائمة. النموذج والقائمة أخوان، لذا يجب أن تعيش الأفلام في أبيهما المشترك. وهذا هو رفع الـ state للأعلى.

\n","toc":[{"id":"sec-1","text":"الـ controlled input","level":2},{"id":"sec-2","text":"الإرسال","level":2},{"id":"sec-3","text":"أنواع أخرى من الحقول","level":2},{"id":"sec-4","text":"React 19: الـ form actions","level":2}],"takeaways":["الـ controlled input يأخذ value من الـ state ويبلّغ عن كل ضغطة مفتاح عبر onChange، فيكون الـ state المصدر الوحيد للحقيقة.","تعامل مع onSubmit على الـ <form> واستدعِ e.preventDefault()؛ فتحصل على الإرسال بـ Enter وعلى سلوك يدعم إمكانية الوصول مجانًا.","تحقّق من المدخلات انطلاقًا من الـ state أثناء الـ render، مثلًا بتعطيل الزر حين يكون العنوان بعد التشذيب فارغًا.","قيم الحقول نصوص دائمًا؛ حوّل الأرقام بنفسك، واستخدم checked لمربّعات الاختيار.","تمرّر الـ form actions في React 19 كائن FormData إلى دالة وتعيد ضبط النموذج؛ ويضيف useActionState نتيجة ومؤشّر انتظار."],"further":[{"title":"Reacting to Input with State","url":"https://react.dev/learn/reacting-to-input-with-state"},{"title":" reference (controlled inputs)","url":"https://react.dev/reference/react-dom/components/input"},{"title":"
reference (form actions)","url":"https://react.dev/reference/react-dom/components/form"},{"title":"useActionState reference","url":"https://react.dev/reference/react/useActionState"}],"quiz":[{"q":"

ترسم <input value={title} /> من دون onChange. ماذا يحدث حين يكتب المستخدم؟

","options":[{"text":"يتحدّث الحقل ويتحدّث الـ state المسمّى title تلقائيًا.","why":"لا تحدّث React الـ state نيابةً عنك أبدًا. الـ controlled input لا يتغيّر إلا حين تضبط الـ state الذي يقرأ منه."},{"text":"لا يتغيّر شيء، وتحذّر React من أنك وفّرت value من دون معالج onChange.","why":"صحيح. كل render يعيد الحقل إلى title. أضف onChange={(e) => setTitle(e.target.value)}، أو استخدم defaultValue لحقل غير متحكَّم به."},{"text":"يتحدّث الحقل، لكن title يبقى كما هو.","why":"هكذا يتصرّف الحقل غير المتحكَّم به مع defaultValue. أمّا مع value فتُبقي React الـ DOM متوافقًا مع الـ state."},{"text":"ترمي React خطأ وتتوقّف عن الـ render.","why":"إنه تحذير في وضع التطوير، لا خطأ. كل ما في الأمر أن الحقل يصبح للقراءة فقط."}],"answer":1},{"q":"

حقل السنة هو <input type="number" value={year} onChange={(e) => setYear(e.target.value)} />. كتب المستخدم 2016. ما نوع year، وماذا يعطي year + 1؟

","options":[{"text":"الرقم 2016، فيكون year + 1 هو 2017.","why":"الخاصية type="number" لا تغيّر إلا لوحة المفاتيح والتحقّق. أمّا e.target.value فهي نص دائمًا."},{"text":"الرقم 2016، لكن year + 1 يعطي NaN.","why":"الرقم زائد 1 لا يكون NaN أبدًا. القيمة ليست رقمًا أصلًا."},{"text":"undefined، لأن حقول الأرقام تحتاج إلى valueAsNumber.","why":"الخاصية e.target.value تعمل مع حقول الأرقام؛ لكنها تُرجع نصًا. وvalueAsNumber بديل يُرجع رقمًا."},{"text":"النص “2016”، فيكون year + 1 هو “20161”.","why":"صحيح. حوّل القيمة حين تستخدمها، مثلًا بـ Number(year)، واحتفظ بالنص الخام في الـ state حتى تعمل المدخلات الجزئية كالحقل الفارغ."}],"answer":3},{"q":"

يضيف نموذجك فيلمًا ويجب أن يمسح العنوان بعد ذلك. أيّ handleSubmit صحيح مع controlled input؟

","options":[{"text":"e.preventDefault(); onAdd(title.trim()); setTitle('');","why":"صحيح. توقف preventDefault إعادة تحميل الصفحة، وتبلّغ onAdd عن الفيلم الجديد، وضبط الـ state على ‘’ يمسح الـ controlled input."},{"text":"onAdd(title); e.target.reset();","why":"من دون preventDefault يحاول المتصفّح الإرسال وإعادة التحميل. كما أن reset() لا تغيّر الـ state المسمّى title، فتعيد React القيمة القديمة في الـ render التالي."},{"text":"e.preventDefault(); onAdd(title); title = '';","why":"إعادة إسناد المتغيّر لا تفعل شيئًا بالـ state؛ يظل الحقل يعرض العنوان القديم."}],"answer":0},{"q":"

متى تكون الـ form action في React 19 مع useActionState أنسب من الـ controlled inputs؟

","options":[{"text":"حين تحتاج إلى تغيير ما يُعرض مع كل ضغطة مفتاح، مثل العدّ المباشر للحروف.","why":"الملاحظات المباشرة تحتاج إلى القيمة في الـ state أثناء الكتابة، وهذا ما تعطيك إياه الـ controlled inputs."},{"text":"أبدًا؛ الـ actions لا تعمل إلا مع أطر عمل الخادم مثل Next.js.","why":"تعمل الـ form actions مع دوال عادية في المتصفّح داخل أي تطبيق React 19. والـ Server Functions استخدام اختياري واحد منها."},{"text":"حين يهمّ النموذج أساسًا لحظة الإرسال، خصوصًا مع عمل غير متزامن، وتريد نتيجة أو خطأ مع مؤشّر انتظار.","why":"صحيح. تستقبل الـ action كائن FormData، ويخزّن useActionState ما تُرجعه، وتكون isPending قيمتها true أثناء تنفيذها."},{"text":"حين يحتوي النموذج على حقل واحد فقط.","why":"عدد الحقول لا يحسم الأمر. المهمّ هو هل تتفاعل مع الكتابة أم مع الإرسال."}],"answer":2}],"exercise":{"kind":"web","mode":"react","starter":{"jsx":"import { useState } from 'react';\n\nfunction AddMovieForm({ onAdd }) {\n // Make both inputs controlled, handle submit, and disable Add while the title is blank.\n return (\n \n \n \n \n \n \n
\n );\n}\n\nlet nextId = 1; // in a real app: crypto.randomUUID()\n\nexport default function App() {\n const [movies, setMovies] = useState([]);\n\n function addMovie(title, year) {\n setMovies([...movies, { id: nextId++, title, year }]);\n }\n\n return (\n
\n \n \n
\n );\n}\n"},"solution":{"jsx":"import { useState } from 'react';\n\nfunction AddMovieForm({ onAdd }) {\n const [title, setTitle] = useState('');\n const [year, setYear] = useState('');\n const trimmed = title.trim();\n\n function handleSubmit(e) {\n e.preventDefault();\n if (!trimmed) return;\n onAdd(trimmed, year === '' ? null : Number(year));\n setTitle('');\n setYear('');\n }\n\n return (\n
\n \n setTitle(e.target.value)} />\n \n setYear(e.target.value)} />\n \n
\n );\n}\n\nlet nextId = 1; // in a real app: crypto.randomUUID()\n\nexport default function App() {\n const [movies, setMovies] = useState([]);\n\n function addMovie(title, year) {\n setMovies([...movies, { id: nextId++, title, year }]);\n }\n\n return (\n
\n \n \n
\n );\n}\n"},"checks":[{"id":"disabled-empty","test":"const b = $('button'); if (!b.disabled) return false; await input('#title', ' '); return $('button').disabled === true;"},{"id":"enabled-with-title","test":"await input('#title', 'Dune'); return $('button').disabled === false;"},{"id":"adds-movie","test":"await input('#year', '2021'); const __f = $('form'); if (__f) __f.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true })); else await click($('button')); await tick(20); const li = $$('li'); return li.length === 1 && text(li[0]) === 'Dune (2021)';"},{"id":"clears-fields","test":"return $('#title').value === '' && $('#year').value === '' && $('button').disabled === true;"},{"id":"trims-title","test":"await input('#title', ' Past Lives '); const __f = $('form'); if (__f) __f.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true })); else await click($('button')); await tick(20); const li = $$('li'); return li.length === 2 && text(li[1]) === 'Past Lives';"}],"title":"نموذج إضافة الأفلام","prompt":"

ابنِ AddMovieForm بحيث يضيف أفلامًا إلى القائمة. أبقِ المعرّفين title وyear على الحقلين.

\n\n

يخزّن App الأفلام مسبقًا ويعرضها بالشكل “Title (Year)”، أو “Title” وحده حين لا توجد سنة.

\n","hints":["قطعتان من الـ state، تبدأ كلتاهما بـ '': const [title, setTitle] = useState('') والمثل لـ year.","ضع onSubmit={handleSubmit} على الـ <form> وابدأ المعالج بـ e.preventDefault().","اشتقّ const trimmed = title.trim(); واستخدمها لكلٍّ من disabled={!trimmed} والقيمة التي تمرّرها إلى onAdd. وحوّل السنة بـ year === '' ? null : Number(year)."],"explanation":"

مع الـ controlled inputs تصبح القيم الحالية للنموذج state عاديًا، وهذا ما يجعل البقية سهلة. يُعاد حساب disabled={!trimmed} مع كل ضغطة مفتاح، ومسح النموذج هو setTitle('') وsetYear('')، والمعالج يقرأ القيم مباشرة من الـ state. وتوقف e.preventDefault() إرسال المتصفّح للصفحة كاملة، وتحويل السنة داخل المعالج يُبقي النص الخام في الـ state، فيبقى الحقل الفارغ فارغًا بدل أن يصبح 0.

\n

ملاحظة عن ساحة التجربة: ترسل الفحوص النموذج بإطلاق حدث submit الخاص به مباشرة.

\n","checkLabels":{"disabled-empty":"زر Add معطّل حين يكون العنوان فارغًا أو مسافات فقط","enabled-with-title":"يصبح زر Add مفعّلًا بمجرّد كتابة عنوان","adds-movie":"الإرسال يضيف “Dune (2021)” إلى القائمة","clears-fields":"يُمسح الحقلان كلاهما بعد الإضافة","trims-title":"يُشذَّب العنوان المحاط بمسافات، والسنة الفارغة تعرض العنوان وحده"}},"words":671,"readMinutes":4}