Skip to content
On this page

IPCPlayer - API 文档 - V3.2

简要

什么是 Web Components

Web Components | MDN (mozilla.org)

ipcplayer-v3 使用 Web Components 打包 为原生 JS 可跨框架使用

一级标题释义

  • PROPS - 配置参数 组件会根据特定的配置 进行生成
  • EVENTS - 触发事件 组件内部某些行为会触发对应的事件
  • INSTANCEFUNCTION - 实例方法 宫格 / 播放器 实例上挂载的方法
    • PROPS 不同 INSTANCEFUNCTION 提供的是对 已生成组件 的操作能力
  • 注解 - 文档中某些需额外介绍的内容
  • V3.1 TO V3.2 - 3.1 版本到 3.2 版本升级指南

整体结构

grid

  • COMPONENT<组件> - 由 DOM组件对象 组成

    PROPSEVENTS 都需要在 DOM组件对象 上使用

    • DOM:使用自定义标签生成的DOM
    • 组件对象:通过 JS ( getElementByIdquerySelector 或 vue 的 ref 等方法 ) 获取的 DOM 对象
  • GRID<宫格> - 由 panes 参数 与 gridIns 组成

    可通过 initEvent 获取

    • panes 参数:由 PANE<窗格> 组成的数组
    • gridIns宫格实例 该对象上挂载了 窗格控制 相关方法
  • PANE<窗格> - 由 url streamType fileName msg data 参数 与 playerIns 组成

    可通过 initEvent 获取

配置

  • scriptSrc 引入
<script src="https://webapi.onewo.com/JSSDK/IPCPlayer/V3.2"></script>
  • 注意

    • 在框架内使用如果有以下异常

    • If this is a native custom element, make sure to exclude it from component resolution via compilerOptions.isCustomElement.

    • 是因为自定义标签和框架内标签冲突 框架无法识别 需配置插件

    • 以下以 vue 为例

    // Vite - vite.config.js
    export default defineConfig({
      plugins: [
        vue({
          template: {
            // 添加以下内容
            compilerOptions: {
              //将所有以ipc-开头的标签作为自定义元素处理
              isCustomElement: (tag) => tag.startsWith("ipc-"),
            },
          },
        }),
      ],
    });
    
    // Vue CLI - vue.config.js
    module.exports = {
      chainWebpack: (config) => {
        config.module
          .rule("vue")
          .use("vue-loader")
          .tap((options) => ({
            ...options, // 其他配置没有则无需
            // 添加以下内容
            compilerOptions: {
              //将所有以ipc-开头的标签作为自定义元素处理
              isCustomElement: (tag) => tag.startsWith("ipc-"),
            },
          }));
      },
    };
    

使用

  • COMPONENT 使用

    直接使用自定义标签生成 DOM

    <body>
      <ipc-player id="player1" />
    </body>
    

    然后获取 组件对象

    const player1 = document.getElementById("player1");
    

    ⚠️ 重要 - <组件对象操作>

    组件对象 上操作的事件 如: props设置复杂类型属性值event
    需确保 DOM 已经生成 后再进行 请在类似 onMounted 之类的生命周期中使用

  • PROPS 使用

    基础类型的属性值 (StringBooleanNumber)

    ⚠️ 注意 - <props 使用>

    ! 直接在标签上设置 props 时 请务必 将小驼峰拆分为 短横线分隔命名
    controlItem => control-item
      - HTML 中的特性名是大小写不敏感的 所以浏览器会把所有大写字符解释为小写字符
      - 所以 controlItem 的 prop 名需要使用其等价的 control-item ( 短横线分隔命名 ) 命名

    • 直接在 标签上 设置
    <ipc-player id="player1" control-item="false" buffer="1000" mode="single" />
    
    • controlItem 会被转换为 false (boolean 类型值) 而 buffer 会被转换为 1000 (number 类型值)

    复杂类型的属性值 (Object)

    ⚠️ 注意 - <props 使用>

    ! 在组件对象上设置 props 时 请保持小驼峰不变

    • 组件对象 上设置
    const player1 = document.getElementById("player1"); // 获取组件对象
    player1.gridItem = {
      allStop: true,
      allCalibration: true,
      layoutChange: true,
      proportionChange: true,
      chosen: true,
      fullScreen: true,
    };
    
    • 基础类型的属性值 通过 组件对象 设置 需要在 DOM 渲染完毕 之后
  • EVENTS 使用

    获取 组件对象 并使用addEventListener监听事件

    // 以 初始化事件-initEvent 为例
    player1.addEventListener("initEvent", (event) => {
      const panes = event.detail[0].panes;
    });
    
    • Web Components 传值
      • addEventListener 的回调函数会返回一个event 对象 其中detail属性为事件的返回值
      • event.detail为多个返回参数组成的数组

