الفرق بين المراجعتين لصفحة: «React/react api»

مراجعة 08:06، 5 سبتمبر 2018

إنّ الكائن React هو نقطة الدخول إلى مكتبة React. إن حمّلت React عن طريق العنصر ‎<script>‎ فستكون هذه الواجهة ذات المستوى الأعلى متوفرة عبر الكائن العام React. وإن استخدمت ES6 مع npm فتستطيع كتابة ‎import React from 'react'‎. إن استخدمت ES5 مع npm فتستطيع كتابة ‎var React = require('react')‎.

لمحة عامة

المكوّنات

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

React.Component.
React.PureComponent.

إن لم تكن تستخدم أصناف ES6 فبإمكانك استخدام الوحدة create-react-class. انظر إلى استخدام React بدون ES6 للمزيد من المعلومات.

إنشاء عناصر React

نوصي باستخدام JSX لوصف مظهر واجهة المستخدم لديك. كل عنصر في JSX هو مجرّد تعبير بديل لاستدعاء التابع React.createElement()‎. لن تضطر بشكل اعتيادي إلى استدعاء التوابع التالية بشكل مباشر إن كنت تستخدم JSX:

createElement()‎.
createFactory()‎.

انظر إلى استخدام React بدون JSX للمزيد من المعلومات.

تحويل العناصر

يُزوّدنا الكائن React بالعديد من واجهات برمجة التطبيقات (APIs) للتعامل مع العناصر:

cloneElement()‎.
isValidElement()‎.
React.Children.

الأجزاء (Fragments)

تُزوِّدنا React أيضًا بمكوّن لتصيير عدة عناصر بدون مُغلِّف له.

React.Fragment.

المراجع (Refs)

React.createRef.
React.forwardRef.

مرجع

`React.Component`

إنّ React.Component هو عبارة عن الصنف الأساسي لمكوّنات React عند تعريفها باستخدام أصناف ES6:

class Greeting extends React.Component {
  render() {
    return <h1>أهلًا {this.props.name}</h1>;
  }
}

انظر إلى مرجع React.Component API للحصول على قائمة بالتوابع والخاصيّات المرتبطة بالصنف React.Component الأساسي.

`React.PureComponent`

يُشبه React.PureComponent الصنف React.Component. الفرق بينهما هي عدم اعتماد الصنف React.Component للتابع shouldComponentUpdate()‎ بينما يعتمده React.PureComponent مع مقارنة ضئيلة بين الخاصيّات والحالة.

إن كان تابع التصيير render()‎ للمكوّن يُصيّر نفس النتيجة عند إعطاء نفس الخاصيّات والحالة فتستطيع استخدام React.PureComponent لتحسين الأداء في بعض الحالات.

ملاحظة: يُقارِن التابع shouldComponentUpdate()‎ الخاص بالصنف React.PureComponent مقارنة ضئيلة فقط بين الكائنات، فإن كانت تحتوي على بنى معطيات معقدة فقد يُنتِج سلبيات كاذبة للمقارنات الأعمق. يجب الامتداد إلى الصنف PureComponent فقط عندما تتوقع امتلاك حالة وخاصيّات بسيطة، أو استخدم التابع forceUpdate()‎ عندما تعلم بتغيّر بنى المعطيات العميقة، أو انظر في استخدام الكائنات غير القابلة للتعديل لتسهيل المقارنات السريعة بين البيانات المتداخلة.

يتخطى التابع shouldComponentUpdate()‎ أيضًا تحديث الخاصيّات لكامل الشجرة الفرعية للمكوّن، احرص على أن تكون المكوّنات الأبناء له أيضًا نقيّة.

`createElement()‎`

React.createElement(
  type,
  [props],
  [...children]
)

يُنشِئ ويُعيد عنصر React جديد من النوع المُعطى. يُمكِن للوسيط type أن يكون إمّا سلسلة نصيّة لاسم العنصر (مثل ‎'div'‎ أو ‎'span'‎)، أو نوع لمكوّن React (مثل صنف أو دالة)، أو نوع لجزء React (أي fragment).

تُحوَّل الشيفرة المكتوبة باستخدام JSX إلى استدعاءات للتابع React.createElement()‎. لن تستدعي هذا التابع بشكل مباشر عادةً إن كنت تستخدم JSX. انظر إلى استخدام React بدون JSX لتعلم المزيد.

`cloneElement()‎`

React.cloneElement(
  element,
  [props],
  [...children]
)

ينسخ ويُعيد عنصر React جديد باستخدام الوسيط element كنقطة بداية. يمتلك العنصر الناتج نفس خاصيّات العنصر الأصلي مع دمج الخاصيّات الجديد. سيحل العناصر الأبناء المُقدمين عبر الوسيط children محل العناصر الأبناء الحاليين. سيُحتفَظ بالمفتاح key والمرجع ref من العنصر الأصلي. يُكافِئ التابع React.cloneElement()‎ كتابة ما يلي:

<element.type {...element.props} {...props}>{children}</element.type>

ولكن يُحافِظ استخدام التابع على المرجع ref أيضًا. يعني هذا أنّه لو كان لديك عنصر ابن مع مرجع ref ضمنه، فلن تأخذه عن طريق الخطأ من العنصر السليف له، بل ستحصل على نفس المرجع مُرفقًا بعنصرك الجديد.

قُدِّمت هذه الواجهة (ِAPI) كبديل للتابع React.addons.cloneWithProps()‎ المُهمَل.

`createFactory()‎`

React.createFactory(type)

يُعيد دالة تُنتِج عناصر React من النوع المُعطى. وكما هو الحال مع التابع React.createElement()‎ يُمكِن للوسيط type أن يكون إمّا سلسلة نصيّة لاسم العنصر (مثل ‎'div'‎ أو ‎'span'‎)، أو نوع لمكوّن React (مثل صنف أو دالة)، أو نوع لجزء React (أي fragment).

