vPlayer

vPlayer iOS封装了AVPlayer视频播放功能（支持音频播放）。iOS 平台上支持的视频文件格式有：WMV，AVI，MKV，RMVB，RM，XVID，MP4，3GP，MPG等，音频文件格式有：MP3，WMA，RM，ACC，OGG，APE，FLAC，FLV等。本插件封装了两套播放方案：一，通过调用 openPlayer 接口，直接打开一个自带默认播放界面的播放器；二，通过 open 接口，打开一个纯播放器界面，再配合 frame 自定义完整的播放页面，通过play、pause等接口控制播放操作。

openPlayer

打开一个自带界面的视频播放器，本播放器为全屏横屏显示，支持屏幕随设备自动旋转。 openPlayer({params}, callback(ret))

params

rect：

类型：JSON 对象
描述：（可选项）插件的位置及尺寸
内部字段：

{
    x: 0,   //（可选项）数字类型；插件左上角的 x 坐标（相对于所属的 Window 或 Frame）；默认：0
    y: 0,   //（可选项）数字类型；插件左上角的 y 坐标（相对于所属的 Window 或 Frame）；默认：0
    w: 320, //（可选项）数字类型；插件的宽度；默认：所属的 Window 或 Frame 的宽度
    h: 300  //（可选项）数字类型；插件的高度；默认：w的3/4
}

styles：

类型：JSON 对象
描述：（可选项）插件的样式设置
内部字段：

