عرض مصدر React/react component

<noinclude>{{DISPLAYTITLE:الصنف React.Component}}</noinclude>
تحتوي هذه الصفحة على مرجع مُفصَّل لواجهة برمجة التطبيقات (API) لتعريف صنف مكوّن React. سنفترض أنك على معرفة بمفاهيم React الأساسية، مثل [[React/components and props|الخاصيّات <code>props</code> والمكوّنات]]، بالإضافة إلى [[React/state and lifecycle|الحالة ودورة حياة المكوّنات]]. إن لم تكن كذلك فاطلع عليها أولًا.

== لمحة عامة ==
تُتيح لك React أن تُعرِّف المكوّنات كأصناف أو دوال. تُزوّدنا المكوّنات المُعرَّفة كأصناف بميزات أكثر حاليًّا والتي سنشرحها بالتفصيل هنا. لتعريف صنف مكوّن React تحتاج إلى أن تمتد إلى الصنف <code>React.Component</code>:<syntaxhighlight lang="javascript">
class Welcome extends React.Component {
  render() {
    return <h1>أهلًا {this.props.name}</h1>;
  }
}

</syntaxhighlight>التابع الوحيد الذي يجب عليك تعريفه في الصنف الفرعي الناتج عن الصنف <code>React.Component</code> هو <code>[[React/react component#render.28.29.E2.80.8E|render()]]</code>‎، أمّا بقية التوابع المذكورة في هذه الصفحة هي اختياريّة.

نوصي بشدّة ألّا تُنشِئ أصنافًا أساسيّة للمكوّنات خاصّة بك، ففي مكوّنات React تتحقّق [[React/composition vs inheritance|إعادة استخدام الشيفرة بشكل أساسي عبر التركيب (composition) بدلًا من الوراثة (inheritance)]].

'''ملاحظة:''' لا تُجبِرك React على استخدام صياغة أصناف ES6. إن كنت تفضّل تجنّب ذلك فبإمكانك استخدام الوحدة <code>create-react-class</code> أو أي تجريد مُخصَّص مماثل بدلًا من ذلك. انظر إلى [[React/react without es6|استخدام React بدون ES6]] لتعلّم المزيد.

== دورة حياة المكوّن ==
يمتلك كل مكوّن توابع دورة حياة متعدّدة والتي تستطيع تجاوزها لتنفيذ الشيفرة في أوقات مُحدَّدة. تستطيع استخدام [http://projects.wojtekmaj.pl/react-lifecycle-methods-diagram/ مُخطّط دورة حياة المكوّنات هذا]. في القائمة التالية سنكتب أسماء توابع دورة الحياة الشائعة بالخط العريض. أما البقية فهي موجودة لحالات الاستخدام النادرة نسبيًّا.

=== الوصل (mounting) ===
تُستدعى هذه التوابع بالترتيب التالي عند إنشاء نسخة من المكوّن وإدخالها إلى DOM:
* <code>[[React/react component#constructor.28.29.E2.80.8E|constructor()]]‎</code>.
* <code>[[React/react component#static getDerivedStateFromProps.28.29.E2.80.8E|static getDerivedStateFromProps()]]‎</code>.
* <code>[[React/react component#render.28.29.E2.80.8E|render()]]‎</code>.
* <code>[[React/react component#componentDidMount.28.29.E2.80.8E|componentDidMount()]]</code>‎.
'''ملاحظة:''' يُعتبر هذا التابع قديمًا ويجب أن [https://reactjs.org/blog/2018/03/27/update-on-async-rendering.html تتجنّب] استخدامه في الشيفرة الجديدة:
* <code>[[React/react component#componentWillUnmount.28.29.E2.80.8E|UNSAFE_componentWillMount()‎]]</code>.

=== التحديث ===
يُمكِن أن يحصل التحديث عن طريق التغييرات في الخاصيّات أو الحالة. تُستدعى هذه التوابع بالترتيب التالي عند إعادة تصيير المكوّن:
* <code>[[React/react component#static getDerivedStateFromProps.28.29.E2.80.8E|static getDerivedStateFromProps()]]‎</code>.
* <code>[[React/react component#shouldComponentUpdate.28.29.E2.80.8E|shouldComponentUpdate()]]‎</code>.
* <code>[[React/react component#render.28.29.E2.80.8E|render()]]‎</code>.
* <code>[[React/react component#getSnapshotBeforeUpdate.28.29.E2.80.8E|getSnapshotBeforeUpdate()]]‎</code>.
* <code>[[React/react component#componentDidUpdate.28.29.E2.80.8E|componentDidUpdate()]]‎</code>.
'''ملاحظة:''' تُعتبر هذه التوابع قديمة ويجب أن تتجنّب استخدامها في الشيفرة الجديدة:
* <code>[[React/react component#UNSAFE componentWillUpdate.28.29.E2.80.8E|UNSAFE_componentWillUpdate()‎]]</code>.
* <code>[[React/react component#UNSAFE componentWillReceiveProps.28.29.E2.80.8E|UNSAFE_componentWillReceiveProps()]]‎</code>.

=== الفصل (unmounting) ===
يُستدعى هذا التابع عند إزالة المكون من DOM:
* <code>[[React/react component#componentWillUnmount.28.29.E2.80.8E|componentWillUnmount()‎]]</code>.

=== معالجة الأخطاء ===
يُستدعى هذا التابع عند وجود خطأ أثناء التصيير، أو في تابع دورة حياة المكوّن، أو في الدالة البانية لأي من المكوّنات الأبناء.

====== [[React/react component#componentDidCatch.28.29.E2.80.8E|componentDidCatch()‎]]. ======

== واجهات برمجة التطبيق الأخرى ==
يُعطينا كل مكوّن بواجهات برمجة تطبيق أخرى:
* <code>[[React/react component#setState.28.29.E2.80.8E|setState()]]‎</code>.
* <code>[[React/react component#forceUpdate.28.29.E2.80.8E|forceUpdate()‎]]</code>.

== خاصيّات الصنف ==
* <code>[[React/react component#defaultProps|defaultProps]]</code>.
* <code>[[React/react component#displayName|displayName]]</code>.

== خاصيّات النسخة (Instance) ==
* <code>[[React/react component#props|props]]</code>.
* <code>[[React/react component#state|state]]</code>.

== مرجع ==

=== أشيع توابع دورة الحياة المستخدمة ===
تُغطّي التوابع في هذا القسم معظم حالات الاستخدام التي ستصادفها أثناء إنشاء مكوّنات React. للحصول على مرجع لمخطط بصري انظر إلى [http://projects.wojtekmaj.pl/react-lifecycle-methods-diagram/ مخطط دورة حياة المكوّنات].

==== <code>render()‎</code> ====
<syntaxhighlight lang="javascript">
render()
</syntaxhighlight>التابع <code>render()‎</code> هو التابع الوحيد المطلوب وجوده في مكوّنات الأصناف.

عند استدعائه يجب أن يفحص <code>this.props</code> و <code>this.state</code> ويُعيد إحدى الأنواع التالية:
* عناصر React: تُنشَأ عادةً عن طريق JSX. على سبيل المثال ‎<code><nowiki><div /></nowiki></code>‎ و ‎<code><MyComponent />‎</code> هي عناصر React والتي تأمر React بتصيير عقدة DOM ومكوّن مُعرَّف من قبل المستخدم على التوالي وبالترتيب.
* الأجزاء والمصفوفات: تسمح لك بإعادة عناصر متعددة من التابع <code>render</code>. انظر إلى [[React/fragments|توثيق الأجزاء]] للمزيد من التفاصيل.
* المداخل (Portals): تسمح لك بتصيير العناصر الأبناء إلى تفرعات مختلفة من DOM. انظر إلى توثيق [[React/portals|المداخل]] للمزيد من التفاصيل.
* الأعداد والسلاسل النصيّة: تُصيَّر كعقد نصيّة في DOM.
* القيم المنطقية (Booleans) أو <code>null</code>: لا تُصيِّر شيئًا. (موجودة في معظم الأحيان لدعم النمط <code>‎return test && <Child /></code>‎ حيث يكون <code>test</code> هو قيمة منطقيّة).
يجب أن يكون التابع <code>render()‎</code> نقيًّا، أي لا يُعدِّل حالة المكوّن، ويعيد نفس النتيجة في كل مرة يُستدعى فيها، ولا يتفاعل بشكل مباشر مع المتصفح.

إن أردت التفاعل مع المتصفح فأنجز العمل المطلوب ضمن التابع <code>componentDidMount()</code>‎ أو أي تابع من توابع دورة الحياة. إنّ الحفاظ على التابع <code>render()</code>‎ نقيًّا يزيد سهولة التفكير بمكوّناتك.

'''ملاحظة:''' لن يُستدعى التابع <code>render()</code>‎ إن أعاد التابع <code>[[React/react component#shouldComponentUpdate.28.29.E2.80.8E|shouldComponentUpdate()]]</code>‎ القيمة <code>false</code>.

==== <code>constructor()‎</code> ====
<syntaxhighlight lang="javascript">
constructor(props)
</syntaxhighlight>إن لم تضع قيمة بدئية للحالة ولم تربط التوابع، فلن تحتاج إلى إضافة دالة بانية إلى مكوناتك.

تُستدعى الدالة البانية لمكوّن React قبل الوصل. عند إضافة الدالة البانية لصنف فرعي عن الصنف <code>React.Component</code> فيجب أن تستدعي <code>super(props)</code>‎ قبل أي جملة أخرى وإلّا ستكون <code>this.props</code> غير معرفة في الدالة البانية والذي قد يؤدي إلى أخطاء.

تستخدم الدوال البانية في React فقط لغرضين عادةً:
* تهيئة [[React#.D8.AD.D8.A7.D9.84.D8.A9 .D9.88.D8.AF.D9.88.D8.B1.D8.A9 .D8.AD.D9.8A.D8.A7.D8.A9 .D8.A7.D9.84.D9.85.D9.83.D9.88.D9.86.D8.A7.D8.AA|الحالة المحلية]] عن طريق تعيين كائن إلى <code>this.state</code>.
* ربط توابع [[React#.D9.85.D8.B9.D8.A7.D9.84.D8.AC.D8.A9 .D8.A7.D9.84.D8.A3.D8.AD.D8.AF.D8.A7.D8.AB .D9.81.D9.8A React|معالج الأحداث]] إلى النسخة (instance).
يجب ألّا تستدعي <code>setState()</code>‎ في الدالة البانية، وإن كان مكوّنك يحتاج استخدام الحالة المحليّة فعيّن الحالة المبدئية إلى <code>this.state</code> مباشرة في الدالة البانية:<syntaxhighlight lang="javascript">
constructor(props) {
  super(props);
  // لا تستدعي this.setState() هنا
  this.state = { counter: 0 };
  this.handleClick = this.handleClick.bind(this);
}

</syntaxhighlight>الدالة البانية هي المكان الوحيد الذي يجب أن تّعين فيه <code>this.state</code> بشكل مباشر، ففي جميع التوابع الأخرى يجب استخدام <code>this.setState()</code>‎ بدلًا من ذلك.

تجنّب تقديم أي تأثيرات جانبية أو اشتراكات في الدالة البانية، ولتلك الحالات استخدم التابع <code>componentDidMount()‎</code>.

'''ملاحظة:''' تجنّب نسخ الخاصيّات إلى الحالة، فهذا خطأ شائع:<syntaxhighlight lang="javascript">
constructor(props) {
 super(props);
 // لا تفعل هذا
 this.state = { color: props.color };
}

</syntaxhighlight>المشكلة هي أنّ هذا غير ضروري (حيث تستطيع استخدام <code>this.props.color</code> بشكل مباشر) ويُعطي أخطاء (لن تنعكس التحديثات على الخاصيّة <code>color</code> في الحالة).

استخدم هذا النمط إن كنت تريد عن قصد تجاهل تحديثات الخاصيّات. في تلك الحالة من المنطقي إعادة تسمية الخاصيّة إلى <code>initialColor</code> أو <code>defaultColor</code>. بإمكانك بعدها إجبار المكوّن على إعادة تعيين حالته الداخلية عن طريق [https://reactjs.org/blog/2018/06/07/you-probably-dont-need-derived-state.html#recommendation-fully-uncontrolled-component-with-a-key تغيير المفتاح] عند الضرورة.

اقرأ [https://reactjs.org/blog/2018/06/07/you-probably-dont-need-derived-state.html هذا المنشور حول تجنب الحالات المشتقة] لتتعلم ما يجب فعله إن أردت أن تعتمد الحالة على الخاصيّات.

==== <code>componentDidMount()‎</code> ====
<syntaxhighlight lang="javascript">
componentDidMount()
</syntaxhighlight>يُستدعى <code>componentDidMount()</code>‎ مباشرة بعد وصل المكوّن (إدخاله ضمن الشجرة). يجب أن نضع هنا التهيئة التي تتطلّب عقدة DOM. إن احتجت إلى تحميل بيانات من نقطة بعيدة فهذا التابع مكان جيد لبدء طلبات الشبكة.

يُعد هذا التابع أيضًا مكانًا جيّدًا لإعداد أي اشتراكات. إن فعلت ذلك فلا تنسَ إزالة الاشتراك في التابع <code>componentWillUnmount()</code>‎.

بإمكانك استدعاء <code>setState()</code>‎ مباشرة في التابع <code>componentDidMount()</code>‎. سيُطلِق تصييرًا إضافيًّا ولكن سيحدث ذلك قبل أن يُحدِّث المتصفح الشاشة. يضمن ذلك عدم رؤية المستخدم للحالة مباشرة على الرغم من استدعاء التابع <code>render()</code>‎ مرتين. استخدم هذا النمط بحذر لأنّه يسبب غالبًا مشاكل بالأداء. يجب في معظم الحالات أن تُعيّن الحالة المبدئية في الدالة البانية بدلًا من ذلك. ولكن قد يكون ذلك ضروريًّا لحالات مثل تلميحات الأدوات (tooltips) عندما تحتاج إلى تقدير عقدة DOM قبل تصيير شيء يعتمد على حجمه أو موقعه.

==== <code>componentDidUpdate()‎</code> ====
<syntaxhighlight lang="javascript">
componentDidUpdate(prevProps, prevState, snapshot)
</syntaxhighlight>يُستدعى التابع <code>componentDidUpdate()</code>‎ مباشرة بعد حصول التحديث. لا يُستدعى هذا التابع من أجل التصيير المبدئي.

استخدم هذا التابع كفرصة للعمل على DOM عند تحديث المكوّن. يُعد هذا التابع مكانًا جيّدًا لإتمام طلبات الشبكة طالما تُقارِن الخاصيّات الحالية مع الخاصيّات السابقة (أي قد يكون طلب الشبكة غير ضروريّ إن لم تتغير الخاصيّات):<syntaxhighlight lang="javascript">
componentDidUpdate(prevProps) {
  // استخدام نموذجي (لا تنس مقارنة الخاصيات)
  if (this.props.userID !== prevProps.userID) {
    this.fetchData(this.props.userID);
  }
}

</syntaxhighlight>بإمكانك استدعاء <code>setState()‎</code> مباشرة في التابع <code>componentDidUpdate()‎</code> ولكن انتبه أنّه يجب تغليفه ضمن شرط مثل المثال السابق وإلّا ستسبب حدوث حلقة لا نهائيّة وإعادة تصيير إضافيّة والتي رغم عدم وضوحها للمستخدم إلاّ أنّها تؤثّر على أداء المكوّن. إن كنت تحاول أن تعكس الحالة إلى الخاصيّة الآتية من الأعلى فيجب أن تستخدم الخاصيّة بشكل مباشر. اقرأ المزيد في تدوينة [https://reactjs.org/blog/2018/06/07/you-probably-dont-need-derived-state.html لماذا يُسبب نسخ الخاصيّات إلى الحالة أخطاء].

إن كان يعتمد مكوّنك تابع دورة الحياة <code>getSnapshotBeforeUpdate()</code>‎ (وهو أمرٌ نادر)، فستُمرَّر القيمة التي يُعيدها كُمعامل ثالث إلى التابع <code>componentDidUpdate()‎</code>. فيما عدا ذلك يكون هذا المُعامِل غير مُعرَّفًا.

'''ملاحظة:''' لن يُستدعى التابع <code>componentDidUpdate()‎</code> إن أعاد التابع <code>[[React/react component#shouldComponentUpdate.28.29.E2.80.8E|shouldComponentUpdate()]]</code>‎ القيمة <code>false</code>.

==== <code>componentWillUnmount()‎</code> ====
<syntaxhighlight lang="javascript">
componentWillUnmount()
</syntaxhighlight>يُستدعى التابع <code>componentWillUnmount()</code>‎ مباشرةً قبل فصل المكوّن وتدميره. نفّذ أي مسح ضروري في هذا التابع، مثل تعطيل العدادات، وإلغاء طلبات الشبكة، ومسح أي اشتراكات أنشأها التابع <code>componentDidMount()‎</code>.

لا يجب أن تستدعي التابع <code>setState()‎</code> في التابع <code>componentWillUnmount()</code>‎ لأنّ المكوّن لن يُعاد تصييره. حالما تُفصَل نسخة المكوّن فلن تُوصل مرة أخرى.

=== توابع دورة الحياة نادرة الاستخدام ===
تستخدم التوابع المذكورة في هذا القسم في حالات نادرة، وهي مفيدة من حين لآخر، ولكن لن تحتاجها معظم مكوّناتك. تستطيع أن ترى معظم هذه التوابع في [http://projects.wojtekmaj.pl/react-lifecycle-methods-diagram/ مخطط توابع دورة حياة المكوّنات] إن ضغطت على مربع التأشير <code>"Show less common lifecycles"</code> الموجود في الأعلى.

==== <code>shouldComponentUpdate()‎</code> ====
<syntaxhighlight lang="javascript">
shouldComponentUpdate(nextProps, nextState)
</syntaxhighlight>استخدم التابع <code>shouldComponentUpdate()‎</code> لتُعلِم React إن كان ناتج المكوّن لا يتأثر بالتغيير الحالي للخاصيّات أو الحالة. السلوك الافتراضي هو إعادة التصيير عند كل تغيير للحالة، وفي معظم الحالات ستعتمد على هذا السلوك.

يُستدعى التابع <code>shouldComponentUpdate()</code>‎ قبل التصيير عند استقبال الخاصيّات أو الحالة. القيمة الافتراضية هي <code>true</code>. لا يُستدعى هذا التابع للتصيير المبدئي أو عند استخدام التابع <code>forceUpdate()‎</code>.

يتواجد هذا التابع [[React/optimizing performance|كتحسين للأداء]] فقط، لا تعتمد عليه لمنع التصيير، حيث يقود ذلك إلى أخطاء. انظر في استخدام الصنف <code>[[React/react api#React.PureComponent|PureComponent]]</code> المُضمَّن بدلًا من كتابة التابع <code>shouldComponentUpdate()‎</code> بشكلٍ يدوي. يُنفِّذ الصنف <code>PureComponent</code> مقارنة ضئيلة للخاصيّات والحالة ويُقلِّل فرصة تجاوز تحديث ضروري.

إن كنت متأكدًا من أنّك تريد كتابته بشكل يدوي فيجب أن تقارن <code>this.props</code> مع <code>nextProps</code> و <code>this.state</code> مع <code>nextState</code> وتُعيد القيمة <code>false</code> لتخبر React بإمكانية تجاوز التحديث. انتبه إلى أنّ إعادة القيمة <code>false</code> لا تمنع المكوّنات الأبناء من إعادة التصيير عند تغيير حالتها.

لا نوصي بإجراء اختبارات مفصلة للتساوي أو استخدام التابع <code>JSON.stringify()</code>‎ ضمن <code>shouldComponentUpdate()</code>‎، فهذا غير فعال وسيؤثر على الأداء بشكل كبير.

حاليًّا إن أعاد التابع <code>shouldComponentUpdate()‎</code> القيمة <code>false</code>، فلن تُستدعى التوابع <code>[[React/react component#UNSAFE componentWillUpdate.28.29.E2.80.8E|UNSAFE_componentWillUpdate()]]</code>‎ أو <code>[[React/react component#render.28.29.E2.80.8E|render()‎]]</code> أو <code>[[React/react component#componentDidUpdate.28.29.E2.80.8E|componentDidUpdate()]]‎</code>. في المستقبل قد تُعامل React التابع <code>shouldComponentUpdate()</code>‎ كتلميح بدلًا من توجيه صارم، وقد تؤدي إعادة القيمة <code>false</code> إلى إعادة تصيير المكوّن.

==== <code>static getDerivedStateFromProps()‎</code> ====
<syntaxhighlight lang="javascript">
static getDerivedStateFromProps(props, state)
</syntaxhighlight>يُستدعى التابع <code>getDerivedStateFromProps</code> مباشرةً قبل استدعاء تابع التصيير خلال الوصل المبدئي والتحديثات اللاحقة. يجب أن يُعيد كائنًا لتحديث الحالة، أو <code>null</code> لعدم تحديث شيء.

يوجد هذا التابع من أجل [https://reactjs.org/blog/2018/06/07/you-probably-dont-need-derived-state.html#when-to-use-derived-state استخدامات نادرة] عندما تعتمد الحالة على التغييرات في الخاصيّات مع مرور الوقت. على سبيل المثال قد يكون من المفيد تنفيذ المكوّن ‎<code><Transition></code>‎ والذي يقارن بين الأبناء السابقين واللاحقين ليقرر ما ينبغي تحريكه منها للداخل وللخارج.

يؤدي اشتقاق الحالة إلى تعقيد الشيفرة وصعوبة التفكير بمكوّناتك.

[https://reactjs.org/blog/2018/06/07/you-probably-dont-need-derived-state.html احرص على أن تكون على اطلاع على البدائل البسيطة له]:
* إن أردت إنجاز تأثير جانبي (side effect) (مثل الحصول على البيانات أو التحريك) استجابةً للتغيّر في الخاصيّات، فاستخدم تابع دورة الحياة <code>[[React/react component#componentDidUpdate.28.29.E2.80.8E|componentDidUpdate]]</code>.
* إن أردت إعادة حساب بعض البيانات فقط عند تغيير الخاصيّات، فاستخدم [https://reactjs.org/blog/2018/06/07/you-probably-dont-need-derived-state.html#what-about-memoization مساعد التذكير] بدلًا من ذلك.
* إن أردت إعادة تعيين حالة ما عند تغيّر الخاصيّة، فانظر في إمكانية جعل المكوّن [https://reactjs.org/blog/2018/06/07/you-probably-dont-need-derived-state.html#recommendation-fully-controlled-component مضبوطًا بشكل كامل] أو [https://reactjs.org/blog/2018/06/07/you-probably-dont-need-derived-state.html#recommendation-fully-uncontrolled-component-with-a-key غير مضبوط مع استخدام المفاتيح].
لا يمتلك هذا التابع الوصول إلى نسخة المكوّن. إن أردت فبإمكانك إعادة استخدام بعض الشيفرة بين <code>getDerivedStateFromProps()</code>‎ و توابع أخرى للصنف عن طريق استخراج الدوال النقية لخاصيّات وحالة المكوّن خارج تعريف الصنف.

انتبه إلى إطلاق هذا التابع عند كل تصيير بغض النظر عن السبب، وهذا على عكس <code>UNSAFE_componentWillReceiveProps</code>، والذي يُطلَق فقط عندما يُسبِّب المكوّن الأب إعادة التصيير وليس كنتيجة عن التابع <code>setState</code> المحلّي.

==== <code>getSnapshotBeforeUpdate()‎</code> ====
<syntaxhighlight lang="javascript">
getSnapshotBeforeUpdate(prevProps, prevState)
</syntaxhighlight>يُستدعى التابع <code>getSnapshotBeforeUpdate()‎</code> مباشرة قبل تطبيق الناتج الأخير المُصَّير إلى DOM. يُمكّننا من التقاط بعض المعلومات من DOM (مثل موضع النزول في الصفحة scroll) قبل أن تتغيّر. تُمرَّر أي قيمة مُعادة من هذا التابع كمعامل إلى <code>componentDidUpdate()</code>‎.

حالة الاستخدام هذه ليست شائعة، ولكن قد تحدث في واجهات مستخدم مثل محادثة في تطبيق للدردشة يحتاج للتعامل مع موضع النزول في الصفحة بطريقة معينة.

يجب إعادة قيمة snapshot (أو <code>null</code>).

على سبيل المثال:<syntaxhighlight lang="javascript">
class ScrollingList extends React.Component {
  constructor(props) {
    super(props);
    this.listRef = React.createRef();
  }

  getSnapshotBeforeUpdate(prevProps, prevState) {
	// هل نضيف عناصر جديدة للقائمة؟
	// التقط موضع النزول في الصفحة بحيث نتمكن من ضبطه لاحقًا
    if (prevProps.list.length < this.props.list.length) {
      const list = this.listRef.current;
      return list.scrollHeight - list.scrollTop;
    }
    return null;
  }

  componentDidUpdate(prevProps, prevState, snapshot) {
	// إن كانت لدينا قيمة snapshot فقد أضفنا للتو عناصر جديدة
	// ضبط النزول في الصفحة بحيث لا تدفع العناصر الجديدة العناصر القديمة خارج نطاق الرؤية
	// قيمة snapshot هي القيمة المعادة من التابع getSnapshotBeforeUpdate
    if (snapshot !== null) {
      const list = this.listRef.current;
      list.scrollTop = list.scrollHeight - snapshot;
    }
  }

  render() {
    return (
      <div ref={this.listRef}>{/* ...contents... */}</div>
    );
  }
}

</syntaxhighlight>من الهام في المثال السابق قراءة الخاصيّة <code>scrollHeight</code> في <code>getSnapshotBeforeUpdate</code> لأنّه قد توجد تأخيرات بين توابع طور التصيير (مثل التابع <code>render</code>) وتوابع طور التطبيق (مثل <code>getSnapshotBeforeUpdate</code> و <code>componentDidUpdate</code>).

==== <code>componentDidCatch()‎</code> ====
<syntaxhighlight lang="javascript">
componentDidCatch(error, info)
</syntaxhighlight>[[React/error boundaries|حدود الأخطاء]] (Error boundaries) هي مكوّنات React التي تُمسِك أخطاء JavaScript في أي مكان من شجرة المكوّنات الفرعية عنها، وتُسجل الأخطاء، وتعرض واجهة مستخدم بديلة عن شجرة المكوّنات التي انهارت. تُمسِك حدود الأخطاء بالأخطاء خلال التصيير، وفي توابع دورة حياة المكوّنات، وفي الدوال البانية لكل شجرة المكوّنات الأدنى منها.

يُصبح مكوّن الصنف حدًّا للأخطاء إن كان يُعرِّف تابع دورة الحياة <code>componentDidCatch()</code>‎. يسمح لك استدعاء التابع <code>setState()‎</code> في التقاط أخطاء JavaScript غير المُتعامَل معها في المستوى الأدنى من الشجرة مع عرض واجهة مستخدم بديلة. استخدم حدود الأخطاء فقط من أجل التعافي من الأخطاء غير المتوقعة، لا تحاول استخدامها للتحكم بتدفق البيانات.

للمزيد من المعلومات انظر إلى [https://reactjs.org/blog/2017/07/26/error-handling-in-react-16.html التعامل مع الأخطاء في React 16].

'''ملاحظة:''' تُمسِك حدود الأخطاء فقط الأخطاء في المستويات الأدنى منها في شجرة المكوّنات، فلا يستطيع حد الخطأ أن يُمسِك بالأخطاء الحاصلة ضمنه.

=== توابع دورة الحياة القديمة ===
تعتبر توابع دورة الحياة التالية قديمة. لا تزال تعمل ولكن لا نوصي باستخدامها في الشيفرة الجديدة. بإمكانك تعلم المزيد حول الانتقال من التوابع القديمة في [https://reactjs.org/blog/2018/03/27/update-on-async-rendering.html هذا المنشور].

==== <code>UNSAFE_componentWillMount()‎</code> ====
<syntaxhighlight lang="javascript">
UNSAFE_componentWillMount()
</syntaxhighlight>يُستدعى التابع <code>UNSAFE_componentWillMount()</code>‎ مباشرة قبل حدوث الوصل، ويُستدعى قبل تابع التصيير <code>render()‎</code> لذلك لن يُطلِق استدعاء التابع <code>setState()</code>‎ بشكل متزامن في هذا التابع أي تصيير إضافي. نوصي بشكلٍ عام استخدام الدالة البانية <code>constructor()‎</code> بدلًا من ذلك لتهيئة الحالة.

تجنّب تقديم أي آثار جانبية أو اشتراكات في هذا التابع، ولأجل تلك الحالات استخدم التابع <code>componentDidMount()‎</code>.

هذا هو التابع الوحيد من توابع دورة الحياة الذي يُستدعى لأجل التصيير على الخادم.

'''ملاحظة:''' كان يُسمّى هذا التابع سابقًا <code>componentWillMount</code> وسيبقى هذا الاسم يعمل حتى الإصدار 17. استخدم <code>[https://github.com/reactjs/react-codemod#rename-unsafe-lifecycles rename-unsafe-lifecycles codemod]</code> لتحديث مكوّناتك تلقائيًّا.

==== <code>UNSAFE_componentWillReceiveProps()‎</code> ====
<syntaxhighlight lang="javascript">
UNSAFE_componentWillReceiveProps(nextProps)
</syntaxhighlight>'''ملاحظة:''' يقود استخدام تابع دورة الحياة هذا إلى أخطاء وعدم توافقية، لذا سيُهمَل في المستقبل.

إن احتجت إلى إنجاز تأثير جانبي (مثل الحصول على البيانات أو التحريك) استجابةً إلى تغيّر في الخاصيّات، فاستخدم التابع <code>[[React/react component#componentDidUpdate.28.29.E2.80.8E|componentDidUpdate]]</code> بدلًا من ذلك.

من أجل حالات الاستخدام الأخرى اتبع التوصيات في [https://reactjs.org/blog/2018/06/07/you-probably-dont-need-derived-state.html هذا المنشور حول الحالة المشتقة].

إن استخدمت التابع <code>componentWillReceiveProps</code> لإعادة حساب بعض البيانات عند تغيّر الخاصيّات فقط، فاستخدم [https://reactjs.org/blog/2018/06/07/you-probably-dont-need-derived-state.html#what-about-memoization مُساعِد التذكير] بدلًا من ذلك.

إن استخدمت التابع <code>componentWillReceiveProps</code> لإعادة تعيين الحالة عند تغيّر الخاصيّات، فانظر في جعل المكوّن [https://reactjs.org/blog/2018/06/07/you-probably-dont-need-derived-state.html#recommendation-fully-controlled-component مضبوطًا بشكل كامل] أو [https://reactjs.org/blog/2018/06/07/you-probably-dont-need-derived-state.html#recommendation-fully-uncontrolled-component-with-a-key غير مضبوط بشكل كامل مع استخدام المفاتيح] بدلًا من ذلك.

في بعض الحالات النادرة قد ترغب باستخدام تابع دورة الحياة <code>getDerivedStateFromProps</code> كملاذ أخير.

يُستدعى التابع <code>UNSAFE_componentWillReceiveProps()‎</code> قبل أن يستقبل المكوّن الموصول خاصيّات جديدة. إن أردت تحديث الحالة استجابةً لتغيّر الخاصيّة (على سبيل المثال إعادة تعيينها) فبإمكانك مقارنة <code>this.props</code> و <code>nextProps</code> وإتمام تغيير الحالة باستخدام <code>this.setState()‎</code>.

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

لا تستدعي React التابع <code>UNSAFE_componentWillReceiveProps()</code>‎ مع الخاصيّات المبدئية خلال [[React/react component#.D8.A7.D9.84.D9.88.D8.B5.D9.84 .28mounting.29|الوصل]]، وتستدعيه فقط إذا تحدثت بعض خاصيّات المكوّن. لا يُطلِق استدعاء <code>this.setState()‎</code> بشكلٍ عام التابع <code>UNSAFE_componentWillReceiveProps()</code>‎.

'''ملاحظة:''' كان يُسمّى هذا التابع سابقًا <code>componentWillReceiveProps</code> وسيبقى هذا الاسم يعمل حتى الإصدار 17. استخدم <code>[https://github.com/reactjs/react-codemod#rename-unsafe-lifecycles rename-unsafe-lifecycles codemod]</code> لتحديث مكوّناتك تلقائيًّا.

==== <code>UNSAFE_componentWillUpdate()‎</code> ====
<syntaxhighlight lang="javascript">
UNSAFE_componentWillUpdate(nextProps, nextState)
</syntaxhighlight>يُستدعى التابع <code>UNSAFE_componentWillUpdate()‎</code> قبل التصيير عند استقبال خاصيّات أو حالة جديدة. استخدم هذا التابع كفرصة لإنجاز التحضيرات قبل حصول التحديث. لا يُستدعى هذا التابع من أجل التصيير المبدئي.

انتبه إلى أنّك لا تستطيع استدعاء <code>this.setState()‎</code> هنا، ولا ينبغي أن تفعل أي شيء آخر (مثلًا تطبيق إجراء في Redux) يقود إلى إطلاق تحديث مكوّن React قبل إعادة قيمة التابع <code>UNSAFE_componentWillUpdate()‎</code>.

يُمكِن استبدال هذا التابع بالتابع <code>componentDidUpdate()‎</code>. إن كُنتَ تقرأ من DOM في هذا التابع (على سبيل المثال حفظ موضع النزول في الصفحة) فبإمكانك نقل هذا المنطق إلى التابع <code>getSnapshotBeforeUpdate()‎</code>.

'''ملاحظة:''' كان يُسمّى هذا التابع سابقًا <code>componentWillUpdate</code> وسيبقى هذا الاسم يعمل حتى الإصدار 17. استخدم <code>[https://github.com/reactjs/react-codemod#rename-unsafe-lifecycles rename-unsafe-lifecycles codemod]</code> لتحديث مكوّناتك تلقائيًّا.

'''ملاحظة:''' لن يُستدعى التابع <code>UNSAFE_componentWillUpdate()</code>‎ إن أعاد التابع <code>[[React/react component#shouldComponentUpdate.28.29.E2.80.8E|shouldComponentUpdate()]]‎</code> القيمة <code>false</code>.

=== واجهات برمجة التطبيق الأخرى ===
على عكس توابع دورة الحياة السّابقة (والتي تستدعيها React لأجلك)، فإنّ التوابع التالية هي توابع تستطيع استدعاءها من مكوّناتك.

هنالك فقط تابعان: <code>setState()</code>‎ و <code>forceUpdate()</code>‎.

==== <code>setState()‎</code> ====
<syntaxhighlight lang="javascript">
setState(updater[, callback])
</syntaxhighlight>يُطبِّق التابع <code>setState()</code>‎ التغييرات على حالة المكوّن ويُخبِر React بضرورة إعادة تصيير هذا المكوّن ومكوّناته الأبناء مع الحالة الجديدة. هذا هو التابع الرئيسي الذي تستخدمه لتحديث واجهة المستخدم استجابةً لمُعالِج أحداث واستجابات الخادم.

فكّر بالتابع <code>setState()</code>‎ كطلب بدلًا من أمر عاجل لتحديث المكوّن. للحصول على أداء أفضل قد تُؤخِّر React تنفيذ هذا التابع وبعد ذلك تُحدِّث عدّة مكوّنات في نفس الاستدعاء. لا تضمن React تطبيق تغيّرات الحالة بشكلٍ فوري.

لا يُحدِّث التابع <code>setState()‎</code> المكوّن فورًا، فقد يُؤجل التحديث حتى وقتٍ لاحق. يجعل هذا من قراءة <code>this.state</code> مباشرةً بعد استدعاء <code>setState()</code>‎ أمرًا خاطئًا. استخدم بدلًا من ذلك التابع <code>componentDidUpdate</code> أو رد النداء <code>setState</code> (على الشكل <code>setState(updater, callback)</code>‎)، والتي من المضمون إطلاقها بعد تطبيق التحديث. إن احتجت إلى تعيين الحالة بناءً على الحالة السابقة، فاقرأ حول الوسيط <code>updater</code> الذي سنذكره بعد قليل.

يقود <code>setState()</code>‎ إلى إعادة التصيير دومًا ما لم يُرجِع التابع <code>shouldComponentUpdate()‎</code> القيمة <code>false</code>. إن كنت تستخدم الكائنات القابلة للتعديل ولم يكن بالإمكان تطبيق منطق التصيير الشرطي ضمن التابع <code>shouldComponentUpdate()‎</code>، فستتجنّب إعادة التصيير غير الضرورية باستدعاء <code>setState()‎</code> فقط عند اختلاف الحالة الجديدة.

الوسيط الأول هو الدالة <code>updater</code> والتي يكون شكلها كما يلي:<syntaxhighlight lang="javascript">
(prevState, props) => stateChange
</syntaxhighlight><code>prevState</code> هو مرجع إلى الحالة السابقة، فلا يجب تعديله بشكل مباشر، بل يجب تمثيل التغييرات عن طريق بناء كائن جديد اعتمادًا على المُدخلات من <code>prevState</code> و <code>props</code>. فلنفترض مثلًا أنّنا أردنا زيادة القيمة الموجودة في الحالة بإضافة <code>props.step</code> إليها:<syntaxhighlight lang="javascript">
this.setState((prevState, props) => {
  return {counter: prevState.counter + props.step};
});

</syntaxhighlight>من المضمون أن تكون الحالة السابقة <code>prevState</code> والخاصيّات <code>props</code> التي تستقبلها الدالة <code>updater</code> بآخر تحديث. يُدمَج ناتج الدالة <code>updater</code> بشكل ضئيل مع الحالة السابقة <code>prevState</code>.

الوسيط الثاني للتابع <code>setState()</code>‎ هو دالة رد نداء اختياريّة تُنفَّذ حالما يكتمل التابع <code>setState()</code>‎ ويُعاد تصيير المكوّن. نوصي بشكلٍ عام باستخدام التابع <code>componentDidUpdate()</code>‎ لأجل هذا المنطق.

بإمكانك بشكل اختياري تمرير كائن كوسيط أول للتابع <code>setState()‎</code> بدلًا من تمرير دالة:<syntaxhighlight lang="javascript">
setState(stateChange[, callback])
</syntaxhighlight>يؤدي هذا إلى دمج ضئيل لتغيير الحالة <code>stateChange</code> مع الحالة الجديدة، على سبيل المثال لضبط كمية العنصر موجود في سلّة الشراء:<syntaxhighlight lang="javascript">
this.setState({quantity: 2})
</syntaxhighlight>هذا الشكل للتابع <code>setState()</code>‎ غير متزامن أيضًا، ويُمكِن تجميع الاستدعاءات المتعددة خلال نفس الدور مع بعضها. مثلًا إن حاولت زيادة كمية العنصر أكثر من مرّة في نفس الدورة فسينتج عن ذلك ما يلي:<syntaxhighlight lang="javascript">
Object.assign(
  previousState,
  {quantity: state.quantity + 1},
  {quantity: state.quantity + 1},
  ...
)

</syntaxhighlight>تتجاوز الاستدعاءات المتلاحقة القيم من الاستدعاءات السابقة في نفس الدورة، لذا ستزداد الكمية فقط مرّة واحدة. إن كانت الحالة التالية تعتمد على الحالة السابقة فنوصي باستخدام شكل الدالة <code>updater</code> بدلًا من ذلك:<syntaxhighlight lang="javascript">
this.setState((prevState) => {
  return {quantity: prevState.quantity + 1};
});

</syntaxhighlight>للمزيد من التفاصيل انظر:
* [[React/state and lifecycle|دليل توابع دورة الحياة والحالة]].
* [https://stackoverflow.com/a/48610973/458193 شرح مفصّل: متى ولماذا نُجمِّع استدعاءات التابع <code>setState()‎</code>؟].
* [https://github.com/facebook/react/issues/11527#issuecomment-360199710 شرح مفصّل: لماذا لا تُحدَّث قيمة <code>this.state</code> مباشرةً؟].

==== <code>forceUpdate()‎</code> ====
<syntaxhighlight lang="javascript">
component.forceUpdate(callback)
</syntaxhighlight>عندما تتغيّر حالة أو خاصيّات مكوّناتك فسيعيد المكوّن تصيير نفسه بشكلٍ افتراضي. إن كان تابع التصيير <code>render()‎</code> لديك يعتمد على بعض البيانات الأخرى، فبإمكانك إخبار React بضرورة إعادة تصيير المكوّن عن طريق استدعاء التابع <code>forceUpdate()‎</code>.

سيُؤدي استدعاء التابع <code>forceUpdate()‎</code> إلى استدعاء التابع <code>render()</code>‎ في المكوّن مع تجاوز التابع <code>shouldComponentUpdate()‎</code>. سيُطلِق ذلك توابع دورة الحياة الاعتيادية للمكوّنات الأبناء بما في ذلك التابع <code>shouldComponentUpdate()</code>‎ لكل ابن. وستبقى React تُحدِّث DOM فقط عند حصول تغيير.

يجب عليك أن تحاول تجنّب استخدام التابع <code>forceUpdate()‎</code> وأن تقرأ القيم فقط من <code>this.props</code> و <code>this.state</code> في التابع <code>render()</code>‎.

=== خاصيّات الصنف ===

==== <code>defaultProps</code> ====
يُمكِن تعريف <code>defaultProps</code> كخاصيّة لمكوّن الصنف نفسه لتعيين الخاصيّات الافتراضيّة للصنف. تُستخدَم هذه الخاصيّة لأجل الخاصيّات غير المُعرَّفة، ولكن ليس لأجل الخاصيّات null، على سبيل المثال:<syntaxhighlight lang="javascript">
class CustomButton extends React.Component {
  // ...
}

CustomButton.defaultProps = {
  color: 'blue'
};

</syntaxhighlight>إن تُعطى قيمة <code>props.color</code> فستُعيَّن بشكل افتراضي إلى ‎<code>'blue'</code>‎:<syntaxhighlight lang="javascript">
render() {
    return <CustomButton /> ; // props.color ستُعين إلى اللون الأزرق
  }

</syntaxhighlight>إن كانت <code>props.color</code> مُعيَّنة إلى <code>null</code> فستبقى <code>null</code>:<syntaxhighlight lang="javascript">
render() {
    return <CustomButton color={null} /> ; // props.color ستبقى null
  }

</syntaxhighlight>

==== <code>displayName</code> ====
تُستخدَم السلسلة النصيّة <code>displayName</code> في رسائل تنقيح الأخطاء (debugging). لن تحتاج عادةً إلى تعيينها بشكلٍ خاص لأنّها تُشتق من اسم الدالة أو الصنف الذي يُعرِّف المكوّن. قد ترغب بعيينها بشكلٍ صريح إن أردت أن تعرض اسمًا مختلفًا لأغراض تنقيح الأخطاء أو عند إنشاء مكوّن ذو ترتيب أعلى. للمزيد من التفاصيل انظر إلى [[React/higher order components#.D8.AA.D8.BA.D9.84.D9.8A.D9.81 .D8.A7.D9.84.D8.A7.D8.B3.D9.85 .D8.A7.D9.84.D9.85.D8.B9.D8.B1.D9.88.D8.B6 .D9.84.D8.B3.D9.87.D9.88.D9.84.D8.A9 .D8.AA.D9.86.D9.82.D9.8A.D8.AD .D8.A7.D9.84.D8.A3.D8.AE.D8.B|تغليف الاسم المعروض لتسهيل تنقيح الأخطاء]].

=== خاصيّات النسخة (Instance) ===

==== <code>props</code> ====
تحتوي <code>this.props</code> على الخاصيّات المُعرَّفة في السطر الذي استدعى هذا المكوّن. انظر إلى [[React/components and props|توثيق المكوّنات والخاصيّات]] لمقدمة حول الخاصيّات.

<code>this.props.children</code> هي خاصيّة مميزة مُعرَّفة عن طريق الوسم <code>child</code> في تعبير JSX بدلًا من وضعها ضمن الوسم نفسه.

==== <code>state</code> ====
تحتوي الحالة على بيانات خاصّة بهذا المكوّن والتي قد تتغيّر مع مرور الوقت. تُعرَّف الحالة من قبل المستخدم ويجب أن تكون كائن JavaScript مجرّد.

إن لم تكن قيمة ما مستخدمة للتصيير أو تدفق البيانات (على سبيل المثال مُعرِّف عدّاد الوقت) فلا يجب عليك وضعها ضمن الحالة، حيث يُمكِن تعريف مثل هذه القيم كحقول في نسخة المكوّن.

انظر إلى [[React/state and lifecycle|الحالة وتوابع دورة الحياة]] للمزيد من المعلومات حول الحالة.

لا تُعدِّل قيمة <code>this.state</code> بشكلٍ مباشر إطلاقًا، فقد يؤدي استدعاء <code>setState()</code>‎ بعدها إلى تبديل التغيير الذي أجريته. تعامل مع <code>this.state</code> كما لو أنّها قيمة غير قابلة للتعديل.

==مصادر==
*[https://reactjs.org/docs/react-component.html صفحة الصنف React.Component في توثيق React الرسمي].
[[تصنيف:React]]