ReactDom

content/docs/reference-react-dom.md

@@ -6,71 +6,69 @@ 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')`.
+اگر ری‌اکت را با تگ `<script>` بارگذاری کنید، این APIهای سطح بالا در `ReactDOM` به صورت عمومی در دسترس هستن. اگر از ES6 با npm استفاده می‌کنید، می‌توانید بنویسید `import ReactDOM from 'react-dom'`.
+اگر از ES5 با npm استفاده می‌کنید ،می‌توانید بنویسید `var ReactDOM = require('react-dom')`.
 
-## 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 را فراهم می‌کند که در صورت نیاز می‌توان در سطح بالایی از اپلیکیشن شما به عنوان راه فراری از مدل ری‌اکت استفاده کرد. بیشتر کامپوننت‌های شما نیازی ندارند که از این ماژول‌ها استفاده کنند.
 
 - [`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.
+ری‌اکت از تمام مرورگرهای معروف پشتیبانی می‌کند، که شامل Internet Explorer 9 و بالاتر می‌شود، گرچه برای مرورگرهای قدیمی مثل IE 9 و IE 10 [به مکمل‌ها(polyfills) نیاز است](/docs/javascript-environment-requirements.html).
 
-> 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 پشتیبانی نمی‌کنند پشتیبانی نمی‌کنیم، ولی متوجه میشوید که اگر از مکمل‌هایی مثل [es5-shim و es5-sham](https://github.com/es-shims/es5-shim) استفاده کنید برنامه‌های شما در این مرورگرهای قدیمی کار می‌کنند. اما پیامد آن به عهده خودتان است.
 * * *
 
-## Reference {#reference}
+## مرجع {#reference}
 
 ### `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#function-and-class-components)).
+یک المنت ری‌اکت را درون container داده‌شده رندر می‌کند و یک [reference](/docs/more-about-refs.html) به آن کامپوننت (یا null برای [کامپوننت‌های بدون state](/docs/components-and-props.html#function-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.
+اگر المت ری‌اکت قبلا درون `container` رندر شده می‌بود، این دستور یک بروزرسانی روی آن انجام می‌داد و DOM را فقط در صورت لزوم تغغیر (mutate) می‌هد تا آخرین المنت ری‌اکت منعکس شود.
 
-If the optional callback is provided, it will be executed after the component is rendered or updated.
+اگر callback دلخواهی داشتیم، بعد از اینکه کامپوننت رندر یا به‌روزرسانی شد اجرا می‌شود.
 
-> 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 که به داخل آن می‌فرستید را کنترل می کند. هنگامی که برای اولین بار فراخوانی می‌شود هر المنتی که داخلش باشد جایگزین می‌شود. ولی در سایر فراخوانی‌های بعدی برای بهینه بودن به‌روزرسانی از الگوریتم (React’s DOM diffing) استفاده می‌شود.
 >
-> `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()` نود اصلی را تغییر نمیدهد (فقط فرزنده‌های container را تغییر می‌دهد). شاید ممکن باشد که کامپوننتی را درون نودی که قبلا وجود داشته وارد کرد بدون اینکه نیاز به بازنویسی نودهای زیر شاخه(children) باشد.
 >
-> `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
-> [callback ref](/docs/more-about-refs.html#the-ref-callback-attribute) to the root element.
+> `ReactDOM.render()` در حال حاضر یک reference از ریشه instance `ReactComponent` برمی‌گرداند. با این حال استفاده از این مقدار برگشتی سنتی است و باید از آن پرهیز شود زیرا در ورژن‌های آینده ری‌اکت شاید برخی کامپوننت‌ها در گاهی اوقات ناهمگام رندر شوند.اگر شما به مرجع instance ریشه `ReactComponent` نیاز داشتید، بهترین راه حل آن است که یک [callback ref](/docs/more-about-refs.html#the-ref-callback-attribute) به ریشه المنت وصل کنید.
 >
-> 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 کردن یک container که سمت سرور رندر شده‌است، منسوخ شده است و در ورژن ۱۷ ری‌اکت پاک خواهد شد. به جای آن از [`()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.
+مثل [`()render`](#render) است، ولی برای hydrate کردن یک container که محتوای HTML آن توسط [`ReactDOMServer`](/docs/react-dom-server.html) رنده شده است استفاده می‌شود. ری‌اکت تلاش می‌کند به همان المان‌های رندر شده‌ی موجود، event listener هایی را اضافه کند.
 
-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.
+ری‌اکت توقع دارد که محتوای رنده شده بین سرور و کاربر همسان باشند. ری‌اکت میتواند اختلافات را در متن محتوا وصله کند، ولی شما باید با عدم تطابق به عنوان باگ نگاه کنید و آنها را رفع کنید. در حالت توسعه، ری‌اکت این عدم تطابق را در مدت hydration به ما هشدار می‌دهد. هیچ تضمینی وجود ندارد که تفاوت‌های بین attribute در مواردی که عدم تطابق داریم وصله شوند. از این جهت برای عملکرد بهتر مهم است زیرا در اکثر نرم‌افزارها، عدم تطابق نادر است، و راست‌آزمایی markups میتواند از این نظر بسیار گران باشد.
 
-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.
+اگر یک attribute متعلق به المنت یا محتوای متن به صورت اجتناب ناپذیری بین سرور و کاربر متفاوت باشد (برای مثال  timestamp)، شما شاید با اعمال `suppressHydrationWarning={true}` روی المنت این هشدار را ساکت کنید. این فقط تا عمق یک لایه کار می‌کند، و دریچه فراری در نظر گرفته شده است. خیلی از آن استفاده نکنید. مگر محتوا متن باشد، همچنین ری‌اکت نیز برای وصله کردن آن تلاشی نمی‌کند،  در نتیجه تا به‌روزرسانی آتی ناسازگار باقی می‌ماند.
 
-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.
+اگر نیاز دارید تا از عمد چیز متفاوتی سمت سرور یا کاربر رندر کنید، می‌توانید از روش رندر کردن دو-گذری استفاده کنید. کامپوننت‌هایی که چیز متفاوتی سمت کاربر رندر می‌کنند می‌توانند stateای شبیه به `this.state.isClient` را بخوانند، که می‌توانید آن را در `componentDidMount()` برابر `true` قرار دهید. به این طریق در گذر اولیه رندر، همان محتوای سمت سرور رندر می‌شود، از عدم تطابق جلوگیری می‌شود، ولی یک گذر همگام درست بعد از 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.
+به تجربه‌کاربری هنگامی که سرعت اتصال کم است هم توجه کنید. کد جاوااسکریپت ممکن است خیلی بعدتر از رندر اولیه HTML بارگذاری شود، بنابراین اگر شما در آن زمان چیز متفاوتی [از HTML ارسال شده] رندر می‌کنید، این تغییر می‌تواند نامطلوب باشد. گرچه، اگر به خوبی اجرا شود، می‌تواند برای رندر شدن "shell" نرم‌افزار روی سرور مفید باشد، و فقط چند ابزارک سمت کاربر را نشان می‌دهد. برای اینکه بدانید این کار بدون اینکه درچار مشکل تطابق شوید چطور انجام می‌شود، به توضیحات پاراگراف قبلی مراجعه کنید.
 
 * * *
 
@@ -80,28 +78,28 @@ Remember to be mindful of user experience on slow connections. The JavaScript co
 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.
+یک کامپوننت mount شده ری‌اکت را از DOM حذف و تمام event handler ها و state آن را پاک می‌کند. اگر هیچ کامپوننتی در mount container نشده باشد، فراخوانی این تابع هیچ کاری نمی‌کند. مقدار `true` را برای کامپوننت‌هایی که mount شدن و  مقدار `false` را در زمانی که هیچ کامپوننتی mount نشده باشد برمی‌گرداند.
 
 * * *
 
-### `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 نود زیرین استفاده می‌شود. در بیشتر موارد، استفاده از این راه فرار پیش‌نهاد نمی‌شود. زیرا نفوذی به [لایه] abstraction کامپوننت است. این قابلیت [در `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.**
+این متد برای خواندن مقادیر خارج از DOM، مانند مقادیر فیلد‌های فرم و انجام بررسی‌های DOM مفید است. در **بیشتر موارد، شما می‌توانید یک ref به نود DOM متصل کنید و در کل از استفاده‌ی `findDOMNode` بپرهیزید.**
+
 
-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.
+هنگامی که کامپوننت  `null` یا `false` رندر می‌کند `findDOMNode` مقدار `null` برمی‌گرداند. و هنگامی که کامپوننت متن رندر میکند `findDOMNode` یک DOM نود متنی شامل آن مقدار برمی‌گرداند. از از ری‌اکت ۱۶، یک کامپوننت شاید یک 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` فقط روی کامپوننت‌هایی که mount شده اند کار می‌کنند (که آن کامپوننت در جای خود در DOM قرار گرفته است). اگر سعی کنید که آن را در کامپوننت فراخوانی کنید که هنوز در صفحه mount نشده است (مثل فراخوانی  `findDOMNode()` در `render()` روی کامپوننتی که هنوز ایجاد نشده است) به exception میخورید.
 >
-> `findDOMNode` cannot be used on function components.
+> `findDOMNode` در کامپوننت‌های تابعی کار نمی‌کند.
 
 * * *
 
@@ -110,5 +108,4 @@ When a component renders to `null` or `false`, `findDOMNode` returns `null`. Whe
 ```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).
+یک پورتال ایجاد می‌کنند. پورتال‌ها راهی فراهم می‌کند تا [فرزنده‌ها را درون DOM نود بیرون سلسله مراتب DOM قرار دهید](/docs/portals.html).