الكائن ReactDOM

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

لمحة عامة

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

• ()render
• ()hydrate
• ()unmountComponentAtNode
• ()findDOMNode
• ()createPortal

دعم المتصفح

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

ملاحظة

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

مرجع

()render

render(element, container[, callback])

Note:

render has been replaced with createRoot in React 18. See createRoot for more info.

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

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

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

ملاحظة:

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

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

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

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

()hydrate

hydrate(element, container[, callback])

Note:

hydrate has been replaced with hydrateRoot in React 18. See hydrateRoot for more info.

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

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

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

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

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

()unmountComponentAtNode

unmountComponentAtNode(container)

Note:

unmountComponentAtNode has been replaced with root.unmount() in React 18. See createRoot for more info.

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

()findDOMNode

ملاحظة:

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

findDOMNode(component)

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

ملاحظة:

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

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

()createPortal

ReactDOM.createPortal(child, container)

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