Skip to content

Commit

Permalink
Apply suggestions mentioned in #59
Browse files Browse the repository at this point in the history
  • Loading branch information
@sorousht
sorousht committed Jun 20, 2020
1 parent 0153776 commit da97b96
Showing 1 changed file with 22 additions and 28 deletions.
50 changes: 22 additions & 28 deletions content/docs/reference-dom-elements.md
View file
@@ -1,6 +1,6 @@
---
id: dom-elements
title: المنت های DOM
title: المنت‌های DOM
layout: docs
category: Reference
permalink: docs/dom-elements.html
Expand All @@ -14,29 +14,27 @@ redirect_from:
- "tips/dangerously-set-inner-html.html"
---

ری‌اکت دارای سیستم DOM مستقل از مرورگر برای کارایی و سازگاری با مرورگر هاست.
از این فرصت استفاده کردیم تا مقداری زمختی های پیاده سازی DOM مرورگر را مرتب و منظم کنیم.
به دلیل کارایی و سازگاری با مرورگرهای مختلف، ری‌اکت سیستم DOM خود را، مستقل از مرورگر پیاده‌سازی می‌کند. ما از این فرصت استفاده کردیم تا مقداری به زمختی های پیاده‌سازی DOM در مرورگر نظم دهیم.

در ری‌اکت، تمامی ویژگی ها و صفات DOM (از جلمه event handlers) باید به صورت camelCased باشند. برای مثال، صفت HTML `tabindex` با صفت `tabIndex` در ری‌اکت مطابقت دارد. استثناهایی که وجود دارند یکی صفات `aria-*` و دیگری صفات `data-*` هستند که باید
با حروف کوچک نوشته بشوند. برای مثال `aria-label` همان `aria-label` باقی می‌ماند.
در ری‌اکت، تمامی ویژگی‌ها و صفات DOM (از جلمه event handler ها) باید به صورت camelCase باشند. برای مثال، صفت `tabindex` در HTML با صفت `tabIndex` در ری‌اکت مطابقت دارد. استثناهایی که وجود دارند یکی صفات `aria-*` و دیگری صفات `data-*` هستند که باید با حروف کوچک نوشته بشوند. برای مثال `aria-label` همان `aria-label` باقی می‌ماند.

## تفاوت بین صفات {#differences-in-attributes}

صفاتی وجود دارند که عملکردشون در ری‌اکت با HTML متفاوت است:
صفاتی وجود دارند که عملکردشان در ری‌اکت با HTML متفاوت است:

### checked {#checked}

صفت `checked` در کامپوننت های `<input>` که از تیپ `checkbox` یا `radio` هستند قابل استفاده است. شما میتوانید از آن بدین شکل که وضعیت کامپوننت چک خورده باشد یا نه استفاده کنید. این برای ساختن کامپوننت های قابل کنترل مناسب است. معادل غیر کنترلی آن `defaultChecked` هست که فقط وضعیت چک خوردن همان اول کامپوننت را هنگام سوار شدن بر عهده دارد.
صفت `checked` در کامپوننت های `<input>` که از تیپ `checkbox` یا `radio` هستند قابل استفاده است. شما میتوانید از آن بدین شکل که وضعیت کامپوننت چک خورده باشد یا نه استفاده کنید. این برای ساختن کامپوننت‌های کنترل شده مناسب است. معادل کنترل نشده آن `defaultChecked` هست که فقط وضعیت چک خوردن همان اول کامپوننت را هنگام mount شدن بر عهده دارد.

### className {#classname}

برای اختصاص دادن یک کلاس CSS، از صفت `className` استفاده کنید. این در مورد همه المنت های معمول DOM و SVG مانند `<div>`، `<a>` و سایرین صدق می‌کند.

اگر با ری‌اکت از وب کامپوننتس (که البته رایج نیست) استفاده می‌کنید، صفت `class` را مورد استفاده قرار دهید.
اگر از ری‌اکت برای Web Components (که البته رایج نیست) استفاده می‌کنید، صفت class را مورد استفاده قرار دهید.

### dangerouslySetInnerHTML {#dangerouslysetinnerhtml}

