跳到主要内容

起步

在 Vue 框架上通过 Composition API 模式集成 Five 开发，完整源码示例：JavaScript | TypeScript

本章你可以学习到
  • 准备开发环境。
  • 如何引入 Five SDK。
  • 将一个三维空间展示到屏幕中。

准备工作​

开发环境​

  • 你需要准备一个现代浏览器。
信息

Five 的浏览器支持如下，请自行选择一个你熟悉的：

SafariSafari on iOSChromeChrome for AndroidEdgeFirefox
>= 9>= 9>= 49>= 93>= 13>= 45
  • 你需要安装 Node.js，并且 Node.js 版本尽量 >= 12.x，以规避历史遗留的兼容问题。

使用开发构建工具​

本示例通过 Vite 初始化开发环境。你可以通过下方代码自行初始化。

# npm 6.x
npm create vite@latest my-vue-app --template vue

# npm 7+, extra double-dash is needed:
npm create vite@latest my-vue-app -- --template vue

在 src 下建立本次教程的目录 src/0.getting-started。

每一个教程均会创建一个新目录作为记录，便于总结和查找。当课程结束你会得到

src
├── 0.getting-started
├── 1.displaying-work
├── 2.knowing-state
...

这样的目录结构。完整代码样例也是这样的目录结构，你可以随时参考。

提示

如果你熟悉其他的开发构建工具如 Webpack Snowpack parcel 你也可以使用他们。

创建 HTML 文件​

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" href="data:;base64,iVBORw0KGgo=" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>起步 | Getting started</title>
    <!-- highlight-start -->
    <style>
      * {
        margin: 0;
        padding: 0;
      }
      html,
      body,
      #app {
        width: 100%;
        height: 100%;
        overflow: hidden;
      }
    </style>
    <!-- highlight-end -->
  </head>
  <body>
    <!-- highlight-start -->
    <div id="app"></div>
    <script type="module" src="./index"></script>
    <!-- highlight-end -->
  </body>
</html>

使用直接引入 <script type="module" src="./index"></script> 是 Vite 的特征， 如果你使用其他开发构建工具请自行处理代码引入和入口文件。 比如 Webpack 下使用 HtmlWebpackPlugin 等。

书写测试逻辑代码​

我们先创建一个简单的 Hello World 来确保整体代码能够跑通。

const app = document.querySelector("#app");
// highlight-start
app.innerHTML = "Hello World.";
// highlight-end
export {};

最后的 export {}; 是因为 Vite 使用 type="module" 引入的关系，每个文件都需要是一个 module, 需要 export。 如果你使用其他开发构建工具，请按照自己的开发构建工具的要求编写。

启动服务 npm run dev。 并跳转到当前页面 "http://localhost:3000/src/0.getting-started/index.html"。

信息

请查看你的控制台，端口号会因为你的配置以及当前端口占用情况变更，请已控制台输出的为准。 如果你使用其他开发构建工具，请按照自己的开发构建工具的要求启动服务。

然后你会在页面看到

Hello World.

这样的输出，说明开发构建工具的已经完成。

后面几个章节将不再详细叙述上述步骤，请一并完成即可。

从 npm 安装依赖包​

在你的工程目录安装依赖

npm install @realsee/five three@0.117

依赖需要

  • @realsee/five Five
  • three three.js 是 Five 的依赖图形/数学库。 目前请使用 0.117.x 的版本
  • vue Vue 框架 目前请使用 3.0.0 以上版本

测试 Vue 组件​

新建一个 App.vue 组件

import { createApp, h } from "vue";
import App from "./App.vue";

createApp(App).mount("#app");
src/0.getting-started/App.vue
<template>
  <div>{{ str }}</div>
  ˜
</template>

<script setup>
const str = "测试";
</script>

渲染一个三维空间​

是时候渲染一个 VR 场景看看了

加载三维空间​

删除你之前的 App.vue 代码。我们来重新编写。 你可以先不清楚接下来编写的代码的含义，你在下一章会学习到。

<template>
  <FiveProvider :work="work">
    <FiveCanvas :width="512" :height="512" />
  </FiveProvider>
</template>

<script setup>
import { FiveProvider, FiveCanvas } from "@realsee/five/vue";
import { parseWork } from "@realsee/five";
import { ref } from "vue";

const work = ref();
const workURL =
  "https://vr-public.realsee-cdn.cn/release/static/image/release/five/work-sample/07bdc58f413bc5494f05c7cbb5cbdce4/work.json";

fetch(workURL)
  .then((response) => response.text())
  .then((text) => (work.value = parseWork(text)));
</script>

回到你的浏览器，看看是不是已经有一个三维空间已经展示在左上的位置。 你可以用鼠标或者触摸手势操作画面，基本的浏览功能都已经附带了。

让画面铺满整个屏幕​

虽然可能并不能完全理解上述代码的工作原理，但是我们可以看到 FiveCanvas 上有 width 和 height 属性，非常像画面尺寸的样子。并且在浏览器中查看，画面在左上角的位置，也印证了这个猜想。对每次，他们就是用于设置画面尺寸的。

那我们尝试用我们熟悉的 Vue Composition API 方式，将它铺满屏幕。

import { ref, onBeforeUnmount } from "vue";

function useWindowDimensions() {
  const width = ref(window.innerWidth);
  const height = ref(window.innerHeight);

  const listener = () => {
    width.value = window.innerWidth;
    height.value = window.innerHeight;
  };

  window.addEventListener("resize", listener, false);
  onBeforeUnmount(() => {
    window.removeEventListener("resize", listener, false);
  });
  return { width, height };
}
export { useWindowDimensions };
src/0.getting-started/App.vue
<template>
  <FiveProvider :work="work">
    <FiveCanvas :width="width" :height="height" />
  </FiveProvider>
</template>

<script setup>
import { FiveProvider, FiveCanvas } from "@realsee/five/vue";
import { parseWork } from "@realsee/five";
import { ref } from "vue";
import { useWindowDimensions } from "./useWindowDimensions";
const work = ref();
const workURL =
  "https://vr-public.realsee-cdn.cn/release/static/image/release/five/work-sample/07bdc58f413bc5494f05c7cbb5cbdce4/work.json";

fetch(workURL)
  .then((response) => response.text())
  .then((text) => (work.value = parseWork(text)));
const { width, height } = useWindowDimensions();
</script>

回到你的浏览器，看看是不是符合预期。

你真棒 🥳 ！

代码整理拆分​

我们的代码拆分逻辑

  • 将 index 拆分用于挂载 App 根组件。
  • 将 App 拆分到单独文件 App.vue。
  • 将 useWindowDimensions 方法拆分到单独文件。

下一章节你会学到​

下一章节你会学到
  • 了解什么是 Work。
  • 了解刚才的代码，比如 FiveProvider / FiveCanvas 组件是如何工作的。