React TypeScript Cheatsheet 参考文档详解：ReactNode 类型完全指南

React TypeScript Cheatsheet 参考文档详解ReactNode 类型完全指南【免费下载链接】reactCheatsheets for experienced React developers getting started with TypeScript项目地址: https://gitcode.com/gh_mirrors/reactt/react-typescript-cheatsheetReactNode是 React TypeScript 开发中最常用也最容易被误用的类型之一。本文以官方参考文档 docs/reference/ReactNode.md 为主体系统讲解ReactNode的类型定义、联合成员、children标注、异步 Server Components 场景以及它与ReactElement、React.JSX.Element的区别并结合本仓库的实战文档与配置给出可直接落地的代码范式。读完本文你将能准确判断何时该用ReactNode、何时不该用并能在自己的组件库中写出类型正确的children接口。ReactNode 是什么React 可渲染内容的联合类型ReactNode是一个描述“React 可以渲染什么”的类型。它本质上是 React 接受作为children的所有合法值的联合类型。换句话说只要一个值能出现在 JSX 的{...}插值位置并被 React 渲染出来它就属于ReactNode。在 website/sidebars.json 中ReactNode与ComponentProps、CSSProperties、Ref一同被归入API ReferenceAPI 参考分类属于官方参考级文档定位是“按需查阅的类型速查”。ReactNode 的联合成员逐项解析根据参考文档ReactNode由以下成员构成成员说明ReactElementJSX、createElement或cloneElement的返回值即元素对象string字符串文本number数字bigint大整数booleantrue和false渲染时什么都不输出null渲染为空undefined渲染为空IterableReactNode可迭代对象因此既包含节点数组也包含任何可迭代结构ReactPortal通过createPortal创建的传送门PromiseReactNode异步 Server Components 的返回值——React 会通过 Suspense 解包 Promise这份清单揭示了几个容易被忽略的细节boolean、null、undefined都是合法的ReactNode。这是 React 渲染机制的约定条件渲染中{condition Component /}在condition为false时不会产生任何输出而类型层面这种写法恰好是合法的。IterableReactNode的覆盖面比“数组”更广。不仅是ReactNode[]任何实现Symbol.iterator的可迭代对象都在类型允许范围内。PromiseReactNode的加入是 React 19 时代异步渲染能力在类型层面的体现详见下文“异步 Server Components”一节。由于ReactNode是一组联合类型它天然具有“宽松”的特质凡是你能放进 JSX 花括号里的值几乎都能赋给ReactNode。参数说明ReactNode是一个不接受任何类型参数的类型别名。它不像React.ComponentPropsT见 docs/reference/ComponentProps.md那样是泛型工具类型因此使用时不需要、也不能传泛型参数import { ReactNode } from react; type R ReactNode; // ✅ 直接使用 // type R2 ReactNodestring; // ❌ ReactNode 不接受类型参数这一点也决定了它的使用方式它是“拿来即用”的收口类型而不是可扩展的加工工具。实战用 ReactNode 标注 childrenReactNode最常见的用途是标注children。参考文档给出的最小范式如下import { ReactNode } from react; interface Props { children?: ReactNode; } function Component({ children }: Props) { return children; }将children声明为ReactNode后Component就能接受 React 可以渲染的任何内容function Examples() { return ( Component divHello/div /Component ComponentHello/Component Component{123}/Component Component{42n}/Component Component Hello/ /Component Component{true}/Component Component{null}/Component Component{undefined}/Component Component{[1, 2, 3]}/Component / ); }注意上面示例中各种形态的合法传参元素、字符串、数字、大整数、Fragment、布尔值、null、undefined以及数组——它们全部能被children?: ReactNode接收这正是“接受一切 React 可渲染内容”的直观体现。children 相关的更多类型场景本仓库的实战文档 docs/basic/getting-started/basic-type-examples.md 在“Useful React Prop Type Examples”一节中也给出了权威建议export declare interface AppProps { children?: React.ReactNode; // best, accepts everything React can render childrenElement: React.JSX.Element; // A single React element }可以看到社区推荐在标注children时使用ReactNode接受一切可渲染内容而只有当确实需要一个单个元素时才使用React.JSX.Element。此外docs/basic/getting-started/patterns_by_usecase.md 展示了基于ReactNode的结构化 children 类型——你可以标注“一个孩子”或“一对孩子元组”type OneChild React.ReactNode; type TwoChildren [React.ReactNode, React.ReactNode]; type NumbersChildren number[]; type TwoNumbersChildren [number, number];同时该文档也提醒了一个无法做到的事情无法在类型层面限制“children 必须是某个具体组件”例如表达“Routes只能有Route子元素”。原因在于 JSX 表达式的产物类型会被收敛成通用的React.JSX.Element组件身份信息在类型系统中不可见。用 ReactNode 接收“元素或字符串”类的 label 属性不只是children凡是可能接收“元素、字符串或其他可渲染值”的 props 都适合用ReactNode。参考文档给出type Props { content: ReactNode }; MyComponent contenthello / // ✅ string 是 ReactNode MyComponent content{spanhi/span} / // ✅ element 是 ReactNode MyComponent content{null} / // ✅ null 是 ReactNode仓库 docs/basic/getting-started/patterns_by_usecase.md 的 “Render Props” 一节也印证了这一用法——当你要写一个“能接收元素、字符串或其他内容作为 prop”的函数时最佳类型就是ReactNodeimport { ReactNode } from react; interface Props { label?: ReactNode; children?: ReactNode; } const Card ({ children, label }: Props) { return ( div {label div{label}/div} {children} /div ); };而函数作为 children 的 render prop 场景则不同——此时children是一个函数其返回类型才是ReactNodeimport { ReactNode } from react; interface Props { children: (foo: string) ReactNode; }异步 Server Components 与 PromiseReactNodeReactNode联合成员中的PromiseReactNode直接服务于 React 的异步渲染能力。参考文档给出了两种典型场景。场景一async Server ComponentServer Component 可以声明为async其返回值类型即为PromiseReactNode。React 会通过最近的Suspense边界解包这个 Promise// Server Component async function UserProfile({ userId }: { userId: string }) { const user await fetchUser(userId); return p{user.name}/p; } function Page() { return ( Suspense fallback{pLoading…/p} UserProfile userId42 / /Suspense ); }场景二裸 Promise 直接作为 children一个裸的PromiseReactNode也可以直接作为children传入这适合流式streaming渲染模式——父组件先发起异步工作子组件Suspense 边界负责等待结果function Page() { const userPromise fetchUser(); // PromiseReactNode return Suspense fallback{Loading /}{userPromise}/Suspense; }这种写法让“数据获取的发起”与“UI 的展示”解耦父组件不必先await再渲染而是把 Promise 交给 Suspense 边界去解包从而获得更早的渲染时机与更好的并发体验。ReactNode vs ReactElement vs JSX.Element这三个类型都出现在日常 JSX 编写中因此常被混淆但它们不可互换ReactNode范围最广——任何 React 能渲染的内容包括原始类型、null、数组和元素。ReactElement只描述 JSX 或createElement产生的对象——它带有type、props和key。一个string不是ReactElement。React.JSX.Element本质上就是ReactElementany, any——JSX 表达式由 JSX 转换推断出的产物类型。仓库 docs/basic/getting-started/basic-type-examples.md 引用了一条更技术性的解释来区分两者一个合法的 React 节点ReactNode并不等同于React.createElement的返回值。无论组件最终渲染成什么React.createElement总是返回一个对象即React.JSX.Element接口而React.ReactNode是组件所有可能返回值的集合。React.JSX.Element→React.createElement的返回值React.ReactNode→ 组件的返回值何时用 ReactNode 标注 children任何接收“类似 children 内容”的 props 都应用ReactNode标注因为调用方可能传入字符串、数组或null。这正是上文反复强调的用法type Props { content: ReactNode }; MyComponent contenthello / // ✅ string 是 ReactNode MyComponent content{spanhi/span} / // ✅ element 是 ReactNode MyComponent content{null} / // ✅ null 是 ReactNode何时不要用 ReactNode函数组件返回类型函数组件的返回类型应当反映 React 允许组件返回什么而不是允许组件接收什么。直接返回ReactNode它包含bigint、PromiseReactNode等范围过宽比 TypeScript 期望从 JSX 渲染组件中看到的类型要宽泛得多。参考文档明确建议让 TypeScript 自行推断返回类型如果必须显式标注使用React.JSX.Element或ReactElement// 范围过宽且在 JSX 中使用时历史上曾引发问题 const MyComponent (): ReactNode hello; // 让 TS 推断 const MyComponent () hello; // 显式标注 const MyComponent (): React.JSX.Element spanhello/span;这一建议与本仓库 README 中函数组件一节的做法一致——优先让返回类型被推断必要时才显式标注为React.JSX.Element// Easiest way to declare a Function Component; return type is inferred. const App ({ message }: AppProps) div{message}/div; // You can choose to annotate the return type so an error is raised if you accidentally return some other type const App ({ message }: AppProps): React.JSX.Element div{message}/div;仓库中的更多 ReactNode 实战印证除参考文档本身外本仓库的多个文档都在实际场景中运用了ReactNode可作为延伸阅读与印证条件 props 的重载组件docs/basic/getting-started/patterns_by_usecase.md 中基于truncate/expanded的组合使用函数重载实现“按 props 收窄类型”其中公共接口即用children?: ReactNode声明import { ReactNode } from react; interface CommonProps { children?: ReactNode; miscProps?: any; } type NoTruncateProps CommonProps { truncate?: false }; type TruncateProps CommonProps { truncate: true; expanded?: boolean }; // Function overloads to accept both prop types NoTruncateProps TruncateProps function Text(props: NoTruncateProps): React.JSX.Element; function Text(props: TruncateProps): React.JSX.Element; function Text(props: CommonProps { truncate?: boolean; expanded?: boolean }) { const { children, truncate, expanded, ...otherProps } props; const classNames truncate ? .truncate : ; return ( div className{classNames} aria-expanded{!!expanded} {...otherProps} {children} /div ); }注意这个例子同时展示了两种类型的正确分工props 接收侧用ReactNodechildren可接收一切可渲染内容组件返回侧用React.JSX.Element重载签名声明返回单个元素。泛型渲染列表组件同一文档中多个列表组件示例List、ListWithHook等都将renderItem: (item: T) ReactNode作为渲染函数类型同样是“函数返回ReactNode”的典型应用。与 ComponentProps 搭配使用参考文档 docs/reference/ComponentProps.md 中ComponentPropsdiv展开后同样包含children等合法 props可作为理解“元素 props 集合”的姊妹篇。小结ReactNode 使用决策速查场景推荐类型组件childrenpropsReactNode配合?可选可能接收“元素或字符串”的内容型 props如label、contentReactNoderender prop 函数children: (foo) ReactNode的返回类型ReactNode函数组件返回类型需显式标注时React.JSX.Element或ReactElement或干脆让 TS 推断单个元素 propsReact.JSX.Element一句话总结ReactNode用于“收”描述组件能接收什么ReactElement/React.JSX.Element用于“出”描述组件返回什么。在children与内容型 props 上放心使用ReactNode在函数组件返回类型上则交给 TypeScript 推断或使用React.JSX.Element。本文所引用的参考文档 docs/reference/ReactNode.md、实战文档 docs/basic/getting-started/basic-type-examples.md 与 docs/basic/getting-started/patterns_by_usecase.md 均可在仓库中继续查阅获得更多类型编排的完整示例。【免费下载链接】reactCheatsheets for experienced React developers getting started with TypeScript项目地址: https://gitcode.com/gh_mirrors/reactt/react-typescript-cheatsheet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考