更新记录

1.3.0（2026-03-23） 下载此版本

新增多场景切换功能

1.2.0（2026-03-11） 下载此版本

新增补天补地功能

1.1.0（2026-03-09） 下载此版本

新增VR模式、漫游以及热点等功能

平台兼容性

uni-app(4.0)

uni-app x(4.0)

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

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

特性

• 等矩形（equirectangular）2:1 全景图渲染
• 视角模式：普通、VR 左右分屏（可选）
• 手势拖动、双指缩放
• 移动端陀螺仪视角跟随（可选）
• 自动漫游：视角匀速水平旋转，可配置速度
• 热点系统：支持 info / link / image / icon 四种类型
• 补天补地：在天顶/地底叠加贴图，遮盖三脚架、接缝
• 支持网络 HTTPS 与本地静态资源地址
• 加载中/加载失败占位，不白屏
• 符合 DCloud 插件市场规范，无远程脚本、无隐私收集

接入步骤

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

<template>
  <view class="panorama-container">
    <marzipano-panorama
      ref="panoRef"
      :src="panoramaSources"
      :sceneIndex="activeSceneIndex"
      :viewMode="enableVr ? 'vr' : 'normal'"
      :enableGyro="enableGyro"
      :enableDrag="enableDrag"
      :enableZoom="enableZoom"
      :enableAutoTour="enableAutoTour"
      :autoTourSpeed="autoTourSpeed"
      :initialView="{ pitch: 0, yaw: 0, fov: 70 }"
      :minFov="30"
      :maxFov="100"
      :enablePatch="enablePatch"
      :patchImage="patchImage"
      @loadComplete="handleLoadComplete"
      @loadError="handleLoadError"
      @sceneChange="handleSceneChange"
    />
  </view>

  <view class="controls">
    <button @click="multiScene = !multiScene">
      {{ multiScene ? '当前：多场景' : '当前：单场景' }}
    </button>
    <button @click="switchPrev">上一场景</button>
    <button @click="switchNext">下一场景</button>
  </view>
</template>

<script setup>
import { computed, ref } from 'vue'

const panoRef = ref(null)
const multiScene = ref(true)
const activeSceneIndex = ref(0)

// 单场景：传单元素数组；多场景：传多元素数组
const sceneList = [
  'https://www.marzipano.net/media/equirect/angra.jpg',
  'https://pannellum.org/images/alma.jpg',
  'https://pannellum.org/images/cerro-toco-0.jpg'
]
const panoramaSources = computed(() => {
  return multiScene.value ? sceneList : [sceneList[0]]
})

const enableVr = ref(false)
const enableGyro = ref(false)
const enableDrag = ref(true)
const enableZoom = ref(true)
const enableAutoTour = ref(false)
const autoTourSpeed = ref(15)
const enablePatch = ref(false)
const patchImage = ref('/static/补.png')

const handleLoadComplete = () => console.log('加载完成')
const handleLoadError = (e) => console.error('加载失败', e)
const handleSceneChange = (payload) => {
  activeSceneIndex.value = Number(payload?.index || 0)
}

const switchPrev = () => {
  if (!panoramaSources.value.length) return
  const count = panoramaSources.value.length
  activeSceneIndex.value = (activeSceneIndex.value - 1 + count) % count
}
const switchNext = () => {
  if (!panoramaSources.value.length) return
  const count = panoramaSources.value.length
  activeSceneIndex.value = (activeSceneIndex.value + 1) % count
}
</script>

<style scoped>
.panorama-container { width: 100vw; height: 100vh; }
.controls {
  position: fixed;
  left: 12px;
  bottom: 12px;
  z-index: 1000;
  display: flex;
  gap: 8px;
}
</style>

属性（Props）

事件（Events）

实例方法（通过 ref 调用）

局域网 / 手机访问

• 若在 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. 看失败原因：加载失败时会弹出 toast 或在组件内显示「加载失败」及错误信息，可据此判断是脚本未加载还是图片失败。

移动端 H5 不显示全景的常见原因

手机如何看控制台和 Network

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

• Android + Chrome：手机用 USB 连电脑，开启「开发者选项」里的「USB 调试」。电脑打开 Chrome，地址栏输入 chrome://inspect，在「Remote Target」里找到手机上的页面，点 inspect，即可打开该页的 DevTools（含 Console、Network）。
• iPhone + Safari：手机用数据线连 Mac，手机「设置 → Safari → 高级」打开「Web 检查器」。Mac 上打开 Safari，菜单栏「开发」里选你的 iPhone 和对应页面，即可用 Web 检查器查看控制台和网络。
• 不连电脑时：加载失败会弹出 toast 或在组件内显示错误信息，可据此判断是脚本未加载还是图片失败。

陀螺仪在 H5 移动端（iOS/Android 浏览器）的限制

陀螺仪必须在「安全上下文」下才能工作，即页面必须是 HTTPS 或 localhost。

