Справочник типов React

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

Все эти типы экспортируются из модуля react как именованные экспорты типов. Если вы хотите обращаться к ним как к свойствам объекта React (например, React.Node) и импортируете React как ES-модуль, то можете импортировать React как пространство имён или как экспорт по умолчанию:

import * as React from 'react';


<div /> as React.MixedElement; // OK

import React from 'react';


<div /> as React.MixedElement; // OK

Если вы используете CommonJS, то также можете подключить React с помощью require:

const React = require('react');

В среде ES-модулей или CommonJS также можно использовать именованные импорты типов:

import type {Node} from 'react';

Типы содержимого​

Типы содержимого, которое компонент отображает или принимает в качестве дочерних элементов.

React.Node​

Этот тип представляет любой узел, который можно отобразить в приложении React. React.Node может быть undefined, null, логическим значением, числом, строкой, элементом React, порталом React или итерируемым объектом (включая массивы) из любых таких значений, возможно, вложенных друг в друга.

Чаще всего этот тип используется для описания типа children, который принимает компонент. В синтаксисе компонентов объявляйте children, как и любой другой параметр:

import * as React from 'react';


component MyComponent(children: React.Node) {
  return <div>{children}</div>;
}

У всех JSX-встроенных элементов react-dom тип дочерних элементов — React.Node: <div>, <span> и все остальные.

React.Node также удобно использовать по умолчанию для аннотации возвращаемого типа функционального компонента или метода render класса. (В синтаксисе компонентов этот возвращаемый тип выводится автоматически, поэтому указывать его не нужно.)

import * as React from 'react';


function MyComponent(props: {}): React.Node {
  return null;
}


class MyClassComponent extends React.Component<{}> {
  render(): React.Node {
    return null;
  }
}

React.MixedElement​

Наиболее общий тип всех элементов React (аналог unknown для любых значений).

В отличие от React.Node, React.MixedElement может представлять только один элемент. Он не включает строки, числа, массивы, null, undefined или false.

Этот тип часто используют, когда нужно аннотировать элемент типом, скрывающим подробности об элементе. Например:

import * as React from 'react';


const element: React.MixedElement = <div />;

Как выбрать между React.Node, renders и React.MixedElement​

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

• React.Node: любой контент, который можно отобразить (элементы, строки, числа, массивы, null, undefined, false). Используйте его для children, а также для любых свойств и возвращаемых значений, допускающих произвольное содержимое. Это тип по умолчанию.
• renders Foo: значение, которое отображает конкретный элемент Foo (или что-либо, отображающее Foo). Используйте его, если свойство должно принимать определённый элемент дизайн-системы, а не произвольное содержимое.
• React.MixedElement: ровно один элемент React, тип которого скрыт. В отличие от React.Node, этот тип не включает строки, числа, массивы, null, undefined или false. Используйте его, если нужен один элемент, но не важно, какой именно.

React.ChildrenArray<T>​

Массив дочерних элементов React может быть одиночным значением или массивом, вложенным на любую глубину. Он предназначен для использования с API React.Children.

Например, если вы хотите получить обычный массив JavaScript из React.ChildrenArray<T>, смотрите следующий пример:

import * as React from 'react';


// A children array can be a single value...
const childrenSingle: React.ChildrenArray<number> = 42;
// ...or an arbitrarily nested array.
const childrenNested: React.ChildrenArray<number> = [[1, 2], 3, [4, 5]];


// Using the `React.Children` API can flatten a single value into an array.
const array: Array<number> = React.Children.toArray(childrenSingle);

Типы компонентов и элементов​

Типы, описывающие компоненты, типы элементов и ключи элементов.

React.ComponentType<Props>​

Тип компонента, принимающего объект свойств Props. Он эквивалентен component(...Props) типа компонента:

import * as React from 'react';


type Props = {foo: number};


// `React.ComponentType<Props>` is equivalent to `component(...Props)`:
declare const a: React.ComponentType<Props>;
declare const b: component(...Props);


a as component(...Props); // OK
b as React.ComponentType<Props>; // OK

Значение React.ComponentType<Props> можно отобразить, передав ему ожидаемые свойства:

import * as React from 'react';


declare const Comp: React.ComponentType<{foo: number}>;


<Comp foo={3} />; // OK
<Comp />; // ERROR: `foo` is required

React.ElementType​

Похож на типы компонентов, но также включает JSX-встроенные элементы (строки).

Определение React.ElementType выглядит примерно так:

import * as React from 'react';


type ElementType =
  | string
  | React.ComponentType<empty>;

Он принимает как JSX-встроенные элементы, так и компоненты:

import * as React from 'react';


component Button() {
  return <button />;
}


const intrinsic: React.ElementType = 'div'; // OK: a JSX intrinsic
const custom: React.ElementType = Button; // OK: a component

React.Key​

Тип свойства key элементов React — объединение строк и чисел:

type Key = string | number;

Обычно нет необходимости указывать React.Key самостоятельно: key — это специальное свойство, обрабатываемое React и передаваемое непосредственно элементам (<Row key={id} />); оно встречается главным образом в собственных определениях типов React.

Типы ссылок ref​

Типы для работы со ссылками ref. Полное руководство см. в разделе «Ссылки ref».

React.RefObject<T>​

Тип значения, возвращаемого хуком useRef. Используйте его для аннотации всего, что хранит этот объект ref или принимает его.

import {useRef} from 'react';


