更新记录

0.0.1(2024-10-11) 下载此版本

已完成基本功能。


平台兼容性

Vue2 Vue3
×
App 快应用 微信小程序 支付宝小程序 百度小程序 字节小程序 QQ小程序
HBuilderX 4.28 × × × × ×
钉钉小程序 快手小程序 飞书小程序 京东小程序
× × × ×
H5-Safari Android Browser 微信浏览器(Android) QQ浏览器(Android) Chrome IE Edge Firefox PC-Safari
× × × × × × × × ×

小程序自定义组件的通用使用方式详见:uni-app中使用小程序自定义组件教程


一、说明:

1.本组件基于微信小程序的xr-frame框架封装,所以只能支持微信小程序平台。

同样,由于xr-frame是微信小程序平台专门开发的3D框架,其本身占用内存较少(相对于three.js等第三方库),播放带动画的模型也更流畅,所以建议做微信小程序端的小伙伴们多了解了解这个框架。

2.本组件只是对xr-frame做了一个简单的封装,用于glb模型的展示。如有更多需求,则需要进一步定制。

二、安装方法:

小程序组件相对通用组件要复杂一些

1.通过HBuilder安装或下载zip文件,安装后,文件目录如右侧图片所示

  • 根目录
    • wxcomponents
    • xr-gltf
      • index.js
      • index.json
      • index.wxml

2.配置manifest.json文件

点击源码视图,在微信小程序相关配置出加入下面的配置

"mp-weixin" : {
        "appid" : "你的appid",
        "setting" : {
            "urlCheck" : false
        },
        "usingComponents" : true,
        "lazyCodeLoading" : "requiredComponents",
        "optimization" : {
            "subPackages" : true
        }
 },

3.修改pages.json文件

这里我们需要在使用组件的页面上增加配置,比如要在 pages/index/index这个页面上使用插件,就要写入如下配置

"path": "pages/index/index",
            "style": {
                "navigationBarTitleText": "uni-app",
                "navigationBarTextStyle": "black",
                "usingComponents": {
                    "xr-gltf": "../../wxcomponents/xr-gltf"
                },
                "disableScroll": true,
            }

这里起关键作用的配置就是在style节点下加入usingComponents的配置。

配置好后,就可以在这个界面使用该组建了,如果需要在其他页面使用,就还需要在其他页面同样配置一下

三、使用组件

1 .按照上面的配置好后,就可以在页面上引入组件了。如下

<template>
    <view class="content">
        <xr-gltf ref="xr" id="main-frame" disable-scroll
        :url="url"
        :width="renderWidth"
        :height="renderHeight"
        :style="'width:'+width+'px;height:'+height+'px;'"></xr-gltf>
    <view style="width: 750rpx;display: flex;flex-direction: row;align-items: center;justify-content: center;">
            <button @click="play">播放</button>
            <button @click="stop">停止</button>
        </view>
    </view>
</template>

2.我们需要在onLoad()周期函数中设置组件的宽和高。

因为xr-frame是基于canvas的,而由于不同手机的dpi不同,所以我们需要在onLoad()周期函数中,先获取屏幕信息,然后根据获取到的dpi值区设置canvas的宽高。代码如下

onLoad() {
            //这里将组件的宽高直接设置为全屏
            //我们也可以根据自己的需求设置宽高
            this.width = uni.getWindowInfo().windowWidth
            this.height = uni.getWindowInfo().windowHeight
            const dpi = uni.getWindowInfo().pixelRatio
            this.renderWidth = this.width * dpi
            this.renderHeight = this.height * dpi
        },

3.设置组件属性和调用组件方法

这里通过对xr-frame的封装,设置了一些常用的属性和组件的方法,详细说明如下:

组件属性

props 说明 默认值 数据类型
url 模型链接地址 String
directLightColor 直线光源颜色 1 1 1 String
directLightIntensity 直线光强度 2 Number
directLightRotation 直线光旋转角度 40 170 0 String
glbScale 模型缩放 1 1 1 String
glbPosition 模型位置 0 -1 0 String
camPosition 相机位置 0 1 5 String
autoPlay 模型动画是否自动播放 true Boolean
clearColor 清屏颜色 0 0 0 0 String

以上属性,只有url是必须填的,模型需要是glb格式的,在填写网络地址时记得将服务器的地址加入小程序白名单。否则会遇到模拟器能显示,但手机端预览无法显示的情况。

其他属性可根据自己项目的需要设置。

组件方法

方法名 说明
playAnim(name) 播放模型动画,其参数为模型中动画片段的名字
stopAnim() 停止当前模型动画
setControlSpeed(speed) 设置轨道控制器的滑动速度
setControlDamping(damping) 设置轨道控制器阻尼系数
lockControl() 锁定轨道控制器
nLockControl() 解锁轨道控制器

这些方法,可直接通过给组件设置ref属性,然后调用子组件方法实现。示例如下:

methods: {
            // 播放模型动画,参数需要根据自己模型中动画片段的名字修改
            play(){
                this.$refs.xr.playAnim('kick')
            },

            stop(){
                this.$refs.xr.stopAnim()
            },

            // 设置轨道控制器的速度
            setSpeed(){
                this.$refs.xr.setControlSpeed(1)
            }
        }

四、需要注意的问题

1.本组件基于xr-frame框架封装,经测试,当glb文件过大时会容易造成卡顿,所以尽量将glb文件控制在1M以内

2.由于开启投影后会对机能造成很大负担,非常容易造成手机卡顿,所以投影是没有开启的

3.还有什么其他的问题欢迎留言,看到后我会第一时间回复。

隐私、权限声明

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

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

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

许可协议

MIT协议

使用中有什么不明白的地方,就向插件作者提问吧~ 我要提问