• 用 http://电脑IP:端口 在手机浏览器访问时，属于非安全上下文，陀螺仪不会生效（iOS 会提示未授权，Android 可能静默不触发事件）。
• 若要在手机上测试陀螺仪，可任选其一：
  1. 本机用 localhost：仅在 PC 浏览器访问 http://localhost:端口 测试。
  2. 开发环境开 HTTPS：给 H5 开发服务配置 HTTPS（如 Vite 的 @vitejs/plugin-basic-ssl 或 server.https），手机用 https://电脑IP:端口 访问，打开陀螺仪开关即可（H5 端不单独显示「点击授权」，在开关切换的同一手势内完成授权）。
  3. 内网穿透：用 localtunnel 等工具把本地端口映射为公网 HTTPS 地址（如 https://xxx.localtunnel.me），手机用该地址访问后打开陀螺仪开关即可。

本插件示例项目（xy-pano Demo） 已集成 @vitejs/plugin-basic-ssl，在 HBuilderX 中运行到浏览器即可用 HTTPS 在手机上测试陀螺仪，完整步骤见项目根目录 README.md 的「使用 HTTPS 在手机上测试陀螺仪」一节。Demo 中示例全景图约 2MB，网速不佳时加载可能较慢，请耐心等待几秒。

注意事项

• 图片格式：仅支持等矩形（equirectangular）2:1 比例的全景图，常见为 JPG/PNG。
• 跨域：使用网络地址时，图片所在域名需配置 CORS 或允许跨域。
• 小程序：微信/支付宝等小程序无 DOM 环境，组件会显示占位提示，建议使用 web-view 打开已部署的 H5 全景页。
• 陀螺仪：H5 下需 HTTPS 或 localhost；Marzipano 在 H5 端不单独显示申请陀螺仪权限的按钮，在用户打开陀螺仪开关的同一手势内完成授权（iOS 13+ 会弹出系统权限）。拒绝或非安全上下文时仍可正常使用拖动与缩放。

兼容说明

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

开源协议

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

版本历史

v1.2.0（2026-03-11）

• 新增补天补地功能（enablePatch / patchImage），在天顶和地底叠加贴图遮盖三脚架、接缝等
• 组件内部自动管理全景层与页面层的 z-index 层级，使用者无需手动处理 teleport 或全局样式
• 兼容 H5 与 App 端，移除对 teleport 的依赖

v1.1.0（2026-03-09）

• 新增 VR 左右分屏模式（viewMode: 'vr'）
• 新增自动漫游（enableAutoTour / autoTourSpeed）
• 新增热点系统（hotspots），支持 info / link / image / icon 四种类型

v1.0.1（2026-03-07）

• Demo 支持 HTTPS，方便手机端测试陀螺仪
• 修复陀螺仪权限申请相关问题

v1.0.0（2026-03-02）

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

TODO / 版本计划

以下是计划中的功能，不代表最终承诺，优先级可能调整。欢迎提 Issue 或反馈需求。

近期（v1.3.x）

• [ ] 补天补地支持分别设置天顶图和地底图（patchSkyImage / patchGroundImage）
• [ ] 补天补地贴图尺寸可配置（patchSize）
• [ ] 热点支持自定义 HTML 模板（通过 slot 或 render 函数）
• [ ] 新增场景切换功能，支持多个全景图之间平滑过渡

中期（v1.4.x ~ v1.5.x）

• [ ] 立方体贴图（cube map）格式支持，除等矩形外的第二种输入格式
• [ ] 多分辨率瓦片加载（multi-resolution tiles），提升大图加载性能
• [ ] 内置小行星视角（little planet）效果
• [ ] 热点支持动画效果（呼吸、弹跳、脉冲等）
• [ ] 初始加载动画（从小行星视角展开到正常视角）

远期（v2.x）

• [ ] 视频全景（video panorama）支持
• [ ] 多楼层 / 多房间漫游，支持场景地图导航
• [ ] 内置标注编辑器（可视化拖拽添加热点）
• [ ] 支持微信小程序原生渲染（基于 WebGL canvas 方案）
• [ ] 性能优化：WebWorker 解码、渐进式加载、自适应画质

长期（v3.x）

• [ ] 配套 uni-admin 管理端插件：在 uni-admin 后台上传、管理全景图，支持场景编辑、热点配置、补天补地设置等可视化操作
• [ ] 对接 uniCloud 云存储：全景图直传 uniCloud（阿里云 / 腾讯云），自动生成 CDN 访问地址，无需自建图片服务器
• [ ] 移动端展示插件：提供开箱即用的全景展示页模板（App + H5），从 uniCloud 拉取场景数据并渲染，支持分享链接直达
• [ ] 完整的「上传→管理→展示」闭环：admin 上传 → uniCloud 存储 → 移动端 / H5 展示，一套方案覆盖全流程
• [ ] 支持全景图自动切片：上传原图后服务端自动生成多分辨率瓦片，配合组件的瓦片加载实现超大图秒开