From 9d4e193658c87eee0d4b11de4ee5f5c112cb0c2c Mon Sep 17 00:00:00 2001
From: leuvi <528046@qq.com>
Date: Tue, 4 Aug 2026 16:33:21 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E8=BF=90=E8=A1=8C=E6=97=B6=E5=9B=9E?=
 =?UTF-8?q?=E8=B0=83=E5=8F=AF=E5=88=87=E6=8D=A2=20+=20HLS/DASH=20=E5=BC=95?=
 =?UTF-8?q?=E6=93=8E=E5=BC=80=E7=AE=B1=E5=8D=B3=E7=94=A8=20+=20React/Vue?=
 =?UTF-8?q?=20=E5=9B=9E=E5=BD=92=E6=B5=8B=E8=AF=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- core: 新增 setCallbacks()，onPrev/onNext/onSavePrefs 等可在运行时新增/替换/移除
- core: bindPersistence/bindProgressMemory 的写入目标每次读取当前回调，支持远端/本地运行时切换
- core: hls.js/dashjs 从 optional peer 改为常规 peer，npm 安装自动带上
- react: useBrowserLayoutEffect 创建 player 并维护 ref，父组件 layout effect 即可用
- react: hasXxx 变化时同步 setCallbacks；回调函数替换通过稳定代理动态生效
- vue: hasListener() 检测 prev/next 事件监听，未监听时按钮禁用；watch + onUpdated 同步回调
- test: 新增 react 2 个 + vue 4 个回归测试（ref 时机、回调切换、按钮状态、持久化远端/本地）
- 根 test 命令改为三包全跑
---
 .changeset/fix-round2-review.md          |  24 +++++
 README.md                                |   4 +-
 README.zh-CN.md                          |   4 +-
 package.json                             |   2 +-
 packages/core/package.json               |   8 --
 packages/core/src/index.ts               |   1 +
 packages/core/src/player.ts              |  62 ++++++++----
 packages/core/src/types.ts               |   5 +
 packages/core/src/ui/controls.ts         |  11 ++-
 packages/react/package.json              |   7 +-
 packages/react/src/SweetPlayer.tsx       |  99 +++++++++++++++++---
 packages/react/test/SweetPlayer.test.tsx |  85 +++++++++++++++++
 packages/react/vitest.config.ts          |  14 +++
 packages/vue/package.json                |   3 +
 packages/vue/src/SweetPlayer.ts          |  50 +++++++---
 packages/vue/test/SweetPlayer.test.ts    | 114 +++++++++++++++++++++++
 packages/vue/vitest.config.ts            |  14 +++
 pnpm-lock.yaml                           |  18 ++++
 18 files changed, 466 insertions(+), 59 deletions(-)
 create mode 100644 .changeset/fix-round2-review.md
 create mode 100644 packages/react/test/SweetPlayer.test.tsx
 create mode 100644 packages/react/vitest.config.ts
 create mode 100644 packages/vue/test/SweetPlayer.test.ts
 create mode 100644 packages/vue/vitest.config.ts

diff --git a/.changeset/fix-round2-review.md b/.changeset/fix-round2-review.md
new file mode 100644
index 0000000..e4a6b74
--- /dev/null
+++ b/.changeset/fix-round2-review.md
@@ -0,0 +1,24 @@
+---
+'@sweet-player/core': minor
+'@sweet-player/react': minor
+'@sweet-player/vue': minor
+---
+
+修复第二轮 review 发现的问题，并让 HLS/DASH 引擎开箱即用：
+
+**React ref 首次挂载即可用**
+- 去掉 `useImperativeHandle`（其 factory 执行早于 player 创建，且 effect 赋值不触发 render）
+- 在浏览器 layout effect 中创建 player 并维护 forwarded ref，父组件的 layout effect 可直接读取实例
+
+**setId 换集修复**
+- `progressCleanup` 现在移除 `loadedmetadata` restore listener，避免旧 ID 进度恢复到新视频
+- React/Vue 的 `id` 更新先于 `src` 执行：先保存旧进度再换源，防止进度丢失
+- `setId` 签名扩展为 `setId(id: string | null)`，传 `null` 解除进度记忆
+
+**运行时回调不再用旧闭包**
+- core 新增 `setCallbacks()`，导航按钮和持久化写入目标可在运行时切换
+- React：稳定代理函数转发到最新 props，新增、替换或移除 `onNext`/`onPrev`/`onSavePrefs` 等回调都会生效
+- Vue：动态同步 `onSavePrefs`/`onSaveProgress`，未监听 `prev`/`next` 时对应按钮保持禁用
+
+**HLS/DASH 引擎开箱即用**
+- `hls.js` / `dashjs` 从 optional peer 改为常规 peer（npm 7+ 安装 core 时自动安装），Chrome/Firefox HLS 与 DASH 播放不再因缺依赖失败
diff --git a/README.md b/README.md
index 14e8008..3004321 100644
--- a/README.md
+++ b/README.md
@@ -39,7 +39,7 @@ npm install @sweet-player/core
 | `@sweet-player/react` | React component wrapper |
 | `@sweet-player/vue` | Vue component wrapper |
 
