如何在小程序中优雅地使用 three.js

项目官网： Three.js Platform Adapter

目录

• 成果展示
• 兼容性
• • Three.js 版本
  • Loader 支持
• 快速上手
• • 从模板开始
  • 已有项目集成
• 创建一个场景

成果展示

目前仅支持在微信小程序中使用，后续会兼容到微信小游戏/其他平台小程序/小游戏中。

示例的微信小程序，包含了 300 余个 three.js 官方 webgl 示例 , 可以微信搜索 Threejs Adapter 查看

兼容性

Three.js 版本

特殊的实现方式不限制 three.js 本身的版本，理论上支持任意版本，但由于改变了部分 Loader 的代码，所以目前在非 colorSpace 的版本（< r152) 使用没有验证。

Loader 支持

支持 50 余种 loader ，完美覆盖 99% 的使用场景

快速上手

从模板开始

你可以选择 uni-app 或 weapp-vite 作为基础框架的模板，然后参照模板内包含基本的使用用例和插件配置进行开发。

如遇下载失败，你也可以手动到 github 代码仓库根据对应分支下载模板。

使用 uni

npx degit minisheeep/threejs-miniprogram-template#uni-ts my-uni-three

使用 weapp-vite

npx degit minisheeep/threejs-miniprogram-template#weapp-vite my-weapp-three

如有其他需要集成的框架模板，你也可加群联系我们

已有项目集成

目前只支持在基于 rollup / vite 进行开发的项目中使用，后续会推出没有这个限制的版本。

首先需要在项目下的 .npmrc 文件添加以下配置，因为这些依赖包并没有发布在 npm 官方仓库中。

@minisheep:registry=https://npm.minisheep.cn

然后在命令行中执行以下命令：

pnpm i @minisheep/mini-program-polyfill-core @minisheep/three-platform-adapter

它将会安装两个依赖，用于补全小程序执行环境缺失的一些 DOM / BOM / WEB API，和辅助开发的 rollup 插件。

详情请查看 mini-program-polyfill-core 和 three-platform-adapter 文档。

安装依赖后，首先你需要在你的 vite 或 rollup 配置文件中添加以下插件:

import threePlatformAdapter from '@minisheep/three-platform-adapter/plugin'; 
export default {
  plugins: [
    //...
    threePlatformAdapter() // 详细配置见使用文档
    //...
  ]
}

再根据对应小程序平台在项目入口按需添加以下代码：

微信小程序

import '@minisheep/mini-program-polyfill-core/wechat-polyfill'; // 微信专用
import { adapter } from '@minisheep/three-platform-adapter';
import { wechat } from '@minisheep/three-platform-adapter/wechat'; // 微信专用
// THREEGlobals 是插件中 prefixName 的默认值，你也可以改成你自己定义的
adapter.useAdapter(wechat).patch('THREEGlobals'); 

更多平台将在后续支持

然后你就能开始你的 three.js 开发之旅了。 不过与在 web 中进行开发相比，仍有一些小小的区别，请继续阅读。

创建一个场景

由于本项目并没有改变 three.js 的源码，所以在使用上和 官方文档 所描述的基本没有差异，
不过由于小程序环境不支持动态添加 dom 元素和只能异步获取元素的特性，所以在初始化 WebGLRenderer 的时候必须传递 canvas 对象。

我们在 @minisheep/three-platform-adapter 提供了 useCanvas api 用于返回基本标准（至少满足 three.js 用例）的 HTMLCanvasElement 以供 Renderer 使用。

例如 creating-a-scene 里的例子只需进行以下修改就可以完美运行，以在 uni-app 中运行为例：

main.vue

<script setup>
  import * as THREE from 'three';
  import { adapter } from '@minisheep/three-platform-adapter'; // [!code ++]

  adapter.useCanvas('#canvas').then(({ canvas, requestAnimationFrame }) => {  // [!code ++]
    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);//  [!code --]
    const camera = new THREE.PerspectiveCamera(75, canvas.clientWidth/canvas.clientHeight, 0.1, 1000);//  [!code ++]

    const renderer = new THREE.WebGLRenderer(); // [!code --]
    renderer.setSize(window.innerWidth, window.innerHeight); // [!code --]
    document.body.appendChild(renderer.domElement); // [!code --]
    const renderer = new THREE.WebGLRenderer({ canvas }); // [!code ++]
    renderer.setSize(canvas.clientWidth, canvas.clientHeight); // [!code ++]

    const geometry = new THREE.BoxGeometry(1, 1, 1);
    const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
    const cube = new THREE.Mesh(geometry, material);
    scene.add(cube);

    camera.position.z = 5;

    function animate() {
      requestAnimationFrame(animate);

      cube.rotation.x += 0.01;
      cube.rotation.y += 0.01;

      renderer.render(scene, camera);
    }

    animate();
  }); // [!code ++]
</script>

template

<template>
  <canvas type="webgl2" id="canvas"/>
</template>

css

<style>
  canvas {
    width: 100vw;
    height: 100vh;
  }
</style>

其他更详细的教程你可以查看官网。