const viewer = new Viewer({
  container: ...,  // （必填）容器
  panorama: ...,   // （必填）全景图
  // ... 其余可选配置
});

// container 支持两种写法：DOM 元素或 CSS 选择器字符串
const viewer1 = new Viewer({
  container: document.getElementById('my-viewer'),
  panorama: '/images/panorama.jpg',
});

const viewer2 = new Viewer({
  container: '#my-viewer',
  panorama: '/images/panorama.jpg',
});

// 字符串 URL
panorama: 'path/to/image.jpg',

// Blob 对象（例如从 canvas 导出）
panorama: blob,

// 函数（首次渲染时才调用，适合懒加载）
panorama: () => fetch('/api/panorama').then(r => r.blob()),

import { Viewer, CubemapAdapter } from '@photo-sphere-viewer/core';
import { MarkersPlugin } from '@photo-sphere-viewer/markers-plugin';

const viewer = new Viewer({
  container: '#viewer',
  panorama: 'panorama.jpg',

  // adapter: 直接传入类
  adapter: EquirectangularAdapter,

  // 或传入元组，第二个元素为适配器选项
  adapter: [EquirectangularAdapter, { resolution: 64 }],

  // plugins: 数组中每个元素同上
  plugins: [
    // 直接传入类（使用默认配置）
    MarkersPlugin,
    // 元组形式（传入插件配置）
    [MarkersPlugin, { clickEventOnMarker: false }],
  ],
});

const viewer = new Viewer({
  container: '#viewer',
  panorama: 'room.jpg',

  // 度数写法（自动转为弧度）
  defaultYaw: '45deg',      // 水平方向看向右侧 45 度
  defaultPitch: '10deg',    // 略向上看 10 度

  // 也可以用数字（弧度）
  // defaultYaw: Math.PI / 4,

  // 缩放级别 0-100，70 表示偏近（放大），20 表示偏远（缩小）
  defaultZoomLvl: 70,

  // 限制缩放范围：只允许 30° – 60° 之间
  minFov: 30,
  maxFov: 60,
});

// 适中畸变
fisheye: true,    // 等效于 fisheye: 1.0

// 强烈畸变
fisheye: 1.8,

// 轻微畸变
fisheye: 0.4,

const viewer = new Viewer({
  container: '#viewer',
  panorama: 'showroom.jpg',

  // 鼠标滚轮缩放——按住 Ctrl 才能滚动
  mousewheelCtrlKey: true,
  mousewheel: true,

  // 关闭鼠标拖拽（只允许通过按钮旋转）
  mousemove: false,

  // 移动端：要求双指才能旋转
  touchmoveTwoFingers: true,

  // 降低移动速度，让浏览更平缓
  moveSpeed: 0.5,

  // 关闭惯性，视角即刻停止
  moveInertia: false,

  // 键盘：仅在全屏时响应
  keyboard: 'fullscreen',
});

const viewer = new Viewer({
  container: '#viewer',
  panorama: 'scene.jpg',
  keyboard: true,
  keyboardActions: {
    // W/S 控制俯仰
    'KeyW':      'pitch-up',
    'KeyS':      'pitch-down',
    // A/D 控制水平旋转
    'KeyA':      'yaw-left',
    'KeyD':      'yaw-right',
    // Ctrl+Shift+Up 急速缩小
    'ctrl+shift+ArrowUp': 'zoom-out-fast',
    // 自定义缩写也支持: Ctrl 可写为 ctrl 或 control
  },
});

const viewer = new Viewer({
  container: '#viewer',
  panorama: 'cropped-pano.jpg',

  panoData: {
    fullWidth:   12000,    // 原始全景图的总宽度
    fullHeight:   6000,    // 原始全景图的总高度
    croppedWidth: 9600,    // 裁剪后图像的宽度
    croppedHeight: 4800,   // 裁剪后图像的高度
    croppedX:      1200,   // 裁剪区域的左上角 X 坐标
    croppedY:       600,   // 裁剪区域的左上角 Y 坐标
  },
});

