TypeScript中定义Media Session Set Screen Wake Lock Mute Active API屏幕唤醒锁静音状态同步类型

在构建音视频类Web应用时，开发者在TypeScript环境中最容易遇到的一个困惑是Media Session、Screen Wake Lock与普通页面状态之间的类型边界不够清晰。Media Session API负责把页面播放状态暴露给操作系统媒体中心，让用户能通过耳机线控、手表或系统通知栏控制页面；Screen Wake Lock则负责阻止屏幕熄灭。二者一个偏重交互，一个偏重显示，却在真实的播放器场景中需要协同工作。若不在TypeScript中定义好这些状态同步的类型，很容易在回调里出现空值访问、动作分发遗漏等隐患。

Media Session API 的类型边界与动作分发

先从Media Session API的TypeScript定义说起。这个API在DOM标准中的核心对象是navigator.mediaSession，它管理着媒体元数据与系统级媒体控件。在TypeScript中，我们通常需要声明三个数据维度：第一是元数据结构，也就是MediaMetadata所描述的信息；第二是动作处理器类型，即用户点击系统面板上的播放、暂停、上一首等按钮时浏览器调用的回调；第三是播放状态标记，用于告诉系统当前是播放中还是已暂停。很多项目的类型混乱，根源就在于这三者之间没有形成统一的约束。

参考以下类型定义，可以看到MediaSessionAction是一个字符串字面量联合类型，它严格约束了系统能回调的动作集合。而MediaSessionActionHandler接收一个细节对象，其中可能包含跳转时间等信息。TypeScript的索引签名在这里就很有用，我们可以用一个Partial<Record<MediaSessionAction, MediaSessionActionHandler>>来映射不同动作对应的回调，这样在调用setActionHandler时就能获得完整的类型推导，避免传错动作名称。此外，playbackState字段应当显式标注为MediaSessionPlaybackState，不能使用普通的string，这样才能在赋值阶段拦截无效状态值。

interface MediaImage {
  src: string;
  sizes?: string;
  type?: string;
}

type MediaSessionAction =
  | 'play'
  | 'pause'
  | 'seekbackward'
  | 'seekforward'
  | 'previoustrack'
  | 'nexttrack'
  | 'seekto'
  | 'stop'
  | 'hangup';

interface MediaSessionActionDetails {
  action: MediaSessionAction;
  seekTime?: number;
  fastSeek?: boolean;
}

type MediaSessionActionHandler = (details: MediaSessionActionDetails) => void;

type MediaSessionPlaybackState = 'none' | 'paused' | 'playing';

interface MediaSession {
  metadata: MediaMetadata | null;
  playbackState: MediaSessionPlaybackState;
  setActionHandler(
    action: MediaSessionAction,
    handler: MediaSessionActionHandler | null
  ): void;
}

interface MediaMetadata {
  title: string;
  artist: string;
  album: string;
  artwork: MediaImage[];
}

这里有个值得注意的细节：setActionHandler的第二参数允许传入null，这意味着要解除某个动作时，应当显式地传入null而不是undefined。在TypeScript代码中调用时，如果声明的回调变量是可选的，直接传undefined往往会导致运行时浏览器抛出异常。因此建议在封装层中先判空，再将回调或null交给API，这样的类型设计更贴近真实运行环境。

Screen Wake Lock 与静音状态的联动同步

Screen Wake Lock API的类型定义与Media Session有很大差异，它涉及的是WakeLockSentinel这个可释放的引用对象。WakeLockSentinel本质上是页面持有的一把锁，用于持续唤醒屏幕。既然它是长期存活的资源，TypeScript类型中就应当明确区分“已获取锁”与“锁已释放”两个阶段。我们可以使用WakeLockSentinel的非空联合null来表示锁是否存在，而WakeLockSentinel内部的released属性则用来表达锁是否处于生效状态。这种双层表达容易带来混淆，第一层是引用是否存在，第二层是锁是否激活。推荐的做法是在自己的状态管理器中只保存一个字段，例如activeWakeLock: WakeLockSentinel | null，配合监听器来更新。

静音状态与唤醒锁之间通常存在间接关联：播放器在静音状态下也可能继续播放视频画面，此时屏幕依然需要常亮。但有些产品逻辑认为静音的视频播放可以视为不重要的后台播放，从而释放唤醒锁以节省电量。这种业务规则适合用TypeScript的判别联合类型来建模。定义一个MediaState联合类型，其中status字段作为判别属性，再用muted和lockHeld字段组合出不同的状态机，可以避免在组件中零散地修改锁状态。

interface WakeLockSentinel extends EventTarget {
  released: boolean;
  type: 'screen';
  release(): Promise<void>;
  onrelease: ((this: WakeLockSentinel, ev: Event) => void) | null;
}

interface Navigator {
  wakeLock: {
    request(type: 'screen'): Promise<WakeLockSentinel>;
  };
}

