@brightcove/player-loader

中文文档

1.8.1发布于 2025/10/16Apache-2.0ESM + CJS近 30 天下载 25.7万

Brightcove玩家的同步脚本加载器.

文档目录19 节

许可证
我为什么要这图书馆?
Blightcove 玩家支持
浏览器支持
安装
包含
ES6模块(例如:滚出、Webpack)
普通JS( 如浏览器)
AMD(例如要求JS)
<script> 标记
使用量
实例
已存在的玩家
避免下载
使用承诺或召回
正在清理
参数
常数
基础 URL

亮湾玩家加载器

Brightcove玩家的同步脚本加载器.

目录 生成方式 DocTOC 文档

许可证
我为什么要这图书馆?
- Blightcove 玩家支持
- 浏览器支持
安装
包含
使用量

许可证

Apache-0. 版权 (c) Blightcove, Inc.

虽然这个库,即 Blightcove Player Loader, 拥有开源许可证并可以自由使用亮湾玩家 (c) Brightcove股份有限公司.

同样,所有文件都在 vendor/ 不属于Apache -2.0许可证。相反,它们受专有的Brightcove软件许可证管辖,是版权(c)Brightcove股份有限公司.

我为什么要这图书馆?

每个闪光湾玩家都是为我们客户建造的,并通过我们的CDN服务. 这对大多数传统网站都大有裨益,在模板中加入嵌入码或CMS是直截了当的,特别是对非开发者而言!

然而,随着网络向ES模块移动,以及我们更技术的客户采用现代的构建工具,许多用户并不想要复制/粘贴嵌入码. 他们想要一个模块,他们可以捆绑入他们的网络应用,而不需要写出大量集成代码来下载他们的玩家并嵌入.

这个工具旨在通过提供我们自己的库来解决这个问题,该库可以下载任何已出版的布莱特科玩家并嵌入到DOM中.

Blightcove 玩家支持

目前,此库支持 Blightcove Players v6.0.0并更高.

这个可能为一些配置中的 v5.x 玩家工作, 但这不是一个支持的用例 .

浏览器支持

这个库支持常见的常绿浏览器-克罗梅,Firefox,Edge,Safari-和IE11. 早期的IE版本为: 没有已支持.

安装

npm install --save @brightcove/player-loader

包含

要在您的网站或网络应用程序中包含 Blightcove Player loader, 请使用以下任何方法 .

ES6模块(例如:滚出、Webpack)

这是最现代的用例.

import brightcovePlayerLoader from '@brightcove/player-loader';

brightcovePlayerLoader();

普通JS( 如浏览器)

当使用普通JS或浏览器时,安装 @brightcove/player-loader 通过 npm 和 require 与您一样的库 :

var brightcovePlayerLoader = require('@brightcove/player-loader');

brightcovePlayerLoader();

AMD(例如要求JS)

注: 使用其中之一 dist/brightcove-player-loader.js 或者说 dist/brightcove-player-loader.min.js。无论哪种情况,全球变量 brightcovePlayerLoader 将被创建.

使用 RequestJS( 或另一个 AMD 库) 时, 以您喜欢的方式获取脚本 require 通常情况下,图书馆:

require(['@brightcove/player-loader'], function(brightcovePlayerLoader) {
  brightcovePlayerLoader();
});

`<script>` 标记

注: 使用其中之一 dist/brightcove-player-loader.js 或者说 dist/brightcove-player-loader.min.js。无论哪种情况,全球变量 brightcovePlayerLoader 将被创建.

这是最简单的案例。以任何你喜欢的方式获取剧本,并包含:

<script src="//path/to/@brightcove/brightcove-player-loader.min.js"></script>
<script>
  brightcovePlayerLoader();
</script>

使用量

注意: 如果您想用 React 来使用, 我们有一个正式的反应组件叫做 @ brightcove/ react-player-loader (英语)

"明亮之地"玩家加载器暴露出单一功能. 此函数使用一个参数对象来描述它应该加载并返回的玩家 Promise 当玩家被装入并创建时解析,如果失败,则解析.

实例

这是一个最小的例子,只使用所需的参数,它将加载视频云账户的默认播放器:

brightcovePlayerLoader({
  refNode: someElement,
  accountId: '123456789'
});

这是一个比较完整的示例,使用一些可选参数并处理返回的 Promise数字 :