const viewer = new Viewer({
  container: '#viewer',
  panorama: 'camera-pano.jpg',

  useXmpData: true,  // 自动读取 panoData 和 poseHeading
});

const viewer = new Viewer({
  container: '#viewer',
  panorama: 'room.jpg',

  // 拍摄时相机向右倾斜了 3 度，需要反向补偿
  sphereCorrection: {
    pan:   0,
    tilt:  0,
    roll: -3 * Math.PI / 180,
  },
});

const viewer = new Viewer({
  container: '#viewer',
  panorama: 'scene-a.jpg',

  defaultTransition: {
    speed: '20rpm',     // 旋转速度，接受 rpm（转/分）或秒数
    rotation: true,     // 是否让过渡路径走"最短圆弧"
    effect: 'fade',     // 过渡效果：'fade' 或 'none'
  },
});

const viewer = new Viewer({
  container: '#viewer',
  panorama: 'gallery.jpg',

  caption: '<h2>巴黎卢浮宫</h2>',
  description: `
    <p>拍摄日期：2026年7月</p>
    <p>摄影师：张三</p>
    <p>器材：Ricoh Theta Z1</p>
  `,

  downloadUrl:  '/images/gallery-full.jpg',
  downloadName: '卢浮宫全景.jpg',
});

const viewer = new Viewer({
  container: '#viewer',
  panorama: 'huge-pano.jpg',

  loadingImg: '/assets/spinner.svg',
  loadingTxt: '全景图加载中，请稍候...',
});

// 平滑旋转到指定位置，动画持续 2 秒
const anim = viewer.animate({
  yaw:   Math.PI / 2,    // 水平 90°
  pitch: 0.2,            // 略向上
  zoom:  75,             // 缩放到 75 级
  speed: '2rpm',         // 速度：每分钟 2 转
});

// 等待动画完成
await anim;

// 或在中途取消
setTimeout(() => anim.cancel(), 1000);

let currentAnim = null;

async function goToSpot(spot) {
  // 取消上一次动画
  currentAnim?.cancel();

  currentAnim = viewer.animate({
    yaw: spot.yaw,
    pitch: spot.pitch,
    zoom: spot.zoom,
    speed: '3rpm',
  });

  await currentAnim;
  console.log('已到达目标位置');
}

// 单页应用路由切换时，销毁旧的 viewer
router.beforeEach(() => {
  if (currentViewer) {
    currentViewer.destroy();
    currentViewer = null;
  }
});

// 获取标记插件实例并调用其方法
const markersPlugin = viewer.getPlugin('markers');
if (markersPlugin) {
  markersPlugin.addMarker({
    id: 'point-1',
    position: { yaw: Math.PI / 4, pitch: 0.1 },
  });
}

const pos = viewer.getPosition();
console.log(`水平: ${pos.yaw.toFixed(3)} rad, 垂直: ${pos.pitch.toFixed(3)} rad`);

// 应用场景：保存用户浏览状态
function saveViewState() {
  const { yaw, pitch } = viewer.getPosition();
  const zoom = viewer.getZoomLevel();
  localStorage.setItem('viewState', JSON.stringify({ yaw, pitch, zoom }));
}

// 恢复浏览状态
function restoreViewState() {
  const saved = JSON.parse(localStorage.getItem('viewState'));
  if (saved) {
    viewer.rotate({ yaw: saved.yaw, pitch: saved.pitch });
    viewer.zoom(saved.zoom);
  }
}

const level = viewer.getZoomLevel();
if (level > 80) {
  console.log('用户正在仔细观察细节');
}

// 立刻跳到水平 180°（回头看）
viewer.rotate({ yaw: Math.PI, pitch: 0 });

// 配合按钮点击时用得最多
button.addEventListener('click', () => {
  viewer.rotate({ yaw: 0, pitch: 0 }); // 一键回正
});

// 更新单个选项
viewer.setOption('minFov', 15);
viewer.setOption('moveSpeed', 2);

