起步

本教程在 React 中直接使用 @realsee/five。

本章你可以学到

• 在 React 项目中安装并引入 Five SDK。
• 使用 useRef 与 useEffect 在组件中挂载/销毁 Five。
• 渲染一个三维空间并随窗口变化自适应。

准备工作

使用 Vite 快速创建 React 项目

JavaScript

npm create vite@latest my-react-app -- --template react
cd my-react-app
npm install

TypeScript

npm create vite@latest my-react-app -- --template react-ts
cd my-react-app
npm install

安装依赖

npm install @realsee/five three@0.117

信息

• @realsee/five: Five 渲染引擎。
• three@0.117: Five 依赖的图形/数学库，目前请使用 0.117.x 版本。

渲染一个三维空间

下面在 React 组件中完成最小可运行示例：创建 Five 实例、挂载到容器、加载 work.json、监听窗口变化并在组件卸载时清理。

JavaScript

import { useEffect, useRef } from 'react'
import { Five, parseWork } from '@realsee/five'

const workURL = 'https://vr-public.realsee-cdn.cn/release/static/image/release/five/work-sample/07bdc58f413bc5494f05c7cbb5cbdce4/work.json'

export default function FiveCanvas() {
  const containerRef = useRef(null)
  const fiveRef = useRef(null)

  useEffect(() => {
    const five = new Five()
    fiveRef.current = five

    if (containerRef.current) {
      five.appendTo(containerRef.current)
    }

    const controller = new AbortController()
    fetch(workURL, { signal: controller.signal })
      .then((res) => res.json())
      .then((json) => five.load(parseWork(json)))
      .catch(() => {})

    const onResize = () => five.refresh()
    window.addEventListener('resize', onResize, false)

    return () => {
      controller.abort()
      window.removeEventListener('resize', onResize, false)
      fiveRef.current && fiveRef.current.dispose()
    }
  }, [])

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <div ref={containerRef} style={{ width: '100%', height: '100%', overflow: 'hidden' }} />
    </div>
  )
}

src/App.jsx

import FiveCanvas from './FiveCanvas'

export default function App() {
  return <FiveCanvas />
}

TypeScript

import { useEffect, useRef } from 'react'
import { Five, parseWork } from '@realsee/five'

const workURL = 'https://vr-public.realsee-cdn.cn/release/static/image/release/five/work-sample/07bdc58f413bc5494f05c7cbb5cbdce4/work.json'

export default function FiveCanvas() {
  const containerRef = useRef<HTMLDivElement | null>(null)
  const fiveRef = useRef<Five | null>(null)

  useEffect(() => {
    const five = new Five()
    fiveRef.current = five

    if (containerRef.current) {
      five.appendTo(containerRef.current)
    }

    const controller = new AbortController()
    fetch(workURL, { signal: controller.signal })
      .then((res) => res.json())
      .then((json) => five.load(parseWork(json)))
      .catch(() => {})

    const onResize = () => five.refresh()
    window.addEventListener('resize', onResize, false)

    return () => {
      controller.abort()
      window.removeEventListener('resize', onResize, false)
      fiveRef.current?.dispose()
    }
  }, [])

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <div ref={containerRef} style={{ width: '100%', height: '100%', overflow: 'hidden' }} />
    </div>
  )
}

src/App.tsx

import FiveCanvas from './FiveCanvas'

export default function App() {
  return <FiveCanvas />
}

启动开发服务器：

npm run dev

访问浏览器并确认三维空间成功渲染。如果你需要了解 work.json、parseWork(json) 与 five.load(work) 等概念，请继续下一章。