TypeScript中HTMLVideoElement扩展属性类型错误与视频音频检测问题

这是TypeScript处理浏览器私有DOM API的常见问题——标准HTMLVideoElement类型只包含各浏览器通用的属性，而mozHasAudio（Firefox）、webkitAudioDecodedByteCount（Chrome/WebKit）这类带厂商前缀的私有属性不在默认类型定义里，所以会报类型错误。可以通过以下步骤解决：

1. 扩展HTMLVideoElement类型声明 #

在你的项目中添加类型扩展文件（比如dom-extensions.d.ts），或者直接在组件文件顶部声明扩展接口，让TypeScript识别这些私有属性：

// dom-extensions.d.ts
interface HTMLVideoElement {
  // Firefox私有属性：直接标识是否有音频轨道
  mozHasAudio?: boolean;
  // Chrome/WebKit私有属性：已解码的音频字节数，非零则表示有音频
  webkitAudioDecodedByteCount?: number;
}

如果是在组件文件中声明，要确保是全局作用域：

declare global {
  interface HTMLVideoElement {
    mozHasAudio?: boolean;
    webkitAudioDecodedByteCount?: number;
  }
}

2. 安全检测音频存在性 #

即使扩展了类型，运行时还是要做属性存在性检查（避免浏览器不支持时出错），同时优先使用标准API：

const checkVideoHasAudio = (player: HTMLVideoElement | null): boolean => {
  if (!player) return false;

  // 优先使用标准audioTracks API
  if ('audioTracks' in player && player.audioTracks.length > 0) {
    return true;
  }
  // 检测Firefox私有属性
  if ('mozHasAudio' in player && typeof player.mozHasAudio === 'boolean') {
    return player.mozHasAudio;
  }
  // 检测Chrome/WebKit私有属性
  if ('webkitAudioDecodedByteCount' in player && player.webkitAudioDecodedByteCount > 0) {
    return true;
  }

  // 兜底逻辑：根据业务需求调整，比如默认认为有音频
  return true;
};

3. 在React Player中正确获取视频元素 #

通过React Player的ref获取内部的视频元素时，注意类型转换：

import React, { useRef, useEffect } from 'react';
import ReactPlayer from 'react-player';

const VideoPlayer = () => {
  const playerRef = useRef<ReactPlayer | null>(null);

  useEffect(() => {
    // 获取ReactPlayer内部的HTMLVideoElement实例
    const videoEl = playerRef.current?.getInternalPlayer() as HTMLVideoElement | null;
    if (videoEl) {
      const hasAudio = checkVideoHasAudio(videoEl);
      console.log('视频是否包含音频:', hasAudio);
    }
  }, []);

  return <ReactPlayer ref={playerRef} url="/path/to/your/video.mp4" />;
};

export default VideoPlayer;

这样既保留了TypeScript的类型安全，又能兼容Chrome和Firefox的音频检测需求。

内容的提问来源于stack exchange，提问作者LadyBug