{"componentChunkName":"component---src-templates-docs-js","path":"/docs/react-api.html","result":{"data":{"markdownRemark":{"html":"

React نقطه‌ی ورود به کتابخانه‌ی ری‌اکت است. اگر شما React را از تگ <script> بارگذاری کنید، این APIهای سطح بالا از React گلوبال قابل دسترسی هستند. اگر شما از ES6 ‌به‌همراه npm استفاده می‌کنید، می‌توانید بنویسید import React from 'react'. اگر از ES5 به‌همراه npm استفاده می‌کنید، می‌توانید بنویسید var React = require('react').

\n

مرور کلی

\n

کامپوننت‌ها

\n

کامپوننت‌های ری‌اکت به شما اجازه می‌دهند تا رابط کاربری را به بخش‌های مستقل با قابلیت استفاده‌ی مجدد تقسیم کنید، و درمورد هر قسمت به صورت جداگانه فکر کنید. کامپوننت‌های ری‌اکت را می‌توان به عنوان زیرکلاسی برای React.Component یا React.PureComponent تعریف کرد.

\n\n

اکر شما از کلاس‌های ES6 استفاده نمی‌کنید، می‌توانید به جای آن از create-react-class استفاده کنید. بخش ری‌اکت بدون استفاده از ES6 را برای آگاهی بیشتر ببینید.

\n

کامپوننت‌های ری‌اکت می‌توانند به شکل تابع نیز تعریف شوند که می‌توان آن‌ها را با memo بسته‌بندی (wrap) کرد:

\n\n

ایجاد المنت‌های ری‌اکت

\n

ما پیشنهاد می‌کنیم برای توصیف رابط کاربری از JSX استفاده کنید. هر المنت JSX یک Syntactic sugar است برای صدا زدن ()React.createElement. اگر از JSX استفاده کنید، معمولا متدهای زیر را به شکل مستقیم فراخوانی نخواهید کرد.

\n\n

برای آگاهی بیشتر از بخش ری‌اکت بدون استفاده از JSX دیدن کنید.

\n

تبدیل المنت‌ها

\n

React، چندین API برای دست‌کاری کردن المنت‌ها فراهم می‌کند:

\n\n

فرگمنت‌ها

\n

React همچنین برای یک کامپوننت، امکان رندر کردن چند المنت بدون استفاده از wrapper را فراهم می‌سازد.

\n\n

Refs

\n\n

تعلیق (Suspense)

\n

Suspense به کامپوننت‌ها اجازه می‌دهد تا قبل از رندر شدن، برای چیزی «صبر» کنند. فعلا Suspense فقط یک مورد کاربرد را پشتیبانی می‌کند: بارگذاری پویای کامپوننت‌ها با استفاده از React.lazy. در آینده، از مورد کاربردهای دیگری چون واکشی داده (data fetching) پشتیبانی خواهد کرد.

\n\n

هوک‌ها

\n

هوک‌ها یک افزونه جدید در ری‌اکت ۱۶.۸ هستند. آن‌ها به شما این توانایی را می‌دهند که بدون نوشتن کلاس از state بهره ببرید. هوک‌ها یک بخش توضیحات جدا و یک مرجع API جدا دارند:

\n\n
\n

مرجع

\n

React.Component

\n

React.Component کلاس پایه است برای کامپوننت‌های ری‌اکت وقتی به روش کلاس‌های ES6 تعریف شده باشند:

\n
class Greeting extends React.Component {\n  render() {\n    return <h1>Hello, {this.props.name}</h1>;\n  }\n}
\n

مرجع React.Component API را برای لیستی از متدها و ویژگی‌های مربوط به کلاس پایه React.Component ببینید.

\n
\n

React.PureComponent

\n

React.PureComponent به React.Component شبیه است. تفاوت آن‌ها این است که React.Component تابع ()shouldComponentUpdate را پیاده‌سازی نمی‌کند، ولی React.PureComponent آن‌را با یک قیاس سطحی props و state پیاده‌سازی می‌کند.

\n

اگر تابع render() کامپوننت ری‌اکت شما، در صورت یکسان بودن props و state، خروجی یکسان تولید می‌کند، برای ارتقای کارایی در برخی از موارد می‌توانید از React.PureComponent استفاده کنید.

\n
\n

نکته

\n

shouldComponentUpdate() در React.PureComponent فقط به صورت سطحی (shallow) اشیاء را مقایسه می‌کند. اگر این اشیاء دارای ساختاری پیچیده باشند، ممکن است باعث رخ‌داد منفی کاذب(false-negative) برای تفاوت‌های عمیق‌تر شود. تنها زمانی PureComponent را extend کنید که توقع دارید state و props ساده‌ باشند، یا زمانی از ()forceUpdate استفاده کنید که می‌دانید ساختار عمیق داده‌ها تغییر پیدا کرده است. و یا داده‌های تغییرناپذیز را برای تسهیل مقایسه سریع داده‌های تودرتو استفاده کنید.

\n

علاوه بر این، shouldComponentUpdate() در React.PureComponent، به‌روز شدن state و props را در کل زیردرخت کامپوننت درنظر نمی‌گیرد. پس مطمئن شوید که همه‌ی کامپوننت‌های فرزند نیز «pure» باشند.

\n
\n
\n

React.memo

\n
const MyComponent = React.memo(function MyComponent(props) {\n  /* render using props */\n});
\n

React.memo یک کامپوننت مرتبه بالا می‌باشد.

\n

اگر کامپوننت شما در صورت گرفتن props یکسان، نتیجه‌ی یکسان تولید می‌کند، می‌توانید آن‌را در یک فراخوانی React.memo، wrap کنید تا با یادداشت‌برداری نتیجه، کارایی را بالا برید. این کار به آن معناست که ری‌اکت رندر کردن کامپوننت را در نظر نمی‌گیرد و آخرین نتایج رندرهای قبلی را درنظر می‌گیرد.

\n

به صورت پیش‌فرض این فقط یک مقایسه سطحی بین اشیاء موجود در شیء props انجام می‌دهد. اگر می‌خواهید خودتان این مقایسه را کنترل کنید، می‌توانید یک تابع مقایسه شخصی‌سازی شده را به عنوان آرگومان دوم به این تابع بدهید.

\n

React.memo تنها تغییرات props را بررسی می‌کند. اگر کامپوننت شما درون React.memo قرار گرفته‌است و در آن از هوک‌های useState و useContext استفاده شده‌است، تغییر state یا context باعث رندر شدن مجدد می‌شود.

\n
function MyComponent(props) {\n  /* render using props */\n}\nfunction areEqual(prevProps, nextProps) {\n  /*\n  return true if passing nextProps to render would return\n  the same result as passing prevProps to render,\n  otherwise return false\n  */\n}\nexport default React.memo(MyComponent, areEqual);
\n

این روش فقط به عنوان بهینه‌سازی کارایی مورد استفاده است. برای «جلوگیری» از رندر، از آن استفاده نکنید، به خاطر آن‌که می‌تواند به خطا سرانجام یابد.

\n
\n

نکته:

\n

برخلاف متد ()shouldComponentUpdate در کامپوننت‌های به شکل کلاس، تابعareEqual مقدار true را بازمی‌گرداند اگر propها یکسان باشند و false برمیگرداند اگر propها متفاوت باشند. این رفتاری عکس shouldComponentUpdateمی‌باشد.

\n
\n
\n

()createElement

\n
React.createElement(\n  type,\n  [props],\n  [...children]\n)
\n

ایجاد و برگرداندن یک المنت ری‌اکت جدید با توجه به نوع (type) داده شده. آرگومان نوع داده شده می‌تواند رشته‌ی نام یک تگ (مثل 'div' یا 'span')، یک نوع کامپوننت ری‌اکت (کلاس یا تابع)، یا یک نوع فرگمنت ری‌اکت باشد.

\n

کد نوشته شده با JSX تبدیل به حالتی می‌شود که از React.createElement() استفاده کند. شما در حالت معمول اگر از JSX استفاده کنید به صورت مستقیم React.createElement() را فرا نمی‌خوانید. ری‌اکت بدون استفاده از JSX را برای یادگیری بیشتر ببینید.

\n
\n

()cloneElement

\n
React.cloneElement(\n  element,\n  [props],\n  [...children]\n)
\n

شبیه‌سازی (clone) و برگرداندن یک المنت به عنوان یک نقطه شروع. المنت جدید، دارای props المنت اصلی همراه با props جدید به شکل ترکیب شده سطحی می‌باشد. فرزندان جدید جایگزین فرزندان قبلی می‌شوند. key و ref المنت اصلی محفوظ می‌مانند.

\n

React.cloneElement() تقریبا برابر است با:

\n
<element.type {...element.props} {...props}>{children}</element.type>
\n

گرچه، این کار refها را محفوظ نگاه می‌دارد. این یه آن معناست که اگر شما یک فرزند را با ref آن دریافت کنید، آن‌را به شکل اتفاقی از اجداد خود سرقت نمی‌کنید. شما ref یکسان متصل شده به المنت جدید خواهید داشت.

\n

این API به عنوان جایگزینی برای React.addons.cloneWithProps() منسوخ شده معرفی شد.

\n
\n

()createFactory

\n
React.createFactory(type)
\n

یک تابع برمی‌گرداند که المنت‌های ری‌اکت با نوع داده شده را تولید می‌کند. مثل ()React.createElement، آرگومان نوع داده شده می‌تواند رشته‌ی نام یک تگ (مثل 'div' یا 'span')، یک نوع کامپوننت ری‌اکت (کلاس یا تابع)، یا یک نوع فرگمنت ری‌اکت باشد.

\n

این helper یک نوع قدیمی(legacy) محسوب می‌شود و ما شما را تشویق می‌کنیم که به صورت مستقیم از React.createElement() یا JSX استفاده کنید.

\n

اگر از JSX استفاده کنید، معمولا React.createFactory() را مستقیما فراخوانی نخواهید کرد. ری‌اکت بدون استفاده از JSX را برای یادگیری بیشتر ببینید.

\n
\n

()isValidElement

\n
React.isValidElement(object)
\n

بررسی میکند که آیا شیء مورد نظر، المنت ری‌اکت هست یا خیر. true یا false برمی‌گرداند.

\n
\n

React.Children

\n

React.Children ابزاری برای کار با ساختمان‌داده‌ی غیرشفافthis.props.children فراهم می‌کند.

\n

React.Children.map

\n
React.Children.map(children, function[(thisArg)])
\n

یک تابع روی هر فرزند immediate داخل children فرامی‌خواند که this را به عنوان thisArg تنظیم می‌کند. اگر children یک آرایه باشد از آن میگذرد و تابع روی تک‌تک فرزند‌های درون آرایه اجرا می‌شود. اگر children، null یا undefined باشد، این متد به جای یک آرایه، null یا undefined برمی‌گرداند.

\n
\n

نکته:

\n

اگر children، یک فرگمنت باشد به عنوان یک فرزند تنها با آن برخورد می‌شود و از آن نمی‌گذرد.

\n
\n

React.Children.forEach

\n
React.Children.forEach(children, function[(thisArg)])
\n

مانند ()React.Children.map است ولی آرایه‌ای برنمی‌گرداند.

\n

React.Children.count

\n
React.Children.count(children)
\n

تعداد کامپوننت‌های موجود در children را برمی‌گرداند، برابر تعداد دفعاتی است که callback داده شده به map یا forEach فراخوانی شده است.

\n

React.Children.only

\n
React.Children.only(children)
\n

بررسی می‌کند که آیا children فقط یک فرزند (المنت ری‌اکت) دارد و آن را برمی‌گرداند. در غیراین‌صورت این متد یک ارور برمی‌گرداند.

\n
\n

نکته:

\n

React.Children.only()، مقدار برگردانده شده توسط ()React.Children.map را قبول نمی‌کند زیرا یک آرایه است نه یک المنت ری‌اکت.

\n
\n

React.Children.toArray

\n
React.Children.toArray(children)
\n

ساختمان‌ داده‌ی غیرشفاف children را به شکل یک آرایه‌ی مسطح با فرزندهایی که به هرکدام یک کلید اختصاص ‌داده شده برمی‌گرداند. کاربردی است اگر بخواهید مجموغه‌هایی از فرزندان را در متدهای رندر خود دستکاری کنید، مخصوصا اگر بخواهید this.props.children را قبل از پاس دادن به سطوح پایین‌تر، قطعه‌قطعه یا دوباره مرتب کنید.

\n
\n

نکته:

\n

React.Children.toArray() در فرایند مسطح‌سازی لیست فرزندان، کلیدها را تغییر می‌دهد تا معنای آرایه‌های تودرتو حفظ شود. به این معنا که، toArray، هر کلید را پیشوندگذاری می‌کند تا کلید هر المنت به‌‌ همان آرایه‌ی واردشده‌ای محدود شود که دارای آن کلید بوده است .

\n
\n
\n

React.Fragment

\n

کامپوننت React.Fragment به شما این توانایی را می‌دهد تا چندین المنت را در متد render() برگردانید، بدون آن‌که المنت DOM جدیدی بسازید:

\n
render() {\n  return (\n    <React.Fragment>\n      Some text.\n      <h2>A heading</h2>\n    </React.Fragment>\n  );\n}
\n

همچنین می‌توانید آن را به شکل خلاصه‌ی <></> نمایش دهید. برای آگاهی بیشتر، ری‌اکت نسخه‌ی 16.2.0: پشتیبانی ارتقا یافته از فرگمنت‌ها را ببینید.

\n

React.createRef

\n

React.createRef یک ref می‌سازد که می‌تواند با استفاده از خصوصیت ref به المنت متصل شود.\n

\n 
class MyComponent extends React.Component {\n  constructor(props) {\n    super(props);\n\n    this.inputRef = React.createRef();  }\n\n  render() {\n    return <input type=\"text\" ref={this.inputRef} />;  }\n\n  componentDidMount() {\n    this.inputRef.current.focus();  }\n}
\n

\n

React.forwardRef

\n

React.forwardRef یک کامپوننت ری‌اکت ایجاد می‌کند که خصوصیت ref دریافت شده را به کامپوننت زیرین در درخت فوروارد کند. این روش خیلی معمول نیست مگر در دو مورد:

\n\n

React.forwardRef، یک تابع رندرکننده را به عنوان آرگومان می‌پذیرد. ری‌اکت این تابع را با props و ref به عنوان دو آرگومان صدا می‌زند. این تابع باید یک نود ری‌اکت برگرداند.

\n

\n 
const FancyButton = React.forwardRef((props, ref) => (  <button ref={ref} className=\"FancyButton\">    {props.children}\n  </button>\n));\n\n// You can now get a ref directly to the DOM button:\nconst ref = React.createRef();\n<FancyButton ref={ref}>Click me!</FancyButton>;
\n

\n

در مثال بالا، ری‌اکت، ref داده شده به المنت <FancyButton ref={ref}> را به عنوان آرگومان دوم به تابع رندرکننده صدازده‌ شده درون React.forwardRef می‌دهد. این تابع رندرکننده، ref را به المنت <button ref={ref}> انتقال می‌دهد.

\n

در نتیجه، بعد از این‌که ری‌اکت، ref را متصل کرد، ref.current مستقیما به المنت DOM مربوط به <button> اشاره می‌کند.

\n

برای آگاهی بیشتر، فوروارد refها را ببینید.

\n

React.lazy

\n

React.lazy() به شما اجازه می‌دهد کامپوننتی تعریف کنید که به شکل پویا بارگذاری می‌شود. این کمک می‌کند تا حجم بسته‌ی نهایی(bundle) کاهش یابد تا بارگذاری کامپوننت‌هایی که در رندر ابتدایی استفاده نشده‌اند را به تعویق اندازد.

\n

می‌توانید برای یادگیری نحوه‌ی استفاده از آن به سند بخش‌بندی کد بروید. ممکن است بخواهید این مقاله را بررسی کنید، که در مورد چگونگی استفاده از آن با جزئیاتی بیشتر توضیح داده است .

\n
// این کامپوننت به صورت پویا بارگذاری می‌شود\nconst SomeComponent = React.lazy(() => import('./SomeComponent'));
\n

توجه کنید که کامپوننت‌های lazy نیازمند وجود یک کامپوننت <React.Suspense> در سطوح بالاتر درخت رندر هستند. این نحوه‌ی مشخص کردن یک loading indicator است.

\n
\n

نکته

\n

استفاده از React.lazyهمراه با import پویا نیازمند آن است که Promiseها در محیط جاوااسکریپت قابل استفاده باشند. این نیازمند یک polyfill روی IE11 و کمتر از آن است.

\n
\n

React.Suspense

\n

React.Suspense به شما اجازه می‌دهد loading indicator را مشخص کنید در حالتی که برخی کامپوننت‌های زیرین آن در درخت هنوز آماده‌ی رندر نباشند. فعلا، کامپوننت‌های با بارگذاری lazy، تنها مورد کاربردی است که <React.Suspense> از آن پشتیبانی می‌کند:

\n
// این کامپوننت به صورت پویا بارگذاری می‌شود\nconst OtherComponent = React.lazy(() => import('./OtherComponent'));\n\nfunction MyComponent() {\n  return (\n    // Displays <Spinner> until OtherComponent loads\n    <React.Suspense fallback={<Spinner />}>\n      <div>\n        <OtherComponent />\n      </div>\n    </React.Suspense>\n  );\n}
\n

این قسمت در راهنمای بخش‌بندی کد توضیح داده شد‌ه‌است. توجه کنید که کامپوننت‌های lazy می‌توانند در اعماق یک درخت Suspense موجود باشند (نیازی نیست که تک‌تک آن‌ها را به این شکل wrap کنید) . بهترین تمرین این است که <Suspense> را جایی قرار دهید که میخواهید یک loading indicator مشاهده کنید، اما lazy() را جایی قرار دهید که می‌خواهید کد را بخش‌بندی کنید.

\n

گرچه این امکان فعلا وجود ندارد، در آینده برنامه‌ریزی کرده‌ایم که به Suspense اجازه دهیم تا به سناریوهای دیگری چون واکشی داده رسیدگی کند. در این مورد می‌توانید به نقشه‌ی راه ما مراجعه کنید.

\n
\n

نکته:

\n

React.lazy() و <React.Suspense> هنوز توسط ReactDOMServer پشتیبانی نمی‌شوند. این یک محدودیت شناخته شده است که در آینده برطرف خواهد شد.

\n
","frontmatter":{"title":"API سطح بالای React","next":null,"prev":null},"fields":{"path":"content/docs/reference-react.md","slug":"docs/react-api.html"}}},"pageContext":{"slug":"docs/react-api.html"}},"staticQueryHashes":[]}