PROPS

使用方法见 PROPS 使用

⚠️ 注意 - <props 使用> - 再次提醒


1. 直接在标签上设置 props 时 请务必 将小驼峰拆分为 短横线分隔命名
controlItem => control-item
  - HTML 中的特性名是大小写不敏感的 所以浏览器会把所有大写字符解释为小写字符
  - 所以 controlItem 的 prop 名需要使用其等价的 control-item ( 短横线分隔命名 ) 命名


2. 在组件对象上设置 props 时 请保持小驼峰不变

< mode > - 通用参数

  • 释义播放器模式 目前有六种 👇

    参数释义
    "single"单播放器
    "single-PTZ"单播放器+云台
    "grid"宫格
    "grid-PTZ"宫格+云台
    "grid-polling"宫格+轮巡
    "single-playback"单播放器回放
    "grid-PTZ-playback"宫格回放
  • 类型string

  • 默认值grid-PTZ

  • 注意singlesingle-PTZ 模式请手动设置宽高

< controlItem > - 通用参数

  • 释义控制播放器按钮显隐
  • 类型Boolean Object
  • 默认值
    • {
        fullscreen: true, // 播放器全屏
        screenshot: true, // 截图
        play: true, // 播放
        record: true, // 录制
        stop: true, // 停止
        VDetail: true, // 详情
        reset: true, // 重置
        speed: true, // 网速显示
      }
      
    • 为 false 则全不显示

< loadingMsg > - 通用参数

  • 释义loading 文字(转圈下方)
  • 类型String
  • 默认值视频加载中

< buffer > - 通用参数

  • 释义缓冲时长
  • 类型Number
  • 默认值500

< streamRetryTimes > - 通用参数

  • 释义播放过程中连接断开后重新连接次数

  • 类型Number

  • 默认值3

  • e.g.:

    • -1:无限重连
    • n:重连 n 次

< dataRateType > - 通用参数

  • 释义控制码流选择下拉显示
  • 类型Boolean Array
  • 默认值false
  • false 不显示
  • true 时显示默认码流选项 等同于 ["子码流", "主码流"]
  • Array 时 数组元素为将替换下拉选项内容
    • 数组 0 号索引元素为默认值

< gridItem > - 宫格参数

  • 释义控制宫格按钮显隐

  • 类型Object

  • 默认值

    • {
        allStop: true, // 全部停止
        allCalibration: true, // 全部校准
        layoutChange: true, // 布局变化
        proportionChange: true, // 比例变化
        chosen: true, // 已选窗格信息
        fullScreen: true, // 宫格全屏
      };
      

< gridLayout> - 宫格参数

< gridProportion> - 宫格参数

  • 释义初始播放器高宽比
  • 类型Number
  • 默认值9/16

< pollingNum > - 轮巡参数

  • 释义需进行轮巡的数组长度

  • 类型Number

  • 默认值10

    播放器会根据 pollingNum当前宫格数 自动计算并返回每组轮巡对应的 [1]Index 数组

    • e.g.:有 10 个设备需进行轮巡 -> 宫格数:4 pollingNum:10
    • 初始化时 indexChange 事件会返回 [0, 1, 2, 3]
    • 每次 点击下一组按钮 / 计时结束 indexChange 事件会依次返回 [1]Index 数组 ( 以初始状态为例 )
      • [4, 5, 6, 7]
      • [8, 9, 0, 1]
      • [2, 3, 4, 5]
      • [6, 7, 8, 9]
      • ...... 依此类推
    • 每次 点击上一组按钮 indexChange 事件会依次返回 [1]Index 数组 ( 以初始状态为例 )
      • [6, 7, 8, 9]
      • [2, 3, 4, 5]
      • [8, 9, 0, 1]
      • [4, 5, 6, 7]
      • ...... 依此类推