// 批量更新
viewer.setOptions({
  mousewheelCtrlKey: false,
  moveInertia: 0.5,
  fisheye: 1.2,
});

// 动态修改标题
viewer.setOption('caption', '<h3>新标题</h3>');

// 动态修改键盘行为
viewer.setOption('keyboard', true);

// 切换导航栏文字
viewer.setOption('description', '更新后的描述');

const transition = await viewer.setPanorama('/images/room-2.jpg', {
  transition: {
    speed: '10rpm',
    rotation: true,
    effect: 'fade',
  },
  caption: '第二展厅',
  description: '切换到第二展厅',
  panoData: {           // 新全景图可以有不同的裁剪信息
    fullWidth: 8000,
    fullHeight: 4000,
    croppedWidth: 8000,
    croppedHeight: 4000,
    croppedX: 0,
    croppedY: 0,
  },
  sphereCorrection: {   // 以及不同的校正参数
    pan: 0,
    tilt: 0.1,
    roll: 0,
  },
  showLoader: true,     // 切换期间显示加载动画
});

// 不同过渡效果对比

// 淡入淡出
await viewer.setPanorama('next.jpg', {
  transition: { effect: 'fade', speed: '5rpm' },
});

// 快速旋转切换（更有 VR 穿梭感）
await viewer.setPanorama('next.jpg', {
  transition: { effect: 'none', speed: '30rpm', rotation: true },
});

// 从 API 动态获取全景图 Blob
async function loadNextPanorama(id) {
  const response = await fetch(`/api/panorama/${id}`);
  const blob = await response.blob();

  await viewer.setPanorama(blob, {
    showLoader: true,
    transition: { speed: '8rpm', rotation: true },
  });
}

// 直接设置缩放级别（0-100）
viewer.zoom(60);

// 在当前级别上增加 10
viewer.zoomIn(10);

// 在当前级别上减少 5
viewer.zoomOut(5);

// 搭建一个缩放步进按钮
document.getElementById('zoom-in-btn').addEventListener('click', () => {
  const current = viewer.getZoomLevel();
  if (current < 100) {
    viewer.zoomIn(20);
  }
});

document.getElementById('zoom-out-btn').addEventListener('click', () => {
  const current = viewer.getZoomLevel();
  if (current > 0) {
    viewer.zoomOut(20);
  }
});

// 场景一：浏览器窗口缩放
window.addEventListener('resize', () => {
  viewer.needsUpdate();
});

// 场景二：侧边栏展开/收起
document.getElementById('toggle-sidebar').addEventListener('click', () => {
  sidebar.classList.toggle('collapsed');
  // 布局变化后告知 viewer
  setTimeout(() => viewer.needsUpdate(), 300); // 等 CSS 过渡完成后调用
});

// v5 推荐写法：使用事件常量
viewer.addEventListener('ready', handler);

// 也可以用静态属性（IDE 友好的常量）
// 从 @photo-sphere-viewer/core 导入 Viewer
viewer.addEventListener(Viewer.READY_EVENT, handler);

// 传统字符串同样有效
viewer.addEventListener('position-updated', (e) => {
  console.log(e.yaw, e.pitch, e.zoom);
});

// 移除事件
viewer.removeEventListener('position-updated', myHandler);

const viewer = new Viewer({ container: '#v', panorama: 'p.jpg' });

viewer.addEventListener('ready', () => {
  // 安全的操作起点
  console.log('Viewer 就绪');
  viewer.animate({ yaw: '90deg', pitch: '10deg', speed: '3rpm' });
});

function whenReady(viewer) {
  return new Promise(resolve => {
    viewer.addEventListener('ready', resolve, { once: true });
  });
}

const viewer = new Viewer({ container: '#v', panorama: 'p.jpg' });
await whenReady(viewer);
console.log('Viewer 已就绪，可以安全操作');

