useMediaAttach
预计阅读时间: 4 分钟
注册自定义媒体元素的钩子。
useMediaAttach 用于在 Video.js React 中注册自定义的媒体元素。当你想替换默认的 Video 或 Audio 组件时，这个钩子允许你将自己的媒体元素注册到播放器上下文中。
示例
基本用法
import { useMediaAttach } from '@videojs/react';
function CustomVideo({ src, ...props }) {
const setMedia = useMediaAttach();
return (
<video
ref={setMedia}
src={src}
className="custom-video"
{...props}
/>
);
}
自定义媒体源
import { useMediaAttach } from '@videojs/react';
function HlsVideo({ src, ...props }) {
const setMedia = useMediaAttach();
// 使用 HLS.js 或其他自定义播放器
const videoRef = useRef<HTMLVideoElement>(null);
useEffect(() => {
if (videoRef.current && src) {
// 初始化 HLS.js 或其他播放逻辑
const hls = new Hls();
hls.loadSource(src);
hls.attachMedia(videoRef.current);
}
}, [src]);
return (
<video
ref={(el) => {
setMedia(el);
(videoRef as any).current = el;
}}
className="hls-video"
playsInline
{...props}
/>
);
}
与自定义容器结合
import { useMediaAttach, useContainerAttach } from '@videojs/react';
function CustomPlayer() {
const setContainer = useContainerAttach();
const setMedia = useMediaAttach();
return (
<div ref={setContainer} className="custom-player">
<video
ref={setMedia}
className="custom-video-element"
autoPlay
muted
playsInline
/>
<Controls />
</div>
);
}
API 参考
返回值
| 返回值 | 类型 | 说明 |
|---|
Dispatch<RefObject<HTMLMediaElement>> | React.RefCallback<HTMLMediaElement> | 设置器函数，用于注册媒体元素 |
返回值详解
返回的函数是一个 RefCallback，当你将其附加到 <video> 或 <audio> 元素时，该元素会自动注册为播放器媒体元素。
类型签名：
type Dispatch = React.RefCallback<HTMLMediaElement>
使用场景
何时需要
useMediaAttach 主要在以下场景使用：
- 替换 Video/Audio 组件 - 当你想使用自定义的媒体组件
- HLS/DASH 流媒体 - 使用 HLS.js 或 DASH.js 等库处理流媒体
- 自定义播放器逻辑 - 需要完全控制媒体元素的播放行为
- 集成第三方播放器 - 将 Video.js React 与其他播放器库集成
安全使用
这个钩子可以安全地在 Player.Provider 外部调用：
function SafeVideo({ src }) {
const setMedia = useMediaAttach();
// 在 Provider 外调用会返回 undefined
// 不会抛出错误
return <video ref={setMedia} src={src} />;
}
当在 Provider 外调用时，返回值为 undefined，但不会抛出错误。
与 useContainerAttach 的区别
| 钩子 | 用途 | 何时使用 |
|---|
useMediaAttach | 注册媒体元素 | 替换 Video/Audio 组件时 |
useContainerAttach | 注册容器元素 | 替换 Player.Container 时 |
注意事项
元素类型
注册的元素必须是 <video> 或 <audio> HTML 元素。如果注册了其他类型的元素，可能会导致运行时错误。
初始化顺序
确保在媒体元素挂载后再进行其他操作：
function VideoComponent({ src }) {
const setMedia = useMediaAttach();
const [isReady, setIsReady] = useState(false);
return (
<video
ref={setMedia}
src={src}
onCanPlay={() => setIsReady(true)}
/>
);
}
参见
