更新记录

1.0.7（2026-08-21）

更新一下文档

1.0.6（2026-07-22）

ios 云打包异常问题修复

1.0.5（2026-07-21）

相关的更新优化

平台兼容性

uni-app(4.73)

uni-app x(4.84)

hl-hik-player

海康 iSecure Center 视频播放 UTS 原生插件。基于 HatomPlayer SDK（V2.4.6），在 nvue 页面中以原生组件方式使用。

• 支持平台：Android、iOS（真机；iOS 模拟器不支持）
• 使用方式：组件标签 + $ref 调方法 + @event 收事件

插件只负责播放。预览 / 回放 / 对讲的 URL 和 header（如 token）由业务层向平台 OpenAPI 获取后传入。

一、能做什么

二、接入前必读

1. 必须打自定义基座

本插件是 UTS 原生插件，标准基座加载不了。请用 HBuilderX 制作「自定义调试基座」后再运行。

修改了插件原生代码、iOS 原生依赖或 Resources 后，需要重新打基座，热更新不够。

iOS 云端依赖

iOS 的 hatomplayer_core.framework 已从插件包移至公开 Gitee CocoaPods 仓库，构建时由 utssdk/app-ios/config.json 固定拉取 HatomPlayerCore 2.4.0：

https://gitee.com/petalmail/ios-hik-player.git

因此 iOS 打自定义基座或云端构建时需要能够访问 Gitee。SDK 二进制最低支持 iOS 13.0； 插件内的 Resources/com.hri.hpc.mobile.ios.player.metallib 仍必须保留。

2. 页面类型

组件只能用在 nvue 页面，不要放在普通 vue 页面里。

3. 取流地址

• 插件不请求 OpenAPI，不帮你换 token。
• src、header、对讲 URL 都由业务传入。
• SDK 初始化时 accessToken 传空串（插件内部已处理，全局只初始化一次）。

4. 权限

Android（Manifest 已声明）：网络、录音、存储/媒体、WAKE_LOCK。对讲时的 RECORD_AUDIO 需运行时申请。

iOS（Info.plist 已声明）：麦克风（对讲）、相册读写（抓图/录像存相册）。纯播放一般不弹权限；对讲/存相册时由系统弹窗。

三、快速上手

1. 模板

<template>
  <view>
    <hl-hik-player
      ref="playerRef"
      class="player"
      :src="videoUrl"
      :autoplay="0"
      :play-mode="playMode"
      :playback-time="playbackTime"
      :header="header"
      :player-options="playerOptions"
      @event="handleEvent" />
    <button @click="onPlay">播放</button>
    <button @click="onStop">停止</button>
  </view>
</template>

2. 脚本示例

import { ref } from 'vue'

const playerRef = ref(null)
const videoUrl = ref('rtsp://你的预览地址')
const playMode = ref('live') // live | playback
const header = ref({})       // 如 { token: 'xxx' }
const playbackTime = ref({
  start: Date.now() - 60 * 60 * 1000,
  end: Date.now()
})
const playerOptions = ref({
  hardDecode: true,
  privateData: false,
  qualityType: 1,          // 0 主码流，1 子码流（子码流通常首帧更快）
  timeout: 10,
  // Android 缓冲（毫秒）
  // playBuffer: 200,
  // iOS 缓冲（字节，建议 >= 64KB；官方常用 5*1024*1024）
  bufferLength: 1024 * 1024
})

const getPlayer = () => playerRef.value

const onPlay = () => {
  getPlayer()?.playVideo()
}
const onStop = () => {
  getPlayer()?.stopVideo()
}

const handleEvent = (payload) => {
  // nvue 里真正数据常在 detail 里
  const detail = payload?.detail?.dynamicJSONFields
    ?? payload?.detail
    ?? payload
    ?? {}
  const event = detail.event || ''

  switch (event) {
    case 'playStatusChanged':
      console.log('状态', detail.state, detail.errorCode)
      break
    case 'playbackTimeUpdate':
      // detail.osdTime / playedTime / totalTime（毫秒）
      break
    case 'error':
      console.log('错误', detail.message, detail.action)
      break
    case 'debugLog':
      // 插件诊断信息（含分步耗时等）
      console.log('[插件]', detail.message, detail)
      break
    default:
      if (event) console.log(event, detail)
  }
}

3. 样式注意（nvue）

播放器区域需要明确宽高，例如：

.player {
  width: 750rpx;
  height: 420rpx;
  background-color: #000000;
}

四、属性（Props）

playerOptions

注意：playBuffer（毫秒）和 bufferLength（字节）不是一回事，不要把 Android 的毫秒值直接塞给 iOS。

五、方法（通过 ref 调用）

对外方法都有返回值（boolean 或 number），避免 nvue 对无返回值方法派发不稳定。

重要： 播放控制请用 playVideo / stopVideo / pauseVideo / resumeVideo，不要用 play / stop 这类容易和原生或其它 API 冲突的名字。

播放控制

抓图 / 录像 / 声音 / 对讲

鱼眼 / 电子放大 / 全屏

时间 / 帧率 / 解码

鱼眼枚举

correctType：

placeType：

调用示例

const p = playerRef.value
if (!p) return

p.playVideo()
p.switchStream('sub')
p.setSoundEnabled(true)
p.takeSnapshot(saveDir, `snap_${Date.now()}.jpg`)
p.startRecord(`${saveDir}record_${Date.now()}.mp4`, true)
p.enterFullscreen()

iOS 上部分「有返回值」的 ref 方法可能拿不到同步返回值（表现为 undefined），但方法本身一般会执行。以 @event 回调为准更稳妥。

六、事件（@event）

统一走一个事件名：@event="handleEvent"。业务字段在 payload 里，关键字段是 event。

nvue 解析建议：

const detail = payload?.detail?.dynamicJSONFields
  ?? payload?.detail
  ?? payload
  ?? {}
const event = detail.event || ''

playStatusChanged.state

debugLog 常见耗时字段（便于排查首帧慢）

若 submitTotalMs 很小、firstFrameMs 很大，瓶颈多半在网络 / 平台取流，而不是本地 API 调用。

七、Android 与 iOS 差异

前端方法名一致，内部做了适配。需要知道的差异：

八、常见问题

1. 黑屏 / 一直 loading

• 确认自定义基座已安装，且是最新打的。
• 确认 src 有效；预览/回放 URL 是否过期（openUrl 临时码常有时效）。
• 回放模式是否传了正确的 playbackTime.start / end。
• header 里的 token 是否有效；不要误传干扰鉴权的字段。

2. iOS 播放一会儿闪退

优先检查 App 包内是否有：

com.hri.hpc.mobile.ios.player.metallib

该文件应来自插件目录：

uni_modules/hl-hik-player/utssdk/app-ios/Resources/

缺失时，SDK 在 Metal 渲染初始化阶段会断言崩溃。

3. 事件来了但 detail 是空对象

iOS 侧事件必须用 UTSJSONObject 再 $emit。当前插件已按此实现。若仍为空，多半是旧基座，请重打自定义基座。

解析时请使用：

payload.detail.dynamicJSONFields ?? payload.detail ?? payload

4. Android 加载 so 失败

确认自定义基座，且 ABI 只有 armeabi-v7a、arm64-v8a。

5. 对讲无声

确认已授予录音权限，设备扬声器已开，对讲 URL 正确。

6. 首帧很慢（例如接近 10 秒）

可尝试：

• qualityType: 1（子码流）
• privateData: false
• iOS 适当减小 bufferLength（如 1 * 1024 * 1024），观察是否花屏/卡顿再回调

公共及网络错误

RTSP 取流错误

码流处理错误