Npmlibrary

Thumbnail

预计阅读时间: 3 分钟

基于时间的缩略图预览组件，用于时间轴拖动和悬停预览。

快速开始：视频轨道

Thumbnail 可以直接从视频轨道读取缩略图提示。在媒体元素上添加一个 kind="metadata" 和 label="thumbnails" 的 <track>。

<Video src="video.mp4">
  <track
    kind="metadata"
    label="thumbnails"
    src="https://image.mux.com/{PLAYBACK_ID}/storyboard.vtt"
    default
  />
</Video>
<Thumbnail time={12} />

结构

<Thumbnail time={12} />

行为

Thumbnail 根据当前 time 解析图片。

支持的源格式：

文本轨道：<track kind="metadata" label="thumbnails" src="...vtt">
JSON 数组：{ url, startTime, endTime? }[]
JSON 精灵图数组：{ url, startTime, endTime?, width, height, coords }[]

在 React 中，文本轨道模式需要 Player.Provider，因为它从播放器存储读取轨道状态。JSON 模式（thumbnails 属性）无需 Provider 即可工作。

组件选择 startTime 小于或等于当前 time 的最新缩略图，然后缩放/裁剪精灵图块以适应 CSS 最小/最大约束，同时保持宽高比。

样式

使用状态 Data 属性进行纯 CSS 样式：

.thumbnail[data-hidden] {
  display: none;
}

.thumbnail[data-loading] {
  opacity: 0.6;
}

.thumbnail[data-error] {
  outline: 1px solid #ef4444;
}

无障碍

Thumbnail 默认为装饰性（aria-hidden="true"）。它用于视觉预览用户体验（例如时间轴悬停预览），而不是主要的无障碍内容。

示例

文本轨道（VTT）

import { Thumbnail } from '@videojs/react';

function PlayerWithThumbnails() {
  return (
    <Player.Provider>
      <Player.Container>
        <Video src="video.mp4">
          <track
            kind="metadata"
            label="thumbnails"
            src="storyboard.vtt"
            default
          />
        </Video>
        <TimeSlider.Root>
          <TimeSlider.Preview>
            <Thumbnail time={currentTime} />
          </TimeSlider.Preview>
        </TimeSlider.Root>
      </Player.Container>
    </Player.Provider>
  );
}

JSON 数组

<Thumbnail
  time={12}
  thumbnails={[
    { url: 'thumb1.jpg', startTime: 0, endTime: 5 },
    { url: 'thumb2.jpg', startTime: 5, endTime: 10 },
  ]}
/>

API 参考

属性

属性	类型	默认值	描述
`time`	`number`	-	要显示缩略图的时间点（秒）
`thumbnails`	`ThumbnailSource[]`	-	JSON 格式的缩略图源数组

状态

状态	类型	描述
`hidden`	`boolean`	缩略图是否隐藏
`loading`	`boolean`	是否正在加载
`error`	`boolean`	是否加载出错

Data 属性

属性	值	描述
`data-hidden`	-	当缩略图隐藏时存在
`data-loading`	-	当正在加载时存在
`data-error`	-	当加载出错时存在

参见

TimeSlider - 时间滑块
Poster - 海报图片

#Thumbnail

#快速开始：视频轨道

#结构

#行为

#样式

#无障碍

#示例

#文本轨道（VTT）

#JSON 数组

#API 参考

#属性

#状态

#Data 属性

#参见