3D模型展示、动画播放、模型点击 - three.js（threeJs）

更新记录

1.1.5（2025-06-21）下载此版本

模型压缩与加载

小程序压缩参考、加载参考具体代码查看loader.js 默认使用js版本，wasm版本仅支持微信小程序

app、h5 这里暂未实现压缩和加载，请自行使用DRACOLoader

// 代码片段
import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader'
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
const dracoLoader = new DRACOLoader()
// Specify path to a folder containing WASM/JS decoding libraries.
//前往node_modules文件下  找到three文件夹， 找到/examples/js/libs/draco/ 将draco整个文件夹复制下来
// 将复制的draco文件夹复制到public文件夹内
dracoLoader.setDecoderPath(publicPath('/draco/'))
// Optional: Pre-fetch Draco WASM/JS module.
dracoLoader.preload()
const loader = new GLTFLoader(loadingManager)
loader.setDRACOLoader(dracoLoader)

1.1.4（2025-06-11）下载此版本

更新log

h5和小程序渲染相关代码提取到useThree.js中，主要是增加了一些方法（就是下面几个，app可以自己复制粘贴修改,具体请看useThree.js内部实现）内部需要控制渲染
setFps：设置帧率，可以在一些低端机或者不需要高速渲染的时候降低，默认是60
setControlUpdateFlag：控制control的,也就是手势是否可以控制相机转动
setRenderFlag：控制是否渲染的，可以用setFps(0)替代
controlReset：模型归位，比如向某个方向转动了几下，可以过渡到默认位置，可以和controls.saveState()配合使用

1.1.3（2025-06-05）下载此版本

微信小程序分包

子包所使用的node_modules会被打包在主包的vendor.js中，导致超出2m的限制。网上解决方案很多，这里使用的是将node_modules复制到子包中进行构建，然后设置别名，这样代码不需要修改也不会超出限制。具体文件在：演示项目/readme/微信小程序分包demo/subPages.7z

// vite.config.js
import path from 'path'
import fs from 'fs'
import {
    defineConfig
} from 'vite';
import uni from '@dcloudio/vite-plugin-uni';
// 构建之后删除子包中的node_modules
import removeSubPageNodeModule from './vitePlugins/removeSubPageNodeModule';
// 是否是生产环境
const IS_PRD = process.env.NODE_ENV === 'production';
// 别名
const alias = {}
// 映射
const node_modules_sub_map = {
    'three-platformize': 'sub'
}
// 处理
const handSubPage = () => {
    if (!IS_PRD) return
    // 复制node_modules下的文件到对应的子包路径中
    for (const key in node_modules_sub_map) {
        const dir = path.resolve(__dirname, `./node_modules/${key}`)
        if (fs.existsSync(dir)) {
            const subDir = path.resolve(__dirname, `./${node_modules_sub_map[key]}/${key}`)
            if (!fs.existsSync(dir)) {
                fs.mkdir(dir)
            }
            // 复制到子包下
            fs.cpSync(dir, subDir, {
                recursive: true
            })

            // 设置别名
            alias[key] = path.resolve(__dirname, `./${node_modules_sub_map[key]}/${key}`)
        }
    }

}
// #ifdef MP-WEIXIN
handSubPage()
// #endif

export default defineConfig({
    base: "/", // 内网穿透本地nginx代理，或者部署到二级目录才需要写
    plugins: [
        uni(),
        removeSubPageNodeModule(node_modules_sub_map)
    ],
    resolve: {
        alias: {
            // 测试别名
            // import config from '@c/index.js'
            // console.log(config,'config')
            '@c': path.resolve(__dirname, './configs'),
            ...alias
        }
    },
    // 发布时删除 console
    build: {
        minify: 'terser',
        terserOptions: {
            compress: {
                drop_console: IS_PRD,
            },
        },
    }
});

bug

将演示项目中的vue.config.js修改为vite.config.js

平台兼容性

uni-app(4.45)

Vue2	Vue3	Chrome	Safari	app-vue	app-nvue	Android	iOS	鸿蒙
×	√	√	√	√	×	-	-	-

微信小程序	支付宝小程序	抖音小程序	百度小程序	快手小程序	京东小程序	鸿蒙元服务	QQ小程序	飞书小程序	快应用-华为	快应用-联盟
√	×	√	×	×	×	-	×	×	×	×

