Skip to content

Components and Props translation #46

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sorousht merged 7 commits into from
Apr 18, 2019
Merged

Components and Props translation #46

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
804228e
props translation
mohsenkhanpour Apr 3, 2019
33624fc
revisions
mohsenkhanpour Apr 8, 2019
168efa7
fix: typo
mohsenkhanpour Apr 8, 2019
11c340a
revisions
mohsenkhanpour Apr 16, 2019
28768e3
final revisions
mohsenkhanpour Apr 17, 2019
3619bac
revisions
mohsenkhanpour Apr 17, 2019
063a4c3
typo fix
mohsenkhanpour Apr 17, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 61 additions & 49 deletions content/docs/components-and-props.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
id: components-and-props
title: Components and Props
title: کامپوننت‌‌ها و prop ها
permalink: docs/components-and-props.html
redirect_from:
- "docs/reusable-components.html"
Expand All @@ -16,23 +16,27 @@ 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).
کامپوننت‌ها به شما اجازه می‌دهند رابط کاربری را به بخش‌های مستقل قابل استفاده مجدد تقسیم کنید و این بخش‌ها را به صورت مجزا در نظر بگیرید. این صفحه مقدمه‌ای برای مفهوم کامپوننت به شما ارائه می‌دهد. شما می‌توانید مرجع 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.
از لحاظ مفهومی کامپوننت‌ها همانند توابع جاوااسکریپت هستند. آنها ورودی‌های دلخواه خود (props) را دریافت می‌کنند و المنت‌هایی از ری‌اکت را باز می‌گردانند که توصیف کننده آنچه باید روی صفحه نمایان شود است.

## Function and Class Components {#function-and-class-components}

The simplest way to define a component is to write a JavaScript function:
## کامپوننت‌هایی از جنس تابع و کلاس {#function-and-class-components}

ساده‌ترین راه برای تعریف کردن یک کامپوننت، نوشتن یک تابع جاوااسکریپت است:


```js
function Welcome(props) {
return <h1>Hello, {props.name}</h1>;
}
```
این تابع یک کامپوننت ری‌اکت قابل‌قبول است، زیرا یک "props" (که کوچک شده properties است) که آرگومانی از جنس شی همراه با داده است را دریافت و یک المنت ری‌اکت را باز می‌گرداند.
به این نوع کامپوننت‌ها، «کامپوننت‌‌های تابع‌» گفته می‌شود زیرا آنها در واقعیت تابع‌هایی از جاوااسکریپت هستند.


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.

You can also use an [ES6 class](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Classes) to define a component:
شما همچنین می‌توانید از [کلاس‌های ES6](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Classes) برای تعریف کامپوننت‌ها استفاده کنید:

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

The above two components are equivalent from React's point of view.
دو کامپوننت بالا از نظر ری‌اکت یکسان هستند.

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-a-component}

Previously, we only encountered React elements that represent DOM tags:
پیش‌تر ما فقط با المنت‌هایی از ری‌اکت مواجه شدیم که بیانگر تگ‌های 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".
زمانی که ری‌اکت با المنتی مواجه می‌شود که بیانگر یک کامپوننت تعریف شده توسط کاربر باشد، ویژگی‌های JSX را در قالب یک شی واحد به کامپوننت منتقل می‌کند. ما این object را “props” می‌نامیم.

For example, this code renders "Hello, Sara" on the page:

برای مثال کد زیر "Hello, Sara" را روی صفحه رندر می‌کند:

```js{1,5}
function Welcome(props) {
Expand All @@ -76,26 +81,30 @@ ReactDOM.render(
);
```

