# @api\.video/react-player 中文文档 规范地址：https://npmcn.com/package/%40api.video/react-player/ 版本：1\.1\.0 npm 元数据更新时间：2025-05-22T12:50:41.520Z 中文译文更新时间：2026-11-06T09:53:32.323Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40api.video/react-player 原文对照：https://npmcn.com/package/%40api.video/react-player/?lang=original 项目主页：https://github.com/apivideo/api.video-react-player#readme 源码仓库：https://github.com/apivideo/api.video-react-player ## 关键信息（来自 npm 元数据） - 包体积（解压后）：110 kB，9 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：1 个 - peer 依赖：react \>=16\.6\.0 - 首次发布：2022-04-20T16:44:19.959Z - 最新版本发布：2024-06-19T15:43:56.914Z - 近 30 天下载量：19658（2026-10-06 至 2026-11-04，npm 官方下载统计） - 已发布版本数：10（近 12 个月 0 个） ## 中文简介 视频 反应播放器组件 ## 安装 ```sh npm install @api.video/react-player ``` 也可以使用：`pnpm add @api.video/react-player`、`yarn add @api.video/react-player`、`bun add @api.video/react-player` ## README [![badge](https://img.shields.io/twitter/follow/api_video?style=social)](https://twitter.com/intent/follow?screen_name=api_video)   [![badge](https://img.shields.io/github/stars/apivideo/api.video-react-player?style=social)](https://github.com/apivideo/api.video-react-player)   [![badge](https://img.shields.io/discourse/topics?server=https%3A%2F%2Fcommunity.api.video)](https://community.api.video/) ![](https://github.com/apivideo/.github/blob/main/assets/apivideo_banner.png) # 视频 反应播放器组件 ![npm](https://img.shields.io/npm/v/@api.video/react-player) ![ts](https://badgen.net/badge/-/TypeScript/blue?icon=typescript&label) [视频](https://api.video/) 是产品制造者的视频基础设施。 闪电快视频 API 用于在您的应用程序中集成,缩放,并管理点播后低空直播功能. ## 目录 - [目录](https://npmcn.com/package/%40api.video/react-player/#readme-table-of-contents) - [项目说明](https://npmcn.com/package/%40api.video/react-player/#readme-project-description) - [开始](https://npmcn.com/package/%40api.video/react-player/#readme-getting-started) - [安装](https://npmcn.com/package/%40api.video/react-player/#readme-installation) - [基本用途](https://npmcn.com/package/%40api.video/react-player/#readme-basic-usage) - [文档](https://npmcn.com/package/%40api.video/react-player/#readme-documentation) - [属性](https://npmcn.com/package/%40api.video/react-player/#readme-properties) - [设置](https://npmcn.com/package/%40api.video/react-player/#readme-settings) - [控件](https://npmcn.com/package/%40api.video/react-player/#readme-controls) - [玩家主题](https://npmcn.com/package/%40api.video/react-player/#readme-player-theme) - [广告](https://npmcn.com/package/%40api.video/react-player/#readme-ads) - [反应](https://npmcn.com/package/%40api.video/react-player/#readme-responsiveness) - [回电](https://npmcn.com/package/%40api.video/react-player/#readme-callbacks) - [方法](https://npmcn.com/package/%40api.video/react-player/#readme-methods) - [使用大小写](https://npmcn.com/package/%40api.video/react-player/#readme-use-cases) - [私人录像](https://npmcn.com/package/%40api.video/react-player/#readme-private-videos) - [定义元数据](https://npmcn.com/package/%40api.video/react-player/#readme-defining-metadata) - [定义自己的控制](https://npmcn.com/package/%40api.video/react-player/#readme-define-your-own-controls) ## 项目说明 官方 api.video React Player 组件. ## 开始 ### 安装 ```sh $ npm install --save @api.video/react-player ``` ### 基本用途 然后您可以使用您的应用程序中的组件 : ```tsx import ApiVideoPlayer from "@api.video/react-player"; // ... ; ``` ## 文档 ### 属性 #### 设置 以下属性用于配置玩家. 每一个属性的值可以在回放期间随时被更改. | 财产 | 强制性 | 类型 | 说明 | 默认 | | --- | --- | --- | --- | --- | | 视频 | **对** | `{id: string;live?: boolean; token?: string;}` | `id`: 要播放的视频 id `token` (可选):秘密视频符号 `live` (可选):真实的视频 | | | 样式 | 没有 | 反应 CSS 财产 | 适用于玩家容器的 CSS 样式 | {} | | 自动播放 | 没有 | 布尔 | 定义视频是否在装入后立即开始播放 | 虚假 | | 哑巴 | 没有 | 布尔 | 视频是哑音 | 虚假 | | 元数据 | 没有 | `{ [key: string]: string }` | 包含对象 [元数据](https://api.video/blog/tutorials/dynamic-metadata/) (见 **实例** (见下文) | {} | | 隐藏鼠标 | 没有 | 布尔 | 也不要隐藏在视频首播前的海报图像 | 虚假 | | 无铬 | 没有 | 布尔 | 无色模式: 所有控件都隐藏 | 虚假 | | 循环 | 没有 | 布尔 | 视频完成后,会自动重新开始 | 虚假 | | 隐藏标题 | 没有 | 布尔 | 视频标题被隐藏 | 虚假 | | 播放范围 | 没有 | 编号 | 视频的回放率:1为正版,2为x2等. | 1个 | | 显示字幕 | 没有 | 布尔 | 确定是否显示视频字幕 | 虚假 | | 音量 | 没有 | 编号 | 相声卷. 0至1(0=哑音,1=100%) | 1个 | | 控件 | 没有 | 控件Name | 要显示的控件列表 。 如果没有指定和无铬=虚假,则显示所有控件,见下文 [控件](https://npmcn.com/package/%40api.video/react-player/#readme-controls) | 未定义 | | 主题 | 没有 | 玩家主题 | 适用于玩家的主题,见下文 [玩家主题](https://npmcn.com/package/%40api.video/react-player/#readme-player-theme)如果未指定,则使用默认主题 | 未定义 | | 响应 | 没有 | 布尔 | 或玩家shoulb的反应。 见下文 [响应](https://npmcn.com/package/%40api.video/react-player/#readme-responsiveness) | 虚假 | | 视频Style ObjectFit | 没有 | "收""收""收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收"收""收""""""""""""""""""""""""""""""""""""""" | 这个 `object-fit` 视频标签的 CSS 值 | 未定义 | | 相机变形 | 没有 | 字符串 | 这个 `transform` 视频标签的 CSS 值(例:"rotateY (180deg)") | 未定义 | | 广告 | 没有 | {ad TagUrl: string} (韩语) | 见下文 [广告](https://npmcn.com/package/%40api.video/react-player/#readme-ads) | | | 自定义域 | 没有 | 字符串 | 如果您为您的账户启用了自定义域, 那么完整的“ embed” 域名( 如 嵌入.mydomain.com) | | | 热键 | 无( 默认: 真) | 布尔 | 如果错误, 则解除玩家的热键, 使其无法捕捉焦点, 这在某些情况下可能是有益的 | | ##### 控件 这个 `controls` 属性允许您在玩家上显示 wich 控件。 以下是所有可用控件列表: `play`, (中文(简体) ), `seekBackward`, (中文(简体) ), `seekForward`, (中文(简体) ), `playbackRate`, (中文(简体) ), `volume`, (中文(简体) ), `fullscreen`, (中文(简体) ), `subtitles`, (中文(简体) ), `chapters`, (中文(简体) ), `pictureInPicture`, (中文(简体) ), `progressBar`, (中文(简体) ), `chromecast`, (中文(简体) ), `download`, (中文(简体) ), `more`。 。 。 . 实例 ```tsx { /* default: all controls are displayed */ } ; { /* all controls hidden (equivalent to chromeless=true) */ } ; { /* only the play button & the unmute one are displayed */ } ; ``` ##### 玩家主题 这个 `theme` 属性允许您自定义玩家上某些元素的颜色。 以下是可定制元素列表: `text`, (中文(简体) ), `link`, (中文(简体) ), `linkHover`, (中文(简体) ), `trackPlayed`, (中文(简体) ), `trackUnplayed`, (中文(简体) ), `trackBackground`, (中文(简体) ), `backgroundTop`, (中文(简体) ), `backgroundBottom`, (中文(简体) ), `backgroundText`, (中文(简体) ), `linkActive`。 。 。 . 示例 ```tsx { /* display the text in blue and the progress bar in red */ } ; ``` ##### 广告 广告可以在玩家中显示. 要做到这一点,你需要通过 `ads` 选项。 在那个 `ads` 对象,通过 `adTagUrl` 带有广告标签url的属性。 广告标签必须是VAST 2.0或 3.0 url. 有关VAST的更多信息,请查看 [IAB 文件](https://www.iab.com/guidelines/vast/)。 。 。 . 注:广告使用 [谷歌IMA SDK](https://developers.google.com/interactive-media-ads/docs/sdks/html5/quickstart)。 。 。 . ##### 反应 与 `responsive={true}`,玩家高度会根据玩家的宽度,自动设定视频与/高比相匹配. 示例 ```tsx { /* the player width is 160px and response is true: if the video in a 16/9 one, the height of the player will be automatically set to 90px (160 / (16/9)) */ } ; ``` #### 回电 | 财产 | 类型 | 说明 | | --- | --- | --- | | 运行 | () 无效 | 当一个 `play` 触发事件 | | 暂停 | () 无效 | 当一个 `pause` 触发事件 | | 无法控制 | () 无效 | 禁用控件时调用 | | 已启用控制器 | () 无效 | 启用控件时调用 | | 结束 | () 无效 | 当一个 `ended` 触发事件 | | 错误 | () 无效 | 当一个 `error` 触发事件 | | 首页 | () 无效 | 当一个 `firstPlay` 触发事件 | | 屏幕上的变化 | () 无效 | 当一个 `fullscreen` 触发事件 | | 移动输入 | () 无效 | 当鼠标进入玩家区域时调用 | | 移动 | () 无效 | 当鼠标离开玩家区域时调用 | | 更新 | () 无效 | 当一个 `resize` 触发事件 | | 质量变化 | (决议: `{ height: number, width: number }`(虚空) | 视频质量发生变化时调用. 提供了新的质量 | | 在电视上 | (比例:数目) | 当视频大小比变化(即新视频被装入时)时调用. 提供了新的比率 | | 时间变化 | () 无效 | 回放率变化时调用 | | 准备 | () 无效 | 当一个 `ready` 触发事件 | | 正在寻找 | () 无效 | 当一个 `seek` 触发事件 | | 时间更新 | (当前时间: 数字) 虚空 | 当一个 `timeupdate` 触发事件。 提供目前时间 | | 用户 | () 无效 | 当一个 `useractive` 触发事件 | | 用户活动 | () 无效 | 当一个 `userinactive` 触发事件 | | 变化 | (体积:数量) | 音量变化时调用. 已提供卷. | | 时间变化 | (期限:数目) | 视频持续时间变化时调用. 规定期限 | ### 方法 | 方法 | 说明 | | --- | --- | | 播放() | 播放视频 | | 暂停( c) | 暂停视频 | | 搜索( 时间: 数字) | 使用指定时间( 秒) 查找播放量 | | 设置当前时间( 时间: 数字) | 转到指定时间( 秒) | | 请求全屏 () | 请求全屏模式( 根据浏览器限制, 在某些情况下可能无法工作) | | 退出全屏 () | 离开全屏模式 | | 缩写 | 在图片模式下请求图片( 这在某些情况下可能无法工作, 取决于浏览器限制) | | 退出 Picture InPicture () | 在图片模式中保存图片 | ### 使用大小写 #### 私人录像 来玩一个 [私人视频](https://api.video/blog/tutorials/tutorial-private-videos/),在视频属性中添加视频视图符: ```tsx // ... ``` #### 定义元数据 ```tsx // ... ``` #### 定义自己的控制 ```tsx const playerRef = useRef(null); return; ; ``` ## 常见问题 ### @api\.video/react-player 是什么？ 视频 反应播放器组件 ### 如何安装 @api\.video/react-player？ 在项目目录运行 npm install @api\.video/react-player，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16\.6\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @api\.video/react-player 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @api\.video/react-player 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @api\.video/react-player 可以商用吗？ @api\.video/react-player 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @api\.video/react-player 的下载量有多少？ 根据 npm 官方下载统计，@api\.video/react-player 在 2026/10/06 – 2026/11/04 这 30 天内被下载 19,658 次，日均约 655 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @api\.video/react-player 还在维护吗？ 最新版本 1\.1\.0 发布于 2024/06/19（2 年前）；至今共发布 10 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/04/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。