< pollingInterval > - 轮巡参数

  • 释义轮巡时间间隔 单位秒  
  • 类型Number
  • 默认值60

< pollingStartIndex> - 轮巡参数

  • 释义初始开始轮巡起点索引
  • 类型Number
  • 默认值0

< pollingListener > - 轮巡参数

  • 释义根据条件进行轮巡监听
  • 类型<Number>Array / Boolean
  • 默认值false
  • e.g.:
    • 类型为 <Number>Array :当 轮巡计时 与数组中的 number 对应上时 会触发 pollingEvent - pollingListener 事件
      • [55, 47, 30, 10] 表示轮巡计时等于 55/47/30/10 的时候会触发 相当于一个轮巡触发 4
    • 类型为 Boolean : 值为false表示不监听 而值为true则表示全监听 即轮巡计时发生变化时 每秒 都会触发 pollingEvent - pollingListener 事件

< spliceNum > - 回放参数

  • 释义回放刻度分割的数量(必须为奇数)
  • 类型Number
  • 默认值19

< timeUnitLabel > - 回放参数

  • 释义时间刻度间隔(以秒为单位)
    • 目前支持 : 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60, 120, 180, 240, 300, 360, 600, 720, 900, 1200, 1800, 3600
  • 类型Number
  • 默认值3600:即 1 个小时

< timeDiffNum > - 回放参数

  • 释义判断是否播放结束的时间间隔误差
  • 类型Number
  • 默认值10

< autoPlay > - 回放参数

  • 释义拖动或者更改日期后是否自动播放
  • 类型Boolean
  • 默认值true

< operateChosenIndex> - 回放参数

  • 释义当前操作的宫格索引值-建议通过dom.operateChosenIndex =... 的方式赋值
  • 类型Number
  • 默认值0

EVENTS

使用方法见 EVENTS 使用

< initEvent > - 通用事件

释义初始化事件 播放器初始化时触发 返回对应的双向绑定实例

⚠️ 重要 - <初始化事件>

此事件必须监听
宫格模式时返回 <宫格对象> 与 <播放器对象数组> 组成的对象
单播放器模式时返回 <播放器对象>
返回数据请为响应式对象 请保存

