Video · Pactor UI 资产库

元信息

字段	值
规范 ID	`component.video`
名称	Video
二级分类	媒体与内容（`media`）
用途	播放视频内容
描述	中文惯用名：视频播放。

预览

静态结构：<video data-slot="video">（w-full rounded-md，playsInline）；src / poster / controls（默认 true）/ autoplay / loop / muted 透传原生属性。本预览仅配置 poster 封面（未配置 src）。

DSL 结构

DslNode

{
  "type": "Video",
  "props": {
    "src": "https://example.com/intro.mp4",
    "poster": "https://example.com/intro-poster.png",
    "controls": true,
    "loop": true
  }
}

何时用

何时使用

播放视频内容：宣传片、教程、会议录屏。
需要封面图、原生控制条的常规播放场景。

何时不用

直播流 / 自定义播放器皮肤：本组件是原生 video 包装，需自建播放器。
音频内容：使用 Audio。

变体

变体	视觉形态	适用场景
控制条播放	原生 controls	常规视频内容
封面占位	poster 封面	未加载时的视觉占位
静音自动播放	autoplay + muted	背景氛围视频

API 属性

属性	类型	默认值	说明
`src`	`string`	—	视频地址
`poster`	`string`	—	封面图地址
`controls`	`boolean`	true	是否显示原生控制条
`autoplay`	`boolean`	false	自动播放（浏览器策略要求同时 muted）
`loop`	`boolean`	false	循环播放
`muted`	`boolean`	false	静音
`className / style`	`string / CSSProperties`	—	通用：根节点 class 合并 / 内联样式

使用规范

自动播放必须同时 muted（浏览器策略），否则被拦截。
提供 poster 避免加载期空白。
默认全宽渲染，尺寸由外层容器（Grid / Container）约束。

正例

✓ 帮助中心：教程视频 poster 封面 + 控制条播放。
✓ 落地页头图：muted + autoplay + loop 背景视频。

反例

✕ 试图用本组件做直播（协议与延迟要求不同）。
✕ autoplay 不带 muted 然后排查「为什么不播」。

Design Token 映射

不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。

关联资产