更新记录

1.0.0（2026-03-02） 下载此版本

实现全景图url或者本地路径加载全景图功能

平台兼容性

uni-app(3.6.17)

uni-app x(3.6.17)

Marzipano 全景图查看器（UTS 版）v1.0.0

基于 Marzipano 开源引擎的等矩形全景图渲染组件，支持手势拖动、双指缩放、陀螺仪视角跟随，适配 App(Android/iOS)、H5、微信小程序（小程序内需使用 web-view 打开 H5 页）。

特性

• 等矩形（equirectangular）2:1 全景图渲染
• 手势拖动、双指缩放
• 移动端陀螺仪视角跟随（可选）
• 支持网络 HTTPS 与本地静态资源地址
• 加载中/加载失败占位，不白屏
• 符合 DCloud 插件市场规范，无远程脚本、无隐私收集

接入步骤

1. 将本插件放入项目 uni_modules 目录（或通过插件市场安装）。
2. 无需手动注册组件，支持 easycom 自动引入。
3. 在页面中使用：

<template>
  <view class="panorama-container">
    <marzipano-panorama
      :src="panoramaUrl"
      :enableGyro="true"
      :enableDrag="true"
      :enableZoom="true"
      @loadComplete="handleLoadComplete"
      @loadError="handleLoadError"
    />
  </view>
</template>

<script setup>
import { ref } from 'vue'
const panoramaUrl = ref('https://xxx.com/your-panorama.jpg')
const handleLoadComplete = () => console.log('加载完成')
const handleLoadError = (e) => console.error('加载失败', e)
</script>

<style scoped>
.panorama-container { width: 100vw; height: 100vh; }
</style>

属性（Props）

事件（Events）

局域网 / 手机访问

• 若在 PC 上运行正常，但用同一局域网内手机通过「PC 的 IP + 端口」访问时出现黑屏或资源加载失败，请确认：
  1. 开发服务监听所有网卡：使用 Vite 时请加 --host（如 npm run dev -- --host），HBuilderX 运行到浏览器时在运行配置中勾选「局域网访问」或使用可被局域网访问的地址。
  2. 使用相对路径：src 建议使用相对路径（如 /static/panorama.jpg），并将 2:1 等矩形全景图放到项目 static/panorama.jpg，这样在手机通过 IP 访问时图片从当前 host 加载。
  3. 脚本加载：手机通过 IP 访问时，组件会优先请求 /static/marzipano.js，请确保项目根目录 static 下已放置该文件（可从 uni_modules/xy-pano/static/ 复制）。
  4. 看失败原因：demo 页顶部会显示状态（如「加载中…」「加载完成」或具体错误信息），手机无需控制台即可看到失败原因。

手机如何看控制台和 Network

手机浏览器本身没有像 PC 那样的开发者工具，可以用下面方式查看：

• Android + Chrome：手机用 USB 连电脑，开启「开发者选项」里的「USB 调试」。电脑打开 Chrome，地址栏输入 chrome://inspect，在「Remote Target」里找到手机上的页面，点 inspect，即可打开该页的 DevTools（含 Console、Network）。
• iPhone + Safari：手机用数据线连 Mac，手机「设置 → Safari → 高级」打开「Web 检查器」。Mac 上打开 Safari，菜单栏「开发」里选你的 iPhone 和对应页面，即可用 Web 检查器查看控制台和网络。
• 不连电脑时：使用 demo 页顶部的状态栏，会显示「加载中…」「Marzipano 引擎加载失败」或「全景图加载失败（…）」等文字，便于直接判断是脚本未加载还是图片失败。

注意事项

• 图片格式：仅支持等矩形（equirectangular）2:1 比例的全景图，常见为 JPG/PNG。
• 跨域：使用网络地址时，图片所在域名需配置 CORS 或允许跨域。
• 小程序：微信/支付宝等小程序无 DOM 环境，组件会显示占位提示，建议使用 web-view 打开已部署的 H5 全景页。
• 陀螺仪：iOS 13+ 需用户授权设备运动权限；拒绝后仍可正常使用拖动与缩放。

兼容说明

• uni-app 版本：建议 3.6+
• Vue：Vue 3 组合式/选项式 API 均支持

开源协议

本插件使用的全景引擎 Marzipano 遵循 Apache-2.0 协议，版权归 Google Inc. 所有。
插件本身仅供学习与合规商用，使用前请阅读 Marzipano 官方说明：http://www.marzipano.net。

版本历史

v1.0.0

• 首版：等矩形全景渲染、拖动、缩放、陀螺仪、基础事件与占位。