brightcovePlayerLoader({
  refNode: someElement,
  refNodeInsert: 'replace',
  accountId: '123456789',
  playerId: 'AbCDeFgHi',
  embedId: 'default',
  videoId: '987654321'
})
  .then(function(success) {
    // The player has been created!
  })
  .catch(function(error) {
    // Player creation failed!
  });

已存在的玩家

这个库会试图检测页面上原有的玩家. 换句话说,如果这个库在更早的DOM中包含一个布莱特科玩家脚本之后运行,它会探测到它并阻止同一玩家的额外下载. 例如:

<div id="player-container"></div>
<script src="https://players.brightcove.net/123456789/default_default/index.min.js"></script>
<script src="path/to/brightcove-player-loader.js"></script>
<script>

  // This will create a player in #player-container, but will not download
  // the player script a second time!
  brightcovePlayerLoader({
    refNode: '#player-container',
    accountId: '123456789'
  });
</script>

然而,这种行为是有局限性的. 同一页上单独账户的玩家无法保证被正确检测出. 这被视为不支持的用例 .

避免下载

使用时相关的网络包插件,您可以利用玩家加载器的嵌入创建能力,同时避免额外的同步请求,将您的"亮子"玩家捆绑入您的网页包.

简单地同时配置库和您的播放器应该捆绑,不再同步下载 .

使用承诺或召回

默认情况下, 此库将寻找全局 Promise然而,您可以明确提供 Promise b. 通过执行《公约》 Promise 参数 :

brightcovePlayerLoader({
  refNode: someElement,
  accountId: '123456789',
  playerId: 'AbCDeFgHi',
  Promise: MyCustomPromise
})
  .then(function(success) {
    // The player has been created!
  })
  .catch(function(error) {
    // Player creation failed!
  });

承诺不需要这个图书馆工作,而是被推荐. 唯一不支持的主要浏览器 Promise 本土为IE11. 我们建议多填充 window.Promise 构造器,如果它不存在.

在没有的情况下 Promise global 存在, 但没有提供, Brightcove 玩家加载器将返回 undefined。有可用的回调,可以使用,而不是 Promise - 通过它们会阻止 Promise 从被返回时返回 :

brightcovePlayerLoader({
  refNode: someElement,
  accountId: '123456789',
  onSuccess: function(success) {
    // The player has been created!
  },
  onFailure: function(error) {
    // Player creation failed!
  }
});

注: 提供这些回调意味着选择完全放弃承诺。没有 Promise 对象将返回 !

成绩

解决 Promises 或 (简体中文) onSuccess 召回,一个单一的参数会被通过. 此“ 成功对象” 可具有以下属性 :

财产	说明
`type`	无论是 `'in-page'` 或者说 `'iframe'`,描述所创建的嵌入类型.
`ref`	分配给该属性的价值类型将因下列因素而异: `type`用于 `'in-page'` 嵌入,这将是一个视频.js 玩家对象用于 `'iframe'` 嵌入,这将是 `<iframe>` DOM元素.

失败

被拒绝 Promises 或 (简体中文) onFailure 召回,一个单一的参数会被通过. 这将是本地人 Error 对象为 a message 描述出了什么问题.

正在清理

Blightcove Player将创建全局变量并添加到DOM中的元素. 这个图书馆揭露了一个 reset() 函数,可以重设该状态。将它称为具有以下效果:

它会删除全部 script 此库创建的标签并清除其内部记录中装入的文件.
它会处理的全部页面上的 Blightcove 或 Video.js 玩家.
它会删除全部 bc 财务报告和审定财务报表 videojs 属性.

brightcovePlayerLoader({
  refNode: someElement,
  refNodeInsert: 'replace',
  accountId: '123456789',
  playerId: 'AbCDeFgHi',
  embedId: 'default',
  videoId: '987654321'
})
  .then(function(success) {

    /*
      At this point:
      - at least one video player will be in the DOM.
      - at least one script created by this library will be in the DOM.
      - window.bc will exist.
      - window.videojs will exist.
     */

     brightcovePlayerLoader.reset();

    /*
      At this point:
      - no video players will be in the DOM.
      - no scripts created by this library will be in the DOM.
      - window.bc will not exist.
      - window.videojs will not exist.
     */
  });

这个 reset() 函数在长寿网页中可以有用,例如单页应用程序和相类似. 由执行者来决定他们是否仅需要处置其玩家,或完全重设布莱特科夫提供的功能.

参数

下面是所有可以被传递到布莱克科夫玩家加载器功能的参数. 所需参数以星号(*)标出.

参数必须被传递为对象.