{
    head:{ // JSON对象；播放器顶部导航条样式
       bg: 'rgba(161,161,161,0.5)', //（可选项）字符串类型；顶部导航条背景颜色，支持#、rgb、rgba；默认：rgba(161,161,161,0.5)
       height: 44,                  //（可选项）数字类型；顶部导航条的高；默认：44
       marginTop:0,                        // (可选项）数字类型；距离插件顶部的距离；默认：0
       hide:false,    //（可选项）布尔类型；打开播放器时顶部导航条是否隐藏；默认：false

       backBtn:{  //（可选项）JSON对象；播放器左上角返回按钮样式
       size: 44,                //（可选项）数字类型；返回按钮大小；默认：44
       backImg:'', //（可选项）字符串类型；返回按钮的背景图片，要求本地路径（widget://、fs://）；默认：返回小箭头图标
       marginLeft:5                  // (可选项)数字类型；左边距，默认：5
       },

       titleLabel:{ //（可选项）JSON对象；播放器顶部导航条标题
          title:'哈哈哈', //（可选项）字符串类型；标题：默认：无
          size:20,                     //（可选项）数字类型；标题字体大小；默认：20
          color:'#fff',                //（可选项）字符串类型；标题字体颜色；默认：#fff
          backgroundColor:'rgba(0,0,0,0)',  //（可选项）字符串类型；背景颜色；默认：rgba(0,0,0,0)
          width:100,                    //(可选项)数字类型；标题的最大宽度，若numberLines为1，文本超过该宽度，显示...，否则为文本的实际宽度。若numberLines为0或其它，文本超过该宽度，则换行，否则为文本的实际宽度；默认：100
          numberLines:1,  //（可选项）数字类型；文本的行数，与width配合使用，为0时则自动根据文本长度计算行数，需要注意的是，当文本长度较长时，如要完整显示文本，需要播放器顶部导航条的高度足够大；默认：1
          leftMargin:5                //（可选项）数字类型；距离左边返回按钮的外边距；默认：5
       },

       customButtons:[     //（可选项）数组类型；顶部导航条自定义按钮数组，最多支持三个自定义按钮，从右到左排列
          {    //（可选项）JSON对象；顶部导航条自定义按钮
              w:44,  //（可选项）数字类型；按钮宽度；默认：44
              h:44,  //（可选项）数字类型；按钮高度；默认：44
                rightMagin:5,   // (可选项）数字类型；右边距；默认：5
              img:'',         //（可选项）字符串类型；自定义按钮正常状态下设置图片，要求本地路径（widget://、fs://）；默认：无
              imgSelected:'', //（可选项）字符串类型；自定义按钮选中状态下设置图片，要求本地路径（widget://、fs://）；默认：无
          }]
       },

       foot:{     //（可选项）JSON对象；播放器底部导航条样式
          bg: 'rgba(161,161,161,0.5)',     //（可选项）字符串类型；底部导航条背景颜色，支持#、rgb、rgba；默认：rgba(161,161,161,0.5)
          height: 44,    //（可选项）数字类型；底部导航条的高；默认：44
          marginBottom:0, //（可选项）数字类型；底部导航条距离底部的距离；默认：0
          hide:false,  //（可选项）布尔类型；打开播放器时底部导航条是否隐藏；默认：false

       playBtn:{    //（可选项）JSON对象；播放/暂停按钮样式
           size : 44,    //（可选项）数字类型；播放/暂停按钮大小；默认：44
           playImg:'',  //（可选项）字符串类型；播放按钮设置图片，要求本地路径（widget://、fs://）；默认：播放按钮图标
           pauseImg:'', //（可选项）字符串类型；暂停按钮设置图片，要求本地路径（widget://、fs://）；默认：暂停按钮图标
           marginLeft:0                  // (可选项)数字类型；左边距；默认：0
       },

       currentTimeLabel:{   //（可选项）JSON对象；当前时间显示样式
           textSize:14,                  //（可选项）数字类型；时间显示文字大小；默认：14
           textColor:"#fff",             //（可选项）字符串类型；时间显示文字颜色，支持#、rgba、rgb；默认：#fff
           marginLeft:5                  // (可选项)数字类型；距离左边播放/暂停按钮左边距，默认：5
       },

       seekBar:{
           sliderColor:'#fff', //（可选项）字符串类型；底部进度条滑块颜色，支持#、rgba、rgb，注意：若设置了sliderImg，则sliderColor无效；默认：#fff；(android不支持)
           sliderImg:'', //（可选项）字符串类型；底部进度条滑块设置图片，要求本地路径（widget://、fs://）；默认：滑块小图标
           progressColor: '#696969',    //（可选项）字符串类型；进度条背景色，支持#、rgba、rgb，注意：若设置了progressImg，则progressColor无效；默认：#696969(android不支持)
           progressImg:'',     //（可选项）字符串类型；进度条设置图片，要求本地路径（widget://、fs://）；默认：由progressColor确定(android不支持)
           progressSelectedColor: '',        //（可选项）字符串类型；滑动后的进度条背景色，支持#、rgba、rgb，注意：若设置了progressSelectedImg，则progressSelectedColor无效；默认：#333333    (android不支持)       
           progressSelectedImg:'', //（可选项）字符串类型；进度条滑动后的部分设置图片，要求本地路径（widget://、fs://）；默认：由progressSelectedColor确定 (android不支持)

           marginLeft:5,       // (可选项) 数字类型；左边距，默认：5
           marginRight:5      // (可选项)数字类型；右边距，默认：5
       },

       totalTimeLabel:{  //（可选项）JSON对象；当前播放视频时长显示样式
           textSize:14,                  //（可选项）数字类型；时间显示文字大小；默认：14
           textColor:"#fff",                //（可选项）字符串类型；时间显示文字颜色，支持#、rgba、rgb；默认：#fff
           marginRight:5                    // (可选项)数字类型；右边距，默认：5
       },

       fullScreenBtn:{  //（可选项）JSON对象；全屏/非全屏按钮样式
           size:30, //（可选项）数字类型；底部全屏/非全屏按钮大小；默认：44
           img:'',       //（可选项）字符串类型；全屏按钮设置图片，要求本地路径（widget://、fs://）；默认：全屏按钮图标
           fullScreenImg:'',     //（可选项）字符串类型；非全屏按钮设置图片，要求本地路径（widget://、fs://）；默认：非全屏按钮图标
           marginRight:0   // (可选项)数字类型；右边距，默认：0
       }
     }
}

path：

类型：字符串
描述：文档的路径，支持网络和本地（fs://）路径

autoPlay：

类型：布尔
描述：（可选项）打开时是否自动播放
默认值：true（自动播放）

rate：

类型：数值
描述：（可选项）播放速率
默认值：1（正常速度）

coverImg：

类型：字符串
描述：（可选项）封面图路径，播放器打开尚未播放时的封面图，要求本地路径（widget://、fs://）

fixedOn：

类型：字符串
描述：（可选项）插件视图添加到指定 frame 的名字（ios：只指 frame，传 window 无效）
默认：插件依附于当前 window

fixed：

