更新记录

1.0.0（2026-07-24） 下载此版本

兼容微信小程序360全景图预览、VR场景、VR看房等使用场景

平台兼容性

uni-app(5.05)

uni-app x(5.12)

y-panorama 微信小程序的360全景图预览插件、vr全景插件

基于 threejs-miniprogram 和微信小程序 WebGL Canvas 实现的 360 全景图预览组件，目前仅支持微信小程序端。

页面使用方式

需要安装 threejs-miniprogram 插件，否则会报错。

pnpm i threejs-miniprogram

页面只需要传入全景图片地址和交互配置，并在页面生命周期中调用组件暴露的方法。

<template>
    <y-panoramaViewer
        ref="panoramaViewerRef"
        :drag-sensitivity="panoramaConfig.dragSensitivity"
        :enable-gyroscope="panoramaConfig.enableGyroscope"
        :gyroscope-sensitivity="panoramaConfig.gyroscopeSensitivity"
        :image-url="panoramaImageUrl"
        :inertia-damping="panoramaConfig.inertiaDamping"
        :initial-fov="panoramaConfig.initialFov"
        :max-fov="panoramaConfig.maxFov"
        :max-latitude="panoramaConfig.maxLatitude"
        :min-fov="panoramaConfig.minFov"
        :min-inertia-speed="panoramaConfig.minInertiaSpeed"
        :show-badge="panoramaConfig.showBadge"
    />
</template>

<script setup>
import { ref } from 'vue';
import { onHide, onReady, onShow, onUnload } from '@dcloudio/uni-app';

// 替换为实际的等距柱状投影全景图地址，组件会监听地址变化并自动重新加载。
const panoramaImageUrl = '';

// 视角相关参数使用角度；阻尼越接近 1，拖拽松手后的惯性持续时间越长。
const panoramaConfig = {
    minFov: 35,
    maxFov: 85,
    initialFov: 70,
    maxLatitude: 85,
    dragSensitivity: 0.12,
    enableGyroscope: false,
    gyroscopeSensitivity: 1,
    inertiaDamping: 0.92,
    minInertiaSpeed: 0.01,
    showBadge: true,
};

const panoramaViewerRef = ref(null);

// Canvas 节点要等页面首次渲染完成后才能查询并初始化 WebGL。
onReady(() => {
    panoramaViewerRef.value?.initialize();
});

// 页面回到前台时补绘当前视角，并按配置恢复陀螺仪监听。
onShow(() => {
    panoramaViewerRef.value?.resume();
});

// 页面进入后台后停止惯性动画和陀螺仪监听，避免无意义的计算与耗电。
onHide(() => {
    panoramaViewerRef.value?.pause();
});

// 页面卸载时主动释放纹理、几何体和 WebGL 渲染器。
onUnload(() => {
    panoramaViewerRef.value?.dispose();
});
</script>

Props

暴露方法

通过 ref 获取组件实例后可调用以下方法：

注意事项

• 图片建议使用 HTTPS 地址，并确保小程序后台已配置合法下载域名。
• imageUrl 应使用等距柱状投影全景图，否则画面会出现明显拉伸或错位。
• 启用陀螺仪时需要在真机微信小程序中验证，开发者工具对设备方向能力的支持有限。
• 非微信小程序端会展示“当前平台暂不支持”的状态。