declare class Dog {}
hook useRefDemo() {
  const ref: React.RefObject<?Dog> = useRef<?Dog>(null);
}

О том, как он используется с useRef, см. в разделе «Ссылки ref».

React.RefSetter<T>​

Общий тип свойства ref элементов React, а также тип, который следует указать для параметра ref компонента (например, component Foo(ref: React.RefSetter<T>)). React.RefSetter<T> принимает как объект ref со значением T | null, хранящимся в свойстве current, так и функцию ref (callback ref), принимающую T.

Укажите его для параметра ref компонента:

import * as React from 'react';


component TextInput(ref: React.RefSetter<HTMLInputElement>) {
  return <input ref={ref} />;
}

Функция ref принимает ровно один аргумент — экземпляр элемента, полученный с помощью React.ElementRef<typeof Component>, либо null, поскольку при размонтировании React передаёт null в функцию ref.

Определение React.RefSetter<T> выглядит примерно так:

type RefSetter<in T> =
  | { writeonly current: T | null, ... }
  | ((T | null) => unknown)
  | null
  | void;

Здесь in и writeonly — аннотации контравариантности, которые редко встречаются в повседневном коде.

О том, как принимать ссылку ref в компоненте, см. в разделе «Приём ссылки ref с помощью React.RefSetter».

React.RefOf<Component>​

При использовании синтаксиса компонентов React.RefOf<Component> возвращает тип поля current свойства ref компонента. Если у компонента нет свойства ref, будет возвращён тип void.

import * as React from 'react';


component TextInput(ref: React.RefSetter<HTMLInputElement>) {
  return <input ref={ref} />;
}


// Forward a ref of the same instance type that `TextInput` exposes.
component LabeledInput(ref: React.RefSetter<React.RefOf<TextInput>>) {
  return <TextInput ref={ref} />;
}

О том, как это связано со ссылками ref, см. в разделе «Вывод типов ссылок ref».

React.ElementRef<typeof Component>​

Получает тип экземпляра элемента React. Тип экземпляра зависит от типа компонента:

• component(ref: React.RefSetter<Instance>) вернёт тип Instance.
• Для классовых компонентов React это будет экземпляр класса. Например, если у вас есть class Foo extends React.Component<{}> {} и вы используете React.ElementRef<typeof Foo>, типом будет экземпляр Foo.
• У функциональных компонентов React нет базового экземпляра, поэтому React.ElementRef<typeof Bar> (когда Bar равен function Bar() {}) вернёт тип void.
• Для JSX-встроенных элементов, таких как div, будет возвращён их экземпляр DOM. Для React.ElementRef<'div'> это будет HTMLDivElement. Для React.ElementRef<'input'> это будет HTMLInputElement.

Обратите внимание: typeof Component должен быть типом компонента React, поэтому используйте typeof, как в React.ElementRef<typeof MyComponent>.

import * as React from 'react';


component TextInput(ref: React.RefSetter<HTMLInputElement>) {
  return <input ref={ref} />;
}


// The instance type a component exposes via its ref.
declare const instance: React.ElementRef<typeof TextInput>;
instance as HTMLInputElement | null; // OK


// For a JSX intrinsic you get the DOM instance directly.
declare const div: React.ElementRef<'div'>;
div as HTMLDivElement; // OK

О том, как это связано со ссылками ref, см. в разделе «Вывод типов ссылок ref».

Типы свойств​

Типы, позволяющие извлечь свойства, принимаемые компонентом.

React.PropsOf<Component>​

Если Component написан с использованием синтаксиса компонентов, React.PropsOf<Component> возвращает тип объекта, который необходимо передать, чтобы создать экземпляр Component с помощью JSX. Важно отметить, что в результирующем типе свойства со значениями по умолчанию являются необязательными.

Например:

import * as React from 'react';


component MyComponent(foo: number, bar: string = 'str') {
  return null;
}


// Only foo is required
({foo: 3}) as React.PropsOf<MyComponent>;

React.ElementConfig<typeof Component>​

Как и React.PropsOf, эта вспомогательная функция получает тип объекта, который необходимо передать компоненту для создания его экземпляра через createElement() или jsx(). В то время как PropsOf принимает элемент компонента, что удобно при использовании синтаксиса компонентов, ElementConfig принимает тип компонента. typeof Component должен быть типом компонента React, поэтому используйте typeof, как в React.ElementConfig<typeof Component>.

Важно отметить, что в результирующем типе свойства со значениями по умолчанию являются необязательными.

Например:

import * as React from 'react';


component MyComponent(foo: number = 42) {
  return foo;
}


// `React.ElementConfig<>` does not require `foo` since it has a default value.
({}) as React.ElementConfig<typeof MyComponent>;

Обратите внимание: typeof Component должен быть типом компонента React, поэтому используйте typeof, как в React.ElementConfig<typeof MyComponent>.

Устаревшие типы​

Типы, сохранённые для обратной совместимости. Предпочтительно использовать указанные ниже альтернативы.

ExactReactElement_DEPRECATED<typeof Component>​

Тип значения JSX-элемента, параметризованный типом компонента элемента. Также является возвращаемым типом React.createElement() / React.jsx().

import * as React from 'react';


const element: ExactReactElement_DEPRECATED<'div'> = <div />;

См. также​

• Вспомогательные типы — типы Flow общего назначения
• Обобщённые типы — многие типы React параметризованы обобщёнными типами