类型：布尔
描述：（可选项）插件是否随所属 window 或 frame 滚动
默认值：true（不随之滚动）

callback(ret)

ret：

类型：JSON 对象
内部字段：

{
    eventType : 'gestureTap'  //字符串类型；事件类型
    // 取值范围：
       //'clickFullScreen' : 点击全屏按钮事件
    //'clickCancelFull' : 点击非全屏按钮事件
    //'clickPlay' : 点击播放按钮事件
    //'clickPause' : 点击暂停按钮事件
    //'clickBack' : 点击返回按钮事件
    //'clickLoadError' : 点击加载失败按钮事件
    //'clickOne' : 点击第一个自定义按钮事件（正常状态下点击）
    //'clickOneSelected' : 点击第一个自定义按钮事件（选中状态下点击）
    //'clickTwo' : 点击第二个自定义按钮事件（正常状态下点击）
    //'clickTwoSelected' : 点击第二个自定义按钮事件（选中状态下点击）
    //'clickThree' : 点击第三个自定义按钮事件（正常状态下点击）
    //'clickThreeSelected' : 点击第三个自定义按钮事件（选中状态下点击）
    //'stateComplete' : 播放器播放完成事件
    //'stateError' : 播放器加载视频失败事件
    //'stateFullScreen' : 播放器全屏事件
    //'stateCancelFull' : 播放器取消全屏事件
}

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.openPlayer({
                        rect:{
                            y : 30
                        },
                        path : 'http://www.w3school.com.cn/example/html5/mov_bbb.mp4',
                        autoPlay: true,
                        coverImg: 'widget://image/ZFPlayer/ZFPlayer_loading_bgView.png',
                        styles : {
                            head:{
                                bg: 'rgba(161,161,161,0.5)',
                                height: 44,
                                marginTop:0,
                                hide:false,
                                backBtn:{
                                    size: 44,
                                    backImg:'widget://image/ZFPlayer/ZFPlayer_back_full.png',
                                    marginLeft:5
                                },
                                titleLabel:{
                                    title:'哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈哈',
                                    size:20,
                                    color:'#fff',
                                    width:200,
                                    numberLines:1,
                                    leftMargin:5,
                                    backgroundColor:'rgba(0,0,0,0)'
                                },
                                customButtons:[
                                      {
                                          w:44,
                                          h:44,
                                          rightMagin:5,
                                          img:'widget://image/ZFPlayer/ZFPlayer_lock-nor.png',
                                          imgSelected:'widget://image/ZFPlayer/ZFPlayer_repeat_video.png',
                                      },
                                      {
                                          w:44,
                                          h:44,
                                          rightMagin:5,
                                          img:'widget://image/ZFPlayer/ZFPlayer_lock-nor.png',
                                          imgSelected:'widget://image/ZFPlayer/ZFPlayer_repeat_video.png',
                                      },
                                      {
                                          w:44,
                                          h:44,
                                          rightMagin:5,
                                          img:'widget://image/ZFPlayer/ZFPlayer_lock-nor.png',
                                }]
                            },
                            foot:{
                                bg: 'rgba(161,161,161,0.5)',
                                height: 44,
                                marginBottom:0,
                                hide:false,
                                playBtn:{
                                       size : 44,
                                       playImg:'widget://image/ZFPlayer/ZFPlayer_play.png',
                                       pauseImg:'widget://image/ZFPlayer/ZFPlayer_pause.png',
                                       marginLeft:0
                                },
                               currentTimeLabel:{
                                       textSize:14,
                                       textColor:"#FFF",
                                       marginLeft:5
                               },
                               seekBar:{
                                       sliderImg:'widget://image/ZFPlayer/ZFPlayer_slider.png',
                                       progressColor: '#696969',
                                       progressSelectedColor: '#333333',
                                       marginLeft:5,
                                       marginRight:5
                               },
                               totalTimeLabel:{
                                       textSize:14,
                                       textColor:"#FFF",
                                       marginRight:5
                               },
                               fullScreenBtn:{
                                       size:44,
                                       img:'widget://image/ZFPlayer/ZFPlayer_shrinkscreen.png',
                                       fullScreenImg:'widget://image/ZFPlayer/ZFPlayer_fullscreen.png',
                                       marginRight:0
                               }
                            }
                        }
                           },function(ret) {
                           if (ret) {
                            api.alert({msg: JSON.stringify(ret)});
                           }
                       });

