jr3d

v1.0.41

Published

14 hours ago

📦 **npm 包名:** `jr3d` 🌐 **支持:** Vue2 & Vue3 🎨 **基于:** Three.js + GSAP

0High
0Medium
0Low

fanpangdeshenqiangshou

jr3d - 3D模型组件（Vue2 / Vue3 通用）

📦 npm 包名: jr3d
🌐 支持: Vue2 & Vue3
🎨 基于: Three.js + GSAP

快速开始

npm install jr3d

ThreeModel 3D模型组件使用文档（Vue2 / Vue3 通用）

一、组件介绍

基于 Three.js + GSAP 开发的通用 3D 模型渲染组件，同时兼容 Vue2、Vue3。

支持：GLB / GLTF / OBJ 模型加载、多模型切换、点位标注、相机视角动画、坐标拾取、实时相机数据、窗口自适应、资源自动销毁，适用于数字孪生、3D 可视化、模型展示大屏。

核心特性

✅ 支持 GLB、GLTF、OBJ 主流三维模型格式
✅ 多模型动态切换，每个模型独立光照、相机、控制器配置
✅ 3D 点位 POI 标注、浮动动画、点击视角跳转
✅ 鼠标拾取模型坐标、实时相机坐标回调
✅ 平滑相机动画、视角复位、自定义视角定位
✅ 场景雾化、光影配置、鼠标缩放/旋转/平移限制
✅ 完整生命周期管理，自动销毁资源，无内存泄漏
✅ 兼容 Vue2 选项式 / Vue3 setup 双写法

二、环境依赖

组件依赖 three、gsap 动画库

npm install three gsap --save

三、使用方式（双版本全覆盖）

3.1 Vue3 写法（setup）

<template>
  <div class="wrap" style="width:100vw;height:100vh;">
    <ThreeModel
      ref="threeModelRef"
      :model-list="modelList"
      :default-point-icon="icon"
      @camera-update="onCameraUpdate"
      @mouse-pick-update="onPickUpdate"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import ThreeModel from './components/ThreeModel.vue'
import icon from '@/assets/images/default-avatar.png'

const threeModelRef = ref(null)

const modelList = ref([
  {
    url: '/assets/demo.glb',
    initCamera: { x: 2.41, y: 0.86, z: 2.22 },
    initTarget: { x: 0, y: 0, z: 0 },
    pointList: []
  }
])

// 相机实时坐标
const onCameraUpdate = (pos) => {}
// 模型拾取坐标
const onPickUpdate = (pos) => {}
</script>

3.2 Vue2 写法（选项式 API）

<template>
  <div class="wrap" style="width:100vw;height:100vh;">
    <ThreeModel
      ref="threeModelRef"
      :model-list="modelList"
      :default-point-icon="icon"
      @camera-update="onCameraUpdate"
      @mouse-pick-update="onPickUpdate"
    />
  </div>
</template>

<script>
import ThreeModel from './components/ThreeModel.vue'
import icon from '@/assets/images/default-avatar.png'

export default {
  components: { ThreeModel },
  data() {
    return {
      icon,
      modelList: [
        {
          url: '/assets/demo.glb',
          initCamera: { x: 2.41, y: 0.86, z: 2.22 },
          initTarget: { x: 0, y: 0, z: 0 },
          pointList: []
        }
      ]
    }
  },
  methods: {
    onCameraUpdate(pos) {},
    onPickUpdate(pos) {}
  }
}
</script>

四、Props 全局配置（通用）

|参数|类型|默认值|说明| |---|---|---|---| |modelList|Array|必填|模型配置列表（多模型支持）| |defaultPointIcon|String|''|点位默认图标| |backgroundColor|String/Number|0x080a12|画布背景色| |fogEnable|Boolean|true|是否开启雾化| |fogNear / fogFar|Number|30 / 300|雾化远近范围| |cameraNear / cameraFar|Number|0.1 / 2000|相机裁剪面| |globalControls|Object|默认控制器|全局鼠标操作参数| |loadTimeout|Number|10000|模型加载超时时间(ms)|

五、单模型 modelList 完整配置项

