Translating reference react dom.md

content/docs/reference-react-dom.md

@@ -1,114 +1,113 @@
----
+---
 id: react-dom
 title: ReactDOM
 layout: docs
 category: Reference
 permalink: docs/react-dom.html
 ---
 
-If you load React from a `<script>` tag, these top-level APIs are available on the `ReactDOM` global. If you use ES6 with npm, you can write `import ReactDOM from 'react-dom'`. If you use ES5 with npm, you can write `var ReactDOM = require('react-dom')`.
+إن حمّلت React عن طريق العنصر ‎`<script>‎ `فستكون هذه الواجهة ذات المستوى الأعلى متوفرة عبر الكائن العام React. وإن استخدمت ES6 مع npm فتستطيع كتابة ‎`import React from 'react'`‎. إن استخدمت ES5 مع npm فتستطيع كتابة ‎`var React = require('react')`‎.
 
-## Overview {#overview}
+## لمحة عامة {#overview}
 
-The `react-dom` package provides DOM-specific methods that can be used at the top level of your app and as an escape hatch to get outside of the React model if you need to. Most of your components should not need to use this module.
+تُزوِّدنا الحزمة `react-dom` بتوابع خاصّة بـ DOM والتي يُمكِن استخدامها في المستوى الأعلى من تطبيقك وكوسيلة هروب للخروج من نموذج React إن أردت ذلك. ينبغي ألّا تحتاج معظم مكوّناتك إلى استخدام هذه الوحدة.
 