返回参数

  • 数量: 1

  • 获取方式:event.detail[0]

  • 参数类型: Object

  • 参数详解:

    • 宫格模式下 返回参数:

      {
        "gridIns": Object, // 宫格实例 该对象上挂载了 窗格控制 相关方法
        "panes": [ // 由 PANE<窗格> 组成的数组
          {
            "playerIns": Object, // 播放器实例 该对象上挂载了 播放器控制 相关方法
            "url": "", // 该窗格播放视频的地址
            "streamType": "",
            "fileName": "",
            "msg": "",
            "data": undefined
          },
          {
            "playerIns": Object,
            "url": "",
            "streamType": "",
            "fileName": "",
            "msg": "",
            "data": undefined
          },
          {
            "playerIns": Object,
            "url": "",
            "streamType": "",
            "fileName": "",
            "msg": "",
            "data": undefined
          },
          {
            "playerIns": Object,
            "url": "",
            "streamType": "",
            "fileName": "",
            "msg": "",
            "data": undefined
          }
          ......
        ]
      }
      
      • gridIns宫格实例 挂载了宫格对应的方法 详见 gridIns

      • panes由 PANE<窗格> 组成的数组 注意:此处panes为复数

        数组中的 PANE<窗格> 对应播放器窗格 如

        0 号索引 对应 第一个窗格 依次类推

        PANE<窗格> 中参数详解如下 👇

        字段名释义详解
        playerIns播放器实例挂载了播放器对应的方法 详见 playerIns
        url<重要>视频播放地址填入视频地址后会自动播放 地址发生变化会自动更新并播放
        streamType视频流类型将在视频详情中展示(空值则不展示) 一般为 子码流/主码流 需后端提供
        fileName文件名称保存文件 ( 截图/录制 ) 时会在此名称后自动拼接当前时间作为文件名 空值则为时间戳
        msg展示信息窗格中部展示的信息 可用于状态提示等 空值则不显示
        data冗余参数挂载在窗格对象上的冗余参数 按需使用 且不会被 [3]自动清除
        playbackData回放相关数据用于存储更新视频回放中的数据(对象数据类型,详解见下方回放数据结构)
    • 单播放器模式下 返回参数:

      {
        "pane": {
          "playerIns": Object, // 播放器实例 该对象上挂载了 播放器控制 相关方法
          "url": "", // 该窗格播放视频的地址
          "streamType": "",
          "fileName": "",
          "msg": "",
          "data": undefined
        }
      }
      
      • pane:用法同宫格模式 panes 中的 PANE<窗格> 注意:此处pane为单数
    • 单播放回放模式 返回参数:

      {
        "pane": {
          "playerIns": Object, // 播放器实例 该对象上挂载了 播放器控制 相关方法
          "url": "", // 该窗格播放视频的地址
          "streamType": "",
          "fileName": "",
          "msg": "",
          "data": undefined,
           "playbackData": {
               "devicePlayDates": ["2022-10-20","2022-10-21","2022-11-08"], // 可播放日期集合,业务需主动更新改数据
               "playTimes": [	// 可播放时间段集合, 业务方可根据”updateDataEvent“类型中为”getPlayTimes“触发更新改数据集合
                      {
                          "fileName": "ch0014_01000002903000000",
                          "startTime": "2022-11-08 22:16:41",
                          "endTime": "2022-11-08 23:26:44"
                      },
                      {
                          "fileName": "ch0014_01000002951000000",
                          "startTime": "2022-11-08 23:26:44",
                          "endTime": "2022-11-09 00:02:37"
                      }
                  ]
           }
        }
      }
      
    • 宫格回放模式 返回参数:

      {
        "gridIns": Object, // 宫格实例 该对象上挂载了 窗格控制 相关方法
        "panes": [ // 由 PANE<窗格> 组成的数组
          {
            "playerIns": Object, // 播放器实例 该对象上挂载了 播放器控制 相关方法
            "url": "", // 该窗格播放视频的地址
            "streamType": "",
            "fileName": "",
            "msg": "",
            "data": undefined,
            "playbackData": {
                "playStartTime": "", // 播放时间段的开始时间
                "playEndTime": "", // 播放时间段结束时间
                "devicePlayDates": [], // 可播放日期集合
                "uuid": "",
                "playTimes": [], // 可播放时间段集合
            }
          },
          {
            "playerIns": Object,
            "url": "",
            "streamType": "",
            "fileName": "",
            "msg": "",
            "data": undefined,
            "playbackData": {
                "playStartTime": "", // 播放时间段的开始时间
                "playEndTime": "", // 播放时间段结束时间
                "devicePlayDates": [], // 可播放日期集合
                "uuid": "",
                "playTimes": [], // 可播放时间段集合
            }
          }
          ......
        ]
      }
      

< playerEvent > - 通用事件

释义播放器事件 播放器播放/停止/暂停/录制等事件时触发

返回参数

  • 数量:1~3

  • 获取方式:参数1 - event.detail[0] 参数2? - event.detail[1]

  • 参数类型: 参数1 - String 参数2? - Number

  • 参数详解:

    • 参数 1:事件详细类型
    • 参数 2:窗格索引 ( 单播放器模式下无 ) 表示触发此事件的具体窗格
参数 1参数 2参数 3释义
"recordStart"Number/开始录制时触发
"recordEnd"Number/结束录制时触发
"play"Number/开始播放时触发
"pause"Number/暂停播放时触发
"destroy"Number/停止播放时触发
"loadingEnd"Number/loading 转圈结束时触发
"playerZoom"NumberBoolean - 缩放状态播放器窗格缩放
"websocketopen"Number/websocket 开启
"closeStream"Number/触发关流
"dataRateType"NumberNumber - 当前选中下拉数组的索引码流选择下拉变化

< errorEvent > - 通用事件

释义异常事件 组件发生异常时触发

