@ericchen1990/pano-view 2.5.1 → 3.1.0

package/README.md

@@ -143,6 +143,9 @@ export function ControlledExample() {
       <button onClick={() => viewer.setView({ yaw: 90, fov: 55 })}>
         Look right
       </button>
+      <button onClick={() => void viewer.lookTo({ yaw: -45, pitch: 8 })}>
+        Animate left
+      </button>
       <PanoViewer
         ref={viewer.ref}
         controls={{
@@ -166,7 +169,27 @@ export function ControlledExample() {
 
 The handle exposes view, fullscreen, scene, VR, video, and background-audio controls so custom UIs can drive the viewer from a single ref:
 
-**View** — `getView`, `setView`, `reset`.
+**View** — `getView`, `setView`, `reset`, `lookTo`, `moveTo`, `zoomTo`, `lookToHotspot`.
+
+`setView` and `reset` remain immediate. The navigation methods return a Promise
+with `{ status: "completed" | "cancelled" | "not-found" }`; each new navigation
+or user interaction cancels the previous one. They default to 700 ms with
+`easeInOutCubic` and take the shortest yaw path. `lookTo` and `lookToHotspot`
+preserve the current FOV unless `fov` is provided.
+
+```tsx
+const result = await viewer.lookToHotspot("visitor-guide", { fov: 55 });
+
+if (result.status === "not-found") {
+  // The hotspot is not mounted in this PanoViewer.
+}
+
+await viewer.moveTo({ yaw: 170, pitch: 0 }, { shortestPath: false });
+await viewer.zoomTo(48, { duration: 400, easing: "linear" });
+```
+
+Every mounted hotspot type can be targeted, including polygons and polylines,
+which use their spherical center. Hotspot ids must be unique within a viewer.
 
 **Fullscreen** — `enterFullscreen`, `exitFullscreen`, `toggleFullscreen`, `isFullscreen`.
 
@@ -178,6 +201,26 @@ The handle exposes view, fullscreen, scene, VR, video, and background-audio cont
 
 **Background Audio** (requires `<BackgroundAudio />`) — `getBackgroundAudio` returns the `BackgroundAudioController`, `subscribeBackgroundAudio` subscribes to host changes, plus convenience aliases `playBackgroundAudio`, `pauseBackgroundAudio`, `toggleBackgroundAudio`, `setBackgroundAudioVolume`, `setBackgroundAudioMuted`, `toggleBackgroundAudioMuted`. `BackgroundAudio` now accepts an optional `playing` prop (controlled) or uses `defaultPlaying` (uncontrolled).
 
+### Mobile media activation
+
+By default, the viewer shows a **Tap to enable sound** entry layer only when a child has an initial playback intent (`PanoVideo autoPlay`, an active `BackgroundAudio`, `VideoHotspot`, or `AudioHotspot`). Muted video can still preview inline. The same user gesture resumes Web Audio and gives the host the final choice of which media becomes audible, so video, music, and positional sound never all start by assumption. Pass `mediaActivation={false}` to retain the 2.x no-entry-layer behavior.
+
+```tsx
+<PanoViewer
+  mediaActivation={{
+    onActivate: (media) => {
+      // Do not await: start audible media in this gesture's synchronous stack.
+      void media.playVideo({ unmute: true });
+    },
+  }}
+  style={{ height: "min(560px, 68dvh)" }}
+>
+  <PanoVideo autoPlay src="/tour.mp4" />
+</PanoViewer>
+```
+
+The `media` argument provides `resumeAudio()`, `playVideo({ unmute })`, and `playBackgroundAudio()`. Controlled background audio remains host-owned: update its `playing` state from this callback. `viewer.activateMedia()` lets a custom entry button reuse the same path.
+
 Methods that depend on an unmounted child component (e.g. `enterVR` without `<WebVR />`) are safe no-ops — they return `false`, `void`, or `null`.
 
 ### Fullscreen
@@ -517,9 +560,13 @@ export function VideoExample() {
 ```
 
 `muted` defaults to `true` so `autoPlay` has a chance under browser autoplay
-rules. Unmuted playback still needs a user gesture; `onPlaybackStateChange`
-receives `"blocked"` when `play()` is rejected. Remote videos and VTT files
-that are not same-origin should set `crossOrigin` (usually `"anonymous"`).
+rules. `playsInline` also defaults to true and writes both `playsinline` and
+`webkit-playsinline`, keeping the default 360-video path inline on iPhone
+instead of entering the native player. Unmuted playback still needs a user
+gesture; `onPlaybackStateChange` receives `"blocked"` when `play()` is
+rejected. Remote videos and VTT files that are not same-origin should set
+`crossOrigin` (usually `"anonymous"`). For mobile delivery, provide an H.264 +
+AAC MP4 fallback, poster, CORS, and Range support.
 
 ## Tile
 

package/README.zh-CN.md

@@ -126,6 +126,9 @@ export function ControlledExample() {
       <button onClick={() => viewer.setView({ yaw: 90, fov: 55 })}>
         Look right
       </button>
+      <button onClick={() => void viewer.lookTo({ yaw: -45, pitch: 8 })}>
+        Animate left
+      </button>
       <PanoViewer
         ref={viewer.ref}
         controls={{
@@ -149,7 +152,25 @@ export function ControlledExample() {
 
 句柄从单个 `ref` 暴露视图、全屏、场景、VR、视频与背景音乐控制，方便宿主自绘 UI：
 
-**视图** — `getView`、`setView`、`reset`。
+**视图** — `getView`、`setView`、`reset`、`lookTo`、`moveTo`、`zoomTo`、`lookToHotspot`。
+
+`setView` 与 `reset` 仍立即生效。导航方法返回
+`Promise<{ status: "completed" | "cancelled" | "not-found" }>`；新的导航或用户操作会取消前一个导航。默认时长为 700ms，缓动为
+`easeInOutCubic`，YAW 默认走最短路径。`lookTo` 与 `lookToHotspot`
+未传 `fov` 时保持当前 FOV。
+
+```tsx
+const result = await viewer.lookToHotspot("visitor-guide", { fov: 55 });
+
+if (result.status === "not-found") {
+  // 该热点尚未挂载在这个 PanoViewer 中。
+}
+
+await viewer.moveTo({ yaw: 170, pitch: 0 }, { shortestPath: false });
+await viewer.zoomTo(48, { duration: 400, easing: "linear" });
+```
+
+所有已挂载热点都可作为目标，包括使用球面中心点的多边形与折线。每个 viewer 内的热点 `id` 必须唯一。
 
 **全屏** — `enterFullscreen`、`exitFullscreen`、`toggleFullscreen`、`isFullscreen`。
 
@@ -161,6 +182,26 @@ export function ControlledExample() {
 
 **背景音乐**（需 `<BackgroundAudio />`）— `getBackgroundAudio` 返回 `BackgroundAudioController`，`subscribeBackgroundAudio` 订阅宿主变更，另有快捷方法 `playBackgroundAudio`、`pauseBackgroundAudio`、`toggleBackgroundAudio`、`setBackgroundAudioVolume`、`setBackgroundAudioMuted`、`toggleBackgroundAudioMuted`。`BackgroundAudio` 现支持可选 `playing`（受控）或 `defaultPlaying`（非受控）。
 
+### 移动端媒体激活
+
+默认情况下，只要子组件带有初始播放意图（`PanoVideo autoPlay`、播放中的 `BackgroundAudio`、`VideoHotspot` 或 `AudioHotspot`），查看器就会显示「Tap to enable sound」首触层。静音视频仍会内联预览；首触在同一用户手势内恢复 Web Audio，再把播放选择交给宿主，避免视频、BGM 与定点声同时出声。传 `mediaActivation={false}` 可保留 2.x 的无首触层行为。
+
+```tsx
+<PanoViewer
+  mediaActivation={{
+    onActivate: (media) => {
+      // 不要 await；必须在这次点击的同步调用栈内启动有声媒体。
+      void media.playVideo({ unmute: true });
+    },
+  }}
+  style={{ height: "min(560px, 68dvh)" }}
+>
+  <PanoVideo autoPlay src="/tour.mp4" />
+</PanoViewer>
+```
+
+`onActivate` 的 `media` 提供 `resumeAudio()`、`playVideo({ unmute })` 和 `playBackgroundAudio()`。背景音乐若使用受控 `playing`，仍由宿主在回调内更新该状态；`viewer.activateMedia()` 可供自定义入场按钮复用同一流程。
+
 依赖未挂载子组件的方法（如无 `<WebVR />` 时调 `enterVR`）安全空操作，返回 `false`、`void` 或 `null`。
 
 ### 全屏
@@ -477,7 +518,7 @@ export function VideoExample() {
 }
 ```
 
-`muted` 默认为 `true`，以便在浏览器自动播放规则下有机会自动播放。非静音播放仍需要用户手势；`play()` 被拒绝时 `onPlaybackStateChange` 会收到 `"blocked"`。非同源的远程视频与 VTT 文件应设置 `crossOrigin`（通常为 `"anonymous"`）。
+`muted` 默认为 `true`，以便在浏览器自动播放规则下有机会自动播放；`playsInline` 也默认开启，并同时写入 `playsinline` / `webkit-playsinline`，避免 iPhone 将默认的 360 视频提取为原生全屏播放器。非静音播放仍需要用户手势；`play()` 被拒绝时 `onPlaybackStateChange` 会收到 `"blocked"`。非同源的远程视频与 VTT 文件应设置 `crossOrigin`（通常为 `"anonymous"`）。移动端请提供 H.264 + AAC 的 MP4 备选源、poster、CORS 与 Range 支持。
 
 ## Tile