-- [`render()`](#render)
-- [`hydrate()`](#hydrate)
-- [`unmountComponentAtNode()`](#unmountcomponentatnode)
-- [`findDOMNode()`](#finddomnode)
-- [`createPortal()`](#createportal)
+- [`()render`](#render)
+- [`()hydrate`](#hydrate)
+- [`()unmountComponentAtNode`](#unmountcomponentatnode)
+- [`()findDOMNode`](#finddomnode)
+- [`()createPortal`](#createportal)
 
-### Browser Support {#browser-support}
+### دعم المتصفح {#browser-support}
 
-React supports all popular browsers, including Internet Explorer 9 and above, although [some polyfills are required](/docs/javascript-environment-requirements.html) for older browsers such as IE 9 and IE 10.
+تدعم React جميع المتصفحات الشائعة، بما في ذلك Internet Explorer 9 فما فوق، رغم [الحاجة إلى توفير دعم](/docs/javascript-environment-requirements.html) للمتصفحات القديمة مثل Internet Explorer 9 و Internet Explorer 10.
 
-> Note
+> ملاحظة
 >
-> We don't support older browsers that don't support ES5 methods, but you may find that your apps do work in older browsers if polyfills such as [es5-shim and es5-sham](https://github.com/es-shims/es5-shim) are included in the page. You're on your own if you choose to take this path.
+> لا ندعم المتصفحات التي لا تدعم توابع ES5، ولكن قد تجد أنّ تطبيقاتك تعمل في المتصفحات القديمة إن ضمّنت polyfills مثل [es5-shim and es5-sham](https://github.com/es-shims/es5-shim) في الصفحة. ولكن لك حريّة ذلك إن اخترت هذا الطريق.
 
 * * *
 
-## Reference {#reference}
+## مرجع {#reference}
 
-### `render()` {#render}
+### `()render` {#render}
 
 ```javascript
 ReactDOM.render(element, container[, callback])
 ```
 
-Render a React element into the DOM in the supplied `container` and return a [reference](/docs/more-about-refs.html) to the component (or returns `null` for [stateless components](/docs/components-and-props.html#functional-and-class-components)).
+يُصيّر عنصر React إلى DOM ضمن الحاوية المذكورة بالوسيط `container` ويُعيد [مرجعًا](/docs/more-about-refs.html) إلى المكوّن (أو يُعيد `null` [للمكوّنات التي بدون حالة](/docs/components-and-props.html#functional-and-class-components)).
 
-If the React element was previously rendered into `container`, this will perform an update on it and only mutate the DOM as necessary to reflect the latest React element.
+إن كان عنصر React مُصيَّر سابقًا إلى الحاوية`container`, فسيُجري تحديثًا عليه ويُعدِّل DOM فقط كما هو ضروري ليعكس آخر تحديثات عنصر React.
 
-If the optional callback is provided, it will be executed after the component is rendered or updated.
+إن أضفنا رد النداء الاختياري فسيُنفَّذ بعد تصيير أو تحديث المكوّن.
 
-> Note:
+> ملاحظة:
 >
-> `ReactDOM.render()` controls the contents of the container node you pass in. Any existing DOM elements inside are replaced when first called. Later calls use React’s DOM diffing algorithm for efficient updates.
+> يتحكّم التابع `ReactDOM.render()` بمحتويات العقدة الحاوية (container node)  التي تُمرِّرها. تُستبدَل أي عناصر موجودة بداخلها عند أول استدعاء. تستخدم الاستدعاءات اللاحقة خوارزمية المقارنة من أجل التحديث بكفاءة.
 >
-> `ReactDOM.render()` does not modify the container node (only modifies the children of the container). It may be possible to insert a component to an existing DOM node without overwriting the existing children.
+> لا يُعدِّل التابع `ReactDOM.render()`   العقدة الحاوية (بل يُعدِّل فقط العناصر الأبناء لها). من الممكن إدخال مكوّن إلى عقدة DOM موجودة مسبقًا بدون الكتابة فوق العناصر الأبناء الموجودين داخلها.
 >
-> `ReactDOM.render()` currently returns a reference to the root `ReactComponent` instance. However, using this return value is legacy
-> and should be avoided because future versions of React may render components asynchronously in some cases. If you need a reference to the root `ReactComponent` instance, the preferred solution is to attach a
+> يُعيد التابع `ReactDOM.render()` حاليًّا مرجعًا إلى نسخة الصنف `ReactComponent` الجذري. على أيّة حال هذه القيمة المُعادة تعتبر قديمة حاليًّا ويجب تجنبها لأنّ إصدارات React القادمة قد تُصيِّر المكوّنات بشكلٍ غير متزامن في بعض الحالات. إن أردت مرجعًا إلى نسخة الصنف`ReactComponent`  الجذري فالحل الأمثل هو إرفاق مرجع رد نداء إلى العنصر الجذري.
 > [callback ref](/docs/more-about-refs.html#the-ref-callback-attribute) to the root element.
 >
-> Using `ReactDOM.render()` to hydrate a server-rendered container is deprecated and will be removed in React 17. Use [`hydrate()`](#hydrate) instead.
+> أصبح استخدام التابع `ReactDOM.render()` لإجراء hydrate على الحاوية المُصيَّرة من قبل الخادم أمرًا مهمًلا وسيُزال في إصدار React 17. استخدم التابع [`hydrate()`](#hydrate) بدلًا من ذلك.
 
 * * *
 
-### `hydrate()` {#hydrate}
+### `()hydrate` {#hydrate}
 
 ```javascript
 ReactDOM.hydrate(element, container[, callback])
 ```
 
-Same as [`render()`](#render), but is used to hydrate a container whose HTML contents were rendered by [`ReactDOMServer`](/docs/react-dom-server.html). React will attempt to attach event listeners to the existing markup.
+يُشير المصطلح hydrate إلى عمليّة ملء الكائن بالبيانات. هذا التابع مماثل للتابع [`render()`](#render), ولكنّه يُستخدَم لإجراء hydrate على حاوية محتواها مُصيَّر من قبل[`ReactDOMServer`](/docs/react-dom-server.html). تحاول React إرفاق مستمع للأحداث إلى الشيفرة الحالية.
 
-React expects that the rendered content is identical between the server and the client. It can patch up differences in text content, but you should treat mismatches as bugs and fix them. In development mode, React warns about mismatches during hydration. There are no guarantees that attribute differences will be patched up in case of mismatches. This is important for performance reasons because in most apps, mismatches are rare, and so validating all markup would be prohibitively expensive.
+تتوقّع React أنّ المحتوى المُصيَّر متطابق بين الخادم والعميل. بإمكانها تصحيح الاختلافات في محتوى النص ولكن يجب عليك معاملة عدم التطابق كخطأ وإصلاحه. في وضع التطوير تُعطينا React تحذيرات حول عدم التطابق خلال عملية الـ hydration. لا يوجد ضمان بتصحيح الاختلافات بين الخاصيّات في حال عدم التطابق. يعد هذا هامًّا لأسباب تتعلق بالأداء لأنّه في معظم التطبيقات يكون عدم التطابق نادرًا ولذا يصبح التحقق من كل الأخطاء أمرًا مكلفًا.
 
-If a single element's attribute or text content is unavoidably different between the server and the client (for example, a timestamp), you may silence the warning by adding `suppressHydrationWarning={true}` to the element. It only works one level deep, and is intended to be an escape hatch. Don't overuse it. Unless it's text content, React still won't attempt to patch it up, so it may remain inconsistent until future updates.
+إن كانت هنالك خاصيّة عنصر وحيدة أو محتوى نص مختلف بين الخادم والعميل بشكل لا يُمكِن تجنّبه (مثلًا الطابع الزمني) فبإمكانك إيقاف التحذير عن طريق إضافة  `suppressHydrationWarning={true}` للعنصر. يعمل هذا فقط في مستوى واحد فقط والغرض منه إيجاد طريقة للهروب، لذا لا تفرط في استخدامه. لن تصحح React الاختلافات ما لم يكن المحتوى نصيًّا، لذا قد يبقى غير مستقر حتى التحديثات القادمة.
 
-If you intentionally need to render something different on the server and the client, you can do a two-pass rendering. Components that render something different on the client can read a state variable like `this.state.isClient`, which you can set to `true` in `componentDidMount()`. This way the initial render pass will render the same content as the server, avoiding mismatches, but an additional pass will happen synchronously right after hydration. Note that this approach will make your components slower because they have to render twice, so use it with caution.
+إن احتجت عن قصد تصيير شيء مختلف على الخادم والعميل فبإمكانك إجراء تصيير ذو تمريرين. تتمكّن المكوّنات التي تُصيّر شيئًا مختلفًا على العميل من قراءة متغيّر الحالة مثل  `this.state.isClient`, بهذه الحالة سيُصيّر مرور التصيير الأولي نفس محتوى الخادم، متجنبًا بذلك عدم التطابق، ولكن سيحدث مرور إضافي بشكل متزامن بعد عمليّة hydration. انتبه إلى أنّ هذه المقاربة ستجعل مكوّناتك أبطأ لأنّه يجب عليها التصيير مرتين، لذا استخدم ذلك بحذر.
 
-Remember to be mindful of user experience on slow connections. The JavaScript code may load significantly later than the initial HTML render, so if you render something different in the client-only pass, the transition can be jarring. However, if executed well, it may be beneficial to render a "shell" of the application on the server, and only show some of the extra widgets on the client. To learn how to do this without getting the markup mismatch issues, refer to the explanation in the previous paragraph.
+تذكر أن تبقي في ذهنك تجربة المستخدم الذي يمتلك اتصالًا بطيئًا بالإنترنت. قد تُحمَّل شيفرة JavaScript بعد تصيير HTML المبدئي بفترة هامّة، لذا إن صيّرت شيئًا مختلفًا في تمرير العميل فقط، فسيصبح الانتقال بطيئًا. قد يكون من المفيد تصيير واجهة shell للتطبيق على الخادم، وإظهار بعض الأدوات المصغرة فقط من جانب العميل. لتعلّم كيفيّة فعل ذلك بدون الحصول على مشاكل في التوافق فارجع إلى الشرح المذكور في الفقرة السابقة.
 
 * * *
 
-### `unmountComponentAtNode()` {#unmountcomponentatnode}
+### `()unmountComponentAtNode` {#unmountcomponentatnode}
 
 ```javascript
 ReactDOM.unmountComponentAtNode(container)
 ```
 
-Remove a mounted React component from the DOM and clean up its event handlers and state. If no component was mounted in the container, calling this function does nothing. Returns `true` if a component was unmounted and `false` if there was no component to unmount.
+يُزيل مكوّن React الموصول من DOM ويمسح معالجات أحداثه وحالته. إن لم يكن هنالك أي مكوّن موصول في الحاوية فلن يؤدي استدعاء هذا التابع إلى فعل أي شيء. يُعيد هذا التابع القيمة `true` إن فصلنا المكوّن بنجاح و `false` إن لم يكون هنالك مكوّن لفصله.
 
 * * *
 
-### `findDOMNode()` {#finddomnode}
+### `()findDOMNode` {#finddomnode}
 
-> Note:
+> ملاحظة:
 >
-> `findDOMNode` is an escape hatch used to access the underlying DOM node. In most cases, use of this escape hatch is discouraged because it pierces the component abstraction. [It has been deprecated in `StrictMode`.](/docs/strict-mode.html#warning-about-deprecated-finddomnode-usage)
+> التابع `findDOMNode` و وسيلة هروب مستخدمة للوصول إلى عقدة DOM التحتية. من غير المفضل في معظم الأحيان استخدام وسيلة الهروب هذه لأنّها تخرق تجريد المكوّنات. لقد  [أهمل في الوضع الصارم `StrictMode`.](/docs/strict-mode.html#warning-about-deprecated-finddomnode-usage)
 
 ```javascript
 ReactDOM.findDOMNode(component)
 ```
-If this component has been mounted into the DOM, this returns the corresponding native browser DOM element. This method is useful for reading values out of the DOM, such as form field values and performing DOM measurements. **In most cases, you can attach a ref to the DOM node and avoid using `findDOMNode` at all.**
 
-When a component renders to `null` or `false`, `findDOMNode` returns `null`. When a component renders to a string, `findDOMNode` returns a text DOM node containing that value. As of React 16, a component may return a fragment with multiple children, in which case `findDOMNode` will return the DOM node corresponding to the first non-empty child.
+إن كان هذا المكوّن موصولًا إلى DOM، فسيُعيد هذا التابع عنصر DOM الأصلي الموافق في المتصفح. يُفيد هذا التابع لقراءة القيم من DOM، مثل قيم حقول الإدخال وإنجاز قياسات DOM. في معظم الحالات تستطيع إرفاق مرجع إلى عقدة DOM وتجنب استخدام `findDOMNode` نهائيًّا.
+عندما يُصيِّر المكوّن القيمة `false` أو `null` فسيُعيد `findDOMNode` القيمة `null`. عندما يُصيِّر المكوّن سلسلة نصيّة، فسيُعيد هذا التابع عقدة DOM نصيّة تحتوي على تلك القيمة. بدءًا من إصدار React 16 قد يُعيد المكوّن جزءًا (fragment) مع عدّة عناصر أبناء، وفي تلك الحالة سيُعيد `findDOMNode` عقدة DOM الموافقة لأول عنصر ابن غير فارغ.
 
-> Note:
+> ملاحظة:
 >
-> `findDOMNode` only works on mounted components (that is, components that have been placed in the DOM). If you try to call this on a component that has not been mounted yet (like calling `findDOMNode()` in `render()` on a component that has yet to be created) an exception will be thrown.
+> يعمل التابع `findDOMNode` فقط على المكوّنات الموصولة (أي المكوّنات المتوضعة في DOM). إن حاولت استدعاء هذا التابع على مكوّن غير موصول بعد (مثل استدعاء `findDOMNode` في التابع `render` في مكوّن لم يُنشَأ بعد) فسيُرمى استثناء.
 >
-> `findDOMNode` cannot be used on function components.
+> لا يُمكِن استخدام `findDOMNode`على مكوّنات الدوال.
 
 * * *
 
-### `createPortal()` {#createportal}
+### `()createPortal` {#createportal}
 
 ```javascript
 ReactDOM.createPortal(child, container)
 ```
 
-Creates a portal. Portals provide a way to [render children into a DOM node that exists outside the hierarchy of the DOM component](/docs/portals.html).
+يُنشِئ مدخل (portal). تُزوّدنا المداخل بطريقة [لتصيير العناصر الأبناء إلى عقدة DOM موجودة خارج التسلسل الهرمي لمكوّنات DOM](/docs/portals.html).