返回参数

  • 数量:2~3
  • 获取方式:参数1 - event.detail[0] 参数2 - event.detail[1] 参数3? - event.detail[2]
  • 参数类型: 参数1 - String 参数2? - any 参数3? - any
  • 参数详解:
    • 参数 1:异常类型
    • 参数 2:窗格索引 ( 单播放器模式下无 ) 表示触发此事件的具体窗格
    • 参数 3:其他参数 视参数 1 的类型而定
      • 若根据当前事件详细类型存在参数 3 ( 如"timeout" ) 且不存在参数 2 ( 单播放器模式下 ) 参数 3 在event.detail中索引会自动前移
参数 1参数 2参数 3释义
"websocketError"Number/websocket 链接无响应
"fetchError"Number/http 链接无响应
"analysisIFrameError"Number/解析关键帧失败
"decoderError"Number/解码失败
"timeout"Number"request failed" | "stop playing"request failed - 初始请求超时
stop playing - 播放过程中请求超时
"streamEnd"Number/websocket 数据流断开
“playOver”Number/本段流播放完毕事件
“noBackVideoInTime”Number/当前时间暂无可播放录像
“getPlayUrlTimeRangeError”Number/无法确定获取播放 url 的时间范围
“noInCanPlayDate”Number/不在可播放日期范围内

< updateDataEvent > - 回放事件

释义根据事件类型获取更新回放数据

返回参数

  • 数量:1~2
  • 获取方式:参数1 - event.detail[0] 参数2 - event.detail[1] 参数3 - event.detail[2]
  • 参数类型: 参数1 - String 参数2 - Object 参数3? - Number
  • 参数详解:
    • 参数 1:获取数据的类型
    • 参数 2:其他参数 视参数 1 的类型而定
    • 参数 3:当前操作宫格的索引值: 当参数 1 为“getPlayUrl”时才存在该值
参数 1参数 2释义
"getPlayTimes"Object(详解见下方注释)获取可播放时间段
"getPlayUrl"Object(详解见下方注释)获取播放 url
  • getPlayTimes 参 2 详解

    {
        getPlayTimeType: String, // changeTimeRange-drag: 拖动时间滚轴,changeTimeRange-zoom: 缩放时间刻度, device: 切换设备
         getPlayTimeDateString, // 要获取播放时间段的日期: "YYYY-MM-DD"
         uuid: String, // 设备uuid
    }
    
  • getPlayUrl 参数 2 详解

    {
        startTime: string, // 获取回放播放url的开始时间: "YYYY-MM-DD HH:mm:ss"
        endTime: string, // 获取回放播放url的结束时间: "YYYY-MM-DD HH:mm:ss"
        uuid: String, // 设备uuid
    }
    

< gridEvent > - 宫格事件

释义宫格事件 宫格选中窗格/切换布局/批量操作等事件时触发

返回参数

  • 数量:1~2

  • 获取方式:参数1 - event.detail[0] 参数2? - event.detail[1]

  • 参数类型: 参数1 - String 参数2? - any

  • 参数详解:

    • 参数 1:事件详细类型
    • 参数 2:其他参数 视参数 1 的类型而定
参数 1参数 2释义
"PTZShow"Boolean - 当前云台操作展开状态云台操作栏展开/关闭时触发
"ALLStop"/全部窗格停止播放时触发
"ALLCalibration"/全部窗格重置校准时触发
"gridLayoutChange"Number - 当前窗格数量宫格布局变化时触发
"gridProportionChange"Number - 当前窗格高宽比宫格比例变化时触发
"gridChoose"Number - 当前选中窗格的索引窗格选中时触发
"gridZoom"Boolean - 缩放状态宫格缩放时触发

< PTZEvent > - 云台事件

释义云台事件 云台控制按钮被点击时触发

返回参数

  • 数量:2

  • 获取方式:参数1 - event.detail[0] 参数2 - event.detail[1]

  • 参数类型: 参数1 - String 参数2 - Number

  • 参数详解:

    • 参数 1:事件详细类型
    • 参数 2:云台速度
参数 1参数 2释义
"rotateTL"Number云台上仰和左转时触发
"rotateT"Number云台上仰时触发
"rotateTR"Number云台上仰和右转时触发
"rotateL"Number云台左转时触发
"rotateR"Number云台右转时触发
"rotateDL"Number云台下俯和左转时触发
"rotateD"Number云台下俯时触发
"rotateDR"Number云台下俯和右转时触发
"zoomAdd"Number变倍增加时触发
"zoomSubtract"Number变倍减少时触发
"apertureAdd"Number光圈增加时触发
"apertureSubtract"Number光圈减少时触发
"focusAdd"Number聚焦增加时触发
"focusSubtract"Number聚焦减少时触发
"speedAdd"Number速度增加时触发
"speedSubtract"Number速度减少时触发