يُعتبَر هذا التابع قديمًا في React ونوصي باستخدام JSX أو التابع React.createElement()‎ بشكل مباشر بدلًا من ذلك.

لن تستدعي هذا التابع بشكل مباشر إن كنت تستخدم JSX. انظر إلى استخدام React بدون JSX لتعلّم المزيد.

`isValidElement()‎`

React.isValidElement(object)

يتحقّق من أنّ الكائن هو عنصر React. يُعيد القيمة true أو false.

`React.Children`

يُزوّدنا React.Children بأدوات مساعدة للتعامل مع بنية المعلومات this.props.children.

`React.Children.map`

React.Children.map(children, function[(thisArg)])

يستدعي دالة لكل عنصر ابن مباشر موجود ضمن children مع تعيين this إلى قيمة thisArg. إن كان children عبارة عن جزء (fragment) مع مفتاح أو مصفوفة فلن تُمرَّر الدالة للكائن الحاوي. إن كانت قيمة children هي null أو undefined فسيُعيد null أو undefined بدلًا من المصفوفة.

@@ سطر 52: / سطر 52: @@
 == <code>createElement()‎</code> ==
+<syntaxhighlight lang="javascript">
+React.createElement(
+  type,
+  [props],
+  [...children]
+)
+</syntaxhighlight>يُنشِئ ويُعيد عنصر React جديد من النوع المُعطى. يُمكِن للوسيط <code>type</code> أن يكون إمّا سلسلة نصيّة لاسم العنصر (مثل ‎<code>'div'‎</code> أو ‎<code>'span'</code>‎)، أو نوع لمكوّن React (مثل صنف أو دالة)، أو نوع لجزء React (أي fragment).
+تُحوَّل الشيفرة المكتوبة باستخدام JSX إلى استدعاءات للتابع <code>React.createElement()</code>‎. لن تستدعي هذا التابع بشكل مباشر عادةً إن كنت تستخدم JSX. انظر إلى استخدام React بدون JSX لتعلم المزيد.
+== <code>cloneElement()‎</code> ==
+<syntaxhighlight lang="javascript">
+React.cloneElement(
+  element,
+  [props],
+  [...children]
+)
+</syntaxhighlight>ينسخ ويُعيد عنصر React جديد باستخدام الوسيط <code>element</code> كنقطة بداية. يمتلك العنصر الناتج نفس خاصيّات العنصر الأصلي مع دمج الخاصيّات الجديد. سيحل العناصر الأبناء المُقدمين عبر الوسيط <code>children</code> محل العناصر الأبناء الحاليين. سيُحتفَظ بالمفتاح <code>key</code> والمرجع <code>ref</code> من العنصر الأصلي.
+يُكافِئ التابع <code>React.cloneElement()</code>‎ كتابة ما يلي:<syntaxhighlight lang="javascript">
+<element.type {...element.props} {...props}>{children}</element.type>
+</syntaxhighlight>ولكن يُحافِظ استخدام التابع على المرجع <code>ref</code> أيضًا. يعني هذا أنّه لو كان لديك عنصر ابن مع مرجع <code>ref</code> ضمنه، فلن تأخذه عن طريق الخطأ من العنصر السليف له، بل ستحصل على نفس المرجع مُرفقًا بعنصرك الجديد.
+قُدِّمت هذه الواجهة (ِAPI) كبديل للتابع <code>React.addons.cloneWithProps()‎</code> المُهمَل.
+== <code>createFactory()‎</code> ==
+<syntaxhighlight lang="javascript">
+React.createFactory(type)
+</syntaxhighlight>يُعيد دالة تُنتِج عناصر React من النوع المُعطى. وكما هو الحال مع التابع <code>React.createElement()</code>‎ يُمكِن للوسيط <code>type</code> أن يكون إمّا سلسلة نصيّة لاسم العنصر (مثل ‎<code>'div'</code>‎ أو ‎<code>'span'</code>‎)، أو نوع لمكوّن React (مثل صنف أو دالة)، أو نوع لجزء React (أي fragment).
+يُعتبَر هذا التابع قديمًا في React ونوصي باستخدام JSX أو التابع <code>React.createElement()</code>‎ بشكل مباشر بدلًا من ذلك.
+لن تستدعي هذا التابع بشكل مباشر إن كنت تستخدم JSX. انظر إلى استخدام React بدون JSX لتعلّم المزيد.
+== <code>isValidElement()‎</code> ==
+<syntaxhighlight lang="javascript">
+React.isValidElement(object)
+</syntaxhighlight>يتحقّق من أنّ الكائن هو عنصر React. يُعيد القيمة <code>true</code> أو <code>false</code>.
+== <code>React.Children</code> ==
+يُزوّدنا <code>React.Children</code> بأدوات مساعدة للتعامل مع بنية المعلومات <code>this.props.children</code>.
+==== <code>React.Children.map</code> ====
+<syntaxhighlight lang="javascript">
+React.Children.map(children, function[(thisArg)])
+</syntaxhighlight>يستدعي دالة لكل عنصر ابن مباشر موجود ضمن <code>children</code> مع تعيين <code>this</code> إلى قيمة <code>thisArg</code>. إن كان <code>children</code> عبارة عن جزء (fragment) مع مفتاح أو مصفوفة فلن تُمرَّر الدالة للكائن الحاوي. إن كانت قيمة <code>children</code> هي <code>null</code> أو <code>undefined</code> فسيُعيد <code>null</code> أو <code>undefined</code> بدلًا من المصفوفة.
+==== <code>React.Children.forEach</code> ====