React API верхнего уровня

React является точкой входа в библиотеку React. Если вы загружаете React из тега <script>, эти API верхнего уровня доступны в глобальной переменной React. Если вы используете ES6 с npm, вы можете написать import React from 'react'. Если вы используете ES5 с npm, вы можете написать 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

Suspense

Suspense позволяет компонентам «ждать» чего-либо перед рендерингом. Сегодня Suspense поддерживает только один случай использования: динамическую загрузку компонентов с помощью React.lazy. В будущем он будет поддерживать другие случаи использования, такие как получение данных.

• React.lazy
• React.Suspense

Хуксы

Хуксы — это новое дополнение в React 16.8. Они позволяют использовать состояние и другие функции React без написания класса. Хуксы имеют специальный раздел документации и отдельную справку по API:

• Основные хуки

  • useState
  • useEffect
  • useContext

• Дополнительные хуки

  • useReducer
  • useCallback
  • useMemo
  • useRef
  • useImperativeHandle
  • useLayoutEffect
  • useDebugValue

Справочник

React.Component

React.Component — это базовый класс для компонентов React, когда они определяются с помощью классов ES6:

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

Список методов и свойств, связанных с базовым классом React.Component, см. в справке по API React.Component.

React.PureComponent

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

Если функция рендеринга вашего компонента React возвращает одинаковый результат при одинаковых свойствах и состоянии, вы можете использовать React.PureComponent для повышения производительности в некоторых случаях.

Примечание

React.PureComponent's shouldComponentUpdate() сравнивает объекты только поверхностно. Если они содержат сложные структуры данных, это может привести к ложным отрицаниям для более глубоких различий. Наследуйте от PureComponent только тогда, когда ожидаются простые свойства и состояние, или используйте forceUpdate(), когда известно, что изменились глубокие структуры данных. Или, рассмотрите использование неизменяемых объектов для ускорения сравнения вложенных данных.

Кроме того, React.PureComponent's shouldComponentUpdate() пропускает обновления свойств для всего поддерева компонента. Убедитесь, что все дочерние компоненты также являются «чистыми».

React.memo

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

React.memo — это компонент высшего порядка.

Если ваш компонент возвращает одинаковый результат при одинаковых свойствах, вы можете обернуть его вызовом React.memo для повышения производительности в некоторых случаях, кэшируя результат. Это означает, что React пропустит рендеринг компонента и повторно использует последний рендеренный результат.

React.memo проверяет только изменения свойств. Если функциональный компонент, обернутый в React.memo имеет хук useState, useReducer или useContext, он все равно будет перерендерирован при изменении состояния или контекста.

По умолчанию он будет только поверхностно сравнивать сложные объекты в объекте свойств. Если вы хотите управлять сравнением, вы также можете предоставить пользовательскую функцию сравнения в качестве второго аргумента.

function MyComponent(props) {
  /* render using props */
}
function areEqual(prevProps, nextProps) {
  /*
  return true if passing nextProps to render would return
  the same result as passing prevProps to render,
  otherwise return 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 в качестве отправной точки. config должен содержать все новые свойства, key, или ref. Результирующий элемент будет иметь свойства исходного элемента со слитыми новыми свойствами поверхностно. Новые дочерние элементы заменят существующие. key и ref из исходного элемента сохранятся, если key и ref не присутствуют в config.

React.cloneElement() почти эквивалентно:

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

Однако он также сохраняет ref. Это означает, что если вы получите дочерний элемент с ref на нем, вы не случайно украдете его у предка. Вы получите тот же ref, прикрепленный к вашему новому элементу. Новые ref или key заменят старые, если присутствуют.

Этот 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 — это массив, он будет обработан, и функция будет вызвана для каждого дочернего элемента в массиве. Если 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, равное количеству вызовов callback-функции, переданной в 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, который передаёт атрибут ссылку, который он получает, другому компоненту ниже в дереве. Этот приём не очень распространён, но особенно полезен в двух сценариях:

• Передача ссылок на компоненты 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 будет указывать напрямую на экземпляр элемента <button> DOM.

Дополнительную информацию см. в передаче ссылок.

React.lazy

React.lazy() позволяет определить компонент, который загружается динамически. Это помогает уменьшить размер бандла, откладывая загрузку компонентов, которые не используются при первоначальном рендеринге.

Вы можете узнать, как его использовать, из нашей документации по разделению кода. Вы также можете ознакомиться со статьей об использовании его более подробно.

// This component is loaded dynamically
const SomeComponent = React.lazy(() => import('./SomeComponent'));

Обратите внимание, что рендеринг lazy компонентов требует наличия компонента <React.Suspense> выше в дереве рендеринга. Таким образом вы указываете индикатор загрузки.

Примечание

Использование React.lazy с динамическим импортом требует наличия Promises в среде JS. Это требует полифилла для IE11 и ниже.

React.Suspense

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

// This component is loaded dynamically
const OtherComponent = React.lazy(() => import('./OtherComponent'));

function MyComponent() {
  return (
    // Displays <Spinner> until OtherComponent loads
    <React.Suspense fallback={<Spinner />}>
      <div>
        <OtherComponent />
      </div>
    </React.Suspense>
  );
}

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

Хотя это не поддерживается сегодня, в будущем мы планируем позволить Suspense обрабатывать больше сценариев, таких как получение данных. Об этом вы можете прочитать в нашем плане развития.

Примечание:

React.lazy() и <React.Suspense> пока не поддерживаются ReactDOMServer. Это известное ограничение, которое будет устранено в будущем.