更新记录

1.0.0（2026-07-02）

• 新版发布

平台兼容性

uni-app(5.01)

uni-app x(5.01)

yt-hknet

海康威视网络摄像头 SDK 的 uni-app / uni-app x UTS 插件。提供设备登录、实时预览、抓拍、云台控制等能力。

平台支持

框架	Android App	iOS App
uni-app（Vue2 / Vue3，推荐 nvue 页面）	✅ 已实现	❌ 未实现
uni-app x（uvue）	✅ 已实现	❌ 未实现

本插件同时兼容 uni-app 与 uni-app x 的 UTS 插件调用方式；云台相关 API 使用对象入参（见下文 PtzPara / PtzCruisePara），以适配 uni-app JS 侧传参。

特别提醒

• 购买本插件前，请先试用，请先试用，请先试用，确认满足需求之后再行购买。虚拟物品一旦购买之后无法退款。
• 如有使用上的疑问、bug，可以进交流群联系作者；
• 请在合法范围内使用，若使用本插件做非法开发，本方概不负责；
• 插件需先引入再打自定义基座后使用
• uniapp如需摄像头预览则必须把yt-hknet放在在nvue页面，且不能给yt-hknet设置背景色。更多问题详见下方常见问题
• 可下载示例示例demo（unipp-x示例demo在uniapp示例demo的static文件夹下）

目录

• 插件结构
• 平台与框架说明
• 接入步骤
• 典型调用流程
• 数值参数对照表
• API 参考
• 预览组件 yt-hknet
• 完整示例
• 布局与预览注意事项
• 网络与环境要求
• 常见问题
• 参考链接

插件结构

uni_modules/yt-hknet/
├── package.json
├── readme.md
└── utssdk/
    ├── app-android/
    │   ├── index.uts          # UTS API（登录、抓拍、云台等）
    │   ├── index.vue          # 原生预览组件 yt-hknet
    │   ├── PreviewView.kt
    │   ├── AndroidManifest.xml
    │   └── libs/
    │       └── yt_hik-release.aar
    └── app-ios/
        ├── index.uts          # iOS 占位，暂未实现
        └── index.vue

插件包含两部分：

平台与框架说明

uni-app（/ nvue）

• 页面必须使用 nvue（原生渲染），预览组件 <yt-hknet> 。
• UTS API 通过 import * as HKNet from '@/uni_modules/yt-hknet' 引入，在 .nvue 的 <script> 中直接调用。
• 预览组件 $refs 无需额外类型声明，直接调用 init / startPlay 等方法即可。

uni-app x（uvue）

• 页面使用 .uvue，语法与 TypeScript 更接近。
• 可选导入 YtHknetElement 作为预览组件 $refs 的类型。

云台 API 入参说明

以下 4 个云台 API 统一使用对象入参（定义见 utssdk/interface.uts）：

接入步骤

1. 安装插件

将 uni_modules/yt-hknet 目录复制到项目的 uni_modules 下，或在 HBuilderX 中导入 uni_modules 插件。

2. 配置 manifest.json

建议 Android 最低 SDK 版本：

"app-android": {
  "distribute": {
    "abiFilters": ["arm64-v8a", "armeabi-v7a"],
    "minSdkVersion": "24"
  }
}

3. 初始化 SDK

在 App.vue（uni-app）或 App.uvue（uni-app x）的 onLaunch 中调用一次（推荐全局初始化）：

// uni-app / uni-app x 通用
import * as HKNet from '@/uni_modules/yt-hknet'

export default {
  onLaunch() {
    HKNet.initSdk(true)   // 调试时传 true 输出 SDK 日志
  }
}

也可在首个业务页面 onLoad 中调用 initSdk，但全局只应初始化一次。

4. 引入方式

import * as HKNet from '@/uni_modules/yt-hknet'

• HKNet：所有 UTS 函数（登录、抓拍、云台等）

uni-app x 可选（预览组件 ref 类型提示）：

import { YtHknetElement } from '@/uni_modules/yt-hknet'

典型调用流程

App.onLaunch
  └─ initSdk()

登录页
  └─ login(0, ip, port, user, pass)     → 会话写入 SDK 内部 HCNetConfig

操作页
  ├─ onReady + $nextTick
  │    └─ previewView.init(0)           → 绑定登录会话与 Surface 回调
  ├─ previewView.startPlay(0)           → 0=主码流，1=子码流
  ├─ capturePictureFile(0, path)        → 抓拍（无需预览）
  ├─ ptzStartMove({ key:0, command:21 }) / ptzStopMove({ key:0, command:21 })  → 云台（无需预览）
  └─ logout(0)                          → 退出登录

