عرض مصدر React/react dom

<noinclude>{{DISPLAYTITLE:الكائن <code>ReactDOM</code> في React}}</noinclude>
إن حمّلت React عن طريق العنصر ‎<code><script></code>‎ فستكون هذه الواجهة ذات المستوى الأعلى متوفرة عبر الكائن العام <code>React</code>. وإن استخدمت ES6 مع npm فتستطيع كتابة <code>‎import ReactDOM from 'react-dom'</code>‎. إن استخدمت ES5 مع npm فتستطيع كتابة <code>‎var ReactDOM = require('react-dom')</code>‎.
==لمحة عامة==
تُزوِّدنا الحزمة <code>react-dom</code> بتوابع خاصّة بـ DOM والتي يُمكِن استخدامها في المستوى الأعلى من تطبيقك وكوسيلة هروب للخروج من نموذج React إن أردت ذلك. ينبغي ألّا تحتاج معظم مكوّناتك إلى استخدام هذه الوحدة.
* <code>render()‎</code>
* <code>hydrate()‎</code>
* <code>unmountComponentAtNode()‎</code>
* <code>findDOMNode()‎</code>
* <code>createPortal()‎</code>

==دعم المتصفح==
تدعم React جميع المتصفحات الشائعة، بما في ذلك Internet Explorer 9 فما فوق، رغم [[React/javascript environment requirements|الحاجة إلى توفير دعم]] للمتصفحات القديمة مثل Internet Explorer 9 و Internet Explorer 10.

