# @api\.video/player-sdk 中文文档

规范地址：https://npmcn.com/package/%40api.video/player-sdk/

版本：1\.2\.33
npm 元数据更新时间：2025-05-22T12:54:38.885Z
中文译文更新时间：2026-11-06T09:52:59.449Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40api.video/player-sdk
原文对照：https://npmcn.com/package/%40api.video/player-sdk/?lang=original
项目主页：https://github.com/apivideo/player-sdk#readme
源码仓库：https://github.com/apivideo/player-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：135 kB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2020-09-09T20:37:38.025Z
- 最新版本发布：2024-08-21T16:34:19.860Z
- 近 30 天下载量：22805（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：36（近 12 个月 0 个）

## 中文简介

api.video 播放器 SDK

## 安装

```sh
npm install @api.video/player-sdk
```

也可以使用：`pnpm add @api.video/player-sdk`、`yarn add @api.video/player-sdk`、`bun add @api.video/player-sdk`

## 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-player-sdk?style=social)](https://github.com/apivideo/api.video-player-sdk)   [![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)

# api.video 播放器 SDK

[视频](https://api.video/) 是产品制造者的视频基础设施。 闪电快视频 API 用于在您的应用程序中集成,缩放,并管理点播后低空直播功能.

## 目录

-   [目录](https://npmcn.com/package/%40api.video/player-sdk/#readme-table-of-contents)
-   [项目说明](https://npmcn.com/package/%40api.video/player-sdk/#readme-project-description)
-   [开始](https://npmcn.com/package/%40api.video/player-sdk/#readme-getting-started)
    -   [安装](https://npmcn.com/package/%40api.video/player-sdk/#readme-installation)
        -   [方法 1: 要求js](https://npmcn.com/package/%40api.video/player-sdk/#readme-method-1-requirejs)
        -   [方法 第 2 号 :](https://npmcn.com/package/%40api.video/player-sdk/#readme-method-2-typescript)
        -   [方法 2 : 简洁地包含在 Javascript 工程中](https://npmcn.com/package/%40api.video/player-sdk/#readme-method-2-simple-include-in-a-javascript-project)
-   [文档](https://npmcn.com/package/%40api.video/player-sdk/#readme-documentation)
    -   [证据](https://npmcn.com/package/%40api.video/player-sdk/#readme-instantiation)
        -   [广告](https://npmcn.com/package/%40api.video/player-sdk/#readme-ads)
    -   [方法](https://npmcn.com/package/%40api.video/player-sdk/#readme-methods)
    -   [完整实例](https://npmcn.com/package/%40api.video/player-sdk/#readme-full-example)
    -   [使用 SDK 控制已有嵌入式播放器](https://npmcn.com/package/%40api.video/player-sdk/#readme-control-an-existing-embedded-player-using-the-sdk)

## 项目说明

SDK 用于控制并与 api.video HTML5 播放器交互

## 开始

### 安装

#### 方法 1: 要求js

如果您使用需要js, 您可以添加 SDK 作为您的项目依赖性

```sh
$ npm install --save @api.video/player-sdk
```

然后可以在脚本中使用 SDK :

```javascript
var { PlayerSdk } = require("@api.video/player-sdk");

var sdk = new PlayerSdk("#target", {
  id: "<VIDEO_ID>",
  // ... other optional options
});
```

#### 方法 第 2 号 :

如果您使用 Typescript , 您可以将 SDK 添加为您的工程的依赖性

```sh
$ npm install --save @api.video/player-sdk
```

然后可以在脚本中使用 SDK :

```typescript
import { PlayerSdk } from "@api.video/player-sdk";

const sdk = new PlayerSdk("#target", {
  id: "<VIDEO_ID>",
  // ... other optional options
});
```

#### 方法 2 : 简洁地包含在 Javascript 工程中

将 SDK 包含在您的 HTML 文件中 :

```html
<head>
  ...
  <script src="https://unpkg.com/@api.video/player-sdk" defer></script>
</head>
```

然后,一旦 `window.onload` 事件已触发,使用 `new PlayerSdk()`数字 :

```html
<script type="text/javascript">
  window.player = new PlayerSdk("#target", {
    id: "<VIDEO_ID>",
    // ... other optional options
  });
</script>
```

## 文档

### 证据

PlayerSdk 构造器需要两个参数:

-   `targetSelector: string | Element` a CSS 选择器,针对您想要创建播放器的 DOM 元素(如“#目标”),或 DOM 元素本身
-   `options: SdkOptions` 一个包含玩家选项的对象。 现有备选方案如下:

| 选项名称 | 强制性 | 类型 | 说明 |
| --: | --- | --- | --- |
| 编号 | **对** | 字符串 | 视频的代号(视频或直播) (d) 国家 |
| 符号 | 是,用于录像 | 字符串 | 页:1 [私人视频](https://api.video/blog/tutorials/tutorial-private-videos/) url 令牌 |
| 非公开会议 | 没有 | 字符串 | 页:1 [私人视频](https://api.video/blog/tutorials/tutorial-private-videos/) 必要时为会议编号 |
| 现场直播 | 无( 默认: 假) | 布尔 | 表示视频是活的 |
| 自动播放 | 无( 默认: 假) | 布尔 | 装入后立即开始播放视频 |
| 哑巴 | 无( 默认: 假) | 布尔 | 视频被监听 |
| 元数据 | 无( 默认: 为空) | 对象 | 包含对象 [元数据](https://api.video/blog/tutorials/dynamic-metadata/) (见 **完整实例** (见下文) |
| 隐藏控制 | 无( 默认: 假) | 布尔 | 控件被隐藏( 如果视频开始变音, 则解密按钮除外) |
| 无铬 | 无( 默认: 假) | 布尔 | 无铬模式: 所有控件都被隐藏 |
| 隐藏标题 | 无( 默认: 假) | 布尔 | 隐藏视频标题 |
| 隐藏鼠标 | 无( 默认: 假) | 布尔 | 未显示海报图像 |
| 显示字幕 | 无( 默认: 假) | 布尔 | 视频字幕默认显示 |
| 循环 | 无( 默认: 假) | 布尔 | 视频完成后, 自动重新开始 |
| 播放范围 | 无( 默认 :1) | 编号 | 视频的回放速率:1为正版,2为x2等. |
| 顺序 | 没有 | `{start: number, end: number}` | 定义要播放的视频的顺序。 录像从头开始 `start` 时间码并结束于 `end` 时间码。 时间码是数秒. |
| 广告 | 没有 | `{adTagUrl: string}` | 见下文 [广告](https://npmcn.com/package/%40api.video/player-sdk/#readme-ads) |
| 自定义域 | 没有 | 字符串 | 如果您为您的账户启用了自定义域, 那么完整的“ embed” 域名( 如 嵌入.mydomain.com) |
| 热键 | 无( 默认: 真) | 布尔 | 如果错误, 则解除玩家的热键, 使其无法捕捉焦点, 这在某些情况下可能是有益的 |

Sdk实例可用于控制视频回放,并收听玩家事件.

#### 广告

广告可以在玩家中显示. 要做到这一点,你需要通过 `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)。 。 。 .

### 方法

Sdk 实例有以下方法:

**`loadConfig(options: SdkOptions)`**

在玩家的同一实例中装入新视频 。 可用的选项与传递给SDK构建器的选项相同(见可用).

> 示例

```javascript
player.loadConfig({
  id: "<VIDEO_ID>",
  hideTitle: true,
  hideControls: true,
});
```

**`play()`**

开始播放视频.

**`pause()`**

暂停视频播放.

**`mute()`**

关闭视频.

**`unmute()`**

释出相相相.

**`hideControls(controls?: ControlName[])`**

隐藏玩家控制 .

`controls` 参数类型定义 :

```typescript
type ControlName =
  | "play"
  | "seekBackward"
  | "seekForward"
  | "playbackRate"
  | "volume"
  | "fullscreen"
  | "subtitles"
  | "chapters"
  | "pictureInPicture"
  | "progressBar"
  | "chromecast"
  | "download"
  | "more";
```

> 如果没有为"控件"参数提供值,所有控件都会被隐藏.

**说明**:唯一仍能被看到的控制是,如果开始的视频变哑,则解密按钮. 要隐藏所有控件, 包括此控件, 请使用设置 Chromeless () 方法

示例

```javascript
player.hideControls();
```

> 如果提供控制名称清单,相关控制将被隐藏.

示例

```javascript
player.showControls(); // display all controls ...
player.hideControls(["download", "subtitles"]); // ... except "download" and "subtitles"
```

**`showControls(controls?: ControlName[])`**

显示玩家控件 .

`controls` 参数类型定义 :

```typescript
type ControlName =
  | "play"
  | "seekBackward"
  | "seekForward"
  | "playbackRate"
  | "volume"
  | "fullscreen"
  | "subtitles"
  | "chapters"
  | "pictureInPicture"
  | "progressBar"
  | "chromecast"
  | "download"
  | "more";
```

> 如果没有为"控件"参数提供值,则会显示所有控件.

示例

```javascript
player.showControls();
```

> 如果提供了控制名列表,则将显示相关的控制名.

示例

```javascript
player.hideControls(); // hide all controls ...
player.showControls(["download", "subtitles"]); // ... except "download" and "subtitles" ...
// ...
player.showControls(["progressBar"]); // ... and the progress bar
```

**`setChromeless(chromeless: boolean)`**

定义玩家是否应该处于无铬模式(所有控件都隐藏).

**`hideSubtitles()`**

隐藏玩家字幕.

**`showSubtitles()`**

显示玩家字幕.

**`hideTitles()`**

将视频标题藏于视频上方.

**`showTitles()`**

在视频上方显示视频标题.

**`setLoop(loop: boolean)`**

定义视频是否应该循环播放 .

**`setAutoplay(autoplay: boolean)`**

定义视频是否在装入后立即开始播放

**`seek(time: number)`**

添加/ 减除给定秒数到/ 从播放时间.

**`setPlaybackRate(rate: number)`**

设定当前播放率 .

示例

```javascript
player.setPlaybackRate(2); // Play at 2x rate
```

**`setCurrentTime(time: number)`**

设定当前播放时间( 秒) .

> 示例

```javascript
player.setCurrentTime(24); // Go the 24th second
```

**`setVolume(volume: number)`**

将音频音量改为给定值 。 从0到1(0=哑音,1=100%).

> 示例

```javascript
player.setVolume(0.75); // Set the volume to 75%
```

**`setVideoStyleObjectFit(value: "contain" | "cover" | "fill" | "none" | "scale-down")`**

改变 [对象适应](https://developer.mozilla.org/fr/docs/Web/CSS/object-fit) 视频标签的 CSS 值 .

示例

```javascript
player.setVideoStyleObjectFit("cover"); // Set the object-fit to cover
```

**`setVideoStyleTransform(value: string)`**

改变 [转换](https://developer.mozilla.org/fr/docs/Web/CSS/transform) 视频标签的 CSS 值 .

示例

```javascript
player.setVideoStyleTransform("rotateY(180deg)"); // Apply a 180deg rotation around the Y axis (mirroring)
```

**`setTheme(theme: PlayerTheme)`**

改变玩家的外观.

`theme` 参数类型定义 :

```typescript
type PlayerTheme = {
  text?: string;
  link?: string;
  linkHover?: string;
  trackPlayed?: string;
  trackUnplayed?: string;
  trackBackground?: string;
  backgroundTop?: string;
  backgroundBottom?: string;
  backgroundText?: string;
  linkActive?: string;
};
```

> 示例

```javascript
player.setTheme({
  link: "red",
  linkHover: "rgba(0, 255, 0, 1)",
  backgroundBottom: "#0000ff",
});
```

**`requestFullscreen()`**

请求全屏模式( 根据浏览器限制, 在某些情况下可能无法工作)

**`exitFullscreen()`**

离开全屏模式

**`requestPictureInPicture()`**

在图片模式下请求图片( 这在某些情况下可能无法工作, 取决于浏览器限制)

**`exitPictureInPicture()`**

在图片模式中保存图片

**`getPaused(callback?: (paused: boolean) => void): Promise<boolean>`**

请检查date=中的日期值 (帮助).

**`getPlaying(callback?: (playing: boolean) => void): Promise<boolean>`**

看看录像在播放什么.

**`getMuted(callback?: (muted: boolean) => void): Promise<boolean>`**

检查录像是不是哑了.

**`getDuration(callback?: (duration: number) => void): Promise<number>`**

取取相相续相.

**`getCurrentTime(callback?: (currentTime: number) => void): Promise<number>`**

获取视频当前播放时间.

**`getVolume(callback?: (volume: number) => void): Promise<number>`**

取出目前卷来.

**`getLoop(callback?: (loop: boolean) => void): Promise<boolean>`**

检查视频是否为循环模式 .

**`getPlaybackRate(callback?: (rate: number) => void): Promise<number>`**

取出回放速率.

**`isLiveStream(callback?: (live: boolean) => void): Promise<boolean>`**

检查视频是否为活流 .

**`download(filename?: string): void`**

下载视频。 如果不提供文件名,则使用默认名称"video.mp4" . 如果视频无法下载, 则会丢弃例外 .

**`destroy()`**

摧毁玩家实例 .

**`addEventListener(event: string, callback: () => void)`**

定义在指定事件被玩家触发时会调用的回调函数 .

现有活动如下:

| 事件名称 | 说明 | 参数 |
| --: | --- | --- |
| 已关闭 | 开始在播放设备上播放 | \- 说吧 |
| 空投游戏断开连接 | 停止在播放设备上播放 | \- 说吧 |
| 已连接 | 开始在chromecast设备上播放 | \- 说吧 |
| 已断开 | 停止在发光器上播放 | \- 说吧 |
| 无法控制 | 控件现已禁用 | \- 说吧 |
| 启用控制 | 现在启用了控制 | \- 说吧 |
| 结束 | 回放到视频的结尾 | \- 说吧 |
| 错误 | 发生错误 | \- 说吧 |
| 第一场 | 视频第一次开始播放 | \- 说吧 |
| 全屏更改 | 玩家进入( 或返回) 全屏 | `{ isFullScreen: boolean }` |
| 鼠标输入 | 用户鼠标进入玩家区域 | \- 说吧 |
| 鼠标离开 | 用户的鼠标离开玩家区域 | \- 说吧 |
| 暂停 | 视频已被暂停 | \- 说吧 |
| 播放 | 视频开始播放(首次或被暂停后) | \- 说吧 |
| 玩家大小调整 | 玩家大小已经改变 | \- 说吧 |
| 质量变化 | 视频质量有变化 | `{ resolution: { height: number, width: number } }` |
| 汇率变动 | 回放率已经改变 | \- 说吧 |
| 准备 | 玩家准备好了 | \- 说吧 |
| 调整大小 | 视频尺寸已经改变 |  |
| 请求 | 玩家正在寻找 | \- 说吧 |
| 时间更新日期 | 播放时间已经改变 | `{ currentTime: number }` |
| 用户活动 | 用户活动 | \- 说吧 |
| 用户不活动 | 用户不活动 | \- 说吧 |
| 音量变化 | 音量变了 | `{ volume: number }` |

实例:

```javascript
// listen to the 'play' event
player.addEventListener("play", function () {
  console.log("play event received");
});

player.addEventListener("qualitychange", function (ev) {
  console.log(
    `quality has changed: ${ev.resolution.width}x${ev.resolution.height}`
  );
});
```

### 完整实例

```html
<html>
  <head>
    ...
    <script src="/index.js" defer></script>
  </head>

  <body>
    <div id="target"></div>

    <!-- buttons that call player methods to control the video playback -->
    <button onclick="javascript:player.play()" id="play-btn">play</button>
    <button onclick="javascript:player.pause()" id="pause-btn" disabled>
      pause
    </button>
    <button onclick="javascript:player.mute()">mute</button>
    <button onclick="javascript:player.unmute()">unmute</button>
  </body>

  <script type="text/javascript">
    window.onload = function () {
      // create the player in the #target element
      window.player = new PlayerSdk("#target", {
        id: "123456",
        metadata: {
          dogcat: "dog",
        },
      });

      // when the 'play' event is received, disable the 'play' button and enable the 'pause' button
      player.addEventListener("play", function () {
        document.getElementById("play-btn").disabled = true;
        document.getElementById("pause-btn").disabled = false;
      });

      // when the 'pause' event is received, disable the 'pause' button and enable the 'play' button
      player.addEventListener("pause", function () {
        document.getElementById("play-btn").disabled = false;
        document.getElementById("pause-btn").disabled = true;
      });
    };
  </script>
</html>
```

### 使用 SDK 控制已有嵌入式播放器

也可以将SDK整合到一个已经包含嵌入式玩家的页面中,以便控制并收听它的事件. 让我们考虑以下一页:

```html
<html>
  <head>
    ...
  </head>

  <body>
    ...
    <!-- my embedded player -->
    <iframe
      src="//embed.api.video/vod/vi54sj9dAakOHJXKrUycCQZp"
      width="100%"
      height="100%"
      frameborder="0"
      allowfullscreen
    ></iframe>
    ...
  </body>
</html>
```

要将 SDK 附加到这个播放器上, 您必须在您的页面中修改以下内容 :

-   导入 `sdk.js` 脚本在你的页面,
-   创建一个 `PlayerSdk` 实例.

以下为这些变化的页面的外观:

```html
<html>
  <head>
    ...
    <script src="/index.js" defer></script>
  </head>

  <body>
    ...
    <!-- my embedded player -->
    <iframe
      id="myPlayer"
      src="//embed.api.video/vod/vi54sj9dAakOHJXKrUycCQZp"
      width="100%"
      height="100%"
      frameborder="0"
      allowfullscreen
    ></iframe>
    ...
  </body>

  <script type="text/javascript">
    window.onload = function () {
      // attach the sdk to the existing player
      window.player = new PlayerSdk("#myPlayer");

      // window.player can now be used to control the player as described above
    };
  </script>
</html>
```

## 常见问题

### @api\.video/player-sdk 是什么？

api\.video 播放器 SDK

### 如何安装 @api\.video/player-sdk？

在项目目录运行 npm install @api\.video/player-sdk，或使用 pnpm add / yarn add / bun add。

### @api\.video/player-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @api\.video/player-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @api\.video/player-sdk 可以商用吗？

@api\.video/player-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @api\.video/player-sdk 的下载量有多少？

根据 npm 官方下载统计，@api\.video/player-sdk 在 2026/10/06 – 2026/11/04 这 30 天内被下载 22,805 次，日均约 760 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @api\.video/player-sdk 还在维护吗？

最新版本 1\.2\.33 发布于 2024/08/22（2 年前）；至今共发布 36 个版本，其中过去 12 个月发布了 0 个；首次发布于 2020/09/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。