< pollingEvent > - 轮巡事件

释义轮巡事件 轮巡按钮点击/轮巡触发/index 数组变化/轮巡监听等事件时触发

返回参数

  • 数量:2

  • 获取方式:参数1 - event.detail[0] 参数2 - event.detail[1]

  • 参数类型: 参数1 - String 参数2 - any

  • 参数详解:

    • 参数 1:事件详细类型
    • 参数 2:其他参数 视参数 1 的类型而定
参数 1参数 2释义
"indexChange"<Number>Array - 当前轮巡对应的 Index 数组[2]index 数组变化时触发
"pollingState"String - 操作类型:play pause stop prev next轮巡事件按钮被点击时触发
"pollingListener"Number - 当前监听的时间轮巡监听触发事件

INSTANCEFUNCTION

宫格实例 / 播放器实例 上挂载的方法

实例获取见 initEvent

宫格实例

  • initEvent事件中获取的gridIns
方法名使用方式参数释义
PTZShowgridIns.PTZShow(Boolean)是否显示云台控制面板开启关闭
ALLStopgridIns.ALLStop()/窗格全部停止
ALLCalibrationgridIns.ALLCalibration()/窗格全部校准
fullScreengridIns.fullScreen()/宫格全屏
gridLayoutChangegridIns.gridLayoutChange(String)[2] 布局对应字符串宫格布局更改
gridProportionChangegridIns.gridProportionChange(Number)窗格高宽比宫格比例更改
getGridInfogridIns.getGridInfo()/获取宫格信息
[4] 宫格信息返回值
--- 轮巡模式额外方法 👇 ---
pollingStartgridIns.pollingStart()/开始轮巡
pollingPausegridIns.pollingPause()/暂停轮巡
pollingStopgridIns.pollingStop()/停止轮巡
pollingPrevgridIns.pollingPrev()/上一组
pollingNextgridIns.pollingNext()/下一组
pollingResetgridIns.pollingReset()/轮询重启
isPollinggridIns.isPolling()/是否在轮巡中
返回值 Boolean

播放器实例

  • initEvent事件中获取的playerIns
方法名使用方式参数释义
restartPlayplayerIns.restartPlay()/重置校准
playplayerIns.play()/开始播放
pauseplayerIns.pause()/暂停播放
destroyplayerIns.destroy()/停止销毁
isPlayingplayerIns.isPlaying()/是否在播放
返回值 Boolean
VDdetailplayerIns.VDdetail()/打开/关闭详细信息面板
fullscreenplayerIns.fullscreen(Boolean)是否全屏全屏控制
screenshotplayerIns.screenshot()/截图
recordplayerIns.record()/录制
dataRateTypeplayerIns.dataRateType(Number)选择下拉的索引指定码流下拉所选索引

注解

[1] Index数组

  • 长度为当前宫格数 其中的元素为 需进行轮巡的数组 中元素的索引

[2] 布局对应字符串

  • 字符串宫格布局样式宫格数
    "1"1*11
    "2"2*23
    "3"3*39
    "4T22"2+810
    "3LT2"1+2+36
    "4LT3"1+3+48

[3] PANE<窗格>参数自动清除

  • 宫格模式的全部停止事件 / 轮巡模式的停止轮巡事件 / 播放器停止按钮的停止事件

    自动清除 对应 PANE<窗格>url streamType fileName msg 数据

    不会清除 data

[4] 宫格信息返回值

  • {

gridNum: 宫格数,

gridLayout: 宫格布局字符串,

gridProportion: 宫格高宽比,

gridChosen: 当前选中宫格,

};

V3.1 TO V3.2

  • initEvent 事件变化
    • 宫格模式下返回参数中 itemPlayerIns 改为 panes
    • 单播放器模式下返回参数中 itemPlayerIns 改为 pane
  • playerEvent 事件变化
    • 去除 playerEvent 中的 error 类型
    • 单独新增 errorEvent 事件