viewer.addEventListener('click', (e) => {
  const { yaw, pitch, right, dblclick } = e.detail;
  console.log(`点击位置: yaw=${yaw.toFixed(2)}, pitch=${pitch.toFixed(2)}`);
  console.log(`右键: ${right}, 双击: ${dblclick}`);
});

viewer.addEventListener('dblclick', (e) => {
  const { yaw, pitch } = e.detail;
  console.log(`双击: ${yaw.toFixed(2)}, ${pitch.toFixed(2)}`);
});

viewer.addEventListener('position-updated', (e) => {
  const { yaw, pitch } = e.detail;
  // 更新外部 UI 组件，如罗盘、缩略图导航
  updateCompass(yaw);
});

viewer.addEventListener('zoom-updated', (e) => {
  const zoomLevel = e.detail.zoom;
  document.getElementById('zoom-indicator').textContent = `${zoomLevel}%`;
});

viewer.addEventListener('before-render', (e) => {
  // e.detail 包含 { timestamp, delta }
  // 比如在这里更新第三人称视角的 avatar 朝向
});

viewer.addEventListener('render', (e) => {
  // 渲染完成后的回调
});

viewer.addEventListener('fullscreen-updated', (e) => {
  console.log('全屏状态:', e.detail.fullscreen);
});

viewer.addEventListener('size-updated', (e) => {
  const { width, height } = e.detail.size;
  console.log(`新尺寸: ${width} x ${height}`);
});

viewer.addEventListener('panorama-loaded', (e) => {
  console.log('当前全景图已加载:', e.detail.panorama);
  // 可以在这里隐藏自定义的加载指示器
});

viewer.addEventListener('stop-all', () => {
  console.log('所有动画已停止');
});

import { Viewer } from '@photo-sphere-viewer/core';

viewer.addEventListener(Viewer.READY_EVENT,              handler);
viewer.addEventListener(Viewer.CLICK_EVENT,              handler);
viewer.addEventListener(Viewer.DBLCLICK_EVENT,           handler);
viewer.addEventListener(Viewer.POSITION_UPDATED_EVENT,   handler);
viewer.addEventListener(Viewer.ZOOM_UPDATED_EVENT,       handler);
viewer.addEventListener(Viewer.BEFORE_RENDER_EVENT,      handler);
viewer.addEventListener(Viewer.RENDER_EVENT,             handler);
viewer.addEventListener(Viewer.FULLSCREEN_UPDATED_EVENT, handler);
viewer.addEventListener(Viewer.SIZE_UPDATED_EVENT,       handler);
viewer.addEventListener(Viewer.PANORAMA_LOADED_EVENT,    handler);
viewer.addEventListener(Viewer.STOP_ALL_EVENT,           handler);

import { Viewer } from '@photo-sphere-viewer/core';

const viewer = new Viewer({
  container: '#viewer',
  panorama: 'room.jpg',
});

// 就绪后：开始自动导览
viewer.addEventListener('ready', () => {
  startAutoTour();
});

// 跟踪用户浏览路径（每帧更新）
viewer.addEventListener('position-updated', (e) => {
  path.push({ time: Date.now(), yaw: e.detail.yaw, pitch: e.detail.pitch });
});

// 全景图切换后：更新侧边栏信息
viewer.addEventListener('panorama-loaded', (e) => {
  updateSidebarInfo(e.detail.panorama);
});

// 销毁前：保存状态
window.addEventListener('beforeunload', () => {
  const { yaw, pitch } = viewer.getPosition();
  localStorage.setItem('lastView', JSON.stringify({ yaw, pitch }));
  viewer.destroy();
});

const viewer = new Viewer({
  container: '#viewer',
  panorama: 'room.jpg',

  // 简洁的默认导航栏
  navbar: [
    'zoom',       // 缩放按钮组
    'move',       // 移动按钮组
    'fullscreen', // 全屏
  ],
});

navbar: [
  'zoomOut',
  'zoomRange',
  'zoomIn',
  'download',
  'fullscreen',
],

