diff --git a/src/content/reference/react-dom/client/createRoot.md b/src/content/reference/react-dom/client/createRoot.md index d91bc20c6..fd038c2ba 100644 --- a/src/content/reference/react-dom/client/createRoot.md +++ b/src/content/reference/react-dom/client/createRoot.md @@ -4,7 +4,7 @@ title: createRoot -`createRoot` lets you create a root to display React components inside a browser DOM node. +تمكنك `createRoot` من إنشاء نقطة بداية أو جذر (Root) لعرض مكونات React داخل عنصر DOM في المتصفح. ```js const root = createRoot(domNode, options?) @@ -16,11 +16,11 @@ const root = createRoot(domNode, options?) --- -## Reference {/*reference*/} +## المرجع {/*reference*/} ### `createRoot(domNode, options?)` {/*createroot*/} -Call `createRoot` to create a React root for displaying content inside a browser DOM element. +استدعِ `createRoot` لإنشاء جذر React لعرض المحتوى داخل عنصر DOM في المتصفح. ```js import { createRoot } from 'react-dom/client'; @@ -29,104 +29,104 @@ const domNode = document.getElementById('root'); const root = createRoot(domNode); ``` -React will create a root for the `domNode`, and take over managing the DOM inside it. After you've created a root, you need to call [`root.render`](#root-render) to display a React component inside of it: +سيقوم React بإنشاء جذر لـ `domNode`، ويتولى إدارة العنصر DOM داخله. بعد إنشاء الجذر، يتعين عليك استدعاء [`root.render`](#root-render) لعرض مكون React داخله: ```js root.render(); ``` -An app fully built with React will usually only have one `createRoot` call for its root component. A page that uses "sprinkles" of React for parts of the page may have as many separate roots as needed. +يتم عادة إنشاء التطبيق بالكامل باستخدام React بنداء واحد فقط لـ `createRoot` في المكون الجذر. قد يحتوي الموقع الذي يستخدم React لأجزاء محددة من الصفحة على عدد من نقاط البداية الفردية حسب الحاجة. -[See more examples below.](#usage) +[انظر المزيد من الأمثلة أدناه.](#usage) -#### Parameters {/*parameters*/} +#### المعاملات {/*parameters*/} -* `domNode`: A [DOM element.](https://developer.mozilla.org/en-US/docs/Web/API/Element) React will create a root for this DOM element and allow you to call functions on the root, such as `render` to display rendered React content. +* `domNode`: عنصر [DOM](https://developer.mozilla.org/en-US/docs/Web/API/Element) يقوم React بإنشاء جذر لهذا العنصر ويتيح لك استدعاء الدوال على الجذر مثل `render` لعرض المحتوى الذي تنشئه React. -* **optional** `options`: An object with options for this React root. +* `options` **اختياري**: كائن يحتوي على خيارات لجذر React هذا. - * **optional** `onRecoverableError`: Callback called when React automatically recovers from errors. - * **optional** `identifierPrefix`: A string prefix React uses for IDs generated by [`useId`.](/reference/react/useId) Useful to avoid conflicts when using multiple roots on the same page. + * `onRecoverableError` **اختياري**: دالة مرجعية تُستدعى تلقائيًا عندما يفيق React من الأخطاء. + * `identifierPrefix` **اختياري**: بادئة نصيّة يستخدمها React للمعرفات الفريدة التي تنشأ عن طريق [`useId`](/reference/react/useId). مفيد لتجنب التعارض عند استخدام العديد من الجذور في نفس الصفحة. -#### Returns {/*returns*/} +#### العائدات {/*returns*/} -`createRoot` returns an object with two methods: [`render`](#root-render) and [`unmount`.](#root-unmount) +يعيد `createRoot` كائنًا يحتوي على طريقتين: [`render`](#root-render) و [`unmount`](#root-unmount). -#### Caveats {/*caveats*/} -* If your app is server-rendered, using `createRoot()` is not supported. Use [`hydrateRoot()`](/reference/react-dom/client/hydrateRoot) instead. -* You'll likely have only one `createRoot` call in your app. If you use a framework, it might do this call for you. -* When you want to render a piece of JSX in a different part of the DOM tree that isn't a child of your component (for example, a modal or a tooltip), use [`createPortal`](/reference/react-dom/createPortal) instead of `createRoot`. +#### ملاحظات {/*caveats*/} +* إذا كان تطبيقك يتم عرضه من الخادم SSR، فإن استخدام `createRoot()` غير مدعوم. استخدم [`hydrateRoot()`](/reference/react-dom/client/hydrateRoot) بدلاً من ذلك. +* من المرجح أن لديك استدعاء واحد فقط لـ `createRoot` في تطبيقك. إذا كنت تستخدم إطار عمل، فقد يستدعيها الإطار نيابةً عنك. +* عندما ترغب في عرض جزء من JSX في جزء آخر من شجرة DOM التي ليست طفلًا للمكون الخاص بك (على سبيل المثال، نافذة محادثة، أو توضيح Tooltip)، استخدم [`createPortal`](/reference/react-dom/createPortal) بدلاً من `createRoot`. --- ### `root.render(reactNode)` {/*root-render*/} -Call `root.render` to display a piece of [JSX](/learn/writing-markup-with-jsx) ("React node") into the React root's browser DOM node. +استدعِ `root.render` لعرض جزء من [JSX](/learn/writing-markup-with-jsx) ("عنصر React") داخل عنصر DOM في جذر React. ```js root.render(); ``` -React will display `` in the `root`, and take over managing the DOM inside it. +سيعرض React `` في الجذر، وسيتولى إدارة العنصر DOM داخله. -[See more examples below.](#usage) +[انظر المزيد من الأمثلة أدناه.](#usage) -#### Parameters {/*root-render-parameters*/} +#### المعاملات {/*root-render-parameters*/} -* `reactNode`: A *React node* that you want to display. This will usually be a piece of JSX like ``, but you can also pass a React element constructed with [`createElement()`](/reference/react/createElement), a string, a number, `null`, or `undefined`. +* `reactNode`: *عنصر React* الذي ترغب في عرضه. عادةً ما يكون هذا جزءًا من JSX مثل ``، ولكن يمكنك أيضًا تمرير عنصر React المُنشأ باستخدام [`createElement()`](/reference/react/createElement)، أو نص أو رقم أو `null` أو `undefined`. -#### Returns {/*root-render-returns*/} +#### العائدات {/*root-render-returns*/} -`root.render` returns `undefined`. +يعيد `root.render` `undefined`. -#### Caveats {/*root-render-caveats*/} +#### ملاحظات {/*root-render-caveats*/} -* The first time you call `root.render`, React will clear all the existing HTML content inside the React root before rendering the React component into it. +* عندما تستدعي `root.render` للمرة الأولى، سيحذف React كل المحتوى الموجود داخل جذر React قبل عرض مكونات React فيه. -* If your root's DOM node contains HTML generated by React on the server or during the build, use [`hydrateRoot()`](/reference/react-dom/client/hydrateRoot) instead, which attaches the event handlers to the existing HTML. +* إذا كان جذر عنصر DOM الخاص بك يحتوي على HTML أنشأته React على الخادم أو أثناء البناء، استخدم [`hydrateRoot()`](/reference/react-dom/client/hydrateRoot) بدلاً من ذلك، والتي تربط مستمعي الأحداث بـ HTML الموجود بالفعل. + +* إذا استدعيت `render` في نفس الجذر أكثر من مرة، ستحدث React عناصر DOM اللازمة ليظهر أحدث JSX مررتها، ستقرر React أي أجزاء React يمكن إعادة استخدامها، ,أيها يحتاج لإعادة الإنشاء عن طريق ["مطابقتها"](/learn/preserving-and-resetting-state) مع الشجرة المعروضة سابقًا. استدعاء `render` في نفس الجذر مرة أخرى يشبه مناداة [دالة `set`](/reference/react/useState#setstate) في المكون الجذر: تتجنب React تحديثات DOM غير الضرورية. -* If you call `render` on the same root more than once, React will update the DOM as necessary to reflect the latest JSX you passed. React will decide which parts of the DOM can be reused and which need to be recreated by ["matching it up"](/learn/preserving-and-resetting-state) with the previously rendered tree. Calling `render` on the same root again is similar to calling the [`set` function](/reference/react/useState#setstate) on the root component: React avoids unnecessary DOM updates. --- ### `root.unmount()` {/*root-unmount*/} -Call `root.unmount` to destroy a rendered tree inside a React root. +استدعِ `root.unmount` لتدمير شجرة معروضة داخل جذر React. ```js root.unmount(); ``` -An app fully built with React will usually not have any calls to `root.unmount`. - -This is mostly useful if your React root's DOM node (or any of its ancestors) may get removed from the DOM by some other code. For example, imagine a jQuery tab panel that removes inactive tabs from the DOM. If a tab gets removed, everything inside it (including the React roots inside) would get removed from the DOM as well. In that case, you need to tell React to "stop" managing the removed root's content by calling `root.unmount`. Otherwise, the components inside the removed root won't know to clean up and free up global resources like subscriptions. +عادةً، لن يستدعي تطبيق مبني كاملًا بـ React `root.unmount`. -Calling `root.unmount` will unmount all the components in the root and "detach" React from the root DOM node, including removing any event handlers or state in the tree. +هذا يكون مفيدًا بشكل أساسي إذا كان عنصر جذر React الخاصة بك (أو أي من العناصر الأسلاف لها) قد يتم إزالتها من DOM بواسطة بعض الأكواد الأخرى. على سبيل المثال، تخيل أن لديك لوحة علامات jQuery تقوم بإزالة علامات غير نشطة من DOM. إذا تمت إزالة علامة ما، فإن كل ما بداخلها (بما في ذلك جذور React الداخلية) سيتم إزالته من DOM أيضًا. في هذه الحالة، تحتاج إلى إخبار React بأنه يجب "إيقاف" إدارة محتوى الجذر المزال عن طريق استدعاء `root.unmount`. وإلا، فإن المكونات الداخلية في الجذر المزال لن تعرف كيفية التنظيف وتحرير الموارد العامة مثل الاشتراكات. +عند استدعاء `root.unmount`، سيتم إلغاء تثبيت جميع المكونات في الجذر" و"فصل" React عن عنصر DOM الجذر، بما في ذلك إزالة أي معالجات أحداث أو حالة في الشجرة. -#### Parameters {/*root-unmount-parameters*/} -`root.unmount` does not accept any parameters. +#### المعاملات {/*root-unmount-parameters*/} +`root.unmount` لا تستقبل أي معاملات. -#### Returns {/*root-unmount-returns*/} -`root.unmount` returns `undefined`. +#### العائدات {/*root-unmount-returns*/} -#### Caveats {/*root-unmount-caveats*/} +تعيد `root.unmount`: `undefined`. -* Calling `root.unmount` will unmount all the components in the tree and "detach" React from the root DOM node. +#### ملاحظات {/*root-unmount-caveats*/} -* Once you call `root.unmount` you cannot call `root.render` again on the same root. Attempting to call `root.render` on an unmounted root will throw a "Cannot update an unmounted root" error. However, you can create a new root for the same DOM node after the previous root for that node has been unmounted. +* استدعاء `root.unmount` سيلغي تثبيت جميع المكونات في الشجرة ويفصل React عن عنصر DOM الجذر. +* بمجرد استدعاء `root.unmount`، لا يمكنك استدعاء `root.render` مرة أخرى على نفس الجذر. ستؤدي محاولة استدعاء `root.render` على جذر غير مثبتة إلى إطلاق خطأ `"Cannot update an unmounted root"`. ومع ذلك، يمكنك إنشاء جذر جديد لنفس عنصر DOM بعد إلغاء تثبيت الجذر السابقة لذلك العنصر. --- -## Usage {/*usage*/} +## الاستخدام {/*usage*/} -### Rendering an app fully built with React {/*rendering-an-app-fully-built-with-react*/} +### عرض التطبيق المُبني بالكامل بواسطة React {/*rendering-an-app-fully-built-with-react*/} -If your app is fully built with React, create a single root for your entire app. +إذا كان تطبيقك مبنيًا بالكامل بواسطة React، قم بإنشاء جذر واحدة لتطبيقك بالكامل. ```js [[1, 3, "document.getElementById('root')"], [2, 4, ""]] import { createRoot } from 'react-dom/client'; @@ -135,17 +135,19 @@ const root = createRoot(document.getElementById('root')); root.render(); ``` -Usually, you only need to run this code once at startup. It will: +عادةً ما يكون عليك تنفيذ هذا الشيء مرة واحدة فقط عند بدء التشغيل. -1. Find the browser DOM node defined in your HTML. -2. Display the React component for your app inside. + سيقوم بما يلي: + +1. العثور على عنصر DOM للمتصفح المعرف في ملف HTML الخاص بك. +2. عرض مكون React لتطبيقك بداخله. ```html index.html - My app + تطبيقي
@@ -168,7 +170,7 @@ import { useState } from 'react'; export default function App() { return ( <> -

Hello, world!

+

مرحبًا بكم

); @@ -178,7 +180,7 @@ function Counter() { const [count, setCount] = useState(0); return ( ); } @@ -186,46 +188,45 @@ function Counter() {
-**If your app is fully built with React, you shouldn't need to create any more roots, or to call [`root.render`](#root-render) again.** +**إذا كان تطبيقك مبنيًا بالكامل بواسطة React، فغالبًا لن تحتاج إلى إنشاء مزيد من الجذور أو استدعاء [`root.render`](#root-render) مرة أخرى.** -From this point on, React will manage the DOM of your entire app. To add more components, [nest them inside the `App` component.](/learn/importing-and-exporting-components) When you need to update the UI, each of your components can do this by [using state.](/reference/react/useState) When you need to display extra content like a modal or a tooltip outside the DOM node, [render it with a portal.](/reference/react-dom/createPortal) +من هذه النقطة وما بعدها، سيتولى React إدارة DOM للتطبيق بأكمله. لإضافة مكونات إضافية، [احتضنها داخل المكون `App`.](/learn/importing-and-exporting-components) عندما تحتاج إلى تحديث واجهة المستخدم، يمكن أن تقوم كل من مكوناتك بذلك عن طريق [استخدام الحالة.](/reference/react/useState) وعندما تحتاج إلى عرض محتوى إضافي مثل نافذة منبثقة أو نصائح خارج عنصر DOM، [اعرضه باستخدام `createPortal`.](/reference/react-dom/createPortal) -When your HTML is empty, the user sees a blank page until the app's JavaScript code loads and runs: +عندما يكون عنصر HTML خاليًا، يرى المستخدم صفحة فارغة حتى يتم تحميل وتشغيل كود JavaScript للتطبيق: ```html
``` -This can feel very slow! To solve this, you can generate the initial HTML from your components [on the server or during the build.](/reference/react-dom/server) Then your visitors can read text, see images, and click links before any of the JavaScript code loads. We recommend [using a framework](/learn/start-a-new-react-project#production-grade-react-frameworks) that does this optimization out of the box. Depending on when it runs, this is called *server-side rendering (SSR)* or *static site generation (SSG).* +يمكن أن يكون هذا بطيئًا جدًا! لحل هذه المشكلة، يمكنك إنشاء عنصر HTML الأولي من مكوناتك [على الخادم أو أثناء البناء.](/reference/react-dom/server) ثم يمكن لزوار موقعك قراءة النص ورؤية الصور والنقر على الروابط قبل تحميل أي كود JavaScript. نوصي بأن تستخدم [إطار عمل](/learn/start-a-new-react-project#production-grade-react-frameworks) يفعل هذا الأمر تلقائيًا. اعتمادًا على موعد تشغيله، يُطلق عليه *تحميل من جانب الخادم (SSR)* أو *توليد المواقع الثابت (SSG).*
-**Apps using server rendering or static generation must call [`hydrateRoot`](/reference/react-dom/client/hydrateRoot) instead of `createRoot`.** React will then *hydrate* (reuse) the DOM nodes from your HTML instead of destroying and re-creating them. +**يجب على التطبيقات التي تستخدم تقنية تصيير الخادم (server rendering) أو التوليد الثابت (static generation) استدعاء [`hydrateRoot`](/reference/react-dom/client/hydrateRoot) بدلاً من `createRoot`.** سيقوم React بعد ذلك بـ *تحييد hydrate* (إعادة استخدام) عناصر DOM من HTML الخاص بك بدلاً من تدميرها وإعادة إنشائها. --- -### Rendering a page partially built with React {/*rendering-a-page-partially-built-with-react*/} - -If your page [isn't fully built with React](/learn/add-react-to-an-existing-project#using-react-for-a-part-of-your-existing-page), you can call `createRoot` multiple times to create a root for each top-level piece of UI managed by React. You can display different content in each root by calling [`root.render`.](#root-render) +### عرض صفحة مبنية جزئيًا بواسطة React {/*rendering-a-page-partially-built-with-react*/} -Here, two different React components are rendered into two DOM nodes defined in the `index.html` file: +إذا كانت صفحتك [ليست مبنية بالكامل باستخدام React](/learn/add-react-to-an-existing-project#using-react-for-a-part-of-your-existing-page)، يمكنك استدعاء `createRoot` عدة مرات لإنشاء جذر لكل قسم من أقسام واجهة المستخدم الرئيسية التي تُدار بواسطة React. يمكنك عرض محتوى مختلف في كل جذر عن طريق استدعاء [`root.render`](#root-render). +في هذا المثال، يتم عرض نوعين مختلفين من مُكوِّنات React في عنصري DOM موجودين في ملف `index.html`: ```html public/index.html - My app + تطبيقي
-

This paragraph is not rendered by React (open index.html to verify).

+

هذا الجزء ليس مبنيًا بـReact. افتح index.html لتتأكد

@@ -250,8 +251,8 @@ commentRoot.render(); export function Navigation() { return (
    - Home - About + الرئيسية + من نحن
); } @@ -267,9 +268,9 @@ function NavLink({ href, children }) { export function Comments() { return ( <> -

Comments

- - +

التعليقات

+ + ); } @@ -282,34 +283,35 @@ function Comment({ text, author }) { ``` ```css +body { direction: rtl; } nav ul { padding: 0; margin: 0; } nav ul li { display: inline-block; margin-right: 20px; } ```
-You could also create a new DOM node with [`document.createElement()`](https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement) and add it to the document manually. +يمكنك أيضًا إنشاء عنصر DOM جديد باستخدام [`document.createElement()`](https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement) وإضافتها يدويًا إلى المستند. ```js const domNode = document.createElement('div'); const root = createRoot(domNode); root.render(); -document.body.appendChild(domNode); // You can add it anywhere in the document +document.body.appendChild(domNode); // يمكنك إضافتها في أي مكان بالمستند ``` -To remove the React tree from the DOM node and clean up all the resources used by it, call [`root.unmount`.](#root-unmount) +لإزالة شجرة React من عنصر DOM وتنظيف جميع الموارد المستخدمة من قِبلها، استدعِ [`root.unmount`.](#root-unmount) ```js root.unmount(); ``` -This is mostly useful if your React components are inside an app written in a different framework. +تعتبر هذه الطريقة مفيدة بشكل رئيسي إذا كانت مُكوِّنات React الخاصة بك داخل تطبيق مكتوب بإطار عمل مختلف. --- -### Updating a root component {/*updating-a-root-component*/} +### تحديث المكون الجذر {/*updating-a-root-component*/} -You can call `render` more than once on the same root. As long as the component tree structure matches up with what was previously rendered, React will [preserve the state.](/learn/preserving-and-resetting-state) Notice how you can type in the input, which means that the updates from repeated `render` calls every second in this example are not destructive: +يمكنك استدعاء `render` أكثر من مرة على نفس الجذر. طالما أن هيكل شجرة المُكوِّن يُطابق ما تم عرضه سابقًا، ستُحافظ React على [الحالة.](/learn/preserving-and-resetting-state) لاحظ كيف يمكنك كتابة نص في المُدخل، مما يعني أن التحديثات الناتجة عن استدعاءات `render` المتكررة كل ثانية في هذا المثال لا تُؤدي إلى حذف البيانات: @@ -331,8 +333,8 @@ setInterval(() => { export default function App({counter}) { return ( <> -

Hello, world! {counter}

- +

مرحبًا بكم {counter}

+ ); } @@ -340,14 +342,14 @@ export default function App({counter}) {
-It is uncommon to call `render` multiple times. Usually, your components will [update state](/reference/react/useState) instead. +من غير الشائع أن تستدعي `render` عدة مرات. عادةً، يمكن لمكوناتك [تحديث الحالة](/reference/react/useState) بدلاً من ذلك. --- -## Troubleshooting {/*troubleshooting*/} +## حل المشكلات {/*troubleshooting*/} -### I've created a root, but nothing is displayed {/*ive-created-a-root-but-nothing-is-displayed*/} +### لقد أنشأت جذرًا، ولكن لا يتم عرض أي شيء {/*ive-created-a-root-but-nothing-is-displayed*/} -Make sure you haven't forgotten to actually *render* your app into the root: +تأكد من أنك لم تنسى أن تقوم بـ *عرض* تطبيقك فعليًا في الجذر: ```js {5} import { createRoot } from 'react-dom/client'; @@ -357,15 +359,15 @@ const root = createRoot(document.getElementById('root')); root.render(); ``` -Until you do that, nothing is displayed. +إلى أن تفعل ذلك، لن يتم عرض أي شيء. --- -### I'm getting an error: "Target container is not a DOM element" {/*im-getting-an-error-target-container-is-not-a-dom-element*/} +### أواجه خطأ: `"Target container is not a DOM element"` {/*im-getting-an-error-target-container-is-not-a-dom-element*/} -This error means that whatever you're passing to `createRoot` is not a DOM node. +هذا الخطأ يعني أن ما تقوم بتمريره إلى `createRoot` ليس عنصر DOM. -If you're not sure what's happening, try logging it: +إذا لم تكن متأكدًا مما يحدث، جرب استخدام `console.log` للتحقق من القيمة التي تمررها إلى `createRoot`: ```js {2} const domNode = document.getElementById('root'); @@ -374,46 +376,46 @@ const root = createRoot(domNode); root.render(); ``` -For example, if `domNode` is `null`, it means that [`getElementById`](https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementById) returned `null`. This will happen if there is no node in the document with the given ID at the time of your call. There may be a few reasons for it: +على سبيل المثال، إذا كانت `domNode` تساوي `null`، فهذا يعني أن [`getElementById`](https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementById) قد أرجع `null`. وهذا سيحدث إذا لم يكن هناك عنصر في المستند يحمل المعرف ID المعطاة في وقت استدعائك للدالة. قد تكون هناك بعض الأسباب وراء ذلك: -1. The ID you're looking for might differ from the ID you used in the HTML file. Check for typos! -2. Your bundle's `