-`hls.js` and `dashjs` are peer/optional dependencies loaded on demand: `.m3u8` sources pull in `hls.js`, `.mpd` sources pull in `dashjs`; any other source plays through the native `<video>`. Only the engine you actually use is downloaded.
+`hls.js` and `dashjs` are peer dependencies that npm installs automatically with `@sweet-player/core` — no extra setup needed. `.m3u8` sources use `hls.js`, `.mpd` sources use `dashjs`, and any other source plays through the native `<video>`.
 
 ## Quick Start
 
@@ -145,7 +145,9 @@ const player = new SweetPlayer({
 | `screenshot()` | Copy the current frame to the clipboard, or download it. |
 | `copyShareUrl()` | Copy the video URL (`shareUrl`, or `location.href`) to the clipboard. |
 | `load(src)` | Load a new source without recreating the player. |
+| `setId(id)` | Change the progress key; pass `null` to stop remembering position. |
 | `setTitle(title)` | Update the top-left title text. |
+| `setCallbacks(callbacks)` | Replace navigation, track-change, and persistence callbacks at runtime. |
 | `use(plugin)` | Install a plugin at runtime; returns an uninstall function. |
 | `addSettingsRow(section)` | Register a settings-panel row; returns a remove function. |
 | `addContextMenuItem(item, index?)` | Register a right-click menu item; returns a remove function. |
diff --git a/README.zh-CN.md b/README.zh-CN.md
index c458d78..aab2a7e 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -39,7 +39,7 @@ npm install @sweet-player/core
 | `@sweet-player/react` | React 组件封装 |
 | `@sweet-player/vue` | Vue 组件封装 |
 
-`hls.js` 和 `dashjs` 按需加载：`.m3u8` 源自动引入 `hls.js`，`.mpd` 源自动引入 `dashjs`，其余源直接走原生 `<video>`。只有实际用到的引擎会下载。
+`hls.js` 和 `dashjs` 是随 `@sweet-player/core` 自动安装的 peer 依赖，无需额外配置：`.m3u8` 源使用 `hls.js`，`.mpd` 源使用 `dashjs`，其余源直接走原生 `<video>`。
 
 ## 快速开始
 
@@ -145,7 +145,9 @@ const player = new SweetPlayer({
 | `screenshot()` | 截取当前画面，优先复制剪贴板，否则下载 |
 | `copyShareUrl()` | 复制视频地址（`shareUrl`，缺省为 `location.href`）到剪贴板 |
 | `load(src)` | 加载新的播放源，无需重建播放器 |
+| `setId(id)` | 更换断点续播 key；传 `null` 停止记忆进度 |
 | `setTitle(title)` | 更新左上角标题 |
+| `setCallbacks(callbacks)` | 运行时替换导航、轨道切换与持久化回调 |
 | `use(plugin)` | 运行时安装插件，返回卸载函数 |
 | `addSettingsRow(section)` | 注册设置面板行，返回移除函数 |
 | `addContextMenuItem(item, index?)` | 注册右键菜单项，返回移除函数 |
diff --git a/package.json b/package.json
index dced74e..5c41a0d 100644
--- a/package.json
+++ b/package.json
@@ -8,7 +8,7 @@
     "dev:vanilla": "pnpm --filter playground-vanilla dev",
     "dev:react": "pnpm --filter playground-react dev",
     "dev:vue": "pnpm --filter playground-vue dev",
-    "test": "pnpm --filter @sweet-player/core test",
+    "test": "pnpm -r --filter \"./packages/*\" test",
     "typecheck": "pnpm -r --filter \"./packages/*\" typecheck",
     "changeset": "changeset",
     "release": "changeset && git add .changeset && git commit -m \"chore: add changeset\" && git push"
diff --git a/packages/core/package.json b/packages/core/package.json
index 14ffc1a..956f1ad 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -44,14 +44,6 @@
     "dashjs": "^5",
     "hls.js": "^1.5.18"
   },
-  "peerDependenciesMeta": {
-    "dashjs": {
-      "optional": true
-    },
-    "hls.js": {
-      "optional": true
-    }
-  },
   "devDependencies": {
     "dashjs": "^5",
     "hls.js": "^1.5.18",
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index ac0a02b..ee7a995 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -6,6 +6,7 @@ export type { SettingsSection, SettingsItem } from './ui/components/settingsPane
 export type { ContextMenuItem } from './ui/components/contextMenu';
 export type {
   SweetPlayerOptions,
+  SweetPlayerCallbacks,
   SweetPlayerPlugin,
   SweetPlayerLike,
   QualityLevel,
diff --git a/packages/core/src/player.ts b/packages/core/src/player.ts
index 49b3374..2f970ec 100644
--- a/packages/core/src/player.ts
+++ b/packages/core/src/player.ts
@@ -29,6 +29,7 @@ import type {
   PlayerPrefs,
   QualityLevel,
   RestoreState,
+  SweetPlayerCallbacks,
   SweetPlayerOptions,
   SweetPlayerPlugin,
 } from './types';
@@ -280,7 +281,8 @@ export class SweetPlayer {
     this.controls.volume.update(Math.round(this.video.volume * 100), this.video.muted);
     this.controls.updateRate(this.video.playbackRate);
 
-    if (persist || remotePrefs) this.bindPersistence();
+    // 始终绑定轻量事件：persist 或远端回调可在运行时切换，实际写入时再决定目标。
+    this.bindPersistence();
     if (options.id) {
       this.progressId = options.id;
       this.bindProgressMemory(options.id);
@@ -529,17 +531,31 @@ export class SweetPlayer {
   /**
    * 切换视频 ID（断点续播的 key）。
    * 先保存旧视频的进度，再解绑旧的事件/定时器，最后用新 ID 重新绑定。
+   * 传 `null` 表示解除进度记忆（停止保存，也不恢复）。
    */
-  setId(id: string): void {
+  setId(id: string | null): void {
     if (this.progressId === id) return;
+    // 保存旧进度：必须在旧媒体还挂着时读取 currentTime，
+    // 换源（load）之后再调会读到新媒体/重置后的值，进度丢失
     this.saveProgressNow();
     this.progressQueue?.flush();
     this.progressCleanup?.();
     this.progressCleanup = null;
     this.progressQueue = null;
     this.progressId = id;
-    this.options.id = id;
-    this.bindProgressMemory(id);
+    this.options.id = id ?? undefined;
+    if (id) this.bindProgressMemory(id);
+  }
+
+  /** 更新包装层可在运行时变化的回调，不重建播放器或重复绑定媒体事件。 */
+  setCallbacks(callbacks: SweetPlayerCallbacks): void {
+    this.options.onPrev = callbacks.onPrev;
+    this.options.onNext = callbacks.onNext;
+    this.options.onQualityChange = callbacks.onQualityChange;
+    this.options.onAudioTrackChange = callbacks.onAudioTrackChange;
+    this.options.onSavePrefs = callbacks.onSavePrefs;
+    this.options.onSaveProgress = callbacks.onSaveProgress;
+    this.controls.updateNavigation(callbacks.onPrev, callbacks.onNext);
   }
 
   setTitle(title: string): void {
@@ -654,8 +670,12 @@ export class SweetPlayer {
   // ---------- 内部：持久化 ----------
 
   private bindPersistence(): void {
-    // 有 onSavePrefs 走业务方回调，否则回落到 localStorage。两条路径共用同一个节流队列。
-    const write = this.options.onSavePrefs ?? ((p: PlayerPrefs) => savePrefs(p));
+    // 每次发送时读取当前回调，支持包装层在运行时切换远端/本地持久化。
+    const write = (prefs: PlayerPrefs): void | Promise<void> => {
+      const onSavePrefs = this.options.onSavePrefs;
+      if (onSavePrefs) return onSavePrefs(prefs);
+      if (this.options.persist !== false) savePrefs(prefs);
+    };
     this.prefsQueue = createSaveQueue<PlayerPrefs>(write, PREFS_SAVE_DEBOUNCE, '偏好');
 
     const onVolume = () =>
@@ -671,23 +691,24 @@ export class SweetPlayer {
   }
 
   private bindProgressMemory(id: string): void {
-    const onSaveProgress = this.options.onSaveProgress;
     // 两条路径共用队列：seek 连点时合并写入，pause / pagehide / destroy 时 flush 立即落盘
-    const write = onSaveProgress
-      ? (seconds: number | null) => onSaveProgress(id, seconds)
-      : (seconds: number | null) => (seconds === null ? clearProgress(id) : saveProgress(id, seconds));
+    const write = (seconds: number | null): void | Promise<void> => {
+      const onSaveProgress = this.options.onSaveProgress;
+      if (onSaveProgress) return onSaveProgress(id, seconds);
+      if (seconds === null) clearProgress(id);
+      else saveProgress(id, seconds);
+    };
     this.progressQueue = createSaveQueue<number | null>(write, PROGRESS_SAVE_DEBOUNCE, '进度');
 
     // 业务方自管进度时只负责写，读由业务方拿到数据后调 restore()
-    if (!onSaveProgress) {
-      const restore = () => {
-        const saved = loadProgress(id);
-        if (saved !== null && saved > 3 && saved < this.video.duration - PROGRESS_END_GUARD) {
-          this.video.currentTime = saved;
-        }
-      };
-      this.video.addEventListener('loadedmetadata', restore, { once: true });
-    }
+    const restore = () => {
+      if (this.options.onSaveProgress) return;
+      const saved = loadProgress(id);
+      if (saved !== null && saved > 3 && saved < this.video.duration - PROGRESS_END_GUARD) {
+        this.video.currentTime = saved;
+      }
+    };
+    this.video.addEventListener('loadedmetadata', restore, { once: true });
 
     this.progressTimer = setInterval(() => {
       if (!this.video.paused) this.saveProgressNow();
@@ -705,6 +726,9 @@ export class SweetPlayer {
     window.addEventListener('pagehide', onPageHide);
 
     this.progressCleanup = () => {
+      // restore 是 { once: true }，未触发时 removeEventListener 同样有效；
+      // 必须移除，否则换集后旧 id 的 restore 会在新源的 loadedmetadata 上误 seek
+      this.video.removeEventListener('loadedmetadata', restore);
       this.video.removeEventListener('seeked', onSeeked);
       window.removeEventListener('pagehide', onPageHide);
       if (this.progressTimer) {
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
index 40cb61b..541e599 100644
--- a/packages/core/src/types.ts
+++ b/packages/core/src/types.ts
@@ -178,6 +178,11 @@ export interface SweetPlayerOptions {
   onAudioTrackChange?: (track: AudioTrackInfo) => void;
 }
 
+export type SweetPlayerCallbacks = Pick<
+  SweetPlayerOptions,
+  'onPrev' | 'onNext' | 'onQualityChange' | 'onAudioTrackChange' | 'onSavePrefs' | 'onSaveProgress'
+>;
+
 export interface PlayerEventMap {
   ready: void;
   play: void;
diff --git a/packages/core/src/ui/controls.ts b/packages/core/src/ui/controls.ts
index 7f23927..e6c3b7c 100644
--- a/packages/core/src/ui/controls.ts
+++ b/packages/core/src/ui/controls.ts
@@ -55,6 +55,7 @@ export interface Controls {
   updatePip(pip: boolean): void;
   updateLoop(loop: boolean): void;
   updateRatio(ratio: AspectRatio): void;
+  updateNavigation(onPrev?: () => void, onNext?: () => void): void;
   destroy(): void;
 }
 
@@ -94,11 +95,11 @@ export function createControls(ctx: ControlsContext): Controls {
   };
 
   // 左侧：上一个 | 快退 | 播放 | 快进 | 下一个 | 时间
-  button(icons.prev, i18n.t('prev'), () => actions.onPrev?.(), !actions.onPrev, show('prev'));
+  const prevBtn = button(icons.prev, i18n.t('prev'), () => actions.onPrev?.(), !actions.onPrev, show('prev'));
   button(icons.seekBack, i18n.t('seekBack', { n: ctx.seekStep }), () => actions.seekBy(-ctx.seekStep), false, show('seekBack'));
   const playBtn = button(icons.play, i18n.t('playPause'), actions.togglePlay, false, show('play'));
   button(icons.seekForward, i18n.t('seekForward', { n: ctx.seekStep }), () => actions.seekBy(ctx.seekStep), false, show('seekForward'));
-  button(icons.next, i18n.t('next'), () => actions.onNext?.(), !actions.onNext, show('next'));
+  const nextBtn = button(icons.next, i18n.t('next'), () => actions.onNext?.(), !actions.onNext, show('next'));
 
   const timeEl = createEl('span', {
     className: 'sp-time',
@@ -292,6 +293,12 @@ export function createControls(ctx: ControlsContext): Controls {
       const label = ratio === 'original' ? i18n.t('ratioOriginal') : ratio;
       settingsPanel.updateSection('ratio', { activeValue: ratio, currentValue: label });
     },
+    updateNavigation(onPrev, onNext) {
+      actions.onPrev = onPrev;
+      actions.onNext = onNext;
+      prevBtn.classList.toggle('sp-disabled', !onPrev);
+      nextBtn.classList.toggle('sp-disabled', !onNext);
+    },
     destroy() {
       settingsPanel.destroy();
       progress.destroy();
diff --git a/packages/react/package.json b/packages/react/package.json
index 9d6364d..86ccdeb 100644
--- a/packages/react/package.json
+++ b/packages/react/package.json
@@ -19,6 +19,7 @@
   "sideEffects": false,
   "scripts": {
     "build": "tsup",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
   "license": "MIT",
@@ -43,8 +44,12 @@
   },
   "devDependencies": {
     "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^29.1.1",
     "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "tsup": "^8.3.5",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.10"
   }
 }
diff --git a/packages/react/src/SweetPlayer.tsx b/packages/react/src/SweetPlayer.tsx
index 4769220..16e8a03 100644
--- a/packages/react/src/SweetPlayer.tsx
+++ b/packages/react/src/SweetPlayer.tsx
@@ -1,14 +1,18 @@
-import { forwardRef, useEffect, useImperativeHandle, useRef, type CSSProperties } from 'react';
+import { forwardRef, useEffect, useLayoutEffect, useRef, type CSSProperties } from 'react';
 import { SweetPlayer as CorePlayer, type SweetPlayerOptions } from '@sweet-player/core';
 
+const useBrowserLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect;
+
 export interface SweetPlayerProps extends Omit<SweetPlayerOptions, 'container'> {
   className?: string;
   style?: CSSProperties;
   onReady?: (player: CorePlayer) => void;
 }
 
-// forwardRef 兼容 React 18/19：React 18 中 ref 不作为普通 prop 传入，
-// 使用 forwardRef + useImperativeHandle 才能让外部拿到底层 SweetPlayer 实例。
+// forwardRef 兼容 React 18/19：React 18 中 ref 不作为普通 prop 传入。
+// 不用 useImperativeHandle——它的 factory 在 commit 阶段执行，早于创建 player 的
+// useEffect，且 effect 赋值 playerRef.current 不触发 render，导致首次挂载 ref 恒为 null。
+// forwarded ref 由单独的 [ref] layout effect 维护，支持运行时更换 ref（如 inline callback ref）。
 export const SweetPlayer = forwardRef<CorePlayer | null, SweetPlayerProps>(function SweetPlayer(
   { className, style, onReady, src, ...options },
   ref,
@@ -17,25 +21,94 @@ export const SweetPlayer = forwardRef<CorePlayer | null, SweetPlayerProps>(funct
   const playerRef = useRef<CorePlayer | null>(null);
   const optionsRef = useRef({ ...options, src, onReady });
   optionsRef.current = { ...options, src, onReady };
+  const hasOnNext = options.onNext !== undefined;
+  const hasOnPrev = options.onPrev !== undefined;
+  const hasOnQualityChange = options.onQualityChange !== undefined;
+  const hasOnAudioTrackChange = options.onAudioTrackChange !== undefined;
+  const hasOnSavePrefs = options.onSavePrefs !== undefined;
+  const hasOnSaveProgress = options.onSaveProgress !== undefined;
 
-  // useImperativeHandle 的 factory 在 commit 阶段执行，早于创建 player 的 useEffect。
-  // 因此直接返回 ref.current——它会在 effect 中被赋值，父组件通过 ref.current 拿到实例。
-  useImperativeHandle(ref, () => playerRef.current as CorePlayer);
+  // 稳定回调代理：CorePlayer 构造时捕获这些函数引用，代理内部转发到最新 props，
+  // 避免 onNext/onPrev/onSavePrefs 等运行时更新后仍调用旧闭包。
+  // 注意：必须直接返回原 callback 的结果（void | Promise<void>），不能 void 掉——
+  // core 的 save queue 靠返回值判断异步，void 掉会破坏单飞和写入顺序。
+  const callbacksRef = useRef({
+    onNext: () => optionsRef.current.onNext?.(),
+    onPrev: () => optionsRef.current.onPrev?.(),
+    onQualityChange: (q: Parameters<NonNullable<SweetPlayerOptions['onQualityChange']>>[0]) =>
+      optionsRef.current.onQualityChange?.(q),
+    onAudioTrackChange: (t: Parameters<NonNullable<SweetPlayerOptions['onAudioTrackChange']>>[0]) =>
+      optionsRef.current.onAudioTrackChange?.(t),
+    onSavePrefs: (p: Parameters<NonNullable<SweetPlayerOptions['onSavePrefs']>>[0]) =>
+      optionsRef.current.onSavePrefs?.(p) as void | Promise<void> | undefined,
+    onSaveProgress: (id: string, s: number | null) =>
+      optionsRef.current.onSaveProgress?.(id, s) as void | Promise<void> | undefined,
+  });
 
-  useEffect(() => {
+  useBrowserLayoutEffect(() => {
     if (!containerRef.current) return;
-    const { onReady: ready, ...opts } = optionsRef.current;
-    const player = new CorePlayer({ ...opts, container: containerRef.current });
+    const { onReady: _ready, onNext, onPrev, onQualityChange, onAudioTrackChange, onSavePrefs, onSaveProgress, ...opts } =
+      optionsRef.current;
+    const player = new CorePlayer({
+      ...opts,
+      container: containerRef.current,
+      // 仅在用户显式传入时才传代理，否则保持 undefined：
+      // ① core 靠回调是否存在区分本地存储与远端存储——无条件传代理会关闭默认持久化；
+      // ② 无条件传 onNext/onPrev 会让前后集按钮误显示为可用。
+      ...(onNext !== undefined && { onNext: callbacksRef.current.onNext }),
+      ...(onPrev !== undefined && { onPrev: callbacksRef.current.onPrev }),
+      ...(onQualityChange !== undefined && { onQualityChange: callbacksRef.current.onQualityChange }),
+      ...(onAudioTrackChange !== undefined && { onAudioTrackChange: callbacksRef.current.onAudioTrackChange }),
+      ...(onSavePrefs !== undefined && { onSavePrefs: callbacksRef.current.onSavePrefs }),
+      ...(onSaveProgress !== undefined && { onSaveProgress: callbacksRef.current.onSaveProgress }),
+    });
     playerRef.current = player;
-    ready?.(player);
+    optionsRef.current.onReady?.(player);
     return () => {
       playerRef.current = null;
       player.destroy();
     };
-    // 仅在挂载时创建；src/title 变化通过下方 effect 增量更新
+    // 仅在挂载时创建；src/id/title 变化通过下方 effect 增量更新
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  // 单独维护 forwarded ref：父组件可能运行时更换 ref（inline callback ref 每次 render 都是新函数），
+  // 挂载 effect 只捕获首次 ref，这里按 [ref] 同步旧/新 ref。
+  useBrowserLayoutEffect(() => {
+    const player = playerRef.current;
+    if (typeof ref === 'function') ref(player);
+    else if (ref) ref.current = player;
+    return () => {
+      if (typeof ref === 'function') ref(null);
+      else if (ref) ref.current = null;
+    };
+  }, [ref]);
+
+  // 代理引用保持稳定，仅在回调“有/无”切换时同步 core；替换函数本身不会重订阅。
+  useBrowserLayoutEffect(() => {
+    playerRef.current?.setCallbacks({
+      onNext: hasOnNext ? callbacksRef.current.onNext : undefined,
+      onPrev: hasOnPrev ? callbacksRef.current.onPrev : undefined,
+      onQualityChange: hasOnQualityChange ? callbacksRef.current.onQualityChange : undefined,
+      onAudioTrackChange: hasOnAudioTrackChange ? callbacksRef.current.onAudioTrackChange : undefined,
+      onSavePrefs: hasOnSavePrefs ? callbacksRef.current.onSavePrefs : undefined,
+      onSaveProgress: hasOnSaveProgress ? callbacksRef.current.onSaveProgress : undefined,
+    });
+  }, [
+    hasOnNext,
+    hasOnPrev,
+    hasOnQualityChange,
+    hasOnAudioTrackChange,
+    hasOnSavePrefs,
+    hasOnSaveProgress,
+  ]);
+
+  // id 必须先于 src 更新：setId 保存旧进度依赖旧媒体 currentTime，
+  // 若先 load 换源，旧媒体被 detach/重置，进度会丢失。
+  useEffect(() => {
+    playerRef.current?.setId(options.id ?? null);
+  }, [options.id]);
+
   useEffect(() => {
     const player = playerRef.current;
     if (player && src && player.video.currentSrc !== src) player.load(src);
@@ -45,9 +118,5 @@ export const SweetPlayer = forwardRef<CorePlayer | null, SweetPlayerProps>(funct
     playerRef.current?.setTitle(options.title ?? '');
   }, [options.title]);
 
-  useEffect(() => {
-    if (options.id) playerRef.current?.setId(options.id);
-  }, [options.id]);
-
   return <div ref={containerRef} className={className} style={{ width: '100%', height: '100%', ...style }} />;
 });
diff --git a/packages/react/test/SweetPlayer.test.tsx b/packages/react/test/SweetPlayer.test.tsx
new file mode 100644
index 0000000..3047162
--- /dev/null
+++ b/packages/react/test/SweetPlayer.test.tsx
@@ -0,0 +1,85 @@
+import { act, createElement, createRef, useLayoutEffect } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { SweetPlayer as CorePlayer } from '@sweet-player/core';
+import { SweetPlayer } from '../src/SweetPlayer';
+
+let host: HTMLDivElement;
+let root: Root | null;
+
+beforeEach(() => {
+  localStorage.clear();
+  sessionStorage.clear();
+  host = document.createElement('div');
+  document.body.appendChild(host);
+  root = createRoot(host);
+  vi.spyOn(HTMLMediaElement.prototype, 'load').mockImplementation(() => {});
+  vi.spyOn(HTMLMediaElement.prototype, 'play').mockResolvedValue(undefined);
+  vi.spyOn(HTMLMediaElement.prototype, 'pause').mockImplementation(() => {});
+});
+
+afterEach(async () => {
+  if (root) await act(async () => root?.unmount());
+  root = null;
+  host.remove();
+  vi.restoreAllMocks();
+});
+
+describe('SweetPlayer React wrapper', () => {
+  it('exposes the player before parent layout effects run', async () => {
+    const playerRef = createRef<CorePlayer | null>();
+    let availableInLayout = false;
+
+    function Parent() {
+      useLayoutEffect(() => {
+        availableInLayout = playerRef.current !== null;
+      }, []);
+      return createElement(SweetPlayer, { ref: playerRef, src: '/video.mp4' });
+    }
+
+    await act(async () => root?.render(createElement(Parent)));
+
+    expect(availableInLayout).toBe(true);
+    expect(playerRef.current).toBeInstanceOf(CorePlayer);
+  });
+
+  it('switches navigation and progress callbacks between remote and local modes', async () => {
+    let player: CorePlayer | null = null;
+    const onNext = vi.fn();
+    const onSaveProgress = vi.fn();
+    const render = (withCallbacks: boolean) =>
+      createElement(SweetPlayer, {
+        src: '/video.mp4',
+        id: 'episode',
+        onReady: (value) => {
+          player = value;
+        },
+        ...(withCallbacks ? { onNext, onSaveProgress } : {}),
+      });
+
+    await act(async () => root?.render(render(false)));
+    const video = (player as CorePlayer | null)?.video;
+    expect(video).toBeDefined();
+    Object.defineProperty(video!, 'duration', { configurable: true, value: 100 });
+    const nextButton = host.querySelectorAll<HTMLElement>('.sp-controls > [role="button"]')[4];
+
+    await act(async () => root?.render(render(true)));
+    expect(nextButton.classList.contains('sp-disabled')).toBe(false);
+    nextButton.click();
+    video!.currentTime = 12;
+    video!.dispatchEvent(new Event('pause'));
+    expect(onNext).toHaveBeenCalledOnce();
+    expect(onSaveProgress).toHaveBeenLastCalledWith('episode', 12);
+    expect(sessionStorage.getItem('sweet-player:progress')).toBeNull();
+
+    await act(async () => root?.render(render(false)));
+    expect(nextButton.classList.contains('sp-disabled')).toBe(true);
+    video!.currentTime = 22;
+    video!.dispatchEvent(new Event('pause'));
+    const progress = JSON.parse(sessionStorage.getItem('sweet-player:progress') ?? '{}') as Record<
+      string,
+      { t: number }
+    >;
+    expect(progress.episode?.t).toBe(22);
+  });
+});
diff --git a/packages/react/vitest.config.ts b/packages/react/vitest.config.ts
new file mode 100644
index 0000000..05c7cd7
--- /dev/null
+++ b/packages/react/vitest.config.ts
@@ -0,0 +1,14 @@
+import { fileURLToPath } from 'node:url';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@sweet-player/core': fileURLToPath(new URL('../core/src/index.ts', import.meta.url)),
+    },
+  },
+  test: {
+    environment: 'jsdom',
+    include: ['test/**/*.test.tsx'],
+  },
+});
diff --git a/packages/vue/package.json b/packages/vue/package.json
index 0594df0..d8aa384 100644
--- a/packages/vue/package.json
+++ b/packages/vue/package.json
@@ -19,6 +19,7 @@
   "sideEffects": false,
   "scripts": {
     "build": "tsup",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
   "license": "MIT",
@@ -42,8 +43,10 @@
     "vue": "^3.0.0"
   },
   "devDependencies": {
+    "jsdom": "^29.1.1",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
+    "vitest": "^4.1.10",
     "vue": "^3.5.13"
   }
 }
diff --git a/packages/vue/src/SweetPlayer.ts b/packages/vue/src/SweetPlayer.ts
index a61e086..c0c3141 100644
--- a/packages/vue/src/SweetPlayer.ts
+++ b/packages/vue/src/SweetPlayer.ts
@@ -1,8 +1,10 @@
 import {
   defineComponent,
+  getCurrentInstance,
   h,
   onBeforeUnmount,
   onMounted,
+  onUpdated,
   ref,
   shallowRef,
   watch,
@@ -67,8 +69,28 @@ export const SweetPlayer = defineComponent({
     'error',
   ],
   setup(props, { emit, expose }) {
+    const instance = getCurrentInstance();
     const containerRef = ref<HTMLDivElement>();
     const player = shallowRef<CorePlayer | null>(null);
+    const emitPrev = () => emit('prev');
+    const emitNext = () => emit('next');
+    const emitQualityChange = (quality: QualityLevel) => emit('quality-change', quality);
+    const emitAudioTrackChange = (track: AudioTrackInfo) => emit('audio-track-change', track);
+    const hasListener = (name: 'onPrev' | 'onNext') => {
+      const vnodeProps = instance?.vnode.props;
+      return vnodeProps?.[name] != null || vnodeProps?.[`${name}Once`] != null;
+    };
+
+    const syncCallbacks = () => {
+      player.value?.setCallbacks({
+        onPrev: hasListener('onPrev') ? emitPrev : undefined,
+        onNext: hasListener('onNext') ? emitNext : undefined,
+        onQualityChange: emitQualityChange,
+        onAudioTrackChange: emitAudioTrackChange,
+        onSavePrefs: props.onSavePrefs,
+        onSaveProgress: props.onSaveProgress,
+      });
+    };
 
     onMounted(() => {
       if (!containerRef.value) return;
@@ -102,10 +124,10 @@ export const SweetPlayer = defineComponent({
         dashConfig: props.dashConfig,
         onSavePrefs: props.onSavePrefs,
         onSaveProgress: props.onSaveProgress,
-        onPrev: () => emit('prev'),
-        onNext: () => emit('next'),
-        onQualityChange: (q) => emit('quality-change', q),
-        onAudioTrackChange: (t) => emit('audio-track-change', t),
+        ...(hasListener('onPrev') && { onPrev: emitPrev }),
+        ...(hasListener('onNext') && { onNext: emitNext }),
+        onQualityChange: emitQualityChange,
+        onAudioTrackChange: emitAudioTrackChange,
       });
       // 桥接核心播放事件到 Vue emits
       p.on('play', () => emit('play'));
@@ -119,6 +141,19 @@ export const SweetPlayer = defineComponent({
       emit('ready', p);
     });
 
+    watch([() => props.onSavePrefs, () => props.onSaveProgress], syncCallbacks);
+    // 父组件的其他更新也可能同时增删事件监听器；此时刷新导航按钮状态。
+    onUpdated(syncCallbacks);
+
+    // id 必须先于 src 更新：setId 保存旧进度依赖旧媒体 currentTime，
+    // 若先 load 换源，旧媒体被 detach/重置，进度会丢失
+    watch(
+      () => props.id,
+      (id) => {
+        if (player.value) player.value.setId(id ?? null);
+      },
+    );
+
     watch(
       () => props.src,
       (src) => {
@@ -131,13 +166,6 @@ export const SweetPlayer = defineComponent({
       (title) => player.value?.setTitle(title ?? ''),
     );
 
-    watch(
-      () => props.id,
-      (id) => {
-        if (id) player.value?.setId(id);
-      },
-    );
-
     watch(
       () => props.qualities,
       (qualities) => {
diff --git a/packages/vue/test/SweetPlayer.test.ts b/packages/vue/test/SweetPlayer.test.ts
new file mode 100644
index 0000000..70811fb
--- /dev/null
+++ b/packages/vue/test/SweetPlayer.test.ts
@@ -0,0 +1,114 @@
+import { createApp, h, nextTick, ref, type App } from 'vue';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { SweetPlayer as CorePlayer } from '@sweet-player/core';
+import { SweetPlayer } from '../src/SweetPlayer';
+
+let host: HTMLDivElement;
+let app: App<Element> | null;
+
+beforeEach(() => {
+  localStorage.clear();
+  sessionStorage.clear();
+  host = document.createElement('div');
+  document.body.appendChild(host);
+  vi.spyOn(HTMLMediaElement.prototype, 'load').mockImplementation(() => {});
+  vi.spyOn(HTMLMediaElement.prototype, 'play').mockResolvedValue(undefined);
+  vi.spyOn(HTMLMediaElement.prototype, 'pause').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  app?.unmount();
+  app = null;
+  host.remove();
+  vi.restoreAllMocks();
+});
+
+describe('SweetPlayer Vue wrapper', () => {
+  it('disables navigation when no event listener is registered', async () => {
+    app = createApp({ render: () => h(SweetPlayer, { src: '/video.mp4' }) });
+    app.mount(host);
+    await nextTick();
+
+    const buttons = host.querySelectorAll<HTMLElement>('.sp-controls > [role="button"]');
+    expect(buttons[0].classList.contains('sp-disabled')).toBe(true);
+    expect(buttons[4].classList.contains('sp-disabled')).toBe(true);
+  });
+
+  it('enables navigation when a listener is registered', async () => {
+    const onNext = vi.fn();
+    app = createApp({ render: () => h(SweetPlayer, { src: '/video.mp4', onNext }) });
+    app.mount(host);
+    await nextTick();
+
+    const nextButton = host.querySelectorAll<HTMLElement>('.sp-controls > [role="button"]')[4];
+    expect(nextButton.classList.contains('sp-disabled')).toBe(false);
+    nextButton.click();
+    expect(onNext).toHaveBeenCalledOnce();
+  });
+
+  it('updates navigation when a listener is added or removed', async () => {
+    const listenerEnabled = ref(false);
+    const onNext = vi.fn();
+    app = createApp({
+      render: () =>
+        h(SweetPlayer, {
+          src: '/video.mp4',
+          ...(listenerEnabled.value ? { onNext } : {}),
+        }),
+    });
+    app.mount(host);
+    await nextTick();
+
+    const nextButton = host.querySelectorAll<HTMLElement>('.sp-controls > [role="button"]')[4];
+    expect(nextButton.classList.contains('sp-disabled')).toBe(true);
+
+    listenerEnabled.value = true;
+    await nextTick();
+    expect(nextButton.classList.contains('sp-disabled')).toBe(false);
+    nextButton.click();
+    expect(onNext).toHaveBeenCalledOnce();
+
+    listenerEnabled.value = false;
+    await nextTick();
+    expect(nextButton.classList.contains('sp-disabled')).toBe(true);
+  });
+
+  it('switches progress callbacks between remote and local modes', async () => {
+    const remoteEnabled = ref(false);
+    const onSaveProgress = vi.fn();
+    let player: CorePlayer | null = null;
+    app = createApp({
+      render: () =>
+        h(SweetPlayer, {
+          src: '/video.mp4',
+          id: 'episode',
+          onReady: (value: CorePlayer) => {
+            player = value;
+          },
+          ...(remoteEnabled.value ? { onSaveProgress } : {}),
+        }),
+    });
+    app.mount(host);
+    await nextTick();
+
+    const video = (player as CorePlayer | null)?.video;
+    expect(video).toBeDefined();
+    Object.defineProperty(video!, 'duration', { configurable: true, value: 100 });
+    remoteEnabled.value = true;
+    await nextTick();
+    video!.currentTime = 14;
+    video!.dispatchEvent(new Event('pause'));
+    expect(onSaveProgress).toHaveBeenLastCalledWith('episode', 14);
+    expect(sessionStorage.getItem('sweet-player:progress')).toBeNull();
+
+    remoteEnabled.value = false;
+    await nextTick();
+    video!.currentTime = 24;
+    video!.dispatchEvent(new Event('pause'));
+    const progress = JSON.parse(sessionStorage.getItem('sweet-player:progress') ?? '{}') as Record<
+      string,
+      { t: number }
+    >;
+    expect(progress.episode?.t).toBe(24);
+  });
+});
diff --git a/packages/vue/vitest.config.ts b/packages/vue/vitest.config.ts
new file mode 100644
index 0000000..8a4178d
--- /dev/null
+++ b/packages/vue/vitest.config.ts
@@ -0,0 +1,14 @@
+import { fileURLToPath } from 'node:url';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@sweet-player/core': fileURLToPath(new URL('../core/src/index.ts', import.meta.url)),
+    },
+  },
+  test: {
+    environment: 'jsdom',
+    include: ['test/**/*.test.ts'],
+  },
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ae0b85b..b663f8b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -48,15 +48,27 @@ importers:
       '@types/react':
         specifier: ^19.0.0
         version: 19.2.17
+      '@types/react-dom':
+        specifier: ^19.0.0
+        version: 19.2.3(@types/react@19.2.17)
+      jsdom:
+        specifier: ^29.1.1
+        version: 29.1.1
       react:
         specifier: ^19.0.0
         version: 19.2.7
+      react-dom:
+        specifier: ^19.0.0
+        version: 19.2.7(react@19.2.7)
       tsup:
         specifier: ^8.3.5
         version: 8.5.1(postcss@8.5.16)(typescript@5.9.3)
       typescript:
         specifier: ^5.7.2
         version: 5.9.3
+      vitest:
+        specifier: ^4.1.10
+        version: 4.1.10(jsdom@29.1.1)(vite@6.4.3)
 
   packages/vue:
     dependencies:
@@ -64,12 +76,18 @@ importers:
         specifier: workspace:*
         version: link:../core
     devDependencies:
+      jsdom:
+        specifier: ^29.1.1
+        version: 29.1.1
       tsup:
         specifier: ^8.3.5
         version: 8.5.1(postcss@8.5.16)(typescript@5.9.3)
       typescript:
         specifier: ^5.7.2
         version: 5.9.3
+      vitest:
+        specifier: ^4.1.10
+        version: 4.1.10(jsdom@29.1.1)(vite@6.4.3)
       vue:
         specifier: ^3.5.13
         version: 3.5.39(typescript@5.9.3)