'''ملاحظة:''' لا ندعم المتصفحات التي لا تدعم توابع ES5، ولكن قد تجد أنّ تطبيقاتك تعمل في المتصفحات القديمة إن ضمّنت polyfills مثل <code>[https://github.com/es-shims/es5-shim es5-shim and es5-sham]</code> في الصفحة. ولكن لك حريّة ذلك إن اخترت هذا الطريق.
==مرجع==
===<code>render()‎</code>===
<syntaxhighlight lang="javascript">
ReactDOM.render(element, container[, callback])
</syntaxhighlight>يُصيّر عنصر React إلى DOM ضمن الحاوية المذكورة بالوسيط <code>container</code> ويُعيد مرجعًا إلى المكوّن (أو يُعيد <code>null</code> [[React/components and props#.D9.85.D9.83.D9.88.D9.86.D8.A7.D8.AA .D8.A7.D9.84.D8.A3.D8.B5.D9.86.D8.A7.D9.81 .D9.88.D8.A7.D9.84.D8.AF.D9.88.D8.A7.D9.84|للمكوّنات التي بدون حالة]]).

إن كان عنصر React مُصيَّر سابقًا إلى الحاوية <code>container</code>، فسيُجري تحديثًا عليه ويُعدِّل DOM فقط كما هو ضروري ليعكس آخر تحديثات عنصر React.

إن أضفنا رد النداء الاختياري فسيُنفَّذ بعد تصيير أو تحديث المكوّن.

'''ملاحظة:''' يتحكّم التابع <code>ReactDOM.render()</code>‎ بمحتويات العقدة الحاوية التي تُمرِّرها. تُستبدَل أي عناصر موجودة بداخلها عند أول استدعاء. تستخدم الاستدعاءات اللاحقة خوارزمية المقارنة من أجل التحديث بكفاءة.

لا يُعدِّل التابع <code>ReactDOM.render()‎</code> العقدة الحاوية (بل يُعدِّل فقط العناصر الأبناء لها). من الممكن إدخال مكوّن إلى عقدة DOM موجودة مسبقًا بدون الكتابة فوق العناصر الأبناء الموجودين داخلها.

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

أصبح استخدام التابع <code>ReactDOM.render()</code>‎ لإجراء hydrate على الحاوية المُصيَّرة من قبل الخادم أمرًا مهمًلا وسيُزال في إصدار React 17. استخدم التابع [[React/react dom#hydrate.28.29.E2.80.8E|<code>hydrate()</code>‎]] بدلًا من ذلك.
===<code>hydrate()‎</code>===
<syntaxhighlight lang="javascript">
ReactDOM.hydrate(element, container[, callback])
</syntaxhighlight>يُشير المصطلح hydrate إلى عمليّة ملء الكائن بالبيانات. هذا التابع مماثل للتابع <code>[[React/react dom#render.28.29.E2.80.8E|render()]]‎</code> ولكنّه يُستخدَم لإجراء hydrate على حاوية محتواها مُصيَّر من قبل <code>[[React/react dom server|ReactDOMServer]]</code>. تحاول React إرفاق مستمع للأحداث إلى الشيفرة الحالية.

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

إن كانت هنالك خاصيّة عنصر وحيدة أو محتوى نص مختلف بين الخادم والعميل بشكل لا يُمكِن تجنّبه (مثلًا الطابع الزمني) فبإمكانك إيقاف التحذير عن طريق إضافة ‎<code>suppressHydrationWarning={true}‎</code> للعنصر. يعمل هذا فقط في مستوى واحد فقط والغرض منه إيجاد طريقة للهروب، لذا لا تفرط في استخدامه. لن تصحح React الاختلافات ما لم يكن المحتوى نصيًّا، لذا قد يبقى غير مستقر حتى التحديثات القادمة.

إن احتجت عن قصد تصيير شيء مختلف على الخادم والعميل فبإمكانك إجراء تصيير ذو تمريرين. تتمكّن المكوّنات التي تُصيّر شيئًا مختلفًا على العميل من قراءة متغيّر الحالة مثل <code>this.state.isClient</code>. والذي يمكن تعيين قيمته إلى <code>true</code> في<code>componentDidMount()‎</code>.  في هذه الحالة سيُصيّر مرور التصيير الأولي نفس محتوى الخادم، متجنبًا بذلك عدم التطابق، ولكن سيحدث مرور إضافي بشكل متزامن بعد عمليّة hydration. انتبه إلى أنّ هذه المقاربة ستجعل مكوّناتك أبطأ لأنّه يجب عليها التصيير مرتين، لذا استخدم ذلك بحذر.

تذكر أن تبقي في ذهنك تجربة المستخدم الذي يمتلك اتصالًا بطيئًا بالإنترنت. قد تُحمَّل شيفرة JavaScript بعد تصيير HTML المبدئي بفترة هامّة، لذا إن صيّرت شيئًا مختلفًا في تمرير العميل فقط، فسيصبح الانتقال بطيئًا. قد يكون من المفيد تصيير واجهة shell للتطبيق على الخادم، وإظهار بعض الأدوات المصغرة فقط من جانب العميل. لتعلّم كيفيّة فعل ذلك بدون الحصول على مشاكل في التوافق فارجع إلى الشرح المذكور في الفقرة السابقة.
===<code>unmountComponentAtNode()‎</code>===
<syntaxhighlight lang="javascript">
ReactDOM.unmountComponentAtNode(container)
</syntaxhighlight>يُزيل مكوّن React الموصول من DOM ويمسح معالجات أحداثه وحالته. إن لم يكن هنالك أي مكوّن موصول في الحاوية فلن يؤدي استدعاء هذا التابع إلى فعل أي شيء. يُعيد هذا التابع القيمة <code>true</code> إن فصلنا المكوّن بنجاح و <code>false</code> إن لم يكون هنالك مكوّن لفصله.
===<code>findDOMNode()‎</code>===
'''ملاحظة:''' التابع <code>findDOMNode</code> هو وسيلة هروب مستخدمة للوصول إلى عقدة DOM التحتية. من غير المفضل في معظم الأحيان استخدام وسيلة الهروب هذه لأنّها تخرق تجريد المكوّنات. [[React/strict mode#.D8.A7.D9.84.D8.AA.D8.AD.D8.B0.D9.8A.D8.B1 .D8.AD.D9.88.D9.84 .D8.A7.D8.B3.D8.AA.D8.AE.D8.AF.D8.A7.D9.85 .D8.A7.D9.84.D9.88.D8.A7.D8.AC.D9.87.D8.A9 findDOMNode .D8.A7.D9.84.D9.85.D9.87.D9.85.D9.84.D8.A9|لقد أهمل في الوضع الصارم]].<syntaxhighlight lang="javascript">
ReactDOM.findDOMNode(component)
</syntaxhighlight>إن كان هذا المكوّن موصولًا إلى DOM، فسيُعيد هذا التابع عنصر DOM الأصلي الموافق في المتصفح. يُفيد هذا التابع لقراءة القيم من DOM، مثل قيم حقول الإدخال وإنجاز قياسات DOM. في معظم الحالات تستطيع إرفاق مرجع إلى عقدة DOM وتجنب استخدام <code>findDOMNode</code> نهائيًّا.

عندما يُصيِّر المكوّن القيمة <code>false</code> أو <code>null</code> فسيُعيد <code>findDOMNode</code> القيمة <code>null</code>. عندما يُصيِّر المكوّن سلسلة نصيّة، فسيُعيد هذا التابع عقدة DOM نصيّة تحتوي على تلك القيمة. بدءًا من إصدار React 16 قد يُعيد المكوّن جزءًا (fragment) مع عدّة عناصر أبناء، وفي تلك الحالة سيُعيد <code>findDOMNode</code> عقدة DOM الموافقة لأول عنصر ابن غير فارغ.

'''ملاحظة''': يعمل التابع <code>findDOMNode</code> فقط على المكوّنات الموصولة (أي المكوّنات المتوضعة في DOM). إن حاولت استدعاء هذا التابع على مكوّن غير موصول بعد (مثل استدعاء <code>findDOMNode</code> في التابع <code>render</code> في مكوّن لم يُنشَأ بعد) فسيُرمى استثناء.

لا يُمكِن استخدام <code>findDOMNode</code> على مكوّنات الدوال.
===<code>createPortal()‎</code>===
<syntaxhighlight lang="javascript">
ReactDOM.createPortal(child, container)
</syntaxhighlight><span> </span>يُنشِئ مدخل (portal). تُزوّدنا المداخل بطريقة [[React/portals|لتصيير العناصر الأبناء إلى عقدة DOM موجودة خارج التسلسل الهرمي لمكوّنات DOM]].
== انظر أيضًا ==
* [[React/react api|واجهة برمجة التطبيق (API) ذات المستوى الأعلى في React]]
* [[React/react component|الصنف React.Component]]
* [[React/react dom server|الكائن ReactDOMServer]]
* [[React/dom elements|عناصر DOM]]
* [[React/events|الأحداث المصطنعة (Synthetic Events)]]
* [[React/test utils|أدوات الاختبار]]
* [[React/shallow renderer|التصيير السطحي (Shallow Rendering)]]
* [[React/test renderer|مصير الاختبار (Test Renderer)]]
* [[React/javascript environment requirements|متطلبات بيئة JavaScript]]
==مصادر==
*[https://reactjs.org/docs/react-dom.html صفحة الكائن ReactDOM في توثيق React الرسمي].
[[تصنيف:React]]
[[تصنيف:React API Reference]]