开发预览更新于 2026-05-10

VideoPlayer 视频播放器

HTML5 video 之上的自定义控件栏：播放 / 进度 / 时长 / 音量 / 倍速 / 全屏；2 秒空闲自动隐藏；overlay 插槽放章节 / 水印。

基础用法

控件栏在播放后 2 秒无 pointer 移动自动淡出；任意 pointer 移动重新出现。点击视频本体切换播放 / 暂停。captions 传 { src, label, srclang?, default? }[] 自动生成 WebVTT <track>。

背景视口

src/App.vue

<script setup lang="ts">
import { CfVideoPlayer } from '@chufix-design/vue';
</script>
<template>
  <CfVideoPlayer
    src="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
    poster="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/images/BigBuckBunny.jpg"
    aspect-ratio="16 / 9"
  />
</template>

<script setup>
import { CfVideoPlayer } from '@chufix-design/vue';
</script>
<template>
  <CfVideoPlayer
    src="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
    poster="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/images/BigBuckBunny.jpg"
    aspect-ratio="16 / 9"
  />
</template>

import { CfVideoPlayer } from '@chufix-design/react';

export default function Demo() {
  return (
    <>
      <CfVideoPlayer
      src="/clip.mp4"
      poster="/poster.jpg"
      aspectRatio="16 / 9"
      captions={[{ src: '/zh.vtt', label: '中文', srclang: 'zh', default: true }]}
      />
    </>
  );
}

import { CfVideoPlayer } from '@chufix-design/react';

export default function Demo() {
  return (
    <>
      <CfVideoPlayer
      src="/clip.mp4"
      poster="/poster.jpg"
      aspectRatio="16 / 9"
      captions={[{ src: '/zh.vtt', label: '中文', srclang: 'zh', default: true }]}
      />
    </>
  );
}

API

Props

属性	类型	默认	说明
`src`	`string`	—	视频源
`poster`	`string`	—	封面
`aspectRatio`	`string`	`'16 / 9'`	CSS aspect-ratio
`autoplay` / `loop` / `muted`	`boolean`	`false`	原生属性
`preload`	`'auto' \| 'metadata' \| 'none'`	`'metadata'`
`captions`	`VideoCaption[]`	—	字幕轨
`playbackRates`	`number[]`	`[0.5, 0.75, 1, 1.25, 1.5, 2]`	倍速菜单

Slots / overlay

Vue: <template #overlay> 渲染章节标题 / 水印 / 直播提示等；React: overlay prop。

Events

事件	载荷	说明
`play` / `pause` / `ended`	—
`timeupdate`	`(time, duration)`
`volumechange`	`(volume, muted)`
`ratechange`	`rate`	倍速变更