推荐顺序：

1. initSdk
2. login
3. 预览组件 init(key) → startPlay(streamType)
4. 业务操作（抓拍 / 云台）
5. stopPlay + stopDevPreviews → logout

数值参数对照表

插件 API 与组件方法中涉及的业务数字如下，调用时直接传 number 即可。

摄像头 key（key）

多路设备时用不同 key 区分登录会话与预览绑定关系。

用于：login、logout、isLogin、getDeviceIp、stopDevPreviews、capturePictureFile、云台系列 API，以及组件 init(key)。

⚠️ isLogin(key) 的 key 是摄像头标识（如 0），不是预览码流类型 streamType（0/1）。

预览码流（streamType）

用于组件 startPlay(streamType)、switchStream(streamType)。

云台速度（speed，PtzPara 可选字段）

用于 ptzStartMove、ptzStopMove 的 speed 字段；不传时默认 4。

云台 / 镜头命令（command，PtzPara 必填字段）

用于 ptzStartMove({ key, command, speed? })、ptzStopMove({ key, command, speed? })。
按下与抬起必须传相同的 command。

镜头控制

方向控制

预置点序号（presetIndex）

用于 ptzGotoPreset、ptzSetPreset、ptzClearPreset。

巡航参数（PtzCruisePara）

用于 ptzStartCruise({ key, route?, point?, input? })、ptzStopCruise({ key, route?, point?, input? })（停止时参数须与开始时一致）。

3D 定位坐标

用于 ptzSelZoomInEx(key, xTop, yTop, xBottom, yBottom)。
以画面左上角为原点，按 255 归一化：

xTop = 选中区域左上角X × 255 / 画面宽度
yTop = 选中区域左上角Y × 255 / 画面高度
xBottom = 选中区域右下角X × 255 / 画面宽度
yBottom = 选中区域右下角Y × 255 / 画面高度

设备登录端口（port）

API 参考

以下函数均从 @/uni_modules/yt-hknet 导入。单设备场景下 key 一般传 0。

SDK 生命周期

initSdk(isLog: boolean): void

初始化海康 SDK。

HKNet.initSdk(true)

releaseSdk(): void

释放 SDK 资源，应用退出时调用。

HKNet.releaseSdk()

登录 / 登出

login(key, ip, port, userName, passWord): boolean

登录网络摄像头 / NVR 设备。

返回值：true 登录成功，false 失败。

const ok = HKNet.login(
  0,
  '192.168.1.64',
  8000,
  'admin',
  'your_password'
)

logout(key: number): void

退出指定 key 的登录会话。应先停止预览再 logout。

HKNet.logout(0)

isLogin(key: number): boolean

判断指定 key 是否已登录。

HKNet.isLogin(0)

getDeviceIp(key: number): string | null

获取已登录设备的 IP，未登录返回 null。

getDevicePort(key: number): number

获取已登录设备的端口，未登录返回 0。

getDeviceUserName(key: number): string | null

获取已登录设备的用户名，未登录返回 null。

预览 / 抓拍

预览画面渲染由 <yt-hknet> 组件 负责；以下 API 用于停止预览与抓拍。

stopDevPreviews(key: number): void

停止指定 key 的 SDK 预览句柄（释放 previewId）。
建议与组件的 stopPlay() 同时调用。

HKNet.stopDevPreviews(0)

capturePictureFile(key: number, filePath: string): boolean

抓拍当前通道 JPEG 到指定路径。

const filePath = HKNet.createCaptureFilePath()
if (filePath != null) {
  const ok = HKNet.capturePictureFile(0, filePath)
}

createCaptureFilePath(): string | null

在应用私有 Pictures 目录创建抓拍文件，返回绝对路径；失败返回 null。

云台控制

云台相关 API 登录即可调用，无需开启预览。

ptzStartMove(para: PtzPara): boolean

开始云台 / 镜头动作。

必须与 ptzStopMove 成对使用：按钮 按下 时 start，抬起 时 stop。

// 模板：上方向键
@touchstart="onPtzTouchStart(21)"
@touchend="onPtzTouchEnd"

// 脚本
onPtzTouchStart(command) {
  HKNet.ptzStartMove({ key: 0, command: command })       // 默认速度 4
  // HKNet.ptzStartMove({ key: 0, command: command, speed: 6 }) // 指定速度 6
  this.currentPtzCommand = command
}
onPtzTouchEnd() {
  if (this.currentPtzCommand >= 0) {
    HKNet.ptzStopMove({ key: 0, command: this.currentPtzCommand })
    this.currentPtzCommand = -1
  }
}