const viewer = new Viewer({
  container: '#viewer',
  panorama: 'room.jpg',

  navbar: [
    'zoom',
    'fullscreen',
    // 自定义：一键回正按钮
    {
      id: 'reset-view',
      title: '回正视角',
      content: `
        <svg viewBox="0 0 24 24" width="20" height="20"
             fill="none" stroke="currentColor" stroke-width="2">
          <circle cx="12" cy="12" r="10"/>
          <polyline points="8,12 12,8 16,12"/>
          <line x1="12" y1="16" x2="12" y2="8"/>
        </svg>
      `,
      className: 'reset-btn',
      disabled: false,
      visible: true,
      onClick(viewer) {
        viewer.rotate({ yaw: 0, pitch: 0 });
        viewer.zoom(50);
      },
    },
  ],
});

const navbar = viewer.navbar;

// 获取按钮对象
const resetBtn = navbar.getButton('reset-view');
const fullscreenBtn = navbar.getButton('fullscreen');

// 禁用/启用
resetBtn.disabled = true;

// 隐藏/显示
resetBtn.visible = false;

// 修改提示
resetBtn.title = '点击回正视角';

// 修改内容（如切换图标）
resetBtn.content = '... 新的 SVG ...';

// 修改点击行为
resetBtn.onClick = (viewer) => { ... };

import { AutorotatePlugin } from '@photo-sphere-viewer/autorotate-plugin';
import { GyroscopePlugin } from '@photo-sphere-viewer/gyroscope-plugin';

const viewer = new Viewer({
  container: '#viewer',
  panorama: 'room.jpg',
  plugins: [AutorotatePlugin, GyroscopePlugin],
  // 插件按钮会出现在导航栏中，顺序按 navbar 数组
  navbar: [
    'zoom',
    'autorotate',  // 插件注册的按钮
    'gyroscope',   // 插件注册的按钮
    'fullscreen',
  ],
});

// 获取按钮对象后，手动挂载其 DOM
const zoomOutBtn = viewer.navbar.getButton('zoomOut');
document.getElementById('custom-toolbar').appendChild(zoomOutBtn.container);

import { Cache } from '@photo-sphere-viewer/core';

// 修改全局缓存策略（在创建 Viewer 之前设置）
Cache.enabled  = true;    // 启用缓存（默认 true）
Cache.ttl      = 10;      // 缓存保留时长：10 分钟
Cache.maxItems = 50;      // 最多缓存 50 个纹理

// 场景：一个 20 张 16K 全景图的虚拟展厅
// 每张纹理会占用约 100MB 显存，全部缓存会导致 OOM
Cache.enabled = true;
Cache.maxItems = 5;   // 仅缓存最近 5 张
Cache.ttl = 15;       // 15 分钟后自动清除

const viewer = new Viewer({
  container: '#viewer',
  panorama: 'room.jpg',

  lang: {
    loading:          '加载中...',
    autorotate:       '自动旋转',
    zoom:             '缩放',
    zoomOut:          '缩小',
    zoomIn:           '放大',
    move:             '移动',
    moveLeft:         '向左',
    moveRight:        '向右',
    moveUp:           '向上',
    moveDown:         '向下',
    download:         '下载',
    fullscreen:       '全屏',
    menu:             '菜单',
    close:            '关闭',
    twoFingers:       '使用双指移动',
    ctrlZoom:         '按住 Ctrl 键滚动以缩放',
    loadError:        '全景图加载失败',
    panorama:         '全景图',
    gyroscope:        '陀螺仪',
    stereo:           '立体视图',
    stereoNotification:'点击以退出立体视图',
    pleaseRotate:     '请旋转您的设备',
    autorotatePaused: '自动旋转已暂停',
  },
});

lang: {
  // ... 标准键
  'custom-tooltip': '点击查看详情',
  'floor-plan':     '楼层平面图',
},

// 在自定义按钮中引用
{
  id: 'floor-plan-btn',
  title: viewer.config.lang['floor-plan'],
  // ...
}