跳到主要内容

快速开始

线上尝试​

你可以使用StackBlitz快速上手我们的示例。

Vanilla JavaScript

快速使用JavaScript开启三维的世界
立即开始

Vanilla TypeScript

快速使用TypeScript开启三维的世界
立即开始

创建一个 Five 应用​

前提条件
  • 熟悉至少一种前端框架，如 React、Vue 等的开发
  • 熟悉 Node.js，并安装了 14.0.0 以上版本的 Node.js 开发环境
  • 为了快速演示开发，本文档推荐使用 vite 作为脚手架快速开启项目
注意

Five 基于 Three.js, 在使用 Five 时需要同步安装 Three.js 依赖。目前依赖的 Three.js 版本为 115 ~ 117。

浏览器兼容性​

Five 所依赖的 Three.js 是基于现代浏览器 WebGL 能力实现的。其依赖现代浏览器的运行时环境，以下是Five 在主流浏览器上的兼容性列表：

SafariSafari on iOSChromeChrome for AndroidEdgeFirefox
>= 9>= 9>= 49>= 93>= 13>= 45

快速开发​

使用JavaScript开发​

  1. 使用 vite 初始化项目
npm init vite@latest my-five-vanilla-js-app -- --template vanilla
  1. 进入项目目录，安装依赖
cd my-five-vanilla-js-app
npm install @realsee/five @realsee/open-works three@0.117.1
  1. 修改 html 的 viewport 如下：（注意 viewport 的设置会影响三维空间尺寸的展示效果）
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    // highlight-start
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1, maximum-scale=1, minimum-scale=1, viewport-fit=cover, user-scalable=no"
    />
    // highlight-end
    <title>Vite App</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/main.js"></script>
  </body>
</html>
  1. 修改main.js如下：
import workJSON from '@realsee/open-works/virtual/81RojBlJQdVTglNNMr/work.json'
import { Five } from '@realsee/five'
import './style.css'

const $app = document.querySelector('#app')

// five初始化参数请参考
// https://unpkg.com/@realsee/five@latest/docs/interfaces/five.FiveInitArgs.html
const five = new Five({
  imageOptions: {
    // 初始512开启动态瓦片加载，可提升点位加载速度
    size: 512,
  },
  textureOptions: {
    // 关闭模型贴图自动缩放，加载高精度模型贴图，
    // 注意，低性能的机器大模型场景容易崩溃
    autoResize: false,
  },
})

five.load(workJSON)

five.appendTo($app)

// 当容器div尺寸变化时进行画布刷新
window.addEventListener('resize', () => five.refresh())

// 添加切换按钮
const $button = document.createElement('button')

$button.innerText = '切换成模型态'

$button.addEventListener('click', (ev) => {
  console.log(ev)
  // 当前为全景模式
  if (five.getCurrentState().mode === Five.Mode.Panorama) {
    five.changeMode(Five.Mode.Floorplan)
    return
  }
  // 当前为模型态
  if (five.getCurrentState().mode === Five.Mode.Floorplan) {
    five.changeMode(Five.Mode.Panorama)
    return
  }
})

five.on('modeChange', (mode) => {
  if (mode === Five.Mode.Panorama) {
    $button.innerText = '切换成模型态'
  }
  if (mode === Five.Mode.Floorplan) {
    $button.innerText = '切换成全景态'
  }
})

$button.classList.add('btn')

$app.appendChild($button)
  1. 修改style.css如下：
:root {
  font-family: Inter, system-ui, Avenir, Helvetica, Arial, sans-serif;
  line-height: 1.5;
  font-weight: 400;

  color-scheme: light dark;
  color: rgba(255, 255, 255, 0.87);
  background-color: #242424;

  font-synthesis: none;
  text-rendering: optimizeLegibility;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  -webkit-text-size-adjust: 100%;
}

* {
  margin: 0;
  padding: 0;
}

html,
body {
  width: 100%;
  height: 100%;
  position: relative;
}

#app {
  width: 100%;
  height: 100%;
  position: absolute;
  overflow: hidden;
}

.btn {
  position: absolute;
  top: 20px;
  left: 50%;
  transform: translateX(-50%);
  z-index: 10001;
  padding: 0 10px;
  height: 30px;
}
  1. 运行项目
npm run dev
  1. 打开浏览器访问http://localhost:5173/，即可看到效果，如下所示：

使用TypeScript开发​

  1. 使用 vite 初始化项目
npm init vite@latest my-five-vanilla-ts-app -- --template vanilla-ts
  1. 进入项目目录，安装依赖
cd my-five-vanilla-ts-app
npm install @realsee/five @realsee/open-works three@0.117.1
  1. 修改 html 的 viewport 如下：（注意 viewport 的设置会影响三维空间尺寸的展示效果）
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    // highlight-start
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1, maximum-scale=1, minimum-scale=1, viewport-fit=cover, user-scalable=no"
    />
    // highlight-end
    <title>Vite App</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>
  1. 修改src/main.ts如下：
// @ts-ignore
import workJSON from '@realsee/open-works/virtual/816lPVZQkQDF5XOpPo/work.json'
import { Five } from '@realsee/five'
import './style.css'

const $app = document.querySelector<HTMLElement>('#app') as HTMLElement

// five初始化参数请参考
// https://unpkg.com/@realsee/five@latest/docs/interfaces/five.FiveInitArgs.html
const five = new Five({
  imageOptions: {
    // 初始512开启动态瓦片加载，可提升点位加载速度
    size: 512,
  },
  textureOptions: {
    // 关闭模型贴图自动缩放，加载高精度模型贴图，
    // 注意，低性能的机器大模型场景容易崩溃
    autoResize: false,
  },
})

five.load(workJSON)

five.appendTo($app)

// 当容器div尺寸变化时进行画布刷新
window.addEventListener('resize', () => five.refresh())

// 添加切换按钮
const $button = document.createElement('button')

$button.innerText = '切换成模型态'

$button.addEventListener('click', (ev) => {
  console.log(ev)
  // 当前为全景模式
  if (five.getCurrentState().mode === Five.Mode.Panorama) {
    five.changeMode(Five.Mode.Floorplan)
    return
  }
  // 当前为模型态
  if (five.getCurrentState().mode === Five.Mode.Floorplan) {
    five.changeMode(Five.Mode.Panorama)
    return
  }
})

five.on('modeChange', (mode) => {
  if (mode === Five.Mode.Panorama) {
    $button.innerText = '切换成模型态'
  }
  if (mode === Five.Mode.Floorplan) {
    $button.innerText = '切换成全景态'
  }
})

$button.classList.add('btn')

$app.appendChild($button)
  1. 修改style.css如下：
:root {
  font-family: Inter, system-ui, Avenir, Helvetica, Arial, sans-serif;
  line-height: 1.5;
  font-weight: 400;

  color-scheme: light dark;
  color: rgba(255, 255, 255, 0.87);
  background-color: #242424;

  font-synthesis: none;
  text-rendering: optimizeLegibility;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  -webkit-text-size-adjust: 100%;
}

* {
  margin: 0;
  padding: 0;
}

html,
body {
  width: 100%;
  height: 100%;
  position: relative;
}

#app {
  width: 100%;
  height: 100%;
  position: absolute;
  overflow: hidden;
}

.btn {
  position: absolute;
  top: 20px;
  left: 50%;
  transform: translateX(-50%);
  z-index: 10001;
  padding: 0 10px;
  height: 30px;
}
  1. 运行项目
npm run dev
  1. 打开浏览器访问http://localhost:5173/，即可看到效果，如下所示：