// 放大：command 传 11
HKNet.ptzStartMove({ key: 0, command: 11 })
HKNet.ptzStopMove({ key: 0, command: 11 })

ptzStopMove(para: PtzPara): boolean

停止云台动作。command 须与对应的 ptzStartMove 一致；speed 默认 4。

ptzGotoPreset(key, presetIndex): boolean

转到预置点。presetIndex 传 1~255。

HKNet.ptzGotoPreset(0, 1)   // 转到预置点 1

ptzSetPreset(key, presetIndex): boolean

将当前云台位置保存为预置点。

HKNet.ptzSetPreset(0, 1)    // 保存为预置点 1

ptzClearPreset(key, presetIndex): boolean

清除指定预置点。

HKNet.ptzClearPreset(0, 1)  // 清除预置点 1

ptzStartCruise(para: PtzCruisePara): boolean

开始巡航。route、point、input 不传时默认均为 1。

HKNet.ptzStartCruise({ key: 0, route: 1, point: 1, input: 1 })
// 仅传 key，使用全部默认值
HKNet.ptzStartCruise({ key: 0 })

ptzStopCruise(para: PtzCruisePara): boolean

停止巡航，参数须与 ptzStartCruise 一致。

HKNet.ptzStopCruise({ key: 0, route: 1, point: 1, input: 1 })

ptzRunTrack(key): boolean

开始运行已录制的云台轨迹。

HKNet.ptzRunTrack(0)

ptzSelZoomInEx(key, xTop, yTop, xBottom, yBottom): boolean

3D 定位 / 区域缩放，坐标 0~255，需设备支持。

// 框选区域 (10,20)-(30,40) 放大
HKNet.ptzSelZoomInEx(0, 10, 20, 30, 40)

预览组件 yt-hknet

模板用法

<view class="preview-container">
  <yt-hknet ref="ythknet" class="preview-box"></yt-hknet>
</view>

.preview-container {
  margin-top: 16px;
}
.preview-box {
  width: 100%;
  height: 200px;   /* 必须设置固定高度 */
}

组件方法（通过 ref 调用）

UTS 调用示例

uni-app（nvue）

import * as HKNet from '@/uni_modules/yt-hknet'

const CAMERA_KEY = 0   // 业务侧自行定义，与 login 时 key 保持一致

getPreviewRef() {
  return this.$refs['ythknet']
}

// 页面 onReady 后初始化（等原生组件挂载完成）
onReady() {
  this.$nextTick(() => {
    this.getPreviewRef()?.init(CAMERA_KEY)
  })
}

// 开始主码流预览
startPreviewMain() {
  const view = this.getPreviewRef()
  if (view == null) return

  view.stopPlay()
  HKNet.stopDevPreviews(CAMERA_KEY)

  view.init(CAMERA_KEY)
  view.startPlay(0)    // 0=主码流
}

uni-app x（uvue，可选类型）

import * as HKNet from '@/uni_modules/yt-hknet'
import { YtHknetElement } from '@/uni_modules/yt-hknet'

const CAMERA_KEY = 0

getPreviewRef(): YtHknetElement | null {
  return this.$refs['ythknet'] as YtHknetElement | null
}

单窗口切换主/子码流

同一 <yt-hknet> 组件即可，无需两个预览窗口：

view.startPlay(0)           // 主码流
view.startPlay(1)           // 子码流
view.switchStream(1)        // 播放中切换到子码流

停止预览：

this.getPreviewRef()?.stopPlay()
HKNet.stopDevPreviews(CAMERA_KEY)

完整示例

登录页

import * as HKNet from '@/uni_modules/yt-hknet'

const CAMERA_KEY = 0

loginDevice() {
  const success = HKNet.login(
    CAMERA_KEY,
    ip.trim(),
    parseInt(port) || 8000,
    username.trim(),
    password.trim()
  )
  if (success) {
    uni.redirectTo({ url: '/pages/operation/operation' })
  }
}

操作页（预览 + 抓拍 + 云台）

参考本仓库 Demo：

操作页核心逻辑：

const CAMERA_KEY = 0

onLoad() {
  if (!HKNet.isLogin(CAMERA_KEY)) {
    uni.redirectTo({ url: '/pages/login/login' })
    return
  }
}

onReady() {
  this.$nextTick(() => {
    this.getPreviewRef()?.init(CAMERA_KEY)
  })
}

onUnload() {
  this.getPreviewRef()?.stopPlay()
  HKNet.stopDevPreviews(CAMERA_KEY)
}