`dangerouslySetInnerHTML` جایگزین ری‌اکت برای `innerHTML` جهت استفاده در DOM مرورگر است. به طور کلی، قرار دادن HTML از داخل کد، کار پر خطریست، برای اینکه به راحتی کاربران را در معرض حمله [تزریق اسکریپت از طریق وبگاه](https://fa.wikipedia.org/wiki/%D8%AA%D8%B2%D8%B1%DB%8C%D9%82_%D8%A7%D8%B3%DA%A9%D8%B1%DB%8C%D9%BE%D8%AA_%D8%A7%D8%B2_%D8%B7%D8%B1%DB%8C%D9%82_%D9%88%D8%A8%DA%AF%D8%A7%D9%87) قرار می‌دهد. البته که میتوانید مستقیما HTML را از طریق ری‌اکت وارد کنید، اما باید بنویسید `dangerouslySetInnerHTML` و یک شئ با کلید `__html` در آن قرار بدهید تا به خودتان یادآوری کنید که کار خطرناکی کرده اید.
`dangerouslySetInnerHTML` جایگزین ری‌اکت برای `innerHTML` جهت استفاده در DOM مرورگر است. به طور کلی، قرار دادن HTML از داخل کد، کار پر خطریست، برای این‌که به‌راحتی کاربران را در معرض حمله [تزریق اسکریپت از طریق وبگاه (XSS)](https://fa.wikipedia.org/wiki/%D8%AA%D8%B2%D8%B1%DB%8C%D9%82_%D8%A7%D8%B3%DA%A9%D8%B1%DB%8C%D9%BE%D8%AA_%D8%A7%D8%B2_%D8%B7%D8%B1%DB%8C%D9%82_%D9%88%D8%A8%DA%AF%D8%A7%D9%87) قرار می‌دهد. البته که می‌توانید مستقیما HTML را از طریق ری‌اکت وارد کنید، اما باید بنویسید `dangerouslySetInnerHTML` و یک شئ با کلید `__html` در آن قرار بدهید تا به خودتان یادآوری کنید که کار خطرناکی کرده‌اید. برای مثال:

```js
function createMarkup() {
Expand All @@ -54,20 +52,17 @@ function MyComponent() {

### onChange {#onchange}

رویداد `onChange` رفتاری که از او انتظار میرود را دارد: هر وقت که یک مکان درون فرم تغییر کند، این رویداد به صدا در میاید. ما مخصوصا از رفتار موجود مرورگر استفاده نمی‌کنیم، چون `onChange` یک اشتباه لغتیست برای کاری که انجام میدهد و اینکه ری‌اکت به این رویداد برای رسیدگی بی‌درنگ به ورودی کاربر تکیه می‌کند.
رویداد `onChange` رفتاری که از او انتظار می‌رود را دارد: هر وقت که یک فیلد از فرم تغییر کند، این رویداد به صدا در می‌آید. ما مخصوصا از رفتار موجود مرورگر استفاده نمی‌کنیم، چون `onChange` یک اشتباه لغتیست برای کاری که انجام میدهد و اینکه ری‌اکت به این رویداد برای رسیدگی بی‌درنگ به ورودی کاربر تکیه می‌کند.

### selected {#selected}

صفت `selected` توسط کامپوننت های `<option>` پشتیبانی می‌شود. شما می‌توانید از آن برای تعیین اینکه کامپوننت انتخاب شده یا نه استفاده کنید. این برای ساختن کامپوننت های کنترل مناسب است.
صفت `selected` توسط کامپوننت‌های `<option>` پشتیبانی می‌شود. شما می‌توانید از آن برای تعیین اینکه کامپوننت انتخاب شده یا نه استفاده کنید. این برای ساختن کامپوننت‌های کنترل شده مناسب است.

### style {#style}

>یادداشت
>توجه
>
>بعضی مثال ها در این مستندات از `style` برای راحتی کار استفاده می‌کنند، اما
**استفاده کردن از صفت `style` به عنوان راهکار اصلی چیدمان المنت ها، عموما پیشنهاد نمی‌شود.** در غالب موارد، [`className`](#classname) باید برای ارجاع دادن به کلاس های تعریف شده در یک CSS stylesheet خارجی استفاده شود. `style` معمولا در اپلیکیشن های ری‌اکت وقتی استفاده می‌شود که نیاز به اضافه کردن چیدمان های دینامیک در زمان render باشد. مراجعه کنید به [FAQ: Styling and CSS](/docs/faq-styling.html).

صفت `style`، یک شئ جاوااسکریپت با ویژگی های camelCased قبول می‌کند، نه اینکه یک رشته CSS قبول کند. این با ویژگی `style` جاوااسکریپت در DOM سازگاری دارد، بهینه تر است و از منافذ حمله XSS جلوگیری می‌کند. برای مثال:
>بعضی مثال‌های این مستندات از `style` برای راحتی کار استفاده می‌کند، اما **استفاده کردن از صفت style به عنوان راهکار اصلی برای style دادن به المنت‌ها، عموما پیشنهاد نمی‌شود. ** در غالب موارد، [`className`](#classname) باید برای ارجاع دادن به کلاس‌های تعریف شده در یک CSS stylesheet خارجی استفاده شود. `style` معمولا در اپلیکیشن های ری‌اکت وقتی استفاده می‌شود که نیاز به اضافه کردن style های پویا در زمان render باشد. مراجعه کنید به [سوالات متداول: style دادن و CSS](/docs/faq-styling.html). صفت `style`، یک شئ جاوااسکریپت با ویژگی‌های camelCased قبول می‌کند، نه اینکه یک رشته CSS قبول کند. این با ویژگی `style` جاوااسکریپت در DOM سازگاری دارد، بهینه‌تر است و از حفره‌های امنیتی XSS جلوگیری می‌کند. برای مثال:
```js
const divStyle = {
Expand All @@ -80,7 +75,7 @@ function HelloWorldComponent() {
}
```

به یاد داشته باشید که چیدمان ها به صورت اتوماتیک prefix ندارند. برای اینکه بتوانید مرورگرهای قدیمی را هم پشتیبانی کنید، باید ویژگی های مربوطه چیدمان را خودتان اضافه کنید.
به یاد داشته باشید که style ها به صورت اتوماتیک prefix ندارند. برای این‌که بتوانید مرورگرهای قدیمی را هم پشتیبانی کنید، باید ویژگی‌های مربوطه style را خودتان اضافه کنید:

```js
const divStyle = {
Expand All @@ -92,9 +87,9 @@ function ComponentWithTransition() {
return <div style={divStyle}>This should work cross-browser</div>;
}
```
کلیدهای چیدمان به صورت camelCased هستند که این موضوع برای سازگاری داشتن با طریقه دستیابی به ویژگی‌های node های DOM از طریق جاوااسکریپت هست (به عنوان نمونه: `node.style.backgroundImage`). همه Vendor Prefix ها [به جز `ms`](https://www.andismith.com/blogs/2012/02/modernizr-prefixed/) باید با حرف بزرگ شروع بشوند. برای همین است که `WebkitTransition` در ابتدا یک "W" بزرگ دارد.
کلیدهای style به صورت camelCase هستند تا با روشی که node به ویژگی‌های DOM از طریق جاوااسکریپت دسترسی پیدا می‌کند، سازگاری داشته‌باشد (مثال: `node.style.backgroundImage`). همه Vendor Prefix ها [به جز `ms`](https://www.andismith.com/blogs/2012/02/modernizr-prefixed/) باید با حرف بزرگ شروع بشوند. برای همین است که `WebkitTransition` در ابتدا یک "W" بزرگ دارد.

ری‌اکت به طور اتوماتیک یک پسوند "px" به برخی ویژگی‌های عددی درون-خطی چیدمان اضافه می‌کند. اگر می‌خواهید واحدی غیر از "px" استفاده کنید، مقدار آن را به صورت یک رشته همراه با واحد مورد نظر وارد کنید. برای مثال:
ری‌اکت به طور اتوماتیک یک پسوند "px" به برخی ویژگی‌های عددی style درخط (inline) اضافه می‌کند. اگر می‌خواهید واحدی غیر از "px" استفاده کنید، مقدار آن را به صورت یک رشته همراه با واحد مورد نظر وارد کنید. برای مثال:

```js
// Result style: '10px'
Expand All @@ -108,28 +103,27 @@ function ComponentWithTransition() {
</div>
```

البته همه ویژگی‌های چیدمان به رشته های پیکسلی تبدیل نمی‌شوند. برخی از آنها بدون واحد باقی می‌مانند (مثلا `zoom`, `order`, `flex`). لیست کامل این ویژگی‌های بدون واحد در [اینجا](https://github.com/facebook/react/blob/4131af3e4bf52f3a003537ec95a1655147c81270/src/renderers/dom/shared/CSSProperty.js#L15-L59) قابل مشاهده است.
البته همه ویژگی‌های style به رشته و پیکسل تبدیل نمی‌شوند. برخی از آنها بدون واحد باقی می‌مانند (مثلا `zoom`، `order` و `flex`). لیست کامل این ویژگی‌های بدون واحد در [اینجا](https://github.com/facebook/react/blob/4131af3e4bf52f3a003537ec95a1655147c81270/src/renderers/dom/shared/CSSProperty.js#L15-L59) قابل مشاهده است.

### suppressContentEditableWarning {#suppresscontenteditablewarning}

معمولا، هر وفت که یک المنت والد به عنوان `contentEditable` علامت‌ گذاری می‌شود، هشداری به صدا در می‌آید، چون مشکل ساز خواهد شد. این صفت باعث می‌شود تا آن هشدار مسکوت باقی بماند. از این استفاده نکنید، مگر اینکه یک کتابخانه ای دارید می‌سازید مثل [Draft.js](https://facebook.github.io/draft-js/) که خودش به صورت دستی `contentEditable` را مدیریت می‌کند.
معمولا، هر وقت که یک المنت والد به عنوان `contentEditable` علامت‌ گذاری می‌شود، هشداری به صدا در می‌آید، چون مشکل ساز خواهد شد. این صفت باعث می‌شود تا آن هشدار مسکوت باقی بماند. از این استفاده نکنید، مگر اینکه یک کتابخانه ای دارید می‌سازید مثل [Draft.js](https://facebook.github.io/draft-js/) که خودش به صورت دستی `contentEditable` را مدیریت می‌کند.

### suppressHydrationWarning {#suppresshydrationwarning}

اگر از rendering درون-سروری ری‌اکت استفاده می‌کنید، در صورتی که محتوای render شده سرویس گیرنده با محتوای render شده سرور متفاوت باشد، هشداری دریافت می‌کنید.
البته، در برخی موارد خیلی سخت است که دقیقا با همدیگر جور بشوند. برای مثال مهر زمان ها بین سرور و سرویس گیرنده متفاوت خواهند بود.
اگر از rendering سمت سروری ری‌اکت استفاده می‌کنید، در صورتی که محتوای render شده کلاینت با محتوای render شده سرور متفاوت باشد، هشداری دریافت می‌کنید. البته، در برخی موارد خیلی سخت است که دقیقا با همدیگر جور بشوند. برای مثال timestamp ها بین سرور و کلاینت متفاوت خواهند بود.

اگر شما `suppressHydrationWarning` را برای المنتی `true` کنید، ری‌اکت برای مغایرت های صفات و محتوای آن المنت به شما هشدار نخواهد داد. فقط تا یک سطح عمق کار خواهد کرد، و این هم به منظور یک راه فرار است، زیاد از آن استفاده نکنید. شما می‌توانید در مورد hydration بیشتر بخوانید [`ReactDOM.hydrate()` documentation](/docs/react-dom.html#hydrate).
اگر شما `suppressHydrationWarning` را برای المنتی `true` کنید، ری‌اکت برای مغایرت‌های صفات و محتوای آن المنت به شما هشدار نخواهد داد. فقط تا یک سطح از عمق کار خواهد کرد، و این هم به منظور یک راه فرار است، زیاد از آن استفاده نکنید. شما می‌توانید در مورد hydration در [اسناد `ReactDOM.hydrate()`](/docs/react-dom.html#hydrate) بیشتر بخوانید.

### value {#value}

صفت `value` توسط کامپوننت های `<input>` و `<textarea>` پشتیبانی می‌شود. شما می‌توانید از آن برای تعیین مقدار یک کامپوننت استفاده کنید. این برای ساختن کامپوننت های کنترل مناسب است. `defaultValue` معادل غیر کنترلی آن است، که مقدار کامپوننت را در هنگام سوار شدن تعیین می‌کند.
صفت `value` توسط کامپوننت های `<input>` و `<textarea>` پشتیبانی می‌شود. شما می‌توانید از آن برای تعیین مقدار یک کامپوننت استفاده کنید. این برای ساختن کامپوننت های کنترل‌شده مناسب است. `defaultValue` معادل غیر کنترلی آن است، که مقدار کامپوننت را در هنگام mount شدن تعیین می‌کند.

## تمام صفات HTML قابل پشتیبانی {#all-supported-html-attributes}

بعد از ری‌اکت ۱۶، هر صفت DOM استاندارد [یا شخصی ساز](/blog/2017/09/08/dom-attributes-in-react-16.html) کاملا پشتیبانی می‌شود.
بعد از ری‌اکت ۱۶، هر صفت استاندارد [یا سفارشی](/blog/2017/09/08/dom-attributes-in-react-16.html)DOM کاملا پشتیبانی می‌شود.

ری‌اکت همیشه یک API حول جاوااسکریپت برای DOM ارائه کرده است. از آنجایی که کامپوننت های ری‌اکت معمولا prop های شخصی-ساز و مربوط به DOM را دریافت می‌کنند، ری‌اکت از عرف camelCased که در API های DOM وجود دارد استفاده می‌کند.
AP‌Iای که ری‌اکت برای DOM ارائه کرده، همیشه با محوریت JavaScript بوده‌است. از آن‌جایی که کامپوننت‌های ری‌اکت معمولا هم prop‌های مربوط به DOM و همpropهای سفارشی را دریافت می‌کند، ری‌اکت از قانون camelCase استفاده می‌کند. درست مشابه APIهایی که DOM ارائه می‌کند:

```js
<div tabIndex="-1" /> // Just like node.tabIndex DOM API
Expand Down Expand Up @@ -196,4 +190,4 @@ xlinkHref xlinkRole xlinkShow xlinkTitle xlinkType xmlns xmlnsXlink xmlBase
xmlLang xmlSpace y y1 y2 yChannelSelector z zoomAndPan
```

شما می‌توانید صفات شخصی-ساز را استفاده کنید تا وقتی که کاملا با حروف کوچک باشند.
شما می‌توانید صفات سفارشی را استفاده کنید تا وقتی که کاملا با حروف کوچک باشند.

0 comments on commit da97b96

Please sign in to comment.