{
  url: "/assets/xxx.glb",          // 模型地址（public目录）
  initCamera: { x: 2, y: 1, z: 3 },// 初始相机位置
  initTarget: { x: 0, y: 0, z: 0 },// 初始看向目标
  cameraFov: 60,                   // 相机视角

  // 光照
  ambientIntensity: 1.2,
  light1Intensity: 1.0,
  light2Intensity: 0.8,
  light3Intensity: 0.8,

  // 控制器
  freeRotateEnable: true,
  enableControl: true,
  controls: {
    enableDamping: true,
    minDistance: 0.5,
    maxDistance: 10,
    maxPolarAngle: Math.PI / 1.5
  },

  // 点位样式
  pointStyle: { iconSize: 0.02 },
  textColor: "#ffffff",
  showModelFace: true,

  // 点位列表
  pointList: [
    {
      position: { x:0, y:0.5, z:0.4 },
      camera: { x:0.3, y:0.6, z:0.7 },
      target: { x:0, y:0, z:0 },
      title: "点位名称",
      icon: "自定义图标地址"
    }
  ]
}

六、组件实例方法（Vue2 / Vue3 通用）

Vue3：threeModelRef\.value\.xxx

Vue2：this\.$refs\.threeModelRef\.xxx

// 切换模型
switchModel(index)

// 相机平滑跳转视角
gotoCameraView(cameraPos, targetPos)

// 同视角跳转（别名）
translateCamera(cameraPos, targetPos)

// 切换模型 + 跳转视角
gotoModelAndView(modelIndex, cameraPos, targetPos)

// 获取当前模型所有点位
getCurrentPoints()

七、组件事件（Emits）

|事件名|回调参数|说明| |---|---|---| |camera-update|{x,y,z}|实时相机世界坐标| |mouse-pick-update|{x,y,z}|鼠标拾取模型表面坐标| |point-click|index, info|点击点位图标| |zoom-percent-update|Number|缩放百分比 0~100| |model-loaded|index|模型加载成功| |model-load-error|index|模型加载失败/超时| |model-switch|index|模型切换完成| |ready|-|组件初始化完成|

八、内置交互功能

鼠标左键拖拽：旋转模型
鼠标滚轮：缩放远近
点位图标：上下浮动、永远朝向相机
自动适配窗口大小：resize 自动重绘
自动资源销毁：页面关闭释放 Three 内存

九、配套快捷键（父页面可复用）

C 键：复制鼠标拾取的模型坐标
V 键：复制当前相机坐标

十、项目部署注意事项

模型文件必须放置在项目 public 目录，绝对路径引用
OBJ 模型必须配套 同名 .mtl 材质文件
Draco 解压 CDN 已内置，无需本地配置
大屏场景建议限制模型面数，保证帧率稳定
组件完全兼容 Vue2/Vue3，无需修改组件源码

十一、npm 包编译 & 发布指南

编译

# 安装依赖
npm install

# 构建生产包（输出到 dist/ 目录）
npm run build

# 开发模式（监听文件变化）
npm run dev

输出文件说明

编译后会生成以下文件：

dist/jr3d.es.js - ES Module（推荐）
dist/jr3d.umd.js - UMD 格式（兼容旧浏览器）
dist/jr3d.umd.min.js - 压缩版 UMD

npm 账户配置

# 登录 npm
npm login

# 输入用户名、密码、邮箱
# 确认邮箱验证码（npm 会发送到邮箱）

发布到 npm

# 方式1：直接发布（会自动执行 npm run build）
npm publish

# 方式2：手动构建后发布
npm run build
npm publish

版本管理

# 更新版本号（自动更新 package.json）
npm version patch     # 1.0.0 -> 1.0.1 (小修复)
npm version minor     # 1.0.0 -> 1.1.0 (新功能)
npm version major     # 1.0.0 -> 2.0.0 (破坏性变更)

# 发布指定版本
npm publish --tag beta    # 发布测试版
npm publish --tag latest  # 发布正式版（默认）

在项目中使用

Vue2 项目：

// main.js
import Vue from 'vue'
import ThreeModel from 'jr3d'

Vue.component('ThreeModel', ThreeModel)

Vue3 项目：

// main.js
import { createApp } from 'vue'
import ThreeModel from 'jr3d'

const app = createApp({})
app.component('ThreeModel', ThreeModel)

常见问题排查

| 问题 | 解决方案 | |------|--------| | npm login 失败 | 确保已注册 npm 账户，检查 npm registry 配置 | | 发布失败（权限） | 检查包名是否已被占用，或登录状态是否过期 | | 编译报错 | 运行 npm install 重新安装依赖 | | Vue2/Vue3 冲突 | 包已配置 peerDependencies，各项目自行安装 Vue |

包大小优化

# 分析包大小
npm install -g webpack-bundle-analyzer

# 查看编译输出
npm run build -- --analyze

更新发布

# 修改代码后，更新版本
npm version patch

# 重新编译和发布
npm publish

十二、License

MIT