React中iframe渲染HTMLDocument对象报错的原因及解决方案

问题描述 #

在React应用中，原本将服务器返回的HTML字符串传入<iframe>的srcDoc属性能正常展示内容，但改用DOMParser解析HTML字符串得到HTMLDocument对象后，把这个对象作为iframe的子元素传入时，抛出错误："Objects are not valid as a React child (found: [object HTMLDocument])"。相关代码如下：

setFile(new DOMParser().parseFromString(res.data, 'text/html'))
...
return render ? (
    <iframe width='800' height='800'>
      {file}
    </iframe>
): null

JSX渲染原始HTML的原理 #

JSX本质是React.createElement()的语法糖，React在渲染JSX时，仅能处理React元素、字符串、数字、null/undefined这类合法子节点类型：

• 直接用srcDoc传入HTML字符串时，这是利用了浏览器<iframe>的原生属性能力，React只需要把字符串传递给属性即可，不需要处理它的内容渲染。
• 而DOMParser.parseFromString()返回的是浏览器原生的HTMLDocument对象，不属于React能识别的合法子节点范畴。React无法将原生DOM对象转换为React可渲染的元素，因此会抛出“对象不能作为React子元素”的错误。

解决办法 #

办法1：继续使用srcDoc属性（最简便） #

既然原方案可用，没必要额外引入DOMParser，直接保留字符串传递给srcDoc即可：

setFile(res.data) // 直接存储服务器返回的HTML字符串
...
return render ? (
    <iframe width='800' height='800' srcDoc={file} />
): null

办法2：手动操作iframe的原生DOM（适合需修改HTML内容的场景） #

如果确实需要解析HTML并做自定义DOM修改后再渲染，可以通过useRef获取iframe实例，手动写入解析后的内容：

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

function IframeRenderer() {
  const [htmlStr, setHtmlStr] = useState('');
  const iframeRef = useRef(null);

  useEffect(() => {
    if (iframeRef.current && htmlStr) {
      const parsedDoc = new DOMParser().parseFromString(htmlStr, 'text/html');
      // 这里可以对parsedDoc做自定义DOM操作，比如修改节点内容、添加样式等
      iframeRef.current.contentDocument.replaceChildren(...parsedDoc.body.children);
    }
  }, [htmlStr]);

  // 假设这里通过接口请求获取res.data后执行setHtmlStr(res.data)

  return render ? (
    <iframe ref={iframeRef} width='800' height='800' />
  ) : null;
}

这种方式绕过React的JSX渲染限制，直接操作浏览器原生DOM，适合需要对HTML内容做定制化修改的场景。

注意事项 #

• 永远不要尝试把原生DOM对象直接作为JSX子元素传入，React不支持这种用法。
• 如果HTML内容涉及跨域，srcDoc可能存在浏览器限制，此时可以改用src属性指向服务器上的HTML文件地址。

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