Skip to content

Commit

Permalink
Merge pull request #11 from asantarissy/translating-components-and-pr…
Browse files Browse the repository at this point in the history 
…ops.md

Translating components-and-props.md
  • Loading branch information
@asantarissy
asantarissy committed Feb 17, 2019
2 parents ae8ddf2 + ddf8fd0 commit 75ded45
Showing 1 changed file with 45 additions and 45 deletions.
90 changes: 45 additions & 45 deletions content/docs/components-and-props.md
View file
@@ -1,6 +1,6 @@
---
id: components-and-props
title: Components and Props
title: المكونات والخاصيات
permalink: docs/components-and-props.html
redirect_from:
- "docs/reusable-components.html"
Expand All @@ -16,23 +16,23 @@ prev: rendering-elements.html
next: state-and-lifecycle.html
---

Components let you split the UI into independent, reusable pieces, and think about each piece in isolation. This page provides an introduction to the idea of components. You can find a [detailed component API reference here](/docs/react-component.html).
تتيح لنا المُكوِّنات (Components) تقسيم واجهة المستخدم إلى قطع مُستقِلَّة قابلة لإعادة الاستخدام، والتفكير بكل قطعة على انفراد. سنتحدّث في هذه الصفحة عن مُقدّمة إلى مفهوم المُكوِّنات، بإمكانك أن تجد مرجعًا مُفصَّلًا حول [واجهة برمجة التطبيق (API) الخاصّة بالمُكوِّنات من هنا](/docs/react-component.html).

Conceptually, components are like JavaScript functions. They accept arbitrary inputs (called "props") and return React elements describing what should appear on the screen.
تُشبِه المُكوِّنات من الناحية النظريّة دوال JavaScript، فهي تقبل مُدخَلات المستخدم (والتي تُدعى props اختصارًا للكلمة properties وتعني الخاصيّات) وتُعيد عناصر React وصف ما الذي ينبغي عرضه على الشّاشة.

## Function and Class Components {#function-and-class-components}
## مكونات الأصناف والدوال {#function-and-class-components}

The simplest way to define a component is to write a JavaScript function:
إنّ أبسط طريقة لتعريف مُكوِّن هي كتابة دالة JavaScript:

```js
function Welcome(props) {
return <h1>Hello, {props.name}</h1>;
}
```

This function is a valid React component because it accepts a single "props" (which stands for properties) object argument with data and returns a React element. We call such components "function components" because they are literally JavaScript functions.
تُعدّ هذه الدالة مُكوِّنًا صالحًا في React لأنّها تقبل وسيطًا واحدًا من خاصيّات الكائن "props" (اختصارًا للكلمة properties وتعني الخاصيّات) مع بياناته وتُعيد عنصر React. ندعو مثل هذه المُكوِّنات بالمُكوِّنات الداليّة "function components" لأنّها عبارة عن دوال JavaScript.

You can also use an [ES6 class](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Classes) to define a component:
بإمكانك أيضًا أن تستخدم [الأصناف "ES6 class"](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Classes) لتعريف المُكوِّنات كما يلي:

```js
class Welcome extends React.Component {
Expand All @@ -42,27 +42,27 @@ class Welcome extends React.Component {
}
```

The above two components are equivalent from React's point of view.
إنّ المُكوِّنين السابقين مُتكافِئان من وجهة نظر React.

Classes have some additional features that we will discuss in the [next sections](/docs/state-and-lifecycle.html). Until then, we will use function components for their conciseness.
تمتلك الأصناف بعض الميّزات الإضافيّة التي سنتحدّث عنها في قسم [القسم التالي](/docs/state-and-lifecycle.html). وحتى ذلك الوقت سنستخدم المُكوِّنات الداليّة لبساطتها.

## Rendering a Component {#rendering-a-component}
## تصيير المكوّنات (Rendering) {#rendering-a-component}

Previously, we only encountered React elements that represent DOM tags:
م نصادف حتى الآن إلّا عناصر React تُمثِّل عناصر DOM المُعتادة:

```js
const element = <div />;
```

However, elements can also represent user-defined components:
ولكن يُمكِن للعناصر أن تُمثِّل مُكوِّنات مُعرَّفة من قبل المستخدم:

```js
const element = <Welcome name="Sara" />;
```

When React sees an element representing a user-defined component, it passes JSX attributes to this component as a single object. We call this object "props".
عندما تجد React عنصرًا يُمثِّل مُكوِّنًا مُعرَّفًا من قبل المستخدم، فستُمرِّر خاصيّات JSX إليه على شكل كائن وحيد، ندعو هذا الكائن "props".

For example, this code renders "Hello, Sara" on the page:
لى سبيل المثال تعرض هذه الشيفرة عبارة "Hello, Sara" في الصّفحة:

