Media Session API最早是为音乐播放场景设计的，浏览器通过navigator.mediaSession向开发者提供设置播放元数据、动作处理器的能力。随着视频会议类Web应用的普及，浏览器厂商进一步扩展了这套API，引入了通知页面摄像头活跃状态的能力。不过这套能力比较新，TypeScript的内置lib.dom.d.ts里往往还没有对应的类型声明，直接调用会报类型错误。这篇文章就来聊聊如何在TypeScript中为它补齐类型定义，并做好运行时兼容。
一、Set Camera Active API的实际调用形态
先看清楚浏览器暴露的到底是什么。目前在Chromium系浏览器的实现中，这套能力体现为setCameraActive与配套的setMicrophoneActive方法，挂在navigator.mediaSession对象上，接收一个布尔值参数，用来告知浏览器当前页面的摄像头或麦克风是否处于活跃状态，浏览器据此可以在系统UI上展示提示信息。它的方法签名非常简单：
navigator.mediaSession.setCameraActive(true); // 标记摄像头活跃 navigator.mediaSession.setMicrophoneActive(false); // 标记麦克风非活跃
需要特别注意的是，这个方法目前是同步返回的，不返回Promise，也不抛出业务异常。如果浏览器不支持该方法，直接调用会抛出TypeError，因为属性本身不存在。因此在写类型声明之前，要先明确两点：第一，方法是可选成员，旧类型定义里没有；第二，参数是严格的boolean，避免类型收窄成truthy值导致运行时行为不一致。
很多开发者会把它和getUserMedia搞混。后者是真正申请摄像头权限并获取媒体流的异步API，而setCameraActive只是状态通知，它不申请权限、不产生媒体流，二者属于配合使用的关系：先通过getUserMedia拿到流，再调用setCameraActive同步状态。
二、编写类型声明文件
类型声明的核心思路是对TS内置的MediaSession接口做声明合并。TypeScript允许在declare global块中对全局接口追加成员，只要接口名一致，编译期就会自动合并。下面是一个完整可用的d.ts文件：
// camera-active.d.ts
declare global {
interface MediaSession {
/**
* 通知浏览器当前页面的摄像头是否处于活跃状态。
* 该方法同步执行，无返回值。
*/
setCameraActive?(active: boolean): void;
/**
* 通知浏览器当前页面的麦克风是否处于活跃状态。
*/
setMicrophoneActive?(active: boolean): void;
}
}
export {}; // 确保该文件被识别为模块，触发全局声明合并这里有几个细节值得展开。第一，把方法声明成可选成员（方法名后加问号），这样在运行时检测不存在时，类型系统不会强迫你调用它，写if (navigator.mediaSession.setCameraActive)这样的守卫代码不会报错。第二，末尾的export {}不能省，否则这个文件会被当成纯环境声明文件，declare global的写法在某些编译配置下不生效。第三，不要在参数类型上偷懒写成any，保持boolean能让编译器拦截setCameraActive(1)这类隐患。
另一种做法是模块内扩展。如果你的项目全部使用ES模块，也可以通过模块增强的方式实现，即import原始类型定义再做interface扩展。不过对于lib.dom.d.ts中的全局接口，declare global是最省事也最通用的方案，推荐优先采用。
三、运行时能力检测与安全封装
类型声明只解决编译期问题，实际运行时还要处理浏览器不支持的情况。直接调用不存在的方法会抛异常，所以封装一个带能力检测的安全函数是更稳妥的工程实践：
function notifyCameraActive(active: boolean): void {
const session = navigator.mediaSession;
// 能力检测：方法存在才调用
if (session && typeof session.setCameraActive === "function") {
session.setCameraActive(active);
} else {
console.debug("当前浏览器不支持 setCameraActive");
}
}
// 与 getUserMedia 配合使用的典型流程
async function startCamera(): Promise<MediaStream> {
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
notifyCameraActive(true);
return stream;
}这段代码体现了两个工程要点。其一，能力检测要写成typeof session.setCameraActive === "function"而不是简单的if (session.setCameraActive)，虽然后者在这里也能工作，但前者更严谨，能兼容属性被赋值为非函数值的异常场景。其二，状态通知要与真实媒体流的生命周期严格绑定，在track.onended或停止流的地方记得调用notifyCameraActive(false)，否则浏览器UI上的摄像头提示会与实际状态脱节，用户体验会很奇怪。
如果把这套封装放到团队公共库里，还可以进一步用类型守卫收窄类型，给下游调用者提供更清晰的提示。例如定义一个hasCameraActiveSupport函数返回session is MediaSession & { setCameraActive: (a: boolean) => void }，通过守卫后的对象在类型上就是必选成员，调用代码可以少写一层判断。
四、在视频会议场景中的完整实践
以一个简单的会议页面为例，摄像头开关按钮的处理器需要同时维护媒体流和通知状态，两件事必须保持原子性的一致：
let cameraStream: MediaStream | null = null;
async function toggleCamera(on: boolean): Promise<void> {
if (on && !cameraStream) {
cameraStream = await navigator.mediaDevices.getUserMedia({ video: true });
notifyCameraActive(true);
} else if (!on && cameraStream) {
cameraStream.getVideoTracks().forEach(t => t.stop());
cameraStream = null;
notifyCameraActive(false);
}
}这个模式的意义在于让浏览器层面的提示（比如标签页上的摄像头图标、系统状态栏提示）与应用内部状态同步。如果只调用getUserMedia而不做状态通知，在某些实现下用户可能感知不到页面正在使用摄像头，反之如果通知了状态却早已停止了流，又会误导用户。
总结一下整个接入流程：先通过d.ts对MediaSession接口做声明合并，补上可选的setCameraActive方法；再封装带能力检测的安全函数，保证旧浏览器下静默降级；最后在业务层把状态通知与媒体流生命周期绑定。这样一套下来，TypeScript的类型检查和运行时兼容都能兼顾，新API也可以放心地在生产项目中落地。
TypeScriptMedia Session API摄像头激活状态修改时间：2026-09-13 21:20:52