类型参考
React 导出了一些工具类型,在你输入高级 React 模式时可能对你有用。在前面的章节中我们已经看到了其中的一些。以下是每种类型的完整参考以及有关如何/在何处使用它们的一些示例。
¥React exports a handful of utility types that may be useful to you when typing advanced React patterns. In previous sections we have seen a few of them. The following is a complete reference for each of these types along with some examples for how/where to use them.
这些类型全部作为命名类型从 react
模块导出。如果你想将它们作为 React
对象上的成员进行访问(例如 React.Node
),并且你将 React 作为 ES 模块导入,那么你应该将 React
作为命名空间导入:
¥These types are all exported as named type exports from the react
module. If
you want to access them as members on the React
object (e.g.
React.Node
) and
you are importing React as an ES module then you should import React
as a
namespace:
import * as React from 'react';
如果你使用 CommonJS,你还可以要求 React:
¥If you are using CommonJS you can also require React:
const React = require('react');
你还可以在 ES 模块环境或 CommonJS 环境中使用命名类型导入:
¥You can also use named type imports in either an ES module environment or a CommonJS environment:
import type {Node} from 'react';
我们将在以下参考中引用所有类型,就像我们使用以下命令导入它们一样:
¥We will refer to all the types in the following reference as if we imported them with:
import * as React from 'react';
注意:使用默认导入导入 React 时:
¥Note: While importing React with a default import works:
import React from 'react';
你将可以访问 React 导出的所有值,但无法访问下面记录的类型!这是因为 Flow 不会将类型添加到默认导出,因为默认导出可以是任何值(例如数字)。Flow 会将导出的命名类型添加到 ES 命名空间对象中,你可以使用
import * as React from 'react'
获取该对象,因为 Flow 知道你是否导出与导出类型同名的值。¥You will have access to all of the values that React exports, but you will not have access to the types documented below! This is because Flow will not add types to a default export since the default export could be any value (like a number). Flow will add exported named types to an ES namespace object which you can get with
import * as React from 'react'
since Flow knows if you export a value with the same name as an exported type.同样,如果你使用以下命令导入 React:
import React from 'react'
你将能够访问React.Component
、React.createElement()
、React.Children
和其他 JavaScript 值。但是,你将无法访问React.Node
、React.ChildrenArray
或其他 Flow 类型。你将需要使用命名类型导入,例如:import type {Node} from 'react'
除了你的默认导入之外。¥Again, if you import React with:
import React from 'react'
you will be able to accessReact.Component
,React.createElement()
,React.Children
, and other JavaScript values. However, you will not be able to accessReact.Node
,React.ChildrenArray
or other Flow types. You will need to use a named type import like:import type {Node} from 'react'
in addition to your default import.
React.Node
这代表可以在 React 应用中渲染的任何节点。React.Node
可以是 null、布尔值、数字、字符串、React 元素或任何这些类型的递归数组。
¥This represents any node that can be rendered in a React application.
React.Node
can be null, a boolean, a number, a string, a React
element, or an array of any of those types recursively.
React.Node
是一个很好的默认值,可用于注释函数组件和类渲染方法的返回类型。你还可以使用它来键入组件作为子组件接收的元素。
¥React.Node
is a good default to use to annotate the return type of a function component
and class render methods. You can also use it to type elements your component takes in as children.
以下是 React.Node
用作函数组件的返回类型的示例:
¥Here is an example of React.Node
being used as the return type to a function component:
function MyComponent(props: {}): React.Node {
// ...
}
它也可以用作 render
类方法的返回类型:
¥It may also be used as the return type of a class render
method:
class MyComponent extends React.Component<{}> {
render(): React.Node {
// ...
}
}
以下是 React.Node
作为子项 prop 类型的示例:
¥Here is an example of React.Node
as the prop type for children:
function MyComponent({ children }: { children: React.Node }) {
return <div>{children}</div>;
}
所有 react-dom
JSX 内在函数都将 React.Node
作为其子类型。<div>
、<span>
以及所有其他的。
¥All react-dom
JSX intrinsics have React.Node
as their children type.
<div>
, <span>
, and all the rest.
React.MixedElement
所有 React 元素中最通用的类型(类似于所有值的 mixed
)。
¥The most general type of all React elements (similar to mixed
for all values).
这种类型的一个常见用例是当我们想要使用隐藏元素详细信息的类型来注释元素时。例如
¥A common use case of this type is when we want to annotate an element with a type that hides the element details. For example
const element: React.MixedElement = <div />;
React.ChildrenArray<T>
React 子数组可以是单个值或嵌套到任何级别的数组。它设计用于与 React.Children
API 一起使用。
¥A React children array can be a single value or an array nested to any level.
It is designed to be used with the React.Children
API.
例如,如果你想从 React.ChildrenArray<T>
获取普通的 JavaScript 数组,请参见以下示例:
¥For example if you want to get a normal JavaScript array from a
React.ChildrenArray<T>
see the following example:
import * as React from 'react';
// A children array can be a single value...
const children: React.ChildrenArray<number> = 42;
// ...or an arbitrarily nested array.
const children: React.ChildrenArray<number> = [[1, 2], 3, [4, 5]];
// Using the `React.Children` API can flatten the array.
const array: Array<number> = React.Children.toArray(children);
React.AbstractComponent<Config, Instance, Renders>
在 Flow v0.243.0+ 中,请考虑使用 组件类型,这将使你更容易将 Flow 代码迁移到 React 19。
¥In Flow v0.243.0+, consider using Component Types instead, which will make it easier to migrate your Flow code to React 19.
React.AbstractComponent<Config, Instance, Renders>
表示具有 Config 类型配置和 Instance 类型实例的组件,该组件渲染 Renders 类型的内容。
¥React.AbstractComponent<Config, Instance, Renders>
represents a component with
a config of type Config and instance of type Instance that renders something of type Renders.
组件的 Config
是你需要传递给 JSX 的对象类型,以便使用该组件创建元素。组件的 Instance
是写入到传递到 JSX 中 ref
属性的 ref 对象的 current
字段中的值的类型。Renders
是 组件语法 的一项功能,允许你指定组件通过 渲染类型 渲染的内容
¥The Config
of a component is the type of the object you need to pass in to JSX in order
to create an element with that component. The Instance
of a component is the type of the value
that is written to the current
field of a ref object passed into the ref
prop in JSX.
Renders
is a Component Syntax feature that allows you to specify what your
component renders via Render Types
Config 是必需的,但 Instance 是可选的,默认为混合,Renders 是可选的,默认为 React.Node。
¥Config is required, but Instance is optional and defaults to mixed and Renders is optional and defaults to React.Node.
具有配置 Config
的类或函数组件可以用在需要 React.AbstractComponent<Config>
的地方。
¥A class or function component with config Config
may be used in places that expect
React.AbstractComponent<Config>
.
这是 Flow 对 React 组件最抽象的表示,对于编写 HOC 和库定义最有用。
¥This is Flow's most abstract representation of a React component, and is most useful for writing HOCs and library definitions.
React.ComponentType<Config>
这与 React.AbstractComponent
相同,但仅指定第一个类型参数。
¥This is the same as React.AbstractComponent
, but only specifies the first type argument.
React.ElementType
与 React.AbstractComponent<Props>
类似,但它还包含 JSX 内在函数(字符串)。
¥Similar to React.AbstractComponent<Props>
except it also
includes JSX intrinsics (strings).
React.ElementType
的定义大致为:
¥The definition for React.ElementType
is roughly:
type ElementType =
| string
| React.AbstractComponent<empty, mixed, React.Node>;
React.Key
React 元素上 key prop 的类型。它是字符串和数字的联合,定义为:
¥The type of the key prop on React elements. It is a union of strings and numbers defined as:
type Key = string | number;
React.Ref<typeof Component>
React 元素上的 ref 属性 的类型。React.Ref<typeof Component>
可以是字符串、ref 对象或 ref 函数。
¥The type of the ref prop on React elements. React.Ref<typeof Component>
could be a string, ref object, or ref function.
ref 函数将采用一个且唯一的参数,该参数将是使用 React.ElementRef<typeof Component>
或自 React 在卸载时会将 null 传递给 ref 函数 以来的 null 检索的元素实例。
¥The ref function will take one and only argument which will be the element
instance which is retrieved using
React.ElementRef<typeof Component>
or null since
React will pass null into a ref function when unmounting.
与 React.Element<typeof Component>
一样,typeof Component
必须是 React 组件的类型,因此你需要像 React.Ref<typeof MyComponent>
一样使用 typeof
。
¥Like React.Element<typeof Component>
, typeof Component
must be the type of a React component so you need to use typeof
as in
React.Ref<typeof MyComponent>
.
React.Ref<typeof Component>
的定义大致为:
¥The definition for React.Ref<typeof Component>
is roughly:
type Ref<C> =
| string
| (instance: React.ElementRef<C> | null) => mixed;
| { -current: React$ElementRef<ElementType> | null, ... }
React.PropsOf<Component>
当使用 组件语法 编写 Component
时,React.PropsOf<Component>
为你提供一个对象的类型,你必须传入该对象类型才能使用 JSX 实例化 Component
。重要的是,具有默认值的 props 在结果类型中是可选的。
¥When Component
is written using Component Syntax, React.PropsOf<Component>
gives you the type of an object that you must pass in to instantiate Component
with JSX.
Importantly, the props with defaults are optional in the resulting type.
例如:
¥For example:
1import * as React from 'react';2
3component MyComponent(foo: number, bar: string = 'str') {4 return null;5}6
7// Only foo is required8({foo: 3}) as React.ElementConfig<typeof MyComponent>;
React.ElementConfig<typeof Component>
与 React.PropsOf 一样,此实用程序获取必须传递给组件的对象的类型,以便通过 createElement()
或 jsx()
实例化它。PropsOf
接受组件的元素,这在使用 组件语法 时很方便,而 ElementConfig
则接受组件的类型。typeof Component
必须是 React 组件的类型,因此你需要像 React.ElementConfig<typoef Component>
一样使用 typeof
。
¥Like React.PropsOf, this utility gets the type of the object that you must pass in to a
component in order to instantiate it via createElement()
or jsx()
. While PropsOf
takes in an element of
a component, which is convenient when using Component Syntax, ElementConfig
takes in the type of a component
instead. typeof Component
must be the type of a React component so you need to use typeof
as in
React.ElementConfig<typoef Component>
.
重要的是,具有默认值的 props 在结果类型中是可选的。
¥Importantly, props with defaults are optional in the resulting type.
例如,
¥For example,
import * as React from 'react';
class MyComponent extends React.Component<{foo: number}> {
static defaultProps = {foo: 42};
render() {
return this.props.foo;
}
}
// `React.ElementProps<>` requires `foo` even though it has a `defaultProp`.
({foo: 42}) as React.ElementProps<typeof MyComponent>;
// `React.ElementConfig<>` does not require `foo` since it has a `defaultProp`.
({}) as React.ElementConfig<typeof MyComponent>;
与 React.Element<typeof Component>
一样,typeof Component
必须是 React 组件的类型,因此你需要像 React.ElementProps<typeof MyComponent>
一样使用 typeof
。
¥Like React.Element<typeof Component>
, typeof Component
must be the
type of a React component so you need to use typeof
as in
React.ElementProps<typeof MyComponent>
.
React.ElementProps<typeof Component>
注意:因为
React.ElementProps
不保留defaultProps
的可选性,所以React.ElementConfig
(保留)通常是正确的选择,特别是对于像 高阶分量 这样的简单属性传递。你可能不应该使用 ElementProps。¥Note: Because
React.ElementProps
does not preserve the optionality ofdefaultProps
,React.ElementConfig
(which does) is more often the right choice, especially for simple props pass-through as with higher-order components. You probably should not use ElementProps.
获取 React 元素类型的 props,而不保留 defaultProps
的可选性。typeof Component
可以是 React 类组件、函数组件或 JSX 内部字符串的类型。此类型用于 React.Element<typeof Component>
上的 props
属性。
¥Gets the props for a React element type, without preserving the optionality of defaultProps
.
typeof Component
could be the type of a React class component, a function component, or a JSX intrinsic string.
This type is used for the props
property on React.Element<typeof Component>
.
与 React.Element<typeof Component>
一样,typeof Component
必须是 React 组件的类型,因此你需要像 React.ElementProps<typeof MyComponent>
一样使用 typeof
。
¥Like React.Element<typeof Component>
, typeof Component
must be the
type of a React component so you need to use typeof
as in
React.ElementProps<typeof MyComponent>
.
React.RefOf<Component>
使用 组件语法 时,React.RefOf<Component>
将为你提供组件 ref
属性上 current
字段的类型。如果组件上没有 ref
属性,它将返回 void
。
¥When using Component Syntax, React.RefOf<Component>
will give you
the type of the current
field on the ref
prop of the component. If there is no ref
prop
on the component it will return void
.
React.ElementRef<typeof Component>
获取 React 元素的实例类型。对于不同的组件类型,实例会有所不同:
¥Gets the instance type for a React element. The instance will be different for various component types:
React.AbstractComponent<Config, Instance> 将返回 Instance 类型。
¥React.AbstractComponent<Config, Instance> will return the Instance type.
React 类组件将是类实例。因此,如果你有
class Foo extends React.Component<{}> {}
并使用React.ElementRef<typeof Foo>
,那么该类型将是Foo
的实例。¥React class components will be the class instance. So if you had
class Foo extends React.Component<{}> {}
and usedReact.ElementRef<typeof Foo>
then the type would be the instance ofFoo
.React 函数组件没有支持实例,因此
React.ElementRef<typeof Bar>
(当Bar
是function Bar() {}
时)将为你提供 void 类型。¥React function components do not have a backing instance and so
React.ElementRef<typeof Bar>
(whenBar
isfunction Bar() {}
) will give you the void type.像
div
这样的 JSX 内在函数会给你他们的 DOM 实例。对于React.ElementRef<'div'>
,则为HTMLDivElement
。对于React.ElementRef<'input'>
,则为HTMLInputElement
。¥JSX intrinsics like
div
will give you their DOM instance. ForReact.ElementRef<'div'>
that would beHTMLDivElement
. ForReact.ElementRef<'input'>
that would beHTMLInputElement
.
与 React.Element<typeof Component>
一样,typeof Component
必须是 React 组件的类型,因此你需要像 React.ElementRef<typeof MyComponent>
一样使用 typeof
。
¥Like React.Element<typeof Component>
, typeof Component
must be the
type of a React component so you need to use typeof
as in
React.ElementRef<typeof MyComponent>
.
React.Config<Props, DefaultProps>
根据 props 和默认 props 计算配置对象。这对于注释通过配置抽象的 HOC 最有用。请参阅我们的 有关编写 HOC 的文档 了解更多信息。
¥Calculates a config object from props and default props. This is most useful for annotating HOCs that are abstracted over configs. See our docs on writing HOCs for more information.
ExactReactElement_DEPRECATED<typeof Component>
这是自 0.245 以来已删除的 'React.Element' 类型的精确替换。你应该改用 React.MixedElement
或 React.Node
。如果要强制执行设计系统约束,请改用 渲染类型。
¥This is an exact replacement of the removed 'React.Element' type since 0.245.
You should use React.MixedElement
or React.Node
instead.
If you want to enforce design system constraints, use render types instead.
React 元素是 JSX 元素值的类型:
¥A React element is the type for the value of a JSX element:
const element: ExactReactElement_DEPRECATED<'div'> = <div />;
ExactReactElement_DEPRECATED<typeof Component>
也是 React.createElement()
/React.jsx()
的返回类型。
¥ExactReactElement_DEPRECATED<typeof Component>
is also the return type of
React.createElement()
/React.jsx()
.
ExactReactElement_DEPRECATED
采用单一类型参数 typeof Component
。typeof Component
是 React 元素的组件类型。对于内在元素,typeof Component
将是你使用的内在元素的字符串字面量。以下是 DOM 内在函数的一些示例:
¥A ExactReactElement_DEPRECATED
takes a single type argument,
typeof Component
. typeof Component
is the component type of the React
element. For an intrinsic element, typeof Component
will be the string literal
for the intrinsic you used. Here are a few examples with DOM intrinsics:
<div /> as ExactReactElement_DEPRECATED<'div'>; // OK
<span /> as ExactReactElement_DEPRECATED<'span'>; // OK
<div /> as ExactReactElement_DEPRECATED<'span'>; // Error: div is not a span.
typeof Component
也可以是你的 React 类组件或函数组件。
¥typeof Component
can also be your React class component or function component.
function Foo(props: {}) {}
class Bar extends React.Component<{}> {}
<Foo /> as ExactReactElement_DEPRECATED<typeof Foo>; // OK
<Bar /> as ExactReactElement_DEPRECATED<typeof Bar>; // OK
<Foo /> as ExactReactElement_DEPRECATED<typeof Bar>; // Error: Foo is not Bar
记下 typeof
,这是必填项!我们想要获取值 Foo
的类型。Foo as Foo
是一个错误,因为 Foo
不能用作类型,所以以下是正确的:Foo as typeof Foo
。
¥Take note of the typeof
, it is required! We want to get the
type of the value Foo
. Foo as Foo
is an error because Foo
cannot be used
as a type, so the following is correct: Foo as typeof Foo
.
没有 typeof
的 Bar
将是 Bar
实例的类型:new Bar() as Bar
。我们想要 Bar
的类型而不是 Bar
实例的类型。Class<Bar>
也可以在这里使用,但我们更喜欢 typeof
,因为它与功能组件保持一致。
¥Bar
without typeof
would be the type of an instance of Bar
: new Bar() as Bar
.
We want the type of Bar
not the type of an instance of Bar
.
Class<Bar>
would also work here, but we prefer typeof
for consistency
with function components.