@ericchen1990/pano-view 3.0.0 → 3.1.1

package/README.md

@@ -4,7 +4,7 @@
 
 Composable React components for equirectangular and krpano-style multiresolution panorama viewers.
 
-Try the components in the [live playground](https://pano-view-playground.vercel.app/).
+Try the components in the [live playground](https://pano-view-playground.vercel.app/?utm_source=github&utm_medium=readme&utm_campaign=package-readme&utm_content=playground).
 
 ## krpano-compatible tile output
 
@@ -72,6 +72,29 @@ Skip this import only if you do not use those overlays, or if you restyle
 them entirely through `className`, `style`, and appearance props. Without
 the stylesheet, the overlays still mount, but they render unstyled.
 
+## Start with a panorama
+
+Give PanoViewer an explicit size and render one panorama source inside it.
+Import the stylesheet once when you use built-in HTML overlays such as video
+controls, captions, tooltips, the context menu, or WebVR UI.
+
+~~~tsx
+import "@ericchen1990/pano-view/styles.css";
+import { PanoViewer, Sphere } from "@ericchen1990/pano-view";
+
+export function Panorama() {
+  return (
+    <PanoViewer style={{ height: 560 }}>
+      <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
+    </PanoViewer>
+  );
+}
+~~~
+
+For existing krpano tile pyramids, read the [migration
+guide](../../docs/krpano-migration.md) before replacing Sphere with Tile. The
+guide documents the XML-to-prop mapping and the relative-path rules.
+
 ## Exported components
 
 ### Viewer
@@ -143,6 +166,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 +192,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`.
 
@@ -180,7 +226,7 @@ The handle exposes view, fullscreen, scene, VR, video, and background-audio cont
 
 ### 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.
+By default, when a child has an initial playback intent (`PanoVideo autoPlay`, an active `BackgroundAudio`, `VideoHotspot`, or `AudioHotspot`), the viewer silently unlocks audible playback on the first user gesture when the browser requires one, or immediately when autoplay policy already allows it. Muted video can still preview inline. The same 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-automatic-activation behavior.
 
 ```tsx
 <PanoViewer
@@ -196,7 +242,7 @@ By default, the viewer shows a **Tap to enable sound** entry layer only when a c
 </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.
+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 control 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`.
 

package/README.zh-CN.md

@@ -4,7 +4,7 @@
 
 用于等距圆柱（equirectangular）与 krpano 风格多分辨率全景查看器的可组合 React 组件。
 
-在[在线 playground](https://pano-view-playground.vercel.app/) 中试用这些组件。
+在[在线 playground](https://pano-view-playground.vercel.app/?utm_source=github&utm_medium=readme&utm_campaign=package-readme&utm_content=playground) 中试用这些组件。
 
 ## 兼容 krpano 的 tile 输出
 
@@ -55,6 +55,28 @@ import "@ericchen1990/pano-view/styles.css";
 
 仅当你不使用这些叠加层，或完全通过 `className`、`style` 与外观属性重设样式时，可跳过该导入。若不导入样式表，叠加层仍会挂载，但会无样式显示。
 
+## 快速渲染一个全景图
+
+为 PanoViewer 提供明确尺寸，并在其内部渲染一个全景源。使用内置 HTML 叠加层
+（例如视频控件、字幕、tooltip、右键菜单或 WebVR UI）时，需导入一次样式表。
+
+~~~tsx
+import "@ericchen1990/pano-view/styles.css";
+import { PanoViewer, Sphere } from "@ericchen1990/pano-view";
+
+export function Panorama() {
+  return (
+    <PanoViewer style={{ height: 560 }}>
+      <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
+    </PanoViewer>
+  );
+}
+~~~
+
+如需复用现有 krpano tile 金字塔，请在将 Sphere 换成 Tile 前阅读
+[迁移指南](../../docs/krpano-migration.zh-CN.md)。指南说明 XML 到 prop 的映射与
+相对路径规则。
+
 ## 导出组件
 
 ### 查看器
@@ -126,6 +148,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 +174,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`。
 
@@ -163,7 +206,7 @@ export function ControlledExample() {
 
 ### 移动端媒体激活
 
-默认情况下，只要子组件带有初始播放意图（`PanoVideo autoPlay`、播放中的 `BackgroundAudio`、`VideoHotspot` 或 `AudioHotspot`），查看器就会显示「Tap to enable sound」首触层。静音视频仍会内联预览；首触在同一用户手势内恢复 Web Audio，再把播放选择交给宿主，避免视频、BGM 与定点声同时出声。传 `mediaActivation={false}` 可保留 2.x 的无首触层行为。
+默认情况下，只要子组件带有初始播放意图（`PanoVideo autoPlay`、播放中的 `BackgroundAudio`、`VideoHotspot` 或 `AudioHotspot`），查看器会在浏览器需要用户手势时于首次交互静默解锁有声播放；若自动播放策略已允许，则立即激活。静音视频仍会内联预览；激活在同一用户手势内恢复 Web Audio，再把播放选择交给宿主，避免视频、BGM 与定点声同时出声。传 `mediaActivation={false}` 可保留 2.x 的无自动激活行为。
 
 ```tsx
 <PanoViewer
@@ -179,7 +222,7 @@ export function ControlledExample() {
 </PanoViewer>
 ```
 
-`onActivate` 的 `media` 提供 `resumeAudio()`、`playVideo({ unmute })` 和 `playBackgroundAudio()`。背景音乐若使用受控 `playing`，仍由宿主在回调内更新该状态；`viewer.activateMedia()` 可供自定义入场按钮复用同一流程。
+`onActivate` 的 `media` 提供 `resumeAudio()`、`playVideo({ unmute })` 和 `playBackgroundAudio()`。背景音乐若使用受控 `playing`，仍由宿主在回调内更新该状态；`viewer.activateMedia()` 可供自定义控件复用同一流程。
 
 依赖未挂载子组件的方法（如无 `<WebVR />` 时调 `enterVR`）安全空操作，返回 `false`、`void` 或 `null`。