uni-app x(4.66)

Chrome	Safari	Android	iOS	鸿蒙	微信小程序
-	-	-	-	-	-

其他

多语言	暗黑模式	宽屏模式
×	×	√

简介

此组件仅为快速展示 3D 模型的 demo。使用 vue3 + three-platformize 实现。 h5和app用的是官方的threejs,app是基于renderjs实现的目前仅支持微信小程序、抖音小程序，其他小程序可以参考代码修改，或者查看 three-platformize 官网

相关库 github 地址 vue、three.js、three-platformize

使用说明

建议先下载示例代码运行试试

插件命名原则导致需要组件拼接一个前缀，请直接下载示例工程

将 components 下的 threeJs 组件移动到自己项目 omponents 下
下载 three-platformize

npm i three-platformize@1.133.3

引入到组件和相关工具方法

<template>
  <view class="container">
    <!-- onload事件代表初始化完毕 -->
    <Stage @onload="onload"> </Stage>
  </view>
</template>

import * as THREE from "three-platformize";
import Stage from "@/components/threeJs/stage.vue";
import useThreeJs from "@/components/threeJs/index.js";

const {
  getInstance, // 获取canvas、camera、等实例
  centerAndScale, // 用于调整模型大小和位置
  setEnv, // 设置环境贴图
  screenshot, // 截图
} = useThreeJs();

const loadModel = () => {
  const { group, loader } = getInstance();
  // 如果是.gltf+.bin+texture 请手动转成glb，相关nodejs代码可以参考使用说明
  loader
    .load(
      "https://www.ccnihao.fun/public-resource/DamagedHelmet.gltf.glb",
      (p) => {
        // 这里是加载进度
        // 需要后台正确的设置Content-Length才会有进度
      }
    )
    .then((gltf) => {
      group.add(gltf.scene);
      // 居中并缩放到合适的位置
      centerAndScale();
    });
};

// 初始化完毕，开始设置环境贴图，并加载模型
const onload = async () => {
  console.log("onload");
  // 设置环境贴图，传入hdr文件在线地址即可
  await setEnv(
    "https://www.ccnihao.fun/public-resource/studio_small_09_1k.hdr",
    false
  );
  // 加载模型逻辑
  loadModel();
};

工具相关

obj 转 glb

# 先安装obj2gltf
npm i obj2gltf

// nodejs
const obj2gltf = require("obj2gltf");
const fs = require("fs");
const path = require("path");

(async () => {
  // obj 2 glb
  const outPath = "需要导出的路径";
  const inPath = "需要转换的obj文件路径";
  const options = {
    binary: true, // 不传默认导出gltf
  };
  const glb = await obj2gltf(inPath, options);
  const outFile = path.join(
    outPath,
    `newmodel.${options.binary ? "glb" : "gltf"}`
  );
  if (options.binary) {
    fs.writeFileSync(outFile, glb);
  } else {
    const data = Buffer.from(JSON.stringify(glb));
    fs.writeFileSync(outFile, data);
  }
})();

gltf 转 glb

# 先安装gltf-pipeline
npm i gltf-pipeline

// nodejs
const gltfPipeline = require("gltf-pipeline");
const fsExtra = require("fs-extra");
const path = require("path");
(() => {
  // gltf 2 glb
  const outPath = "需要导出的路径";
  const inPath = "需要转换的obj文件路径";
  const gltfToGlb = gltfPipeline.gltfToGlb;
  const gltf = fsExtra.readJsonSync(inPath);
  const dir = path.dirname(inPath);
  const options = { resourceDirectory: dir };
  gltfToGlb(gltf, options).then(function (results) {
    const outFile = path.join(outPath, `newmodel.glb`);
    fsExtra.writeFileSync(outFile, results.glb);
  });
})();

常见问题

ios 端 bounce 特性问题

主要是会与 OrbitControls 控制器冲突

// 在ios端即使页面尺寸刚好是100vw * 100vh 没有滚动条情况，也会出现拖动回弹的情况（就是页面可以拖动然后松开手指回到初始为止）
// 这时在pages.json中对应的page添加disableScroll即可
{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "threeJs",
        "navigationStyle": "custom", // 隐藏原生导航栏
        "enablePullDownRefresh": false, // 禁止下拉刷新
        "disableScroll": true // 在内容刚好沾满屏幕的时候，ios设备可以拖动然后立马回弹，有些情况不是很好用。禁止ios页面回弹（bounce效果）
      }
    }
  ]
}

在抖音小程序上使用本插件

three-platformize 的 BytePlatform 代码中有个 bug，导致一直报错无法使用控制器

// 主要是修改/node_modules/three-platformize/src/BytePlatform/index.js 文件
// 找到dispatchTouchEvent方法，在if (changedTouches.length)上面加一行 const changedTouches = e.changedTouches;

  dispatchTouchEvent(e = {}) {
    const target = { ...this };

    const event = {
      changedTouches: e.changedTouches.map(touch => new Touch(touch)),
      touches: e.touches.map(touch => new Touch(touch)),
      targetTouches: Array.prototype.slice.call(
        e.touches.map(touch => new Touch(touch)),
      ),
      timeStamp: e.timeStamp,
      target: target,
      currentTarget: target,
      type: e.type,
      cancelBubble: false,
      cancelable: false,
    };

    this.canvas.dispatchEvent(event);
    const changedTouches = e.changedTouches; // 新加的
    if (changedTouches.length) {
      const touch = changedTouches[0];
      const pointerEvent = {
        pageX: touch.pageX,
        pageY: touch.pageY,
        pointerId: touch.identifier,
        type: {
          touchstart: 'pointerdown',
          touchmove: 'pointermove',
          touchend: 'pointerup',
        }[e.type],
        pointerType: 'touch',
      };

      this.canvas.dispatchEvent(pointerEvent);
    }
  }

如果你确定使用本插件，请使用 patch-package 给 three-platformize 打补丁（主要是解决重新下载 node_modules 会自动添加上次修改的内容）

    # 1. 安装patch-package
    npm install patch-package -D
    # 2. 在package.json中增加脚本（每次npm i的时候会自动执行postinstall）： "postinstall": "patch-package"
    # 3. 创建补丁,会在文件目录中生成一个patches文件夹
    npx patch-package three-platformize

如果你走到了这里说明那你成功了一大半了，我还要告诉你一些其他的问题 (1) 开发者工具抖音基础库 3.x.x.x 不会显示模型,具体需要你自己测试 (2) 开发者工具抖音基础库 2.97.0.2 以上控制器没有效果，但是真机调试没有问题 (3) 在组件内获取 canvas 开发者工具没有问题，但是真机调试会报错，如果你上传体验版没有问题可以忽略，否则请参考示例项目在组件外获取 canvas

3D模型展示、动画播放、模型点击 - three.js（threeJs） vue3 three.js three-platformize 3D模型 threejs

更新记录

1.1.5（2025-06-21）下载此版本

模型压缩与加载

1.1.4（2025-06-11）下载此版本

更新log

1.1.3（2025-06-05）下载此版本

微信小程序分包

bug

平台兼容性

uni-app(4.45)

uni-app x(4.66)

其他

简介

使用说明

工具相关

常见问题

ios 端 bounce 特性问题

在抖音小程序上使用本插件

隐私、权限声明

1. 本插件需要申请的系统权限列表：

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

许可协议

MIT协议

3D模型展示、动画播放、模型点击 - three.js（threeJs）

uniappx 华为scanKit 扫码插件

cc-swiper-video

滑动验证、图片旋转验证组件

uniuse一个vue3的hooks风格的工具库

3D模型展示、动画播放、模型点击 - three.js（threeJs） vue3 three.js three-platformize 3D模型 threejs

更新记录

1.1.5（2025-06-21） 下载此版本

模型压缩与加载

1.1.4（2025-06-11） 下载此版本

更新log

1.1.3（2025-06-05） 下载此版本

微信小程序分包

bug

平台兼容性

uni-app(4.45)

uni-app x(4.66)

其他

简介

使用说明

工具相关

常见问题

ios 端 bounce 特性问题

在抖音小程序上使用本插件

隐私、权限声明

1. 本插件需要申请的系统权限列表：

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

许可协议

MIT协议

3D模型展示、动画播放、模型点击 - three.js（threeJs）

uniappx 华为scanKit 扫码插件

cc-swiper-video

滑动验证、图片旋转验证组件

uniuse一个vue3的hooks风格的工具库

Modal title

1.1.5（2025-06-21）下载此版本

1.1.4（2025-06-11）下载此版本

1.1.3（2025-06-05）下载此版本