如何修复createPortal的TypeScript类型错误：children属性缺失

错误场景 #

当使用createPortal将元素挂载到document.body时，TypeScript抛出错误：

Property 'children' is missing in type 'ReactElement<any, string | JSXElementConstructor>' but required in type 'ReactPortal'.

即使使用<p>这类原生HTML元素也会触发该错误。

解决方案 #

1. 确保createPortal写法符合规范

createPortal的第一个参数必须是有效的React子元素（单个元素、多个元素用<>/<Fragment>包裹，或null），第二个参数是确定存在的DOM容器。

正确示例：

import { createPortal } from 'react';

function PortalContent() {
  // 安全检查：确保document.body存在
  if (!document.body) return null;

  return createPortal(
    // 单个原生元素作为子节点
    <p>这是通过Portal渲染的内容</p>,
    document.body
  );
}

如果需要渲染多个元素，用Fragment包裹：

return createPortal(
  <>
    <p>第一行内容</p>
    <p>第二行内容</p>
  </>,
  document.body! // 非空断言，适用于确定body一定存在的场景
);

2. 升级React类型定义版本

旧版本的@types/react可能存在类型推断bug，导致错误识别createPortal的返回值类型。执行以下命令升级到最新兼容版本：

# npm
npm install @types/react@latest --save-dev

# yarn
yarn add @types/react@latest --dev

3. 严格模式下的容器类型处理

如果你的TypeScript配置开启了strict: true，需要确保容器元素的类型不为null。可以通过useEffect延迟获取容器，避免初始渲染时的null值：

import { createPortal, useState, useEffect } from 'react';

function SafePortal() {
  const [portalContainer, setPortalContainer] = useState<HTMLElement | null>(null);

  useEffect(() => {
    setPortalContainer(document.body);
  }, []);

  // 容器未就绪时返回null
  if (!portalContainer) return null;

  return createPortal(
    <div>安全渲染的Portal内容</div>,
    portalContainer
  );
}

错误原因说明 #

该错误通常由以下情况导致：

• createPortal的第一个参数不是有效的React子元素（比如传入了非JSX值）
• 容器元素的类型可能为null，触发严格类型检查报错
• @types/react版本过时，类型定义与React核心库不匹配

内容的提问来源于stack exchange，提问作者Matt