عرض مصدر React/jsx in depth

<noinclude>{{DISPLAYTITLE:شرح JSX بالتفصيل في React}}</noinclude>
توفِّر JSX علينا عناء إنشاء العناصر باستخدام الدالة <code>React.createElement(component, props, ...children)</code>‎. انظر إلى الشيفرة التالية في JSX:<syntaxhighlight lang="javascript">
<MyButton color="blue" shadowSize={2}>
  انقر هنا
</MyButton>

</syntaxhighlight>تُترجَم الشيفرة السّابقة إلى:<syntaxhighlight lang="javascript">
React.createElement(
  MyButton,
  {color: 'blue', shadowSize: 2},
  'انقر هنا'
)

</syntaxhighlight>بإمكانك أيضًا استخدام الشكل ذاتي الإغلاق للعنصر إن كان لا يحتوي على أيّة عناصر أبناء:<syntaxhighlight lang="javascript">
<div className="sidebar" />

</syntaxhighlight>تُترجَم الشيفرة السّابقة إلى:<syntaxhighlight lang="javascript">
React.createElement(
  'div',
  {className: 'sidebar'},
  null
)

</syntaxhighlight>إن أردتَ اختبار كيفيّة تحويل بعض شيفرات JSX إلى JavaScript فبإمكانك تجريب [https://babeljs.io/repl/#?presets=react&code_lz=GYVwdgxgLglg9mABACwKYBt1wBQEpEDeAUIogE6pQhlIA8AJjAG4B8AEhlogO5xnr0AhLQD0jVgG4iAXyJA مُترجِم Babel على الإنترنت].

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

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

على سبيل المثال الاستيراد التالي ضروري في هذه الشّيفرة على الرغم من أنّ <code>React</code> و <code>CustomButton</code> لا يُشار إليهما بشكل مباشر من JavaScript:<syntaxhighlight lang="javascript">
import React from 'react';
import CustomButton from './CustomButton';

function WarningButton() {
  
  return <CustomButton color="red" />;
  // تُكافئ: return React.createElement(CustomButton, {color: 'red'}, null);
}

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

== استخدام النقطة لأنواع JSX ==
بإمكانك الإشارة أيضًا إلى مُكوِّن React باستخدام النقطة من داخل JSX. وهو أمرٌ جيّد إن كانت لديك وحدة (module) وحيدة والتي تُصدِّر عدّة مُكوِّنات React. على سبيل المثال إن كان <code>MyComponents.DatePicker</code> مُكوِّنًا، فيُمكِنك استخدامه بشكلٍ مباشر من JSX كما يلي:<syntaxhighlight lang="javascript">
import React from 'react';

const MyComponents = {
  DatePicker: function DatePicker(props) {
    return <div>تخيّل وجود {props.color} انتقاء للتاريخ هنا.</div>;
  }
}

function BlueDatePicker() {
  return <MyComponents.DatePicker color="blue" />;
}

</syntaxhighlight>

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

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

على سبيل المثال لن تعمل الشيفرة التالية كما هو مُتوقَّع:<syntaxhighlight lang="javascript">
import React from 'react';

// :خطأ! هذا مُكوِّن ويجب أن يبدأ بحرف كبير
function hello(props) {
  // صحيح! هنا استخدام العنصر div صحيح كونه عنصر في HTML
  return <div>أهلًا {props.toWhat}</div>;
}

function HelloWorld() {
  // خطأ! تعتقد React أنّ العنصر hello هو عنصر في HTML لأنّه لا يبدأ بحرف كبير
  return <hello toWhat="بالعالم" />;
}

</syntaxhighlight>لإصلاح ذلك سنُعيد تسمية <code>hello</code> إلى <code>Hello</code> وسنستخدم <code>‎<Hello /></code>‎ للإشارة إليه:<syntaxhighlight lang="javascript">
import React from 'react';

// صحيح! هذا مُكوِّن ويجب أن يبدأ بحرف كبير
function Hello(props) {
  // صحيح! هنا استخدام العنصر div صحيح كونه عنصر في HTML
  return <div>أهلًا {props.toWhat}</div>;
}

function HelloWorld() {
  // صحيح! تعلم React أنّ Hello هو مُكوِّن لأنّه يبدأ بحرف كبير
  return <Hello toWhat="بالعالم" />;
}

</syntaxhighlight>

== اختيار النوع في زمن التنفيذ ==
لا يُمكنِك استخدام تعبير عام كنوع لعنصر React، فإن لم ترغب باستخدام تعبير عام للإشارة لنوع العنصر، فعيّنه فقط إلى متغيّر يبدأ بحرف كبير أولًا. يحدث هذا عادةً عندما تريد تصيير مُكوِّن آخر بناءً على خاصيّة <code>prop</code>:<syntaxhighlight lang="javascript">
import React from 'react';
import { PhotoStory, VideoStory } from './stories';

const components = {
  photo: PhotoStory,
  video: VideoStory
};

function Story(props) {
  // خطأ! لا يمكن أن يكون نوع JSX عبارة عن تعبير
  return <components[props.storyType] story={props.story} />;
}

</syntaxhighlight>لإصلاح ذلك سنُعيِّن النوع إلى متغيّر يبدأ بحرف كبير أولًا:<syntaxhighlight lang="javascript">
import React from 'react';
import { PhotoStory, VideoStory } from './stories';

const components = {
  photo: PhotoStory,
  video: VideoStory
};

function Story(props) {
  // صحيح! يُمكِن لنوع JSX أن يكون متغيّرًا يبدأ بحرف كبير
  const SpecificStory = components[props.storyType];
  return <SpecificStory story={props.story} />;
}

</syntaxhighlight>

== الخاصيات <code>props</code> في JSX ==
هنالك عدّة طرق لتحديد الخاصيّات في JSX.

=== تعابير JavaScript كخاصيات ===
بإمكانك تمرير أي تعبير JavaScript كخاصيّة <code>prop</code> عن طريق إحاطته بالقوسين <code>{}‎</code>. على سبيل المثال:<syntaxhighlight lang="javascript">
<MyComponent foo={1 + 2 + 3 + 4} />
</syntaxhighlight>بالنسبة للمُكوِّن <code>MyComponent</code> تكون قيمة <code>props.foo</code> هي <code>10</code> بسبب تقييم التعبير ‎<code>1 + 2 + 3 + 4</code>‎.

لا تُعدُّ جمل <code>if</code> الشرطيّة و حلقات <code>for</code> تعابيرًا في JavaScript، لذلك لا يُمكِن استخدامها في JSX بشكلٍ مباشر، وبدلًا من ذلك بإمكاننا وضعها في الشيفرة المُحيطة. على سبيل المثال:<syntaxhighlight lang="javascript">
function NumberDescriber(props) {
  let description;
  if (props.number % 2 == 0) {
    description = <strong>زوجي</strong>;
  } else {
    description = <i>فردي</i>;
  }
  return <div>{props.number} هو عدد {description}</div>;
}

</syntaxhighlight>يُمكِنك تعلّم المزيد حول [[React/conditional rendering|التصيير الشرطي]] واستخدام [[React/lists and keys|الحلقات]] في أقسامها الخاصّة.

=== استخدام السلاسل النصيّة الحرفيّة ===
بإمكانك تمرير سلسلة نصيّة حرفيّة كخاصيّة، فالتعبيران التاليان في JSX مُتكافئان:<syntaxhighlight lang="javascript">
<MyComponent message="hello world" />

<MyComponent message={'hello world'} />

</syntaxhighlight>عندما تُمرِّر سلسلة نصيّة حرفيّة، ستُهرَّب قيمتها (HTML-unescaped) بشكلٍ افتراضي. لذلك التعبيران التاليان مُتكافئان أيضًا:<syntaxhighlight lang="javascript">
<MyComponent message="&lt;3" />

<MyComponent message={'<3'} />

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

=== القيمة الافتراضيّة للخاصيّات <code>props</code> هي <code>true</code> ===
إن لم تُمرِّر أي قيمة للخاصيّة فقيمتها الافتراضيّة هي <code>true</code>. التعبيران التاليان مُتكافئان:<syntaxhighlight lang="javascript">
<MyTextBox autocomplete />

<MyTextBox autocomplete={true} />

</syntaxhighlight>لا نُوصي إجمالًا بفعل ذلك بسبب الارتباك الذي يُسبّبه التشابه مع [https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Operators/Object_initializer#New_notations_in_ECMAScript_2015 الصيغة المختصرة للكائنات في ES6]، حيث تكون ‎<code>{foo}</code>‎ اختصارًا إلى ‎<code>{foo: foo}</code>‎ بدلًا من ‎<code>{foo: true}</code>‎ كما قد تظن. هذا السّلوك موجود هنا فقط للتوافق مع سلوك HTML.

=== خاصيّات النشر ===
إن كانت لديك خاصيّات <code>props</code> على شكل كائنات، وأردتَ تمريرها في JSX، فبإمكانك استخدام مُعامِل النشر … لتمرير كائن الخاصيّات بشكلٍ كامل. المُكوِّنان التاليان مُتكافئان:<syntaxhighlight lang="javascript">
function App1() {
  return <Greeting firstName="Ben" lastName="Hector" />;
}

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

</syntaxhighlight>بإمكانك أيضًا اختيار خاصيّات مُحدّدة يُحدِّد قيمتها مُكوِّنك وتمرير الخاصيّات الأخرى باستخدام مُعامِل النشر:<syntaxhighlight lang="javascript">
const Button = props => {
  const { kind, ...other } = props;
  const className = kind === "primary" ? "PrimaryButton" : "SecondaryButton";
  return <button className={className} {...other} />;
};

const App = () => {
  return (
    <div>
      <Button kind="primary" onClick={() => console.log("clicked!")}>
        أهلًا بالعالم!
      </Button>
    </div>
  );
};

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

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

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

=== السلاسل النصيّة الحرفيّة ===
بإمكانك وضع سلسلة نصيّة بين عنصري البدء والإغلاق وستكون قيمة الخاصيّة <code>props.children</code> هي تلك السلسلة النصيّة. يُفيد ذلك من أجل العديد من عناصر HTML الداخليّة، على سبيل المثال:<syntaxhighlight lang="javascript">
<MyComponent>أهلًا بالعالم!</MyComponent>

</syntaxhighlight>هذه الصيغة صحيحة في JSX، وستكون قيمة <code>props.children</code> في المُكوِّن <code>MyComponent</code> هي السلسلة النصيّة <code>"أهلًا بالعالم!"</code>. تُهرَّب السلسلة النصيّة لذلك بإمكانك كتابة JSX كما تكتب HTML بهذه الطريقة:<syntaxhighlight lang="javascript">
<div>هذه السلسلة النصيّة صالحة بنفس الوقت في HTML &amp; JSX</div>

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

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

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

<div>

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

</syntaxhighlight>

=== العناصر الأبناء ===
بإمكانك إضافة المزيد من عناصر JSX كأبناء، وهذا يُفيد في عرض المُكوِّنات المتداخلة:<syntaxhighlight lang="javascript">
<MyContainer>
  <MyFirstComponent />
  <MySecondComponent />
</MyContainer>

</syntaxhighlight>بإمكانك دمج عدّة أنواع مختلفة من العناصر الأبناء معًا، أي يُمكِنك استخدام السلاسل النصيّة الحرفيّة مع العناصر. وهذا أمرٌ آخر تتشابه فيه JSX مع HTML، لذا يكون المثال التالي صحيحًا في JSX و HTML:<syntaxhighlight lang="javascript">
<div>
  هذه هي القائمة:
  <ul>
    <li>العنصر 1</li>
    <li>العنصر 2</li>
  </ul>
</div>

</syntaxhighlight>يستطيع مُكوِّن React أن يُعيد مصفوفة من العناصر:<syntaxhighlight lang="javascript">
render() {
  // لا حاجة لوضع عناصر القائمة ضمن عنصر إضافي
  return [
	// لاتنس المفاتيح
    <li key="A">العنصر الأول</li>,
    <li key="B">العنصر الثاني</li>,
    <li key="C">العنصر الثالث</li>,
  ];
}

</syntaxhighlight>

=== استخدام تعابير JavaScript كعناصر أبناء ===
بإمكانك تمرير أي تعبير في JavaScript كعنصر ابن عن طريق تغليفه باستخدام القوسين <code>{}‎</code>. فمثلًا هذا التعبيران مُتكافئان:<syntaxhighlight lang="javascript">
<MyComponent>foo</MyComponent>

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

</syntaxhighlight>يُفيد هذا عادةً في تصيير قائمة من تعابير JSX ذات أطوال مختلفة كما يلي:<syntaxhighlight lang="javascript">
function Item(props) {
  return <li>{props.message}</li>;
}

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

</syntaxhighlight>يُمكِن دمج تعابير JavaScript مع أنواع مختلفة من العناصر الأبناء:<syntaxhighlight lang="javascript">
function Hello(props) {
  return <div>أهلًا {props.addressee}!</div>;
}

</syntaxhighlight>

=== استخدام الدوال كعناصر أبناء ===
تُقيَّم عادةً تعابير JavaScript المُدخلَة في JSX إلى سلاسل نصيّة، عناصر React، أو قائمة من هذه الأشياء. ولكن يعمل <code>props.children</code> مثل أي خاصيّة في أنّه يستطيع تمرير أي نوع من البيانات وليس فقط الأنواع التي تعلم React كيفيّة تصييرها. فمثلًا إن كان لديك مُكوِّن مُخصَّص تستطيع أن تجعله يأخذ رد نداء مثل <code>props.children</code>:<syntaxhighlight lang="javascript">
// استدعاء رد نداء العناصر الأبناء عدد من المرات لإنشاء مُكوِن مُكرّر
function Repeat(props) {
  let items = [];
  for (let i = 0; i < props.numTimes; i++) {
    items.push(props.children(i));
  }
  return <div>{items}</div>;
}

function ListOfTenThings() {
  return (
    <Repeat numTimes={10}>
      {(index) => <div key={index}>هذا هو العنصر {index} في القائمة</div>}
    </Repeat>
  );
}

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

=== تتجاهل JSX القيم المنطقيّة (Booleans)، و <code>Null</code>، والقيم غير المُعرَّفة <code>Undefined</code> ===
تُعدُّ القيم <code>false</code>، و <code>null</code>، و <code>undefined</code>، و <code>true</code> عناصر أبناء صحيحة، ولكنّها ببساطة لا تُصيَّر. حيث ينتج عن التعابير التالية في JSX نفس النتيجة:<syntaxhighlight lang="javascript">
<div />

<div></div>

<div>{false}</div>

<div>{null}</div>

<div>{undefined}</div>

<div>{true}</div>

</syntaxhighlight>يُفيد هذا في التصيير الشرطي لعناصر React. ففي المثال التالي تُصيِّر JSX فقط المُكوِّن ‎<code><Header /></code>‎ إن كانت قيمة <code>showHeader</code> هي <code>true</code>:<syntaxhighlight lang="javascript">
<div>
  {showHeader && <Header />}
  <Content />
</div>

</syntaxhighlight>تُصيِّر React القيم الكاذبة مثل العدد صفر. فمثلًا لن تعمل الشيفرة التالية كما تتوقّع لأنّه ستطبع العدد <code>0</code> عندما تكون المصفوفة  <code>props.messages</code> فارغة:<syntaxhighlight lang="javascript">
<div>
  {props.messages.length &&
    <MessageList messages={props.messages} />
  }
</div>

</syntaxhighlight>لإصلاح ذلك احرص أن يكون التعبير قبل المُعامِل <code>&&</code> قيمة منطقيّة دومًا:<syntaxhighlight lang="javascript">
<div>
  {props.messages.length > 0 &&
    <MessageList messages={props.messages} />
  }
</div>

</syntaxhighlight>إن أردتَ بشكلٍ مُعاكِس أن تظهر القيم مثل <code>false</code>، و <code>true</code>، و <code>null</code>، و <code>undefined</code> في الناتج، فيجب عليك [[JavaScript/String|تحويلها إلى سلسلة نصيّة]] أولًا:<syntaxhighlight lang="javascript">
<div>
  متغير JavaScript قيمته {String(myVariable)}.
</div>

</syntaxhighlight>

== انظر أيضًا ==
* [[React/static type checking|التحقق من الأنواع الثابتة]]
* [[React/typechecking with proptypes|التحقق من الأنواع باستخدام PropTypes]]
* [[React/refs and the dom|استخدام المراجع مع DOM]]
* [[React/uncontrolled components|المكونات غير المضبوطة]]
* [[React/optimizing performance|تحسين الأداء]]
* [[React/react without es6|React بدون ES6]]
* [[React/react without jsx|React بدون JSX]]
* [[React/reconciliation|المطابقة (Reconciliation)]]
* [[React/context|استخدام السياق (Context) في React]]
* [[React/fragments|استخدام الأجزاء (Fragments) في React]]
* [[React/portals|المداخل (Portals) في React]]
* [[React/error boundaries|حدود الأخطاء]]
* [[React/web components|مكونات الويب]]
* [[React/higher order components|المكونات ذات الترتيب الأعلى]]
* [[React/forwarding refs|تمرير المراجع]]
* [[React/render props|خاصيات التصيير]]
* [[React/integrating with other libraries|تكامل React مع المكتبات الأخرى]]
* [[React/accessibility|سهولة الوصول]]
* [[React/code splitting|تقسيم الشيفرة]]
* [[React/strict mode|الوضع الصارم (Strict Mode)]]

==مصادر==
*[https://reactjs.org/docs/jsx-in-depth.html صفحة شرح JSX بالتفصيل في توثيق React الرسمي].
[[تصنيف:React]]
[[تصنيف:React Advanced Guides]]