可用性

iOS系统

可提供的1.0.0及更高版本

replay

重新播放指定播放地址。配合openPlayer接口使用

replay({params})

params

path：

类型：字符串类型
描述：（可选项）视频资源地址,支持网络和本地路径（fs://，widget://）
默认：之前的播放地址

title：

类型：字符串类型
描述：（可选项）顶部标题文字
默认：之前的标题文字

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.replay({
                 path : 'widget://res/haba.mp4'
             });

可用性

iOS系统

可提供的1.0.0及更高版本

open

打开一个视频播放器

open({params})

params

rect：

类型：JSON 对象
描述：（可选项）播放器的位置及尺寸
内部字段：

{
    x: 0,   //（可选项）数字类型；插件左上角的 x 坐标（相对于所属的 Window 或 Frame）；默认值：0
    y: 0,   //（可选项）数字类型；（可选项）插件左上角的 y 坐标（相对于所属的 Window 或 Frame）；默认值：0
    w: 300,  //（可选项）数字类型；插件的宽度；默认值：所属的 Window 或 Frame 的宽度
    h: 200   //（可选项）数字类型；插件的高度；默认值：w的3/4
}

path：

类型：字符串类型
描述：视频资源地址,支持网络和本地路径（fs://）
默认：无

autoPlay：

类型：布尔类型
描述：（可选项）是否自动播放
默认：true

rate：

类型：数值
描述：（可选项）播放速率
默认值：1（正常速度）

fixedOn：

类型：字符串类型
描述：（可选项）插件视图添加到指定 frame 的名字（只指 frame，传 window 无效）
默认：插件依附于当前 window

fixed：

类型：布尔类型
描述：（可选项）插件是否随所属 window 或 frame 滚动
默认：true（不随之滚动）

示例代码

 var vPlayer = api.require('vPlayer');
 vPlayer.open({
                 rect:{
                     x: 0,
                     y: 0,
                     w: 300,
                     h: 200
                 },
                 path : 'http://www.w3school.com.cn/example/html5/mov_bbb.mp4',
                 });

可用性

iOS系统

可提供的1.0.0及更高版本关闭播放器。配合open接口使用

play

close()

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.close();

可用性

iOS系统

可提供的1.0.0及更高版本

play

播放

play()

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.play();

可用性

iOS系统

可提供的1.0.0及更高版本

pause

暂停

pause()

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.pause();

可用性

iOS系统

可提供的1.0.0及更高版本

setPath

设置音/视频的文件路径

setPath({params})

params

path：

类型：字符串
描述：音/视频的文件路径，支持网络和本地（fs://）路径

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.setPath({
                    path : 'widget://res/haba.mp4'
                });

可用性

iOS系统

可提供的1.0.0及更高版本

show

显示播放器

show()

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.show();

可用性

iOS系统

可提供的1.0.0及更高版本

hide

隐藏播放器

hide()

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.hide();

可用性

iOS系统

可提供的1.0.0及更高版本

full

全屏

full()

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.full();

可用性

iOS系统

可提供的1.0.0及更高版本

cancelFull

取消全屏

cancelFull()

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.cancelFull();

可用性

iOS系统

可提供的1.0.0及更高版本

isFull

当前是否为全屏

isFull(callback(ret))

callback(ret, err)

ret：

类型：JSON 对象
内部字段：

{
    isFull:            //布尔类型；是否全屏
}

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.isFull(function(ret) {
    if (ret) {
        api.alert({msg: JSON.stringify(ret)});
    }
 });

可用性

iOS系统

可提供的1.0.0及更高版本

forward

快进

forward({params})

params

seconds：

类型：数字
描述：(可选项)快进的秒数
默认：2秒

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.forward({
    seconds: 2
});

可用性

iOS系统

可提供的1.0.0及更高版本

rewind

快退

rewind({params})

params

seconds：

类型：数字
描述：(可选项)快进的秒数
默认：2秒

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.rewind({
    seconds: 2
});

可用性

iOS系统

可提供的1.0.0及更高版本

seekTo

跳转指定时间播放

seekTo({params})

params

seconds：

类型：数字
描述：(可选项)快进的秒数
默认：2秒

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.seekTo({
    seconds: 20
});

