@ericchen1990/pano-view 2.4.0 → 2.5.0

package/README.md

@@ -113,6 +113,7 @@ the stylesheet, the overlays still mount, but they render unstyled.
 
 ### Hooks and helpers
 
+- `usePanoViewer` — wrap the viewer ref in reusable parent-side commands
 - `usePanoEvents` — subscribe to viewer events inside a custom child ([`PanoEvents`](#panoevents))
 - Coordinate helpers — `normalizePanoPosition`, `normalizePanoYaw`, `clampPanoPitch`, `panoPositionToVector3`, `vector3ToPanoPosition` ([Panorama coordinate events](#panorama-coordinate-events))
 - `cycleSceneId` — wrap previous/next scene ids ([`KeyboardControls`](#keyboardcontrols))
@@ -126,25 +127,24 @@ the stylesheet, the overlays still mount, but they render unstyled.
 Angles are public degrees. Positive yaw looks right and positive pitch looks up.
 
 ```tsx
-import { useRef } from "react";
 import "@ericchen1990/pano-view/styles.css";
 import {
   PanoViewer,
   Sphere,
   AutoRotate,
-  type PanoViewerHandle,
+  usePanoViewer,
 } from "@ericchen1990/pano-view";
 
 export function ControlledExample() {
-  const ref = useRef<PanoViewerHandle>(null);
+  const viewer = usePanoViewer();
 
   return (
     <>
-      <button onClick={() => ref.current?.setView({ yaw: 90, fov: 55 })}>
+      <button onClick={() => viewer.setView({ yaw: 90, fov: 55 })}>
         Look right
       </button>
       <PanoViewer
-        ref={ref}
+        ref={viewer.ref}
         controls={{
           inertia: true,
           rotateDamping: 14,
@@ -183,18 +183,17 @@ Methods that depend on an unmounted child component (e.g. `enterVR` without `<We
 ### Fullscreen
 
 ```tsx
-import { useRef } from "react";
-import { PanoViewer, Sphere, type PanoViewerHandle } from "@ericchen1990/pano-view";
+import { PanoViewer, Sphere, usePanoViewer } from "@ericchen1990/pano-view";
 
 function FullscreenExample() {
-  const ref = useRef<PanoViewerHandle>(null);
+  const viewer = usePanoViewer();
 
   return (
     <>
-      <button onClick={() => void ref.current?.enterFullscreen()}>Enter fullscreen</button>
-      <button onClick={() => void ref.current?.exitFullscreen()}>Exit fullscreen</button>
-      <button onClick={() => console.log(ref.current?.isFullscreen())}>Is fullscreen?</button>
-      <PanoViewer ref={ref} style={{ height: 560 }}>
+      <button onClick={() => void viewer.enterFullscreen()}>Enter fullscreen</button>
+      <button onClick={() => void viewer.exitFullscreen()}>Exit fullscreen</button>
+      <button onClick={() => console.log(viewer.isFullscreen())}>Is fullscreen?</button>
+      <PanoViewer ref={viewer.ref} style={{ height: 560 }}>
         <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
       </PanoViewer>
     </>
@@ -204,14 +203,14 @@ function FullscreenExample() {
 
 ### Imperative scene switching
 
-Use `defaultActiveSceneId` for uncontrolled mode — imperative calls update the internal state directly. For controlled mode keep passing `activeSceneId`; imperative calls invoke `onActiveSceneIdChange` so the parent can update its state.
+Use `usePanoViewer()` to shorten parent-side commands to `viewer.setScene("roof")`. Keep using controlled `activeSceneId` when the host UI needs to render the current scene id reactively. For uncontrolled mode, `defaultActiveSceneId` still lets imperative calls update the internal state directly.
 
 ```tsx
-import { useRef } from "react";
+import { useState } from "react";
 import {
   PanoViewer,
   Scenes,
-  type PanoViewerHandle,
+  usePanoViewer,
   type Scene,
 } from "@ericchen1990/pano-view";
 
@@ -221,16 +220,23 @@ const scenes: Scene[] = [
 ];
 
 function SceneExample() {
-  const ref = useRef<PanoViewerHandle>(null);
+  const viewer = usePanoViewer();
+  const [activeSceneId, setActiveSceneId] = useState("lobby");
 
   return (
     <>
-      <button onClick={() => ref.current?.setScene("roof")}>Go to roof</button>
-      <button onClick={() => ref.current?.nextScene()}>Next</button>
-      <button onClick={() => ref.current?.previousScene()}>Previous</button>
-      <p>Current: {ref.current?.getActiveSceneId()}</p>
-      <PanoViewer ref={ref} style={{ height: 560 }}>
-        <Scenes defaultActiveSceneId="lobby" scenes={scenes} transition="dissolve" />
+      <button onClick={() => setActiveSceneId("roof")}>Go to roof</button>
+      <button onClick={() => viewer.nextScene()}>Next</button>
+      <button onClick={() => viewer.previousScene()}>Previous</button>
+      <button onClick={() => viewer.setScene("roof")}>Jump via hook</button>
+      <p>Current: {activeSceneId}</p>
+      <PanoViewer ref={viewer.ref} style={{ height: 560 }}>
+        <Scenes
+          activeSceneId={activeSceneId}
+          onActiveSceneIdChange={setActiveSceneId}
+          scenes={scenes}
+          transition="dissolve"
+        />
       </PanoViewer>
     </>
   );
@@ -242,25 +248,24 @@ function SceneExample() {
 `enterVR` and `requestVRPermission` must be called from a user gesture.
 
 ```tsx
-import { useRef } from "react";
-import { PanoViewer, Sphere, WebVR, type PanoViewerHandle } from "@ericchen1990/pano-view";
+import { PanoViewer, Sphere, WebVR, usePanoViewer } from "@ericchen1990/pano-view";
 
 function VRExample() {
-  const ref = useRef<PanoViewerHandle>(null);
+  const viewer = usePanoViewer();
 
   return (
     <>
       <button
         onClick={async () => {
-          await ref.current?.requestVRPermission();
-          await ref.current?.enterVR();
+          await viewer.requestVRPermission();
+          await viewer.enterVR();
         }}
       >
         Enter VR
       </button>
-      <button onClick={() => void ref.current?.exitVR()}>Exit VR</button>
-      <button onClick={() => console.log(ref.current?.getVRMode())}>Mode?</button>
-      <PanoViewer ref={ref} style={{ height: 560 }}>
+      <button onClick={() => void viewer.exitVR()}>Exit VR</button>
+      <button onClick={() => console.log(viewer.getVRMode())}>Mode?</button>
+      <PanoViewer ref={viewer.ref} style={{ height: 560 }}>
         <WebVR />
         <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
       </PanoViewer>
@@ -271,31 +276,31 @@ function VRExample() {
 
 ### Custom video controls
 
-Set `controls={false}` on `PanoVideo` and drive playback from the viewer ref. Use `subscribeVideo` with `useSyncExternalStore` for reactive snapshots.
+Set `controls={false}` on `PanoVideo` and drive playback from `usePanoViewer()`. Use `subscribeVideo` with `useSyncExternalStore` for reactive snapshots.
 
 ```tsx
-import { useRef, useSyncExternalStore } from "react";
+import { useSyncExternalStore } from "react";
 import {
   PanoViewer,
   PanoVideo,
-  type PanoViewerHandle,
+  usePanoViewer,
 } from "@ericchen1990/pano-view";
 
 function VideoExample() {
-  const ref = useRef<PanoViewerHandle>(null);
+  const viewer = usePanoViewer();
 
   const snapshot = useSyncExternalStore(
-    (cb) => ref.current?.subscribeVideo(cb) ?? (() => {}),
-    () => ref.current?.getVideo()?.getSnapshot() ?? null,
+    viewer.subscribeVideo,
+    () => viewer.getVideo()?.getSnapshot() ?? null,
     () => null,
   );
 
   return (
     <>
-      <button onClick={() => void ref.current?.toggleVideo()}>
+      <button onClick={() => void viewer.toggleVideo()}>
         {snapshot?.playing ? "Pause" : "Play"}
       </button>
-      <button onClick={() => ref.current?.toggleVideoMuted()}>
+      <button onClick={() => viewer.toggleVideoMuted()}>
         {snapshot?.muted ? "Unmute" : "Mute"}
       </button>
       {snapshot && (
@@ -304,10 +309,10 @@ function VideoExample() {
           min={0}
           max={snapshot.duration}
           value={snapshot.currentTime}
-          onChange={(e) => ref.current?.seekVideo(Number(e.target.value))}
+          onChange={(e) => viewer.seekVideo(Number(e.target.value))}
         />
       )}
-      <PanoViewer ref={ref} style={{ height: 560 }}>
+      <PanoViewer ref={viewer.ref} style={{ height: 560 }}>
         <PanoVideo controls={false} src="/tour.mp4" />
       </PanoViewer>
     </>
@@ -317,32 +322,32 @@ function VideoExample() {
 
 ### Custom background audio controls
 
-`BackgroundAudio` supports uncontrolled mode — omit `playing` and use `defaultPlaying` instead. Drive it from the viewer ref.
+`BackgroundAudio` supports uncontrolled mode — omit `playing` and use `defaultPlaying` instead. Drive it from `usePanoViewer()`.
 
 ```tsx
-import { useRef, useSyncExternalStore } from "react";
+import { useSyncExternalStore } from "react";
 import {
   PanoViewer,
   Sphere,
   BackgroundAudio,
-  type PanoViewerHandle,
+  usePanoViewer,
 } from "@ericchen1990/pano-view";
 
 function BGMExample() {
-  const ref = useRef<PanoViewerHandle>(null);
+  const viewer = usePanoViewer();
 
   const snapshot = useSyncExternalStore(
-    (cb) => ref.current?.subscribeBackgroundAudio(cb) ?? (() => {}),
-    () => ref.current?.getBackgroundAudio()?.getSnapshot() ?? null,
+    viewer.subscribeBackgroundAudio,
+    () => viewer.getBackgroundAudio()?.getSnapshot() ?? null,
     () => null,
   );
 
   return (
     <>
-      <button onClick={() => ref.current?.toggleBackgroundAudio()}>
+      <button onClick={() => viewer.toggleBackgroundAudio()}>
         {snapshot?.playing ? "Pause BGM" : "Play BGM"}
       </button>
-      <button onClick={() => ref.current?.toggleBackgroundAudioMuted()}>
+      <button onClick={() => viewer.toggleBackgroundAudioMuted()}>
         {snapshot?.muted ? "Unmute" : "Mute"}
       </button>
       <input
@@ -351,11 +356,9 @@ function BGMExample() {
         max={1}
         step={0.01}
         value={snapshot?.volume ?? 1}
-        onChange={(e) =>
-          ref.current?.setBackgroundAudioVolume(Number(e.target.value))
-        }
+        onChange={(e) => viewer.setBackgroundAudioVolume(Number(e.target.value))}
       />
-      <PanoViewer ref={ref} style={{ height: 560 }}>
+      <PanoViewer ref={viewer.ref} style={{ height: 560 }}>
         <BackgroundAudio defaultPlaying src="/bgm.mp3" />
         <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
       </PanoViewer>
@@ -367,29 +370,28 @@ function BGMExample() {
 ### All-in-one example
 
 ```tsx
-import { useRef } from "react";
 import {
   PanoViewer,
   Scenes,
   WebVR,
   PanoVideo,
   BackgroundAudio,
-  type PanoViewerHandle,
+  usePanoViewer,
 } from "@ericchen1990/pano-view";
 
 function TourPlayer() {
-  const ref = useRef<PanoViewerHandle>(null);
+  const viewer = usePanoViewer();
 
   return (
     <>
       <nav>
-        <button onClick={() => ref.current?.previousScene()}>← Prev</button>
-        <button onClick={() => ref.current?.nextScene()}>Next →</button>
-        <button onClick={() => void ref.current?.toggleFullscreen()}>Fullscreen</button>
-        <button onClick={() => void ref.current?.enterVR()}>Enter VR</button>
-        <button onClick={() => ref.current?.toggleBackgroundAudio()}>BGM</button>
+        <button onClick={() => viewer.previousScene()}>← Prev</button>
+        <button onClick={() => viewer.nextScene()}>Next →</button>
+        <button onClick={() => void viewer.toggleFullscreen()}>Fullscreen</button>
+        <button onClick={() => void viewer.enterVR()}>Enter VR</button>
+        <button onClick={() => viewer.toggleBackgroundAudio()}>BGM</button>
       </nav>
-      <PanoViewer ref={ref} style={{ height: "100vh" }}>
+      <PanoViewer ref={viewer.ref} style={{ height: "100vh" }}>
         <WebVR />
         <BackgroundAudio defaultPlaying src="/bgm.mp3" />
         <Scenes defaultActiveSceneId="lobby" scenes={scenes} transition="dissolve" />

package/README.zh-CN.md

@@ -96,6 +96,7 @@ import "@ericchen1990/pano-view/styles.css";
 
 ### Hook 与辅助工具
 
+- `usePanoViewer` — 将 viewer ref 封装成可复用的父组件侧命令
 - `usePanoEvents` — 在自定义子组件内订阅查看器事件（[`PanoEvents`](#panoevents)）
 - 坐标辅助函数 — `normalizePanoPosition`、`normalizePanoYaw`、`clampPanoPitch`、`panoPositionToVector3`、`vector3ToPanoPosition`（[全景坐标事件](#全景坐标事件)）
 - `cycleSceneId` — 循环上一/下一场景 id（[`KeyboardControls`](#keyboardcontrols)）
@@ -109,25 +110,24 @@ import "@ericchen1990/pano-view/styles.css";
 角度对外以度为单位。偏航（yaw）为正表示向右看，俯仰（pitch）为正表示向上看。
 
 ```tsx
-import { useRef } from "react";
 import "@ericchen1990/pano-view/styles.css";
 import {
   PanoViewer,
   Sphere,
   AutoRotate,
-  type PanoViewerHandle,
+  usePanoViewer,
 } from "@ericchen1990/pano-view";
 
 export function ControlledExample() {
-  const ref = useRef<PanoViewerHandle>(null);
+  const viewer = usePanoViewer();
 
   return (
     <>
-      <button onClick={() => ref.current?.setView({ yaw: 90, fov: 55 })}>
+      <button onClick={() => viewer.setView({ yaw: 90, fov: 55 })}>
         Look right
       </button>
       <PanoViewer
-        ref={ref}
+        ref={viewer.ref}
         controls={{
           inertia: true,
           rotateDamping: 14,
@@ -166,18 +166,17 @@ export function ControlledExample() {
 ### 全屏
 
 ```tsx
-import { useRef } from "react";
-import { PanoViewer, Sphere, type PanoViewerHandle } from "@ericchen1990/pano-view";
+import { PanoViewer, Sphere, usePanoViewer } from "@ericchen1990/pano-view";
 
 function FullscreenExample() {
-  const ref = useRef<PanoViewerHandle>(null);
+  const viewer = usePanoViewer();
 
   return (
     <>
-      <button onClick={() => void ref.current?.enterFullscreen()}>进入全屏</button>
-      <button onClick={() => void ref.current?.exitFullscreen()}>退出全屏</button>
-      <button onClick={() => console.log(ref.current?.isFullscreen())}>是否全屏？</button>
-      <PanoViewer ref={ref} style={{ height: 560 }}>
+      <button onClick={() => void viewer.enterFullscreen()}>进入全屏</button>
+      <button onClick={() => void viewer.exitFullscreen()}>退出全屏</button>
+      <button onClick={() => console.log(viewer.isFullscreen())}>是否全屏？</button>
+      <PanoViewer ref={viewer.ref} style={{ height: 560 }}>
         <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
       </PanoViewer>
     </>
@@ -187,14 +186,14 @@ function FullscreenExample() {
 
 ### 命令式切换场景
 
-使用 `defaultActiveSceneId` 为非受控模式 — 命令式调用直接更新内部状态。受控模式继续传 `activeSceneId`，命令式调用会触发 `onActiveSceneIdChange` 以便父组件更新 state。
+使用 `usePanoViewer()` 可将父组件侧命令缩短为 `viewer.setScene("roof")`。当宿主 UI 需要响应式显示当前场景 id 时，仍建议继续使用受控 `activeSceneId`。若使用非受控模式，`defaultActiveSceneId` 依然允许命令式调用直接更新内部状态。
 
 ```tsx
-import { useRef } from "react";
+import { useState } from "react";
 import {
   PanoViewer,
   Scenes,
-  type PanoViewerHandle,
+  usePanoViewer,
   type Scene,
 } from "@ericchen1990/pano-view";
 
@@ -204,16 +203,23 @@ const scenes: Scene[] = [
 ];
 
 function SceneExample() {
-  const ref = useRef<PanoViewerHandle>(null);
+  const viewer = usePanoViewer();
+  const [activeSceneId, setActiveSceneId] = useState("lobby");
 
   return (
     <>
-      <button onClick={() => ref.current?.setScene("roof")}>去天台</button>
-      <button onClick={() => ref.current?.nextScene()}>下一场景</button>
-      <button onClick={() => ref.current?.previousScene()}>上一场景</button>
-      <p>当前: {ref.current?.getActiveSceneId()}</p>
-      <PanoViewer ref={ref} style={{ height: 560 }}>
-        <Scenes defaultActiveSceneId="lobby" scenes={scenes} transition="dissolve" />
+      <button onClick={() => setActiveSceneId("roof")}>去天台</button>
+      <button onClick={() => viewer.nextScene()}>下一场景</button>
+      <button onClick={() => viewer.previousScene()}>上一场景</button>
+      <button onClick={() => viewer.setScene("roof")}>通过 hook 跳转</button>
+      <p>当前: {activeSceneId}</p>
+      <PanoViewer ref={viewer.ref} style={{ height: 560 }}>
+        <Scenes
+          activeSceneId={activeSceneId}
+          onActiveSceneIdChange={setActiveSceneId}
+          scenes={scenes}
+          transition="dissolve"
+        />
       </PanoViewer>
     </>
   );
@@ -225,25 +231,24 @@ function SceneExample() {
 `enterVR` 与 `requestVRPermission` 须在用户手势中调用。
 
 ```tsx
-import { useRef } from "react";
-import { PanoViewer, Sphere, WebVR, type PanoViewerHandle } from "@ericchen1990/pano-view";
+import { PanoViewer, Sphere, WebVR, usePanoViewer } from "@ericchen1990/pano-view";
 
 function VRExample() {
-  const ref = useRef<PanoViewerHandle>(null);
+  const viewer = usePanoViewer();
 
   return (
     <>
       <button
         onClick={async () => {
-          await ref.current?.requestVRPermission();
-          await ref.current?.enterVR();
+          await viewer.requestVRPermission();
+          await viewer.enterVR();
         }}
       >
         进入 VR
       </button>
-      <button onClick={() => void ref.current?.exitVR()}>退出 VR</button>
-      <button onClick={() => console.log(ref.current?.getVRMode())}>当前模式？</button>
-      <PanoViewer ref={ref} style={{ height: 560 }}>
+      <button onClick={() => void viewer.exitVR()}>退出 VR</button>
+      <button onClick={() => console.log(viewer.getVRMode())}>当前模式？</button>
+      <PanoViewer ref={viewer.ref} style={{ height: 560 }}>
         <WebVR />
         <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
       </PanoViewer>
@@ -254,31 +259,31 @@ function VRExample() {
 
 ### 自定义视频控件
 
-将 `PanoVideo` 的 `controls` 设为 `false`，从 viewer ref 驱动播放。配合 `useSyncExternalStore` 使用 `subscribeVideo` 获取响应式快照。
+将 `PanoVideo` 的 `controls` 设为 `false`，通过 `usePanoViewer()` 驱动播放。配合 `useSyncExternalStore` 使用 `subscribeVideo` 获取响应式快照。
 
 ```tsx
-import { useRef, useSyncExternalStore } from "react";
+import { useSyncExternalStore } from "react";
 import {
   PanoViewer,
   PanoVideo,
-  type PanoViewerHandle,
+  usePanoViewer,
 } from "@ericchen1990/pano-view";
 
 function VideoExample() {
-  const ref = useRef<PanoViewerHandle>(null);
+  const viewer = usePanoViewer();
 
   const snapshot = useSyncExternalStore(
-    (cb) => ref.current?.subscribeVideo(cb) ?? (() => {}),
-    () => ref.current?.getVideo()?.getSnapshot() ?? null,
+    viewer.subscribeVideo,
+    () => viewer.getVideo()?.getSnapshot() ?? null,
     () => null,
   );
 
   return (
     <>
-      <button onClick={() => void ref.current?.toggleVideo()}>
+      <button onClick={() => void viewer.toggleVideo()}>
         {snapshot?.playing ? "暂停" : "播放"}
       </button>
-      <button onClick={() => ref.current?.toggleVideoMuted()}>
+      <button onClick={() => viewer.toggleVideoMuted()}>
         {snapshot?.muted ? "取消静音" : "静音"}
       </button>
       {snapshot && (
@@ -287,10 +292,10 @@ function VideoExample() {
           min={0}
           max={snapshot.duration}
           value={snapshot.currentTime}
-          onChange={(e) => ref.current?.seekVideo(Number(e.target.value))}
+          onChange={(e) => viewer.seekVideo(Number(e.target.value))}
         />
       )}
-      <PanoViewer ref={ref} style={{ height: 560 }}>
+      <PanoViewer ref={viewer.ref} style={{ height: 560 }}>
         <PanoVideo controls={false} src="/tour.mp4" />
       </PanoViewer>
     </>
@@ -300,32 +305,32 @@ function VideoExample() {
 
 ### 自定义背景音乐控件
 
-`BackgroundAudio` 支持非受控模式 — 省略 `playing`，改用 `defaultPlaying`。通过 viewer ref 驱动。
+`BackgroundAudio` 支持非受控模式 — 省略 `playing`，改用 `defaultPlaying`。通过 `usePanoViewer()` 驱动。
 
 ```tsx
-import { useRef, useSyncExternalStore } from "react";
+import { useSyncExternalStore } from "react";
 import {
   PanoViewer,
   Sphere,
   BackgroundAudio,
-  type PanoViewerHandle,
+  usePanoViewer,
 } from "@ericchen1990/pano-view";
 
 function BGMExample() {
-  const ref = useRef<PanoViewerHandle>(null);
+  const viewer = usePanoViewer();
 
   const snapshot = useSyncExternalStore(
-    (cb) => ref.current?.subscribeBackgroundAudio(cb) ?? (() => {}),
-    () => ref.current?.getBackgroundAudio()?.getSnapshot() ?? null,
+    viewer.subscribeBackgroundAudio,
+    () => viewer.getBackgroundAudio()?.getSnapshot() ?? null,
     () => null,
   );
 
   return (
     <>
-      <button onClick={() => ref.current?.toggleBackgroundAudio()}>
+      <button onClick={() => viewer.toggleBackgroundAudio()}>
         {snapshot?.playing ? "暂停 BGM" : "播放 BGM"}
       </button>
-      <button onClick={() => ref.current?.toggleBackgroundAudioMuted()}>
+      <button onClick={() => viewer.toggleBackgroundAudioMuted()}>
         {snapshot?.muted ? "取消静音" : "静音"}
       </button>
       <input
@@ -334,11 +339,9 @@ function BGMExample() {
         max={1}
         step={0.01}
         value={snapshot?.volume ?? 1}
-        onChange={(e) =>
-          ref.current?.setBackgroundAudioVolume(Number(e.target.value))
-        }
+        onChange={(e) => viewer.setBackgroundAudioVolume(Number(e.target.value))}
       />
-      <PanoViewer ref={ref} style={{ height: 560 }}>
+      <PanoViewer ref={viewer.ref} style={{ height: 560 }}>
         <BackgroundAudio defaultPlaying src="/bgm.mp3" />
         <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
       </PanoViewer>
@@ -350,29 +353,28 @@ function BGMExample() {
 ### 一站式示例
 
 ```tsx
-import { useRef } from "react";
 import {
   PanoViewer,
   Scenes,
   WebVR,
   PanoVideo,
   BackgroundAudio,
-  type PanoViewerHandle,
+  usePanoViewer,
 } from "@ericchen1990/pano-view";
 
 function TourPlayer() {
-  const ref = useRef<PanoViewerHandle>(null);
+  const viewer = usePanoViewer();
 
   return (
     <>
       <nav>
-        <button onClick={() => ref.current?.previousScene()}>← 上一场景</button>
-        <button onClick={() => ref.current?.nextScene()}>下一场景 →</button>
-        <button onClick={() => void ref.current?.toggleFullscreen()}>全屏</button>
-        <button onClick={() => void ref.current?.enterVR()}>进入 VR</button>
-        <button onClick={() => ref.current?.toggleBackgroundAudio()}>BGM</button>
+        <button onClick={() => viewer.previousScene()}>← 上一场景</button>
+        <button onClick={() => viewer.nextScene()}>下一场景 →</button>
+        <button onClick={() => void viewer.toggleFullscreen()}>全屏</button>
+        <button onClick={() => void viewer.enterVR()}>进入 VR</button>
+        <button onClick={() => viewer.toggleBackgroundAudio()}>BGM</button>
       </nav>
-      <PanoViewer ref={ref} style={{ height: "100vh" }}>
+      <PanoViewer ref={viewer.ref} style={{ height: "100vh" }}>
         <WebVR />
         <BackgroundAudio defaultPlaying src="/bgm.mp3" />
         <Scenes defaultActiveSceneId="lobby" scenes={scenes} transition="dissolve" />