type MediaMuteState = 'muted' | 'unmuted';
type MediaPlayState = 'playing' | 'paused';

interface SyncMediaState {
  playState: MediaPlayState;
  muteState: MediaMuteState;
  lockActive: boolean;
}

function shouldHoldWakeLock(state: SyncMediaState): boolean {
  return state.playState === 'playing';
}

async function syncWakeLock(
  state: SyncMediaState,
  previousLock: WakeLockSentinel | null
): Promise<WakeLockSentinel | null> {
  const shouldLock = shouldHoldWakeLock(state);
  if (shouldLock && !previousLock) {
    return navigator.wakeLock.request('screen');
  }
  if (!shouldLock && previousLock) {
    await previousLock.release();
    return null;
  }
  return previousLock;
}

上面的syncWakeLock函数展示了状态同步的核心思路：不直接操作锁，而是根据SyncMediaState推导出锁的期望状态，然后与当前锁的持有状态对比，决定是申请、释放还是保持原样。TypeScript的返回类型Promise<WakeLockSentinel | null>明确表达了锁可能不存在的事实，调用方必须处理null分支，这就迫使开发者避免对锁做无谓的空引用调用。

用类型安全的状态管理器整合所有API

前面两节分别阐述了Media Session和Screen Wake Lock的类型定义，但在实际项目中，它们需要在一个统一的状态管理器内协同。一个健壮的方案是使用泛型约束和事件监听器集合来实现发布订阅模式，从而让播放器组件、系统媒体面板和屏幕唤醒锁共享同一份状态快照。TypeScript在这里最大的贡献是能用最小的事件集合表达所有状态变化，减少无效更新。

定义一个MediaStateManager类，构造函数中注入navigator.mediaSession和navigator.wakeLock，这样便于单元测试时注入模拟实现。内部保存一个state属性，暴露update()方法用于局部更新状态，其它模块通过subscribe()方法来监听状态变化。在update()内部，我们通过比较新旧状态的差异来决定是否调用mediaSession.setActionHandler、是否更新mediaSession.playbackState、是否请求或释放唤醒锁。

type Listener = (state: SyncMediaState) => void;

class MediaStateManager {
  private listeners = new Set<Listener>();
  private wakeLock: WakeLockSentinel | null = null;
  private state: SyncMediaState = {
    playState: 'paused',
    muteState: 'unmuted',
    lockActive: false,
  };

  constructor(
    private mediaSession: MediaSession,
    private wakeLockManager: Navigator['wakeLock']
  ) {
    this.bindMediaActions();
  }

  getSnapshot(): SyncMediaState {
    return this.state;
  }

  subscribe(listener: Listener): () => void {
    this.listeners.add(listener);
    return () => this.listeners.delete(listener);
  }

  async update(patch: Partial<SyncMediaState>): Promise<void> {
    const nextState = { ...this.state, ...patch };
    nextState.lockActive = shouldHoldWakeLock(nextState);
    this.state = nextState;
    this.mediaSession.playbackState = nextState.playState;
    this.notify();
    this.wakeLock = await syncWakeLock(this.state, this.wakeLock);
  }

  private notify(): void {
    this.listeners.forEach((listener) => listener(this.state));
  }

  private bindMediaActions(): void {
    const actionMap: Record<MediaSessionAction, () => void> = {
      play: () => this.update({ playState: 'playing' }),
      pause: () => this.update({ playState: 'paused' }),
      stop: () => this.update({ playState: 'paused' }),
      previoustrack: () => this.update({ playState: 'playing' }),
      nexttrack: () => this.update({ playState: 'playing' }),
      seekbackward: () => this.update({ playState: 'playing' }),
      seekforward: () => this.update({ playState: 'playing' }),
      seekto: () => this.update({ playState: 'playing' }),
      hangup: () => this.update({ playState: 'paused' }),
    };

    (Object.keys(actionMap) as MediaSessionAction[]).forEach((action) => {
      this.mediaSession.setActionHandler(action, () => {
        actionMap[action]();
      });
    });
  }
}

这个管理器最核心的优化在于，update()方法只接收Partial<SyncMediaState>补丁对象，避免了调用方自行计算锁状态。同时，由于syncWakeLock返回的是一个稳定引用或null，在TypeScript下可以清晰地感知到每次更新后锁的生命周期变化。订阅者拿到的快照中lockActive总是与playState保持一致，因此UI层无需再关心底层两条API的时序问题。

这种设计不仅提升了类型安全，还赋予项目更好的可测试性。借助TypeScript的接口只需要模拟MediaSession上的setActionHandler与playbackState，以及wakeLock.request与release()，就能用vitest或jest在Node环境里验证全部状态转换路径。总而言之，类型定义并非只是为满足编译器而写，它是把浏览器API的隐式契约显性化的关键手段。

Media Session APIScreen Wake LockTypeScript类型修改时间：2026-08-24 20:12:17