可用性

iOS系统

可提供的1.0.0及更高版本

setBrightness

设置屏幕亮度

setBrightness({params})

params

brightness：

类型：数字
描述：（可选项）设置的屏幕的亮度，取值范围：0-1.0，**在 iOS 平台上设置的是系统屏幕亮度。
默认值：0.5

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.setBrightness({
    brightness: 0.5
});

可用性

iOS系统

可提供的1.0.0及更高版本

getBrightness

获取当前屏幕亮度值

getBrightness(callback(ret))

callback(ret)

ret：

类型：JSON 对象
内部字段：

{
    brightness:            //数字类型；当前屏幕亮度值
}

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.getBrightness(function(ret) {
    if (ret) {
        api.alert({msg: JSON.stringify(ret)});
    }
});

可用性

iOS系统

可提供的1.0.0及更高版本

setVolume

设置音量

setVolume({params})

params

volume：

类型：数字
描述：（可选项）音量大小，取值范围：0-1.0
默认值：1.0

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.setVolume({
    volume: 100
});

可用性

iOS系统

可提供的1.0.0及更高版本

getVolume

获取当前播放音量

getVolume(callback(ret))

callback(ret)

ret：

类型：JSON 对象
内部字段：

{
    volume:            //数字类型；当前音量值
}

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.getVolume(function(ret) {
    if (ret) {
        api.alert({msg: JSON.stringify(ret)});
    }
});

可用性

iOS系统

可提供的1.0.0及更高版本

setRect

设置视频播放器位置、尺寸

setRect({params})

params

rect：

类型：JSON 对象
描述：（可选项）插件的位置及尺寸
内部字段：

{
    x: 0,         //（可选项）数字类型；插件左上角的 x 坐标（相对于所属的 Window 或 Frame）；默认：open中设置的 x 坐标
    y: 0,         //（可选项）数字类型；插件左上角的 y 坐标（相对于所属的 Window 或 Frame）；默认：open中设置的 y 坐标
    w: 320,       //（可选项）数字类型；插件的宽度；默认：open中设置的宽度
    h: 300        //（可选项）数字类型；插件的高度；默认：open中设置的高度
}

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.setRect({
    rect: {
        x: 0,
        y: 0,
        w: 320,
        h: 300
    }
});

可用性

iOS系统

可提供的1.0.0及更高版本

addEventListener

添加监听

addEventListener({params}，callback(ret))

params

name：

类型：字符串
描述：监听的事件的名字
取值范围：
- 'gesture'：手势事件监听
- 'state'：播放器状态监听

callback(ret)

ret：

类型：JSON 对象
内部字段：

{
   eventType: 'gestureTap'            //字符串类型；事件类型
   // 取值范围：
   // gesture对应的事件类型:
   //'gestureLeftUp' : 播放器靠左的二分之一内的上滑事件
   //'gestureLeftDown' : 播放器靠左的二分之一内的下滑事件
   //'gestureRightUp' : 播放器靠右的二分之一内的上滑事件
   //'gestureRightDown' : 播放器靠右的二分之一内的下滑事件
   //'gestureSwipeLeft' : 播放器上的左滑事件
   //'gestureSwipeRight' : 播放器上的右滑事件
   //'gestureTap' : 点击播放器事件（单击手势）
   //'gestureDoubleTap' : 双击播放器事件（双击手势）
   
   // state对应的事件类型:
   //'stateComplete' : 播放器播放完成事件
   //'stateError' : 播放器加载视频失败事件
   //'stateReady' : 可以播放状态，如果不是自动播放，可在此事件发生时调用play接口
}

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.addEventListener({
                            name : 'gesture'
                       },function(ret) {
                       if (ret) {
                            api.alert({msg: JSON.stringify(ret)});
                       }
                   });

可用性

iOS系统

可提供的1.0.0及更高版本

removeEventListener

移除动作监听

removeEventListener({params})

params

name：

类型：字符串
描述：监听的事件的名字
取值范围：
- 'gesture'：手势事件监听
- 'state'：播放器状态监听

示例代码

var vPlayer = api.require('vPlayer');
vPlayer.removeEventListener({
    name: 'state'
});

可用性

iOS系统

可提供的1.0.0及更高版本

是否仍需要帮助？请保持联络！

最后更新于 2025/09/15