[](codepen://components-and-props/rendering-a-component)
[روی CodePen امتحان کنید](codepen://components-and-props/rendering-a-component)

بیایید جمع‌بندی کنیم که در این مثال چه اتفاقی می‌افتد:

Let's recap what happens in this example:
۱. ما تابع `ReactDOM.render()` را با المنت `<Welcome name="Sara" />` فرا می‌خوانیم.

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>`.
۲. ری‌اکت کامپوننت `Welcome` را به همراه `{name: 'Sara'}` که در ورودی تابع به عنوان `props` تعریف شده است، فرا می‌خواند.

>**Note:** Always start component names with a capital letter.
۳. کامپوننت `Welcome` ما یک المنت `<h1>Hello, Sara</h1>` را به عنوان نتیجه باز می‌گرداند.

۴. DOM ری‌اکت به صورت بهینه DOM را به‌روزرسانی می‌کند تا `<h1>Hello, Sara</h1>` را نمایش دهد.

>**نکته:** همیشه نام کامپوننت‌ها را با یک حرف بزرگ شروع کنید.
>
>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.
>ری‌اکت با کامپوننت‌هایی که با حروف کوچک شروع شده باشند همانند تگ‌های DOM برخورد می‌کند. برای مثال تگ `<div />` بیانگر یک تگ HTML است , اما `<Welcome />` بیانگر یک کامپوننت است و بنابرین لازم است `Welcome` در scope باشد.
>
>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).
>برای یادگیری دلیل این قرارداد، لطفا [JSX In Depth](/docs/jsx-in-depth.html#user-defined-components-must-be-capitalized) را مطالعه فرمایید.

## ترکیب کامپوننت‌ها {#composing-components}

## Composing Components {#composing-components}
کامپوننت‌ها می‌توانند در خروجی خود به دیگر کامپوننت‌ها اشاره کنند. این به ما اجازه می‌دهد تا یک abstraction کامپوننت را برای هر سطحی از جزییات استفاده کنیم. در برنامه‌های ری‌اکتی یک دکمه، یک فرم، یک دیالوگ، و یک صفحه همگی به صورت کامپوننت بیان می‌شوند.

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.
برای مثال ما می‌توانیم یک کامپوننت به نام `App` بسازیم که `Welcome` را بارها رندر می‌کند:

For example, we can create an `App` component that renders `Welcome` many times:

```js{8-10}
function Welcome(props) {
Expand All @@ -118,15 +127,16 @@ ReactDOM.render(
);
```

[](codepen://components-and-props/composing-components)
[روی CodePen امتحان کنید](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.
معمولا، پروژه‌های جدید ری‌اکت دارای یک کامپوننت `App` واحد در بالاترین سطح هستند. اما اگر شما ری‌اکت را با پروژه‌ای موجود ادغام می‌کنید، می‌توانید از سطوح پایین به بالا طراحی کنید، برای مثال از یک کامپوننت کوچک مانند `Button` شروع کنید و تدریجا تا بالای سلسله مراتب view طراحی را ادامه دهید.

## Extracting Components {#extracting-components}

Don't be afraid to split components into smaller components.
## استخراج کامپوننت‌ها {#extracting-components}

For example, consider this `Comment` component:
از این که کامپوننت‌ها را به کامپوننت‌های کوچک‌تر تبدیل کنید هراسان نباشید.

برای مثال این کامپوننت `Comment` را در نظر بگیرید:

```js
function Comment(props) {
Expand All @@ -152,13 +162,13 @@ function Comment(props) {
}
```

[](codepen://components-and-props/extracting-components)
[روی CodePen امتحان کنید](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 (یک string)، و 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 +181,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 آن بجای `author` اسمی عام نظیر `user` داده‌ایم.

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 +208,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 +223,7 @@ function UserInfo(props) {
}
```

This lets us simplify `Comment` even further:
این به ما کمک می‌کند تا `Comment` را حتی بیشتر از این ساده کنیم:

```js{4}
function Comment(props) {
Expand All @@ -231,32 +241,34 @@ function Comment(props) {
}
```

[](codepen://components-and-props/extracting-components-continued)
[روی CodePen امتحان کنید](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}
## propها فقط قابل خواندن هستند {#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) تعریف کرده‌اید، آن کامپوننت نباید هرگز propهای خودش را تغییر دهد.
این تابع `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)"](https://en.wikipedia.org/wiki/Pure_function) نامیده می‌شوند زیرا سعی نمی‌کنند که ورودی خود را تغییر دهند و همیشه با ورودی‌های مشخص خروجی‌های ثابتی را نمایش می‌دهند.

In contrast, this function is impure because it changes its own input:
در نقطه متقابل این کامپوننت "ناخالص (impure)" است زیرا ورودی خود را تغییر می‌دهد:

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

React is pretty flexible but it has a single strict rule:
ری‌اکت خیلی منعطف است اما یک قانون سختگیرانه دارد:

**تمامی کامپوننت‌های ری‌اکت باید نسبت به propهای خود همانند توابع خالص عمل کنند.**

**All React components must act like pure functions with respect to their props.**
البته رابط‌های کاربری اپ‌ها داینامیک هستند و با زمان تغییر می‌کنند. در [بخش بعدی](/docs/state-and-lifecycle.html)، ما یک مفهوم جدید به نام "state" را معرفی می‌کنیم. State به کامپوننت‌های ری‌اکت اجازه می‌دهد تا خروجی خود را در جواب به عملکرد کاربر، پاسخ‌های دریافتی از شبکه، و هر چیز دیگر در زمان مورد نیاز بدون اینکه این قانون را نقض کنند تغییر دهند.

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.