```js{1,5}
function Welcome(props) {
Expand All @@ -78,24 +78,24 @@ ReactDOM.render(

[](codepen://components-and-props/rendering-a-component)

Let's recap what happens in this example:
تلخيص ما حدث في هذا المثال:

1. We call `ReactDOM.render()` with the `<Welcome name="Sara" />` element.
2. React calls the `Welcome` component with `{name: 'Sara'}` as the props.
3. Our `Welcome` component returns a `<h1>Hello, Sara</h1>` element as the result.
4. React DOM efficiently updates the DOM to match `<h1>Hello, Sara</h1>`.
1. نستدعي التّابع `ReactDOM.render()` مع العنصر `<Welcome name="Sara" />`.
2. تستدعي React المُكوِّن `Welcome` مع تمرير `{name: 'Sara'}` كخاصيّة props.
3. يُعيد العنصر `Welcome` العنصر `<h1>Hello, Sara</h1>` كنتيجة له.
4. تُحدِّث React DOM بكفاءة DOM ليُطابِق `<h1>Hello, Sara</h1>`.

>**Note:** Always start component names with a capital letter.
>**ملاحظة:** يجب أن تبدأ أسماء المُكوِّنات دومًا بأحرف كبيرة.
>
>React treats components starting with lowercase letters as DOM tags. For example, `<div />` represents an HTML div tag, but `<Welcome />` represents a component and requires `Welcome` to be in scope.
>تُعامِل React المُكوِّنات التي تبدأ بأحرف صغيرة كعناصر DOM، على سبيل المثال يُمثِّل `<div />` عنصر HTML الذي يُدعى div، بينما تُمثِّل `<Welcome />` مُكوِّنًا في React وتتطلَّب أن يكون تعريف هذا المُكوِّن موجودًا ضمن المجال المُحدَّد.
>
>To learn more about the reasoning behind this convention, please read [JSX In Depth](/docs/jsx-in-depth.html#user-defined-components-must-be-capitalized).
>بإمكانك قراءة المزيد عن المنطق الكامن وراء هذه الاتفاقيّة [من هنا](/docs/jsx-in-depth.html#user-defined-components-must-be-capitalized).
## Composing Components {#composing-components}
## تركيب المكونات {#composing-components}

Components can refer to other components in their output. This lets us use the same component abstraction for any level of detail. A button, a form, a dialog, a screen: in React apps, all those are commonly expressed as components.
يُمكِن للمُكوِّنات أن تشير إلى مُكوِّنات أخرى في ناتجها، يسمح لنا هذا باستخدام نفس المُكوِّن المُجرَّد لأي درجة من التفصيل، زر (button)، أو حقل إدخال (form)، أو مربّع حوار (dialog)، أو شاشة (screen)، ففي React يُعبَّر عنها جميعها بالمُكوِّنات.

For example, we can create an `App` component that renders `Welcome` many times:
على سبيل المثال يُمكننا إنشاء مُكوِّن اسمه `App` يعرض في ناتجه المُكوِّن `Welcome` عدّة مرّات:

```js{8-10}
function Welcome(props) {
Expand All @@ -120,13 +120,13 @@ ReactDOM.render(

[](codepen://components-and-props/composing-components)

Typically, new React apps have a single `App` component at the very top. However, if you integrate React into an existing app, you might start bottom-up with a small component like `Button` and gradually work your way to the top of the view hierarchy.
تحتوي تطبيقات React الجديدة عادةً على المُكوِّن `App` في المستوى الأعلى وتنحدر عنه باقي المُكوِّنات، ولكن إن كنت تدمج React مع تطبيق موجود مُسبقًا فقد تبدأ من المستوى السفلي بمُكوِّن صغير مثل الزر `Button` وتصعد تدريجيًّا حتى المستوى الأعلى في هيكليّة التطبيق.

## Extracting Components {#extracting-components}
## استخراج المكونات {#extracting-components}

Don't be afraid to split components into smaller components.
لا تتردد بتقسيم المُكوِّنات إلى مُكوِّنات أصغر.

For example, consider this `Comment` component:
على سبيل المثال انظر إلى مُكوِّن التعليقات `Comment` التالي:

```js
function Comment(props) {
Expand Down Expand Up @@ -154,11 +154,11 @@ function Comment(props) {

[](codepen://components-and-props/extracting-components)

It accepts `author` (an object), `text` (a string), and `date` (a date) as props, and describes a comment on a social media website.
يقبل هذا المُكوِّن الكائن `author`، والسلسلة النصيّة `text`، والتاريخ `date` كخاصيات props له، ويُمثِّل تعليقًا على مواقع التواصل الاجتماعي.

This component can be tricky to change because of all the nesting, and it is also hard to reuse individual parts of it. Let's extract a few components from it.
من الصعب تغيير هذا المُكوِّن بسبب هذه التداخلات، ومن الصعب أيضًا إعادة استخدام أجزاء منه، فلنحاول استخراج بعض المُكوِّنات منه.

First, we will extract `Avatar`:
سنستخرج في البداية مُكوِّن الصورة الرمزيّة `Avatar`:

```js{3-6}
function Avatar(props) {
Expand All @@ -171,11 +171,11 @@ function Avatar(props) {
}
```

The `Avatar` doesn't need to know that it is being rendered inside a `Comment`. This is why we have given its prop a more generic name: `user` rather than `author`.
لا يحتاج المُكوِّن `Avatar` إلى معرفة أنّه مُستخدَم في المُكوِّن `Comment`. ولذلك أعطينا خاصيّاته prop اسمًا أكثر عموميّةً وهو: `user` بدلًا من `author`.

We recommend naming props from the component's own point of view rather than the context in which it is being used.
نوصي بتسمية الخاصيّات props من وجهة نظر المُكوِّن نفسه وليس في السياق الذي تُستخدَم فيه.

We can now simplify `Comment` a tiny bit:
بإمكاننا الآن تبسيط المُكوِّن `Comment` قليلًا:

```js{5}
function Comment(props) {
Expand All @@ -198,7 +198,7 @@ function Comment(props) {
}
```

Next, we will extract a `UserInfo` component that renders an `Avatar` next to the user's name:
سنستخرج الآن مُكوِّن معلومات المستخدم `UserInfo` والذي يعرض المُكوِّن `Avatar` بجانب اسم المستخدم:

```js{3-8}
function UserInfo(props) {
Expand All @@ -213,7 +213,7 @@ function UserInfo(props) {
}
```

This lets us simplify `Comment` even further:
يُتيح لنا هذا تبسيط المُكوِّن `Comment` أكثر:

```js{4}
function Comment(props) {
Expand All @@ -233,30 +233,30 @@ function Comment(props) {

[](codepen://components-and-props/extracting-components-continued)

Extracting components might seem like grunt work at first, but having a palette of reusable components pays off in larger apps. A good rule of thumb is that if a part of your UI is used several times (`Button`, `Panel`, `Avatar`), or is complex enough on its own (`App`, `FeedStory`, `Comment`), it is a good candidate to be a reusable component.
يبدو استخراج المُكوِّنات في البداية عملًا مجهدًا، ولكن سنرى الفائدة الكبيرة لامتلاك عدّة مُكوِّنات قابلة لإعادة الاستخدام عند بناء تطبيقات كبيرة. القاعدة هنا هي: إن استخدمنا أجزاء واجهة المستخدم عدّة مرّات (مثل الزر `Button`، و اللوحة `Panel`، والصورة الرمزيّة `Avatar`)، أو كانت هذه الأجزاء مُعقّدة بحد ذاتها (مثل مُكوِّن التطبيق `App`، و `FeedStory`، والتعليق `Comment`)، فهي مُرشَّحة بشكل كبير لأن نجعلها مُكوِّنات قابلة لإعادة الاستخدام.

## Props are Read-Only {#props-are-read-only}
## الخاصيات props قابلة للقراءة فقط {#props-are-read-only}

Whether you declare a component [as a function or a class](#function-and-class-components), it must never modify its own props. Consider this `sum` function:
لا يجب تعديل خاصيّات المُكوِّنات، سواءً صرّحنا عنها [كدالة أو كصنف](#function-and-class-components)، فلنأخذ هذا المثال عن دالة الجمع `sum`:

```js
function sum(a, b) {
return a + b;
}
```

Such functions are called ["pure"](https://en.wikipedia.org/wiki/Pure_function) because they do not attempt to change their inputs, and always return the same result for the same inputs.
تُدعى هذه الدوال [بالدوال النقيّة (Pure Functions)](https://en.wikipedia.org/wiki/Pure_function) لأنّها لا تحاول تغيير مُدخلاتها وتُعيد دومًا نفس النتيجة لنفس المُدخلات.

In contrast, this function is impure because it changes its own input:
على العكس من ذلك نجد أنّ هذه الدالة غير نقية لأنّها تُغيِّر مُدخلاتها:

```js
function withdraw(account, amount) {
account.total -= amount;
}
```

React is pretty flexible but it has a single strict rule:
إنّ React مرنة جدًّا ولكن لديها قاعدة واحدة صارمة وهي:

**All React components must act like pure functions with respect to their props.**
**يجب أن تسلك مُكوِّنات React سلوك الدوال النقيّة مع احترامها لخاصيّاتها (props).**

Of course, application UIs are dynamic and change over time. In the [next section](/docs/state-and-lifecycle.html), we will introduce a new concept of "state". State allows React components to change their output over time in response to user actions, network responses, and anything else, without violating this rule.
تتغيّر واجهات المستخدم الخاصّة بالتطبيق مع الزمن بالطبع، سنتحدّث في [القسم التالي](/docs/state-and-lifecycle.html)، حول مفهوم جديد وهو الحالة (state). حيث تسمح الحالة لمُكوِّنات React بتغيير ناتجها مع مرور الزمن استجابةً لتفاعل المستخدم، والردود القادمة من الشبكة، وأي شيء آخر، بدون خرق هذه القاعدة.

0 comments on commit 75ded45

Please sign in to comment.