الكائن ReactDOM

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

لمحة عامة

تُزوِّدنا الحزمة react-dom بتوابع خاصّة بـ DOM والتي يُمكِن استخدامها في المستوى الأعلى من تطبيقك وكوسيلة هروب للخروج من نموذج React إن أردت ذلك. ينبغي ألّا تحتاج معظم مكوّناتك إلى استخدام هذه الوحدة.

دعم المتصفح

تدعم React جميع المتصفحات الشائعة، بما في ذلك Internet Explorer 9 فما فوق، رغم الحاجة إلى استخدام polyfills لدعم المتصفحات القديمة مثل Internet Explorer 9 و Internet Explorer 10.

ملاحظة: لا ندعم المتصفحات التي لا تدعم توابع ES5، ولكن قد تجد أنّ تطبيقاتك تعمل في المتصفحات القديمة إن ضمّنت polyfills مثل es5-shim and es5-sham في الصفحة. ولكن لك حريّة ذلك إن اخترت هذا الطريق.

مرجع

render()‎

ReactDOM.render(element, container[, callback])

يُصيّر عنصر React إلى DOM ضمن الحاوية المذكورة بالوسيط container ويُعيد مرجعًا إلى المكوّن (أو يُعيد null للمكوّنات التي بدون حالة).

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

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

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

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

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

أصبح استخدام التابع ReactDOM.render()‎ لإجراء hydrate على الحاوية المُصيَّرة من قبل الخادم أمرًا مهمًلا وسيُزال في إصدار React 17. استخدم التابع hydrate()‎ بدلًا من ذلك.

hydrate()‎

ReactDOM.hydrate(element, container[, callback])

يُشير المصطلح hydrate إلى عمليّة ملء الكائن بالبيانات. هذا التابع مماثل للتابع render()‎ ولكنّه يُستخدَم لإجراء hydrate على حاوية محتواها مُصيَّر من قبل ReactDOMServer. تحاول React إرفاق مستمع للأحداث إلى الشيفرة الحالية.

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

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

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

تذكر أن تبقي في ذهنك تجربة المستخدم الذي يمتلك اتصالًا بطيئًا بالإنترنت. قد تُحمَّل شيفرة JavaScript بعد تصيير HTML المبدئي بفترة هامّة، لذا إن صيّرت شيئًا مختلفًا في تمرير العميل فقط، فسيصبح الانتقال بطيئًا. قد يكون من المفيد تصيير واجهة shell للتطبيق على الخادم، وإظهار بعض الأدوات المصغرة فقط من جانب العميل. لتعلّم كيفيّة فعل ذلك بدون الحصول على مشاكل في التوافق فارجع إلى الشرح المذكور في الفقرة السابقة.

unmountComponentAtNode()‎

ReactDOM.unmountComponentAtNode(container)

يُزيل مكوّن React الموصول من DOM ويمسح معالجات أحداثه وحالته. إن لم يكن هنالك أي مكوّن موصول في الحاوية فلن يؤدي استدعاء هذا التابع إلى فعل أي شيء. يُعيد هذا التابع القيمة true إن فصلنا المكوّن بنجاح و false إن لم يكون هنالك مكوّن لفصله.

findDOMNode()‎

ReactDOM.findDOMNode(component)

إن كان هذا المكوّن موصولًا إلى DOM، فسيُعيد هذا التابع عنصر DOM الأصلي الموافق في المتصفح. يُفيد هذا التابع لقراءة القيم من DOM، مثل قيم حقول الإدخال وإنجاز قياسات DOM. في معظم الحالات تستطيع إرفاق مرجع إلى عقدة DOM وتجنب استخدام findDOMNode نهائيًّا.

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

ملاحظة: التابع findDOMNode هو وسيلة هروب مستخدمة للوصول إلى عقدة DOM التحتية. من غير المفضل في معظم الأحيان استخدام وسيلة الهروب هذه لأنّها تخرق تجريد المكوّنات.

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

لا يُمكِن استخدام findDOMNode على مكوّنات الدوال.

createPortal()‎

ReactDOM.createPortal(child, container)

يُنشِئ مدخل (portal). تُزوّدنا النوافذ بطريقة لتصيير العناصر الأبناء إلى عقدة DOM موجودة خارج التسلسل الهرمي لمكوّنات DOM.