在iframe中渲染React组件时如何正确引用其本地document

问题 #

我有一个调用全局document对象的Modal组件，当在iframe中渲染该组件时，它引用的是父页面的document而非iframe的document，导致锁定滚动时影响的是父页面而非iframe内部。

Modal组件代码：

export const Modal: FC<ModalProps> = ({ opened, ...props }) => {
  // ...

  useEffect(() => {
    // 这里锁定的是主DOM的滚动，但我只想锁定iframe内部的滚动
    document.body.style.overflow = opened ? "hidden" : "";
  }, [opened]); 

  // ...
}

我使用自定义IFrame组件在独立iframe中渲染React元素，尝试过createPortal和直接创建根节点渲染，但都无法让Modal的document指向iframe的document：

import { FC, DetailedHTMLProps, IframeHTMLAttributes, useEffect, useMemo, useState } from "react";
import { createPortal } from "react-dom";

export const IFrame: FC<DetailedHTMLProps<IframeHTMLAttributes<HTMLIFrameElement>, HTMLIFrameElement>> = ({ children, style, ...props }) => {
  const [contentRef, setContentRef] = useState<HTMLIFrameElement | null>(null);
  const headNode = useMemo(() => contentRef?.contentWindow?.document?.head, [contentRef]);
  const mountNode = useMemo(() => contentRef?.contentWindow?.document?.body, [contentRef]);

  // 继承父页面样式
  useEffect(() => {
    if (headNode) {
      for (const style of Array.from(document.head.querySelectorAll("link"))) {
        headNode.appendChild(style.cloneNode(true));
      }
      for (const style of Array.from(document.head.querySelectorAll("style"))) {
        headNode.appendChild(style.cloneNode(true));
      }
    }
  }, [headNode]);

  return (
    <>
      <iframe
        {...props}
        style={{ border: "none", ...style }}
        ref={setContentRef}
      />
      {mountNode ? createPortal(children, mountNode) : null}
    </>
  );
});

也曾尝试直接在iframe的body创建根节点渲染：

useEffect(() => {
  if (mountNode) {
    const root = createRoot(mountNode);
    root.render(children);

    return () => {
      root.unmount();
    };
  }
}, [mountNode]);

return (
  <iframe
    {...props}     
    style={{ border: "none", ...style }}
    ref={setContentRef}
  />
);

请问如何让Modal组件的document指向iframe的document？

解决方案 #

方法1：通过React Context传递iframe的document #

这是最优雅的方案，既不需要大幅修改Modal核心逻辑，又能保证组件在iframe和非iframe环境下都能正常工作。

1. 创建DocumentContext和自定义Hook

import { createContext, useContext } from "react";

const DocumentContext = createContext<Document | null>(null);

export const useDocument = () => {
  // 优先使用Context提供的document， fallback到全局document
  const doc = useContext(DocumentContext);
  return doc || document;
};

2. 在IFrame组件中注入Context
   修改IFrame组件，用Context Provider包裹portal渲染的子元素，传入iframe的document：

// ... 其他导入
import { DocumentContext } from './DocumentContext';

export const IFrame: FC<DetailedHTMLProps<IframeHTMLAttributes<HTMLIFrameElement>, HTMLIFrameElement>> = ({ children, style, ...props }) => {
  const [contentRef, setContentRef] = useState<HTMLIFrameElement | null>(null);
  const iframeDoc = useMemo(() => contentRef?.contentWindow?.document, [contentRef]);
  const headNode = useMemo(() => iframeDoc?.head, [iframeDoc]);
  const mountNode = useMemo(() => iframeDoc?.body, [iframeDoc]);

  // ... 继承父页面样式的逻辑不变

  return (
    <>
      <iframe
        {...props}
        style={{ border: "none", ...style }}
        ref={setContentRef}
      />
      {mountNode && iframeDoc ? (
        <DocumentContext.Provider value={iframeDoc}>
          {createPortal(children, mountNode)}
        </DocumentContext.Provider>
      ) : null}
    </>
  );
});

3. 修改Modal组件使用自定义Hook
   把直接调用document的地方替换成useDocument()：

import { useDocument } from './DocumentContext';

export const Modal: FC<ModalProps> = ({ opened, ...props }) => {
  const doc = useDocument();

  useEffect(() => {
    doc.body.style.overflow = opened ? "hidden" : "";
  }, [opened, doc]); 

  // ...
}

方法2：给Modal组件添加自定义document属性 #

如果不想用Context，可以直接给Modal增加可选的document属性，让父组件传入iframe的document实例。

1. 更新ModalProps类型

interface ModalProps {
  opened: boolean;
  // 新增可选属性，允许传入自定义document
  document?: Document;
  // ... 其他原有属性
}

2. 调整Modal组件逻辑

export const Modal: FC<ModalProps> = ({ opened, document: customDoc, ...props }) => {
  // 优先使用传入的document，否则用全局document
  const doc = customDoc || document;

  useEffect(() => {
    doc.body.style.overflow = opened ? "hidden" : "";
  }, [opened, doc]); 

  // ...
}

3. 在IFrame中传入iframe的document
   修改IFrame组件支持回调式children，让子组件能拿到iframe的document：

// 修改IFrame的children类型为函数
export const IFrame: FC<DetailedHTMLProps<IframeHTMLAttributes<HTMLIFrameElement>, HTMLIFrameElement> & {
  children: (doc: Document | null) => React.ReactNode;
}> = ({ children, style, ...props }) => {
  const [contentRef, setContentRef] = useState<HTMLIFrameElement | null>(null);
  const iframeDoc = useMemo(() => contentRef?.contentWindow?.document, [contentRef]);
  const headNode = useMemo(() => iframeDoc?.head, [iframeDoc]);
  const mountNode = useMemo(() => iframeDoc?.body, [iframeDoc]);

  // ... 继承样式逻辑不变

  return (
    <>
      <iframe
        {...props}
        style={{ border: "none", ...style }}
        ref={setContentRef}
      />
      {mountNode ? createPortal(children(iframeDoc), mountNode) : null}
    </>
  );
});

使用时：

<IFrame>
  {(iframeDoc) => <Modal opened={true} document={iframeDoc} />}
</IFrame>

方法3：在iframe环境中重写全局document（不推荐） #

如果无法修改Modal组件代码，可以尝试在iframe的window中替换全局document，但这种方式风险较高，可能影响其他依赖全局document的组件，仅适合完全独立的iframe应用场景：

// 在IFrame组件的useEffect中添加
useEffect(() => {
  if (contentRef?.contentWindow) {
    // 仅在iframe内部的window中替换全局document
    contentRef.contentWindow.document = contentRef.contentWindow.document;
  }
}, [contentRef]);

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