Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
361 lines (241 sloc) 22.9 KB
id title layout category permalink redirect_from
react-api
React API верхнього рівня
docs
Reference
docs/react-api.html
docs/reference.html
docs/clone-with-props.html
docs/top-level-api.html
docs/top-level-api-ja-JP.html
docs/top-level-api-ko-KR.html
docs/top-level-api-zh-CN.html

React є точкою входу у бібліотеку React. Якщо ви завантажуєте React з тега <script>, API верхнього рівня доступні в глобальному об'єкті React. Якщо ви використовуєте ES6 разом із npm, ви можете написати import React from 'react', якщо ES5 -- var React = require('react').

Огляд {#overview}

Компоненти {#components}

React-компоненти дозволяють розділити інтерфейс користувача на незалежні частини, які можна використовувати повторно та працювати з кожною окремо. Компоненти у React можуть бути визначені за допомогою підкласу React.Component або React.PureComponent.

Якщо ви не використовуєте ES6 класи, замість них ви можете використовувати модуль create-react-class. Для додаткової інформації, читайте Використання React без ES6.

React-компоненти також можуть бути визначені як функції, що обгорнуті у:

Створення React-елементів {#creating-react-elements}

Ми рекомендуємо використання JSX для опису того, як повинен виглядати ваш інтерфейс користувача. Кожен JSX-елемент — це просто синтаксичний цукор для виклику React.createElement(). Вам не доведеться використовувати наступні методи безпосередньо, якщо ви використовуєте JSX.

Для додаткової інформації, дивіться Використання React без JSX.

Трансформація елементів {#transforming-elements}

React надає декілька API для маніпулювання елементами:

Фрагменти {#fragments}

React також надає компонент для рендерингу множини елементів без обгортки.

Довідки {#refs}

Затримка {#suspense}

Затримка дозволяє компонентам "почекати" чого-небудь перед рендерингом. На даний час існує тільки один спосіб використання затримки: динамічне завантаження компонентів із React.lazy. В майбутньому варіантів застосування затримки стане більше, наприклад, вибірка даних.

Хуки {#hooks}

Хуки є новим доповненням у React 16.8. Вони дозволяють вам використовувати стан та інші React особливості без написання класу. Хукам присвячено секцію в документації та окремий API довідник:


Довідка {#reference}

React.Component {#reactcomponent}

React.Component є базовим класом для React-компонентів, коли вони визначені за допомогою ES6 класів:

class Greeting extends React.Component {
  render() {
    return <h1>Привіт, {this.props.name}</h1>;
  }
}

Дивіться довідник React.Component API для пошуку методів та властивостей, що пов'язані із базовим класом React.Component.


React.PureComponent {#reactpurecomponent}

React.PureComponent подібний до React.Component. Різниця між ними тільки в тому, що React.Component не реалізує shouldComponentUpdate(), а React.PureComponent реалізує його через поверхове порівняння пропсів та стану.

Якщо метод render() компонента React відображає той самий результат з тими самими пропсами та станом, ви можете використовувати React.PureComponent для підвищення продуктивності у деяких випадках.

Примітка

Метод shouldComponentUpdate() класу React.PureComponent тільки поверхово порівнює об'єкти. Якщо вони містять складні структури даних, це може призвести до помилкових спрацьовувань під час більш глибокого порівняння. Розширюйте PureComponent тільки тоді, коли ви очікуєте на прості пропси та стан, або використовуйте forceUpdate(), коли ви знаєте, що структури даних змінилися. Або розгляньте можливісь застосування незмінних об'єктів для спрощення швидкого порівняння вкладених даних.

Крім того, метод shouldComponentUpdate() класу React.PureComponent пропускає оновлення пропсів для всього піддерева компоненту. Впевніться, що всі дочірні компоненти також "чисті".


React.memo {#reactmemo}

const MyComponent = React.memo(function MyComponent(props) {
  /* рендер з використанням пропсів */
});

React.memo є компонентом вищого порядку. Він подібний до React.PureComponent, але застосовується для компонентів-функцій, а не класів.

Якщо ваш компонент-функція відображає той самий результат з тими самими пропсами та станом, ви можете обгорнути його у виклик React.memo для підвищення продуктивності в деяких випадках шляхом запам'ятовування результату. Це означає, що React пропустить рендеринг компоненту та повторно використає останній результат рендерингу.

За замовчуванням він тільки поверхово порівнює складні об'єкти, що знаходяться в об'єкті пропсів. Якщо ви хочете контролювати процес порівняння, ви також можете надати користувальницьку функцію для порівняння помістивши її другим аргументом.

function MyComponent(props) {
  /* рендер з використанням пропсів */
}
function areEqual(prevProps, nextProps) {
  /*
  повертає true, якщо передавання nextProps для рендерингу
  поверне той самий результат, що і передавання prevProps,
  інакше повертає false
  */
}
export default React.memo(MyComponent, areEqual);

Цей метод існує тільки для оптимізації продуктивності. Не покладайтеся на нього, щоб "запобігти" рендерингу, бо це може призвести до помилок.

Примітка

На відміну від методу shouldComponentUpdate() для компонентів-класів, функція areEqual повертає true, якщо пропси рівні і false, якщо пропси не рівні. Це інверсія shouldComponentUpdate.


createElement() {#createelement}

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

Створює та повертає новий React-елемент вказаного типу. Аргумент типу може бути або рядком тегу (наприклад, 'div' або 'span'), або типом компоненту React (клас чи функція), або фрагментом React.

Код написаний за допомогою JSX буде конвертований у виклики React.createElement(). Зазвичай ви не викликаєте React.createElement() безпосередньо, коли використовуєте JSX. Для того, щоб дізнатися більше, читайте React без JSX.


cloneElement() {#cloneelement}

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

Клонує та повертає новий елемент React, використовуючи element як зразок. Отриманий елемент буде містити пропси оригінального елемента з новими властивостями, об'єднаними поверхово. Нові потомки замінять існуючих. key і ref з оригінального елемента будуть збережені.

React.cloneElement() майже рівнозначний:

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

Проте, він також зберігає посилання. Це означає, що якщо ви отримаєте потомка з атрибутом ref, ви не зможете випадково вкрасти його у свого предка. Ви отримаєте той самий ref, доданий до вашого нового елемента.

Цей API був впроваджений як заміна застарілого React.addons.cloneWithProps().


createFactory() {#createfactory}

React.createFactory(type)

Повертає функцію, яка створює React-елементи вказаного типу. Подібно до React.createElement(), аргумент типу може бути або рядком тегу (наприклад, 'div' або 'span'), або типом компоненту React (клас чи функція), або фрагментом React.

Цей помічник вважається застарілим, тому ми рекомендуємо використовувати або JSX, або безпосередньо React.createElement().

Зазвичай ви не викликаєте React.createFactory() безпосередньо, коли використовуєте JSX. Для того, щоб дізнатися більше, дивіться React без JSX.


isValidElement() {#isvalidelement}

React.isValidElement(object)

Перевіряє чи об'єкт є елементом React. Повертає true або false.


React.Children {#reactchildren}

React.Children надає утиліти для роботи з непрозорою структурою даних this.props.children.

React.Children.map {#reactchildrenmap}

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

Викликає функцію для кожного дочірнього елемента, що міститься в children із this встановленим у thisArg. Якщо children є масивом, він буде пройдений та функція виконається для кожного його елемента. Якщо children дорівнює null або undefined, функція поверне null або undefined, а не масив.

Примітка

Якщо children — це компонент Fragment, він буде розглядатися як один потомок і не буде пройдений.

React.Children.forEach {#reactchildrenforeach}

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

Подібний до React.Children.map(), але не повертає масив.

React.Children.count {#reactchildrencount}

React.Children.count(children)

Повертає загальну кількість компонентів у children, що дорівнює кількості викликів функції зворотнього виклику, яка передана у map чи forEach.

React.Children.only {#reactchildrenonly}

React.Children.only(children)

Перевіряє чи children має тільки один дочірній елемент (React-елемент) і повертає його. В іншому випадку цей метод спричиняє помилку.

Примітка:

React.Children.only() не приймає значення, яке повертає метод React.Children.map(), бо воно є масивом, а не елементом React.

React.Children.toArray {#reactchildrentoarray}

React.Children.toArray(children)

Повертає непрозору структуру даних children як плоский масив з ключами, призначеними для кожного потомка. Це корисно, якщо ви хочете маніпулювати колекціями потомків у ваших рендер-методах, особливо якщо ви хочете змінити порядок або обрізати this.props.children, перш ніж передавати його далі.

Примітка:

React.Children.toArray() змінює ключі для збереження семантики вкладених масивів під час вирівнювання списку потомків. Тобто, toArray додає префікс до кожного ключа у повернутому масиві, тому ключ кожного елемента охоплює вхідний масив, що його містить.


React.Fragment {#reactfragment}

Компонент React.Fragment доволяє вам повертати множину елементів у методі render() без створення додаткового DOM елемента:

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

Крім того, ви можете використовувати скорочений синтаксис <></>. Для отримання додаткової інформації, дивіться React v16.2.0: Покращена підтримка для фрагментів.

React.createRef {#reactcreateref}

React.createRef створює посилання, яке може бути додане до елемента React через ref атрибут. embed:16-3-release-blog-post/create-ref-example.js

React.forwardRef {#reactforwardref}

React.forwardRef створює React-компонент, що передає атрибут ref, який він отримав, іншому компоненту, розташованому нижче у дереві. Цей прийом не дуже поширений, але він особливо корисний у двох випадках:

React.forwardRef приймає рендер-функцію як аргумент. React викличе цю функцію з двома аргументами props і ref. Ця функція повинна повертати вузол React.

embed:reference-react-forward-ref.js

У прикладі вище, React передає посилання ref, передане елементу <FancyButton ref={ref}>, у рендер-функцію всередині виклику React.forwardRef в якості другого аргументу. Потім ця функція передає посилання ref у елемент <button ref={ref}>.

В результаті, коли React додасть посилання, ref.current буде посилатися беспосередньо на DOM елемент <button>.

Для отримання додаткової інформації, дивіться розділ про передавання посилань.

React.lazy {#reactlazy}

React.lazy() дає вам змогу визначити компонент, що динамічно завантажується. Це допомагає зменшити розмір бандлу шляхом затримки рендерингу компонентів, які не використовуються під час початкового рендерингу.

Більш детальіше ви можете дізнатися у розділі документації про розділення коду, а також прочитавши дану статтю.

// Цей компонент завантажується динамічно
const SomeComponent = React.lazy(() => import('./SomeComponent'));

Зверніть увагу, що рендеринг lazy компонентів потребує наявності компонента <React.Suspense>, розташованого вище у дереві рендерингу. Таким чином ви можете вказати індикатор завантаження.

Примітка

Використання React.lazy з динамічним імпортом вимагає підтримки промісів від вашого JS оточення. Для IE11 та нижче, потрібно використовувати polyfill.

React.Suspense {#reactsuspense}

React.Suspense дозволяє вам вказати індикатор завантаження у випадку, якщо деякі компоненти у дереві нижче ще не готові до рендерингу. Сьогодні, ледаче завантаження компонентів — це єдиний варіант використання, що підтримується <React.Suspense>:

// Цей компонент завантажується динамічно
const OtherComponent = React.lazy(() => import('./OtherComponent'));

function MyComponent() {
  return (
    // Відображає <Spinner> поки OtherComponent завантажується
    <React.Suspense fallback={<Spinner />}>
      <div>
        <OtherComponent />
      </div>
    </React.Suspense>
  );
}

Це задокументовано у розділі про розділення коду. Зауважте, що lazy компоненти можуть бути розташовані глибоко всередині дерева Suspense -- йому не обов'язково обгортати кожнен з них. Найкраще розміщувати <Suspense> там, де ви хочете бачити індикатор завантаження, але lazy() використовувати всюди, де ви хочете розділити код.

Хоча це і не підтримується на даний час, в майбутньому ми плануємо дати можливість Suspense обробляти більше сценаріїв, наприклад, вибірку даних. Ви можете прочитати про це у нашому плані дій.

Примітка:

ReactDOMServer не підтримує React.lazy() та <React.Suspense>. Це відоме обмеження буде вирішено в майбутньому.

You can’t perform that action at this time.