`accountId`* 联合国

需求
类型 : string | number

视频云账户ID.

`adConfigId`

类型 : string

这个视频云SSAI 附加配置 ID 用于生成嵌入体.

`applicationId`

类型 : string

这个应用程序标识用于生成嵌入体.

`catalogSearch`

类型 : string | Object

注: 只支持Brightcove Player版本的6.18.0和更新版本.

视频云目录搜索要表演. 这可以是简单的字符串搜索,也可以是匹配的对象目录 getSearch 方法。。。 .

如果给出了一个非字符串值,那么这个参数将不会被忽略.

例如:

brightcovePlayerLoader({
  // ...
  catalogSearch: 'some search term'
});

...或者说:

brightcovePlayerLoader({
  // ...
  catalogSearch: {
    q: 'some search term',
    limit: 10
  }
});

`catalogSequence`

类型 : Array | Object

注: 只支持Brightcove Player版本的6.18.0和更新版本.

要表演的视频云表序列见目录 getLazySequence 方法文档为了更多.

如果给出了一个非字符串值,那么这个参数将不会被忽略.

例如:

brightcovePlayerLoader({
  // ...
  catalogSequence: [{
    type: 'search',
    id: {
      q: 'some search term',
      limit: 10
    }
  }, {
    type: 'video',
    id: '1234567890'
  }, {
    type: 'playlist',
    id: '0987654321'
  }]
});

`deliveryConfigId`

类型 : string

动态传输规则配置 ID 要应用到生成的嵌入器 .

`embedId`

类型 : string
默认 : 'default'

亮湾玩家嵌入式标识为玩家。对大多数用户来说,默认值是正确的.

`embedOptions`

类型 : Object

曾经为嵌入式生成提供了某些选择. 其中包括:

`embedOptions.pip`

类型 : boolean
默认 : false

若为 true,将嵌入式包起来 <div class="vjs-pip-container"> 键。当您需要支持时应当使用此工具 blightcove 图片插件。。。 .

`embedOptions.playlist`

类型 : boolean | Object
默认 : false

对于页面内嵌入,如果 true,将添加一个 <div class="vjs-playlist"> 元素在嵌入后。当您需要支持时应当使用此工具 blightcove 播放列表 UI 插件。。。 .

对于页面内嵌入器,我们遗留的播放列表UI插件也使用了一个 <ul> 元素而不是一个 <div>。可以通过 legacy: true 这里使用 <ul>。。。 .

对于 Iframe 嵌入式,此参数将被忽略 .

`embedOptions.responsive`

类型 : boolean | Object
默认 : false

注: 这种方法应适用于页面内嵌入,但建议您使用Video.js fluid 和(或) aspectRatio 选项:
options: {
  aspectRatio: '16:9'
}

使用自定义嵌入码来生成一个响应大小的播放器 “内在比”包装方法。。。 .

何时 true,将生成一个反应性嵌入码,其外观比为16:9,将填充容器.

可提供一个对象,以下列子属性自定义它:

aspectRatio:一个字符串可以用来自定义相比到16:9以外的值(例如, '4:3' 或者说 '16:10') (中文(简体) ). 任何外观比例都可以使用——不仅仅是Video.js支持的.
iframeHorizontalPlaylist: 对于配置有水平播放列表的 Iframe 播放器,设置为 true 以适应额外的高度。此选项对于页面内玩家来说被忽略了,因为他们的风格独立于其关联的播放列表.
maxWidth:用于限制玩家最大宽度的字符串. 这应该使用 CSS 单元,例如像素(例如, '960px') (中文(简体) ).

`embedOptions.tagName`

类型 : string
默认 : 'video-js'

用于自定义嵌入元素的标记名。此参数的值必须是:

'video-js' 或者说 brightcovePlayerLoader.EMBED_TAG_NAME_VIDEOJS: 此值是默认值, 仅由 Blightcove Player v6.1.10. 0 以上支持 .
'video' 或者说 brightcovePlayerLoader.EMBED_TAG_NAME_VIDEO: 当对 Blightcove Player 版本的支持早于 v6.11.0.时,此值可能会被使用.

此选项仅在 embedType 实值 'in-page'; 当 embedType 实值 'iframe'。。。 .

`embedOptions.unminified`

类型 : boolean
默认 : false

若为 true,将使用玩家未忽略的版本。这对调试目的可能有用,但以更大的玩家下载为代价而来. 不推荐生产!

`embedType`

类型 : string
默认 : 'in-page'

这个嵌入代码类型生产。此参数的值必须是以下之一:

'in-page' 或者说 brightcovePlayerLoader.EMBED_TYPE_IN_PAGE:也称高级嵌入码,这直接将玩家注入顶级网页.
'iframe' 或者说 brightcovePlayerLoader.EMBED_TYPE_IFRAME: 也称为基本嵌入码,这给玩家注入了一个 <iframe> 键.

`onEmbedCreated`

类型 : Function(Element)

用于自定义嵌入元素的回调( 无论是 video-js 元素或一个 iframe 要素) 在此之前 它被插入到DOM中,或者由于 embedOptions 在玩家下载和初始化之前.

嵌入元素可能会被变异,或者,如果此调回元素返回一个元素,该元素将被用作嵌入元素.

可能的用例是添加/删除属性或添加儿童元素,如来源或音轨等.

`onFailure`

类型 : Function(Error)

允许处理故障的回调函数 Promise 不可用或不可取。传递此函数将防止 (单位:千美元) Promise 从被送回.

它得到一个单身 Error 对象作为参数。此函数的返回值被忽略 .

`onSuccess`

类型 : Function(Object)

回调函数,允许在 Promise 不可用或不可取。传递此函数将防止 (单位:千美元) Promise 从被送回.

它得到一个单一的"成功对象"作为论据. 此函数的返回值被忽略 .

`options`

类型 : Object

A 类视频.js 选项对象在玩家创建过程中通过。这些选项将优先于Brightcove Player配置中指定的任何设置.

注: 无法使用 Iframe 嵌入式!

`playerUrl`

类型 : string

如果主机为您试图加载自己的玩家,而您不想从亮相洞中加载玩家,请通过url给玩家在这里.

注意: Iframes应该解决到一个HTML页面,而其他嵌入符应该指向一个JavaScript文件.

`playerId`

类型 : string
默认 : 'default'

亮河玩家身份证明.

`playlistId`

类型 : string | number

视频云视频标识或参考编号。。。 .

`playlistVideoId`

类型 : string | number

视频 Cloud 视频 ID ,该视频 ID 将出现在您指定的播放列表中 playlistId。如果 playlistId 缺少.

`poster`

类型 : string

Playback API 返回的海报图像的 URL .

此选项仅在 embedType 实值 'in-page'; 当 embedType 实值 'iframe'。。。 .

`Promise`

类型 : Function(Function)
默认 : window.Promise

用于明确规定 Promise 执行。如果提供,将用它代替任何全局 Promise。。。 .

`refNode`* 联合国

需求
类型 : Element | string

玩家将嵌入的 DOM 元素。如果不作为 DOM 元素提供,它可以作为字符串提供,然后传递给 document.querySelector。。。 .

`refNodeInsert`

类型 : string
默认 : 'append'

相对于参考 DOM 元素插入玩家的方式(由 refNode) (中文(简体) ). 此参数的值必须是以下之一:

'append' 或者说 brightcovePlayerLoader.REF_NODE_INSERT_APPEND:玩家将是参考节点的最后一个孩子.
'prepend' 或者说 brightcovePlayerLoader.REF_NODE_INSERT_PREPEND:玩家将成为参考节点的第一个孩子.
'before' 或者说 brightcovePlayerLoader.REF_NODE_INSERT_BEFORE:玩家会是参考节点的前同名兄弟.
'after' 或者说 brightcovePlayerLoader.REF_NODE_INSERT_AFTER: 玩家将在参考节点后成为下一个兄弟姐妹.
'replace' 或者说 brightcovePlayerLoader.REF_NODE_INSERT_REPLACE: 引用节点将被删除并被玩家所取代.

`videoId`

类型 : string | number

视频云视频ID或参考ID.

常数

图书馆暴露了几个与主要图书馆功能相关的常数, brightcovePlayerLoader。大多数可用于参数值,并在相关标题下被提及,但在此收集以供参考:

常数	相关参数
`EMBED_TAG_NAME_VIDEO`	`embedOptions.tagName`
`EMBED_TAG_NAME_VIDEOJS`	`embedOptions.tagName`
`EMBED_TYPE_IN_PAGE`	`embedType`
`EMBED_TYPE_IFRAME`	`embedType`
`REF_NODE_INSERT_APPEND`	`refNodeInsert`
`REF_NODE_INSERT_PREPEND`	`refNodeInsert`
`REF_NODE_INSERT_BEFORE`	`refNodeInsert`
`REF_NODE_INSERT_AFTER`	`refNodeInsert`
`REF_NODE_INSERT_REPLACE`	`refNodeInsert`
`VERSION`	无

基础 URL

默认情况下,所使用的基础URL是Brightcove CDN. 然而,对于一些非生产案例和测试,您可能想要覆盖基础URL. 这可以通过呼吁 setBaseUrl 函数 :

brightcovePlayerLoader.setBaseUrl('https://localhost:9999/');

版本与发布记录

@brightcove/player-loader 共发布 16 个版本，首次发布于 2018/07/24；过去 12 个月发布了 0 个版本。

版本	发布日期	距今
`1.8.1`latest	2025/10/16	1.1 年前
`1.8.0`	2020/10/10	6 年前
`1.7.1`	2019/06/22	7 年前
`1.7.0`	2019/06/05	7 年前
`1.6.0`	2018/10/25	8 年前
`1.5.0`	2018/10/06	8 年前

关于 @brightcove/player-loader 的常见问题

@brightcove/player-loader 是什么？

Brightcove玩家的同步脚本加载器.

如何安装 @brightcove/player-loader？

在项目目录运行 npm install @brightcove/player-loader，或使用 pnpm add / yarn add / bun add。

@brightcove/player-loader 支持 TypeScript 吗？

该包的 package.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/brightcove__player-loader 是否存在。

@brightcove/player-loader 支持 ESM 还是 CommonJS？

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

@brightcove/player-loader 可以商用吗？

@brightcove/player-loader 使用 Apache-2.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

@brightcove/player-loader 的下载量有多少？

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

@brightcove/player-loader 还在维护吗？

最新版本 1.8.1 发布于 2025/10/16（1.1 年前）；至今共发布 16 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/07/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install @brightcove/player-loader

pnpmpnpm add @brightcove/player-loader
yarnyarn add @brightcove/player-loader
bunbun add @brightcove/player-loader

在你的项目目录中运行此命令。

近 30 天下载

256,831

约 25.7万次日均 8,561 次

统计周期 2026/10/09 – 2026/11/07
数据来自 npm 官方下载统计，今天更新

最新版本1.8.1发布于 1.1 年前

开源许可Apache-2.0宽松许可

包体积435 kB25 个文件 · 解压后

运行依赖1 个

模块格式ESM + CJS

TypeScript未声明类型可查找 @types/brightcove__player-loader

发布版本16 个近 12 个月 0 个

首次发布2018/07/248 年前

元数据更新2026/11/06

每一个软件包背后，
都有分享与创造的人。

@brightcove/player-loader

亮湾玩家加载器

许可证

我为什么要这图书馆?

Blightcove 玩家支持

浏览器支持

安装

包含

ES6模块(例如:滚出、Webpack)

普通JS( 如浏览器)

AMD(例如要求JS)

<script> 标记

使用量

实例

已存在的玩家

避免下载

使用承诺或召回

成绩

失败

正在清理

参数

accountId* 联合国

adConfigId

applicationId

catalogSearch

catalogSequence

deliveryConfigId

embedId

embedOptions

embedOptions.pip

embedOptions.playlist

embedOptions.responsive

embedOptions.tagName

embedOptions.unminified

embedType

onEmbedCreated

onFailure

onSuccess

options

playerUrl

playerId

playlistId

playlistVideoId

poster

Promise

refNode* 联合国

refNodeInsert

videoId

常数

基础 URL

版本与发布记录

关于 @brightcove/player-loader 的常见问题

@brightcove/player-loader 是什么？

如何安装 @brightcove/player-loader？

@brightcove/player-loader 支持 TypeScript 吗？

@brightcove/player-loader 支持 ESM 还是 CommonJS？

@brightcove/player-loader 可以商用吗？

@brightcove/player-loader 的下载量有多少？

@brightcove/player-loader 还在维护吗？

`<script>` 标记

`accountId`* 联合国

`adConfigId`

`applicationId`

`catalogSearch`

`catalogSequence`

`deliveryConfigId`

`embedId`

`embedOptions`

`embedOptions.pip`

`embedOptions.playlist`

`embedOptions.responsive`

`embedOptions.tagName`

`embedOptions.unminified`

`embedType`

`onEmbedCreated`

`onFailure`

`onSuccess`

`options`

`playerUrl`

`playerId`

`playlistId`

`playlistVideoId`

`poster`

`Promise`

`refNode`* 联合国

`refNodeInsert`

`videoId`