Introduction

外挂字幕组件，目前支持vtt格式的解析

Start

1. Install

   $ npm install xgplayer-subtitles

2. Usage

   Step 1:

   <div id="vs"></div>

   Step 2:

   import Player from 'xgplayer';
   
   const player = new Player({
       id: 'vs',
       url: ''
   })
   
   const options = {
      player: player, // 可选, 如果初始化的时候已经有播放器实例
      subTitles: [{              //必选 字幕信息
        label: '中文',
        language : '',          //必选
        id: 'cn',               //必选
        isDefault: false,       //必选 是否是默认字幕
        url: './subtitle/cn.vtt' //必选 字幕链接地址
       }, {
         label: '英文',
         url: './subtitle/en.vtt',
         id: 'en',
         isDefault: true,
         language: 'en'
       }],
       domRender: true, // 默认为true，会创建dom自行渲染，如果配置为false则只触发更新事件, 不做dom更新
       defaultOpen: false, // 是否默认开启字幕
       mode: 'bg', //可选 字幕显示模式，支持bg(背景）和 stroke(字体边框填充)，默认stroke
       line: 'double', // 可选 字幕最大显示行数 默认单行，single, 支持single/double/three、
       updateMode: 'vod' // 字幕更新类型，vod-字幕内容会做缓存，live-字幕内容不做缓存, 渲染完即丢弃， 默认为vod 1.1.0 之后的版本支持
       renderMode: 'normal', // 渲染方式，step - 逐字渲染 normal或者''- 普通渲染 
       debugger: 'false' // 调试信息输出，默认为false
     }
   const subTitle = new window.XgSubtitle(options)
   // 如果在初始化的时候播放器还没有播放器实例，也可以使用以下挂载播放器
   
   subTitle.attachPlayer(player)
   

config

{
    // 关联的播放器实例,可以为空,初始化完成之后调用 subTitle.attachPlayer(player)在做关联
    player: any,
    // 可使用的字幕列表，
    subTitles: [{
        label?: any,          // 可选，当前字幕显示的标签文案
        language: any,        //必选, 当前字幕对应的语言,language和id必选其一
        id: any,              //必选, 当前字幕对应的id,language和id必选其一
        isDefault: boolean,   //必选 是否是默认字幕
        url: string           // url/list/stringContent 必选一个 字幕链接地址
        list: [{
            start: number, // 该条字幕开始时间，单位s
            end: number,   // 该条字幕结束时间，单位s
            text: Array<string> // 字幕内容
        }],
        stringContent: string   // string类型，该string必须是vtt格式
      },
      ...
    ],

    // 默认为true,会创建dom进行字幕渲染，如果配置为false则只触发更新事件, 不做dom渲染
    domRender: boolean,

    // 是否默认开启字幕, 默认为false
    defaultOpen: boolean,

    //可选 字幕显示模式，支持bg(背景）和 stroke(字体边框填充)，默认stroke, 只在domRender为true的时候生效
    mode: string,

     // 可选 字幕最大显示行数 默认单行，single, 支持single/double/three,
    line: string
}

安全渲染

domRender 开启时，字幕内容不会通过 innerHTML 直接插入 DOM。组件会在最终渲染层统一处理字幕文本：

• 支持基础字幕富文本标签：b、i、u、span、c、ruby、rt、v、lang、br
• 不在白名单内的标签会作为普通文本展示
• 事件属性、style、href、src 等可执行或外链属性不会写入字幕 DOM
• VTT、ASS、JSON 字幕最终都走同一套安全渲染入口

API

atttchPlayer(player)

挂载播放器实例

detachPlayer(player)

卸载播放器实例

destroy

销毁组件

switch({id:'', language:''})

切换字幕. id和language只需有一个即可，用户从初始化的字幕列表中选择字幕

subtitle.switch({id: 'cn', language:'cn'}).then(() => {
    console.log('切换成功')
}).catch(() => {
    console.log('切换失败')
})

切换信息返回说明

{
    code: 0, // 切换成功
    msg: 'SUCCESS'
},{
    code: 1, // 下载错误
    msg: 'LOAD_ERROR'
}, {
    code: 2, // 解析错误
    msg: 'PARSER_ERROR'
}, {
    code: 3,  // 格式不支持
    msg: 'FORMAT_NOT_SUPPORTED'
},
{
    code: 4, // id或者语言不存在
    msg: 'ID_OR_LANGUAGE_NOT_EXIST'
}, {
    code: 5, // 参数错误
    msg: 'PARAMETERS_ERROR'
}, {
    code: 6, // 操作中断
    msg: 'ABORT'
}, {
    code: 7, // 未知错误
    msg: 'UNKNOWN'
}

switchExt({id:'', language:''})

开启附属字幕是，字幕时间戳和switch接口开启的字幕一致，只是文本不一致

switchOff()

关闭字幕更新

setSubTitles(subTitles, isOpen)

• @param subTitles要更新的字幕列表
• @isOpen boolean 是否默认开启字幕

事件

update

字幕更新事件

subTitle.on('update', data => {
  if (data.length === 0) {
    // todo 清除当前显示的字幕
  } else {
    // todo 更新字幕文案
  }
})

off

字幕被关闭的时候触发，subtitle.switchOff()接口会触发该事件

change

字幕变化的时候触发

subTitle.on('change', data => {
 console.log('current subtitle is ', data)
})

reset

字幕重置，该事件只在字幕集成在hls中的时候触发

subTitle.on('reset', data => {
 console.log('the new subTitle list is ', data.list)
})