React API верхнього рівня

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

Огляд

Компоненти

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

• React.Component
• React.PureComponent

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

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

• React.memo

Створення React-елементів

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

• createElement()
• createFactory()

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

Трансформація елементів

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

• cloneElement()
• isValidElement()
• React.Children

Фрагменти

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

• React.Fragment

Довідки

• React.createRef
• React.forwardRef

Затримка

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

• React.lazy
• React.Suspense

Transitions

Transitions are a new concurrent feature introduced in React 18. They allow you to mark updates as transitions, which tells React that they can be interrupted and avoid going back to Suspense fallbacks for already visible content.

• React.startTransition
• React.useTransition

Хуки

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

• Основні хуки

  • useState
  • useEffect
  • useContext

• Додаткові хуки

  • useReducer
  • useCallback
  • useMemo
  • useRef
  • useImperativeHandle
  • useLayoutEffect
  • useDebugValue
  • useDeferredValue
  • useTransition
  • useId

• Library Hooks

  • useSyncExternalStore
  • useInsertionEffect

Довідка

React.Component

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

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

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

React.PureComponent

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

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

Примітка

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

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

React.memo

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

React.memo є компонентом вищого порядку.

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

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

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

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

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

Примітка

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

createElement()

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

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

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

cloneElement()

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

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

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

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

Проте, він також зберігає посилання. Це означає, що якщо ви отримаєте потомка з атрибутом ref, ви не зможете випадково вкрасти його у свого предка. Ви отримаєте той самий ref, доданий до вашого нового елемента. The new ref or key will replace old ones if present.

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

createFactory()

React.createFactory(type)

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

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

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

isValidElement()

React.isValidElement(object)

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

React.Children

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

React.Children.map

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

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

Примітка

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

React.Children.forEach

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

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

React.Children.count

React.Children.count(children)

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

React.Children.only

React.Children.only(children)

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

Примітка:

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

React.Children.toArray

React.Children.toArray(children)

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

Примітка:

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

React.Fragment

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

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

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

React.createRef

React.createRef створює посилання, яке може бути додане до елемента React через ref атрибут.

class MyComponent extends React.Component {
  constructor(props) {
    super(props);

    this.inputRef = React.createRef();  }

  render() {
    return <input type="text" ref={this.inputRef} />;  }

  componentDidMount() {
    this.inputRef.current.focus();  }
}

React.forwardRef

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

• Передавання посилань DOM компонентам
• Передавання посилань у компоненти вищого порядку

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

const FancyButton = React.forwardRef((props, ref) => (  <button ref={ref} className="FancyButton">    {props.children}
  </button>
));

// You can now get a ref directly to the DOM button:
const ref = React.createRef();
<FancyButton ref={ref}>Click me!</FancyButton>;

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

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

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

React.lazy

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

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

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

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

React.Suspense

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() використовувати всюди, де ви хочете розділити код.

Note

For content that is already shown to the user, switching back to a loading indicator can be disorienting. It is sometimes better to show the “old” UI while the new UI is being prepared. To do this, you can use the new transition APIs startTransition and useTransition to mark updates as transitions and avoid unexpected fallbacks.

React.Suspense in Server Side Rendering

During server side rendering Suspense Boundaries allow you to flush your application in smaller chunks by suspending. When a component suspends we schedule a low priority task to render the closest Suspense boundary’s fallback. If the component unsuspends before we flush the fallback then we send down the actual content and throw away the fallback.

React.Suspense during hydration

Suspense boundaries depend on their parent boundaries being hydrated before they can hydrate, but they can hydrate independently from sibling boundaries. Events on a boundary before it is hydrated will cause the boundary to hydrate at a higher priority than neighboring boundaries. Read more

React.startTransition

React.startTransition(callback)

React.startTransition lets you mark updates inside the provided callback as transitions. This method is designed to be used when React.useTransition is not available.

Примітка:

Updates in a transition yield to more urgent updates such as clicks.

Updates in a transition will not show a fallback for re-suspended content, allowing the user to continue interacting while rendering the update.

React.startTransition does not provide an isPending flag. To track the pending status of a transition see React.useTransition.