云台方向键示例（对象入参）：

onPtzTouchStart(command) {
  HKNet.ptzStartMove({ key: CAMERA_KEY, command: command, speed: 4 })
  this.currentPtzCommand = command
}
onPtzTouchEnd() {
  if (this.currentPtzCommand >= 0) {
    HKNet.ptzStopMove({ key: CAMERA_KEY, command: this.currentPtzCommand, speed: 4 })
    this.currentPtzCommand = -1
  }
}

布局与预览注意事项

原生预览底层为 Android SurfaceView，布局不当会导致有登录、能抓拍，但画面不显示。

✅ 推荐做法

1. 给 <yt-hknet> 设置固定宽高，如 width: 100%; height: 200px
2. 不要将预览组件放入 scroll-view 内部
3. 预览按钮、状态文字放在预览组件同级，位于 scroll-view 上方
4. 在 onReady + $nextTick 中调用 init()，确保原生 View 已挂载
5. 开始预览前调用 init(key)，再 startPlay(streamType)
6. 停止预览时同时调用 stopPlay() + stopDevPreviews(key)
7. 页面 onUnload 时停止预览，避免 Surface 销毁后 SDK 仍持有句柄

❌ 避免

• 预览组件放在 scroll-view 内
• 父容器使用 flex: 1 的 scroll-view 与 SurfaceView 同级且可能遮挡
• 未调用 init() 直接 startPlay()（loginBean 未绑定，预览无画面）
• 将 streamType（0/1）误传给 isLogin()（应传摄像头 key，如 0）

网络与环境要求

• 手机需能 TCP 访问 设备 IP:端口（默认 8000），不要求必须同一网段，但需网络路由可达
• 局域网调试时，建议手机与摄像头在同一网段（如均为 192.168.1.x）
• 注意 访客 WiFi / AP 隔离 导致设备间无法互访
• 外网访问需公网 IP、端口映射、VPN 或海康/萤石云平台，非 SDK 限制

常见问题

登录失败

• 检查 IP、端口（8000）、用户名、密码
• 确认手机能 ping 通或访问设备 IP
• 检查是否跨网段且无路由（如手机 192.168.9.x，设备 192.168.8.x）

能抓拍但预览无画面

• 确认已调用 previewView.init(0)（或与 login 时相同的 key）
• 确认在 onReady 之后初始化，而非仅在 onLoad
• 检查预览组件是否被 scroll-view 遮挡或高度为 0
• 停止预览后重新开始：stopPlay + stopDevPreviews → init → startPlay
• 检查<yt-hknet>标签不能设置背景色，设置了去掉重试。

子码流预览提示未登录

• isLogin() 的参数必须是摄像头 key（如 0），不能传码流类型 1

云台无响应

• 确认设备支持 PTZ 且已登录
• 方向控制须 按下 start、抬起 stop，不能只调 start
• command 对照 数值参数对照表 确认数字是否正确
• 预置点序号范围 1~255

多设备

• 每台设备使用不同 key（0、1、2…）分别 login
• 每个预览窗口 init 时传入对应的 key

参考链接

• UTS 语法
• UTS API 插件
• UTS 兼容模式组件
• UTS 标准模式组件
• Hello UTS

更多好用插件推荐

• 高德定位连续定位后台定位保活定位
• 百度汽车摩托车导航插件
• 百度鹰眼轨迹插件支持后台采集、保活
• 百度定位插件、连续定位、保活、坐标系转换、支持双端
• 计步器插件，支持Android、iOS双端
• uts经典蓝牙插件、蓝牙电子秤
• 获取唯一标识、ServiceID、卸载更新不变iOS+Android
• Android经典蓝牙
• 华为ScanKit统一扫码插件支持iOS+Android原生插件
• 【华为扫码】统一扫码插件支持多码连续扫码支持半屏扫码uts插件iOS+Android+HarmonyOS
• 截屏、录屏、防截屏、录屏iOS、Android
• 人脸采集插件 最新百度SDK 离线人脸采集、活体检测
• 页面截长图、截取WebView内容，生成长截图Android+iOS
• Android无预览拍照、录制、静默拍照、静默录制、抓拍插件支持
• uni高德地图功能拓展地图截图
• 科大讯飞离线合成插件支持iOS、android
• iOS保活Android保活鸿蒙保活定位插件系统定位
• 高德定位、猎鹰轨迹插件
• 海康威视综合安防平台视频播放插件
• 支持NFC读写功能检测支持Android iOS HarmonyOS
• 自定义相机