react-three-fiber中如何从Canvas外部传送元素到Canvas内部？

已尝试的方案与报错 #

• 最初直接调用R3F的createPortal将mesh传入Canvas，运行时报错target element is not a DOM element，原因是R3F的场景对象不是真实DOM元素，无法被ReactDOM直接识别。
  初始尝试代码：

  import * as React from 'react'
  import { Canvas, createPortal } from '@react-three/fiber'
  
  export const Element = ({ parent }) => {
    return createPortal(
      <mesh>
        <boxGeometry args={[1, 1, 1]} />
        <meshStandardMaterial color="red" />
      </mesh>
    , parent);
  };
  
  export const MyPage = () => {
    const ref = React.useRef(null);
  
    return (
      <div>
        <Canvas>
          <group ref={ref} />
        </Canvas>
  
        <Element parent={ref.current} />
      </div>
    );
  };
  

• 后续尝试使用ReactDOM.createPortal实现，报错R3F hooks can only be used within the Canvas component!，原因是R3F的渲染依赖独立的自定义reconciler，只有Canvas内部的组件才能访问到Three.js场景上下文。
  该尝试代码：

  import * as ReactDOM from 'react-dom'
  import * as React from 'react'
  import { Canvas } from '@react-three/fiber'
  
  export const Element = ({ parent }) => {
    return ReactDOM.createPortal(
      <mesh>
        <boxGeometry args={[1, 1, 1]} />
        <meshStandardMaterial color="red" />
      </mesh>
    , parent);
  };
  
  export const MyPage = () => {
    const ref = React.useRef(null);
  
    return (
      <div>
        <Canvas>
          <group ref={ref} />
        </Canvas>
  
        <Element parent={ref.current} />
      </div>
    );
  };
  

• 尝试将createPortal逻辑包裹在额外的Canvas组件中，虽然可以实现传送效果，但存在明显缺陷：three.js对单页面Canvas实例数量存在限制，且冗余挂载无用Canvas节点的实现方式完全不适合生产环境。
  该无效方案代码：

  export const Element = ({ parent }) => {
     return (
      <Canvas>
        {createPortal(
          <mesh>
            <boxGeometry args={[1, 1, 1]} />
            <meshStandardMaterial color="blue" />
          </mesh>,
          portalTo
        )}
      </Canvas>
    );
  };
  

需求目标 #

实现挂载在根节点、尺寸适配整个文档的全局单Canvas，支持将项目任意位置定义的3D元素统一传送挂载到该Canvas场景中。

可行实现方案 #

R3F的createPortal必须在Canvas上下文内调用才能正常工作，不需要强行突破这个限制，通过上下文共享+动态元素注册表的方式就可以在不新增Canvas实例的前提下实现需求，所有portal调用最终都在全局Canvas内部完成，外部组件只负责传递要渲染的3D元素即可。

1. 封装全局单例Canvas与共享上下文

   import * as React from 'react'
   import { Canvas, createPortal } from '@react-three/fiber'
   
   // 全局3D元素注册上下文
   const Global3DContext = React.createContext({
     addElement: () => {},
     removeElement: () => {}
   })
   
   // 全局单例Canvas，挂载在应用根节点
   export const GlobalCanvas = ({ children, ...canvasProps }) => {
     const [elements, setElements] = React.useState([])
     const rootGroupRef = React.useRef(null)
   
     const registerApi = React.useMemo(() => ({
       addElement: (id, element, parent) => {
         setElements(prev => [...prev, { id, element, parent }])
       },
       removeElement: (id) => {
         setElements(prev => prev.filter(item => item.id !== id))
       }
     }), [])
   
     return (
       <Global3DContext.Provider value={registerApi}>
         <Canvas {...canvasProps}>
           <group ref={rootGroupRef} />
           {/* Canvas内部统一处理所有portal挂载 */}
           {elements.map(({ id, element, parent }) => 
             createPortal(
               element, 
               parent ?? rootGroupRef.current,
               null,
               id
             )
           )}
           {children}
         </Canvas>
       </Global3DContext.Provider>
     )
   }
   

2. 封装通用传送组件，支持在任意位置调用

   export const RenderInGlobalCanvas = ({ children, parent }) => {
     const elementId = React.useId()
     const { addElement, removeElement } = React.useContext(Global3DContext)
   
     React.useEffect(() => {
       addElement(elementId, children, parent)
       return () => removeElement(elementId)
     }, [elementId, children, parent, addElement, removeElement])
   
     // 组件本身不渲染任何DOM内容
     return null
   }
   

3. 使用方式
   首先在应用根节点挂载全局Canvas，设置为铺满视口的背景层：

   import { GlobalCanvas } from './global-canvas'
   
   function App() {
     return (
       <div className="app-container">
         <GlobalCanvas 
           style={{ position: 'fixed', inset: 0, zIndex: 0 }}
           camera={{ position: [0, 0, 5] }}
         />
         {/* 其余业务路由、组件 */}
         <AppContent />
       </div>
     )
   }
   

   之后在项目任意组件中，不管嵌套层级多深，都可以直接将3D元素传送到全局Canvas渲染：

   import { RenderInGlobalCanvas } from './global-canvas'
   
   // 任意业务组件
   const ProductCard = () => {
     return (
       <div className="card" style={{ position: 'relative', zIndex: 1 }}>
         <h3>商品名称</h3>
         <p>商品描述</p>
         {/* 3D元素直接在这里定义，会自动传送到全局Canvas渲染 */}
         <RenderInGlobalCanvas>
           <mesh position={[2, 0, 0]} rotation={[0, Math.PI/4, 0]}>
             <boxGeometry args={[1, 1, 1]} />
             <meshStandardMaterial color="hotpink" />
           </mesh>
         </RenderInGlobalCanvas>
       </div>
     )
   }
   

如果需要将元素挂载到Canvas内的指定父节点（比如特定的group、scene子节点），只需要将对应节点的ref通过状态管理或上下文透传，传入RenderInGlobalCanvas的parent参数即可。

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