{"componentChunkName":"component---src-templates-docs-js","path":"/docs/jsx-in-depth.html","result":{"data":{"markdownRemark":{"html":"
\n
\n

These docs are old and won’t be updated. Go to react.dev for the new React docs.

\n
\n
\n

توفِّر JSX علينا عناء إنشاء العناصر بإستخدام الدالة React.createElement(component, props, ...children). انظر إلى الشيفرة التالية في JSX:

\n
<MyButton color=\"blue\" shadowSize={2}>\n  انقر هنا\n</MyButton>
\n

تُترجَم الشيفرة السّابقة إلى:

\n
React.createElement(\n  MyButton,\n  {color: 'blue', shadowSize: 2},\n  'انقر هنا'\n)
\n

بإمكانك أيضًا استخدام الشكل ذاتي الإغلاق للعنصر إن كان لا يحتوي على أيّة عناصر أبناء:

\n
<div className=\"sidebar\" />
\n

تُترجَم الشيفرة السّابقة إلى:

\n
React.createElement(\n  'div',\n  {className: 'sidebar'}\n)
\n

إن أردتَ اختبار كيفيّة تحويل بعض شيفرات JSX إلى JavaScript فبإمكانك تجريب مُترجِم Babel على الإنترنت.

\n

تحديد نوع عنصر React

\n

يُحدِّد الحرف الأول في وسم JSX نوعَ عنصر React.

\n

تُشير الأنواع التي تبدأ بحرف كبيرة (Capitalized types) إلى أنّ العنصر المذكور هو مُكوِّن React. تُترجَم هذه العناصر إلى مرجع مباشر إلى المتغيّر الذي يحمل اسمها، لذا إن استخدمت التعبير ‎<Foo />‎ في JSX يجب أن يكون المتغيّر Foo في نفس المجال.

\n

يجب على React أن تكون في نفس المجال

\n

لمّا كانت JSX تُترجَم إلى نداءات للتابع React.createElement، فيجب على مكتبة React أن تكون في نفس المجال الذي تكون فيه شيفرة JSX.

\n

على سبيل المثال الاستيراد التالي ضروري في هذه الشّيفرة على الرغم من أنّ React و CustomButton لا يُشار إليهما بشكل مباشر من JavaScript:

\n
import React from 'react';import CustomButton from './CustomButton';\nfunction WarningButton() {\n  // return React.createElement(CustomButton, {color: 'red'}, null);  return <CustomButton color=\"red\" />;\n}
\n

إن لم تستخدم مُحزِّم JavaScript وطلبتَ React من داخل عنصر <script>، فهي موجودة مُسبقًا في نفس المدى لأنّها عامّة (global).

\n

استخدام النقطة لأنواع JSX

\n

بإمكانك الإشارة أيضًا إلى مُكوِّن React باستخدام النقطة من داخل JSX. وهو أمرٌ جيّد إن كانت لديك وحدة (module) وحيدة والتي تُصدِّر عدّة مُكوِّنات React. على سبيل المثال إن كان MyComponents.DatePicker مُكوِّنًا، فيُمكِنك استخدامه بشكلٍ مباشر من JSX كما يلي:

\n
import React from 'react';\n\nconst MyComponents = {\n  DatePicker: function DatePicker(props) {\n    return <div>تخيّل وجود {props.color} انتقاء للتاريخ هنا.</div>;\n  }\n}\n\nfunction BlueDatePicker() {\n  return <MyComponents.DatePicker color=\"blue\" />;}
\n

يجب كتابة المكونات المعرفة من قبل المستخدم بأحرف كبيرة

\n

عندما يبدأ نوع العنصر بحرف صغير، فهو يُشير إلى مُكوِّنات داخليّة مثل <div> أو <span> وينتج عنه السلسلة النصيّة 'div' أو 'span' والتي تُمرَّر إلى التّابع React.createElement. أمّا الأنواع التي تبدأ بأحرف كبيرة مثل ‎<Foo /> فتُترجَم إلى React.createElement(Foo) وتُوافِق مُكوِّنات مُعرَّفة أو مُستوردة في ملّف JavaScript لديك.

\n

نوصي بتسمية المُكوِّنات بأحرف كبيرة، وإن كان لديك مُكوِّن يبدأ بحرف صغير فعيّنه إلى مُتغيّر يبدأ بحرف كبير قبل استخدامه في JSX.

\n

على سبيل المثال لن تعمل الشيفرة التالية كما هو مُتوقَّع:

\n
import React from 'react';\n\n// :خطأ! هذا مُكوِّن ويجب أن يبدأ بحرف كبيرfunction hello(props) {  // صحيح! هنا استخدام العنصر div صحيح كونه عنصر في HTML\n  return <div>أهلًا  {props.toWhat}</div>;\n}\n\nfunction HelloWorld() {\n  // خطأ! تعتقد React أنّ العنصر hello هو عنصر في HTML لأنّه لا يبدأ بحرف كبير  return <hello toWhat=\"بالعالم\" />;}
\n

لإصلاح ذلك سنُعيد تسمية hello إلى Hello وسنستخدم <Hello />‎ للإشارة إليه:

\n
import React from 'react';\n\n// صحيح! هذا مُكوِّن ويجب أن يبدأ بحرف كبيرfunction Hello(props) {  // صحيح! هنا استخدام العنصر div صحيح كونه عنصر في HTML\n  return <div>Hello {props.toWhat}</div>;\n}\n\nfunction HelloWorld() {\n  // صحيح! تعلم React أنّ Hello هو مُكوِّن لأنّه يبدأ بحرف كبير  return <Hello toWhat=\"World\" />;}
\n

اختيار النوع في زمن التنفيذ

\n

لا يُمكنِك استخدام تعبير عام كنوع لعنصر React، فإن لم ترغب باستخدام تعبير عام للإشارة لنوع العنصر، فعيّنه فقط إلى متغيّر يبدأ بحرف كبير أولًا. يحدث هذا عادةً عندما تريد تصيير مُكوِّن آخر بناءً على خاصيّة prop:

\n
import React from 'react';\nimport { PhotoStory, VideoStory } from './stories';\n\nconst components = {\n  photo: PhotoStory,\n  video: VideoStory\n};\n\nfunction Story(props) {\n  // خطأ! لا يمكن أن يكون نوع JSX عبارة عن تعبير  return <components[props.storyType] story={props.story} />;}
\n

لإصلاح ذلك سنُعيِّن النوع إلى متغيّر يبدأ بحرف كبير أولًا:

\n
import React from 'react';\nimport { PhotoStory, VideoStory } from './stories';\n\nconst components = {\n  photo: PhotoStory,\n  video: VideoStory\n};\n\nfunction Story(props) {\n  // صحيح! يُمكِن لنوع JSX أن يكون متغيّرًا يبدأ بحرف كبير  const SpecificStory = components[props.storyType];  return <SpecificStory story={props.story} />;}
\n

الخاصيات props في JSX

\n

هنالك عدّة طرق لتحديد الخاصيّات في JSX.

\n

تعابير JavaScript كخاصيات

\n

بإمكانك تمرير أي تعبير JavaScript كخاصيّة prop عن طريق إحاطته بالقوسين {}. على سبيل المثال:

\n
<MyComponent foo={1 + 2 + 3 + 4} />
\n

بالنسبة للمُكوِّن MyComponent تكون قيمة props.foo هي 10 بسبب تقييم التعبير ‎1 + 2 + 3 + 4.

\n

لا تُعدُّ جمل if الشرطيّة و حلقات for تعابيرًا في JavaScript، لذلك لا يُمكِن استخدامها في JSX بشكلٍ مباشر، وبدلًا من ذلك بإمكاننا وضعها في الشيفرة المُحيطة. على سبيل المثال:

\n
function NumberDescriber(props) {\n  let description;\n  if (props.number % 2 == 0) {    description = <strong>even</strong>;  } else {    description = <i>فردي</i>;  }  return <div>{props.number} هو عدد {description}</div>;\n}
\n

يُمكِنك تعلّم المزيد حول التصيير الشرطي واستخدام loops في أقسامها الخاصّة.

\n

استخدام السلاسل النصيّة الحرفيّة

\n

بإمكانك تمرير سلسلة نصيّة حرفيّة كخاصيّة، فالتعبيران التاليان في JSX مُتكافئان:

\n
<MyComponent message=\"hello world\" />\n\n<MyComponent message={'hello world'} />
\n

عندما تُمرِّر سلسلة نصيّة حرفيّة، ستُهرَّب قيمتها (HTML-unescaped) بشكلٍ افتراضي. لذلك التعبيران التاليان مُتكافئان أيضًا:

\n
<MyComponent message=\"&lt;3\" />\n\n<MyComponent message={'<3'} />
\n

لا علاقة لهذا السّلوك بموضوعنا، ولكن ذكرناه هنا من أجل الفائدة.

\n

القيمة الافتراضيّة للخاصيّات props هي true

\n

إن لم تُمرِّر أي قيمة للخاصيّة فقيمتها الافتراضيّة هي true. التعبيران التاليان مُتكافئان:

\n
<MyTextBox autocomplete />\n\n<MyTextBox autocomplete={true} />
\n

لا نُوصي إجمالًا بفعل ذلك بسبب الارتباك الذي يُسبّبه التشابه مع الصيغة المختصرة للكائنات في ES6، حيث تكون {foo} اختصارًا إلى {foo: foo} بدلًا من ‎{foo: true}‎ كما قد تظن. هذا السّلوك موجود هنا فقط للتوافق مع سلوك HTML.

\n

خاصيّات النشر

\n

إن كانت لديك خاصيّات props على شكل كائنات، وأردتَ تمريرها في JSX، فبإمكانك استخدام مُعامِل النشر ... لتمرير كائن الخاصيّات بشكلٍ كامل. المُكوِّنان التاليان مُتكافئان:

\n
function App1() {\n  return <Greeting firstName=\"Ben\" lastName=\"Hector\" />;\n}\n\nfunction App2() {\n  const props = {firstName: 'Ben', lastName: 'Hector'};\n  return <Greeting {...props} />;}
\n

بإمكانك أيضًا اختيار خاصيّات مُحدّدة يُحدِّد قيمتها مُكوِّنك وتمرير الخاصيّات الأخرى باستخدام مُعامِل النشر:

\n
const Button = props => {\n  const { kind, ...other } = props;  const className = kind === \"primary\" ? \"PrimaryButton\" : \"SecondaryButton\";\n  return <button className={className} {...other} />;\n};\n\nconst App = () => {\n  return (\n    <div>\n      <Button kind=\"primary\" onClick={() => console.log(\"clicked!\")}>\n        أهلًا بالعالم!\n      </Button>\n    </div>\n  );\n};
\n

في المثال السّابق، حدّدنا قيمة الخاصيّة kind ولم نُمرِّرها إلى العنصر <button> في DOM. تُمرَّر كافّة الخاصيّات الأخرى عبر الكائن ‎...other‎ ممّا يجعل هذا المُكوِّن مرنًا بشدّة. بإمكانك أن ترى أنّه يُمرِّر خاصيّات onClick و children.

\n

قد تكون خاصيّات النشر مفيدة ولكنّها تُسهِّل تمرير خاصيّات غير ضروريّة إلى المُكوِّنات التي لا تُبالي لها، أو تمرير خاصيّات HTML خطأ إلى DOM. نُوصي باستخدام هذه الصّياغة بحذر.

\n

العناصر الأبناء في JSX

\n

يُمرَّر المحتوى الموجود بين عنصر البدء وعنصر الإغلاق في JSX كخاصيّة مُميّزة وهي props.children. هنالك عدّة طرق مختلفة لتمرير العناصر الأبناء:

\n

السلاسل النصيّة الحرفيّة

\n

بإمكانك وضع سلسلة نصيّة بين عنصري البدء والإغلاق وستكون قيمة الخاصيّة props.children هي تلك السلسلة النصيّة. يُفيد ذلك من أجل العديد من عناصر HTML الداخليّة، على سبيل المثال:

\n
<MyComponent>أهلًا بالعالم!</MyComponent>
\n

هذه الصيغة صحيحة في JSX، وستكون قيمة props.children في المُكوِّن MyComponent هي السلسلة النصيّة \"أهلًا بالعالم!\". تُهرَّب السلسلة النصيّة لذلك بإمكانك كتابة JSX كما تكتب HTML بهذه الطريقة:

\n
<div>هذه السلسلة النصيّة صالحة بنفس الوقت في HTML &amp; JSX</div>
\n

تُزيل JSX المسافات الفارغة في بداية ونهاية السطر، كما تُزيل الأسطر الفارغة والأسطر الجديدة التي تسبق العناصر. تُجمَّع الأسطر الجديدة التي تكون في وسط السلسلة النصيّة إلى مسافة فارغة واحدة. لذا يكون ناتج هذه الأمثلة مُتماثلًا:

\n
<div>أهلًا بالعالم</div>\n\n<div>\n  أهلًا بالعالم\n</div>\n\n<div>\n  أهلًا\n  بالعالم\n</div>\n\n<div>\n\n  أهلًا بالعالم\n</div>
\n

العناصر الأبناء

\n

بإمكانك إضافة المزيد من عناصر JSX كأبناء، وهذا يُفيد في عرض المُكوِّنات المتداخلة:

\n
<MyContainer>\n  <MyFirstComponent />\n  <MySecondComponent />\n</MyContainer>
\n

بإمكانك دمج عدّة أنواع مختلفة من العناصر الأبناء معًا، أي يُمكِنك استخدام السلاسل النصيّة الحرفيّة مع العناصر. وهذا أمرٌ آخر تتشابه فيه JSX مع HTML، لذا يكون المثال التالي صحيحًا في JSX و HTML:

\n
<div>\n  هذه هي القائمة:\n  <ul>\n    <li>العنصر 1</li>\n    <li>العنصر 2</li>\n  </ul>\n</div>
\n

يستطيع مُكوِّن React أن يُعيد مصفوفة من العناصر:

\n
render() {\n  // لا حاجة لوضع عناصر القائمة ضمن عنصر إضافي\n  return [\n\t// لاتنس المفاتيح :) \n    <li key=\"A\">العنصر الأول</li>,\n    <li key=\"B\">العنصر الثاني</li>,\n    <li key=\"C\">العنصر الثالث</li>,\n  ];\n}
\n

استخدام تعابير JavaScript كعناصر أبناء

\n

بإمكانك تمرير أي تعبير في JavaScript كعنصر ابن عن طريق تغليفه باستخدام القوسين {}. فمثلًا هذا التعبيران مُتكافئان:

\n
<MyComponent>foo</MyComponent>\n\n<MyComponent>{'foo'}</MyComponent>
\n

يُفيد هذا عادةً في تصيير قائمة من تعابير JSX ذات أطوال مختلفة كما يلي:

\n
function Item(props) {\n  return <li>{props.message}</li>;}\n\nfunction TodoList() {\n  const todos = ['إنهاء المستند', 'تقديم الطلبات', 'مراجعة الطلب'];\n  return (\n    <ul>\n      {todos.map((message) => <Item key={message} message={message} />)}    </ul>\n  );\n}
\n

يُمكِن دمج تعابير JavaScript مع أنواع مختلفة من العناصر الأبناء:

\n
function Hello(props) {\n  return <div>أهلًا {props.addressee}!</div>;}
\n

استخدام الدوال كعناصر أبناء

\n

تُقيَّم عادةً تعابير JavaScript المُدخلَة في JSX إلى سلاسل نصيّة، عناصر React، أو قائمة من هذه الأشياء. ولكن يعمل props.children مثل أي خاصيّة في أنّه يستطيع تمرير أي نوع من البيانات وليس فقط الأنواع التي تعلم React كيفيّة تصييرها. فمثلًا إن كان لديك مُكوِّن مُخصَّص تستطيع أن تجعله يأخذ رد نداء مثل props.children:

\n
// استدعاء رد نداء العناصر الأبناء عدد من المرات لإنشاء مُكوِن مُكرّر\nfunction Repeat(props) {\n  let items = [];\n  for (let i = 0; i < props.numTimes; i++) {    items.push(props.children(i));\n  }\n  return <div>{items}</div>;\n}\n\nfunction ListOfTenThings() {\n  return (\n    <Repeat numTimes={10}>\n      {(index) => <div key={index}>هذا هو العنصر {index} في القائمة</div>}    </Repeat>\n  );\n}
\n

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

\n

تتجاهل JSX القيم المنطقيّة (Booleans)، و Null، والقيم غير المُعرَّفة Undefined

\n

تُعدُّ القيم false و null، و undefined، و true عناصر أبناء صحيحة، ولكنّها ببساطة لا تُصيَّر. حيث ينتج عن التعابير التالية في JSX نفس النتيجة:

\n
<div />\n\n<div></div>\n\n<div>{false}</div>\n\n<div>{null}</div>\n\n<div>{undefined}</div>\n\n<div>{true}</div>
\n

يُفيد هذا في التصيير الشرطي لعناصر React. ففي المثال التالي تُصيِّر JSX فقط المُكوِّن <Header />‎ إن كانت قيمة showHeader هي true:

\n
<div>\n  {showHeader && <Header />}  <Content />\n</div>
\n

تُصيِّر React القيم الكاذبة مثل العدد صفر. فمثلًا لن تعمل الشيفرة التالية كما تتوقّع لأنّه ستطبع العدد 0 عندما تكون المصفوفة props.messages فارغة:

\n
<div>\n  {props.messages.length &&    <MessageList messages={props.messages} />\n  }\n</div>
\n

لإصلاح ذلك احرص أن يكون التعبير قبل المُعامِل && قيمة منطقيّة دومًا:

\n
<div>\n  {props.messages.length > 0 &&    <MessageList messages={props.messages} />\n  }\n</div>
\n

إن أردتَ بشكلٍ مُعاكِس أن تظهر القيم مثل false، و true، و null، و undefined في الناتج، فيجب عليك تحويلها إلى سلسلة نصيّة أولًا:

\n
<div>\n  متغير JavaScript قيمته {String(myVariable)}.</div>
","frontmatter":{"title":"شرح JSX بالتفصيل","next":null,"prev":null},"fields":{"path":"content/docs/jsx-in-depth.md","slug":"docs/jsx-in-depth.html"}}},"pageContext":{"slug":"docs/jsx-in-depth.html"}},"staticQueryHashes":[]}