更新记录

1.0.0（2026-04-10）

1.0.0（2026-04-10）

• 首次发布
• 支持 H5 和微信小程序双端 GLB 模型渲染
• 支持 Draco 压缩解码
• 自适应容器尺寸
• 触控旋转、双指缩放
• 内置加载进度条
• 伴侣动画系统（idle / curious / happy）
• WebGL 上下文丢失自动恢复
• 主/备地址自动切换

平台兼容性

uni-app(4.64)

Three-Glb 3D模型渲染组件

基于 Three.js 的 GLB/Draco 3D 模型渲染组件，兼容 H5 和微信小程序（安卓/iOS/鸿蒙）。

特性

• 支持 H5 和微信小程序双端
• 支持 Draco 压缩的 GLB 模型
• 自适应任意尺寸父容器，不变形
• 触控旋转、双指缩放
• 内置加载进度条（可自定义 GIF）
• 伴侣动画系统（idle / curious / happy 三种模式，支持自动循环）
• WebGL 上下文丢失自动恢复
• 主地址失败自动切换备用地址
• 可配置光照（环境光、主方向光、补光）

平台兼容性

安装

从 uni-app 插件市场导入本插件。

依赖说明

微信小程序端需要安装以下 npm 依赖：

npm install three-platformize

H5 端需要安装：

npm install three

基本用法

<template>
  <view style="width: 100%; height: 600rpx;">
    <Three-Glb
      :src="modelUrl"
      :draco="true"
      :autoRotate="true"
      @loaded="onLoaded"
      @error="onError"
      @progress=""
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      modelUrl: 'https://example.com/model.glb'
    }
  },
  methods: {
    onLoaded(gltf) {
      console.log('模型加载完成', gltf);
    },
    onError(err) {
      console.error('加载失败', err);
    },
    ({ loaded, total, ratio }) {
      console.log('加载进度', ratio);
    }
  }
}
</script>

属性（Props）

事件（Events）

方法（Methods）

通过 ref 调用：

伴侣动画

组件内置三种动画模式，适合做虚拟伴侣/宠物场景：

• idle：缓慢呼吸浮动，偶尔转头
• curious：快速呼吸，频繁转头，好奇状态
• happy：快速呼吸 + 身体微颤，开心状态

开启 animateCycle 后会自动按 idle → curious → happy 循环切换。

注意事项

1. 父容器必须有明确的宽高，组件会自适应父容器尺寸
2. 微信小程序端使用 three-platformize 渲染，H5 端使用原生 three
3. 小程序端 Draco 解码在主线程执行（小程序不支持 Web Worker），大模型可能短暂卡顿
4. 如果 GLB 没有使用 Draco 压缩，请设置 :draco="false" 以跳过解码器加载
5. OSS 链接带签名时，组件已自动处理 content-type 请求头兼容问题