更新记录

1.0.0（2026-06-13）

初始化版本发布。

平台兼容性

uni-app(5.0)

uni-app x(5.0)

概述

zf-ONVIFCameraUTS 用于 App 端接入 ONVIF 摄像头：自动搜索摄像头、获取设备信息、获取 RTSP 地址、VLC 预览播放、抓拍、当前流录制，以及按时间下载历史录像。

插件采用两层设计：

• ONVIF 层：负责 WS-Discovery、GetDeviceInformation、GetProfiles、GetStreamUri、GetSnapshotUri、Recording/Search/Replay 等能力。
• 播放层：参考 ZF-playRtspUTS，Android 使用 org.videolan.android:libvlc-all，iOS 使用 UTSMobileVLCKit，Harmony 使用 @ohos/vlc。

当前实现边界：

• Android 已接入 ONVIF 原生网络实现，包含自动搜索、设备信息、RTSP 地址获取和抓拍下载；历史录像下载仍依赖摄像头 Recording/Search/Replay 服务，当前返回结构化不支持错误。
• iOS 和 Harmony 已保留同名接口与 VLC 预览通路；ONVIF 自动搜索、SOAP 信息获取、抓拍下载和历史录像下载目前返回结构化不支持错误，后续需要补齐各平台网络层。

使用前提

Android

• App 需要网络权限，插件已声明 INTERNET、ACCESS_NETWORK_STATE、CHANGE_WIFI_MULTICAST_STATE。
• ONVIF/RTSP 多数为局域网明文 HTTP/RTSP，插件 Android 端已开启 usesCleartextTraffic。
• 安卓一体机通过网线直连摄像头时，建议先手动输入摄像头 IP；自动搜索作为辅助能力。

iOS

• iOS 局域网搜索需要本地网络权限；如需多播搜索，还需要在 App 配置中补充对应能力说明。
• iOS 播放依赖 UTSMobileVLCKit。
• 当前 UTSMobileVLCKit 提供的是 iPhoneOS framework，仅包含设备架构；iOS 模拟器编译需要替换为包含 simulator 切片的 XCFramework 或对应 Pod。

Harmony

• Harmony 预览依赖 @ohos/vlc。
• 当前参考播放器中 Harmony 已支持 RTSP 预览；播放画面截图和 VLC 当前流录制能力需要按 Harmony 底层能力继续补齐。

插件接口

discoverCameras

通过 ONVIF WS-Discovery 搜索同网段摄像头。搜索失败或设备不响应时，应回退到手动 IP。

uni-app项目中（nvue）调用示例：

import { discoverCameras } from '@/uni_modules/zf-ONVIFCameraUTS'

discoverCameras({
  timeoutMs: 4000,
  complete: (res) => {
    console.log(res)
  }
})

uni-app x项目（uvue）中调用示例：

import { discoverCameras, type ZFOnvifDiscoverOptions } from '@/uni_modules/zf-ONVIFCameraUTS/utssdk/interface.uts'

let options = {
  timeoutMs: 4000,
  complete: (res : any) => {
    console.log(res)
  }
} as ZFOnvifDiscoverOptions

discoverCameras(options)

可用性

Android 系统可用；iOS、Harmony 系统当前为接口占位，可提供的1.0.0及更高版本。

getCameraInfo

获取 ONVIF 摄像头信息，包括厂商、型号、固件、序列号、profiles 和可用 RTSP 地址。

uni-app x项目（uvue）中调用示例：

import { getCameraInfo, type ZFOnvifConnectionOptions } from '@/uni_modules/zf-ONVIFCameraUTS/utssdk/interface.uts'

let options = {
  host: '192.168.1.64',
  username: 'admin',
  password: '',
  complete: (res : any) => {
    console.log(res)
  }
} as ZFOnvifConnectionOptions

getCameraInfo(options)

可用性

Android 系统可用；iOS、Harmony 系统在传入 streamUri 时可返回手动信息，否则当前为接口占位，可提供的1.0.0及更高版本。

getStreamUri

获取指定 profile 的 RTSP 播放地址。

uni-app x项目（uvue）中调用示例：

import { getStreamUri, type ZFOnvifStreamUriOptions } from '@/uni_modules/zf-ONVIFCameraUTS/utssdk/interface.uts'

let options = {
  host: '192.168.1.64',
  username: 'admin',
  password: '',
  profileToken: '',
  complete: (res : any) => {
    console.log(res)
  }
} as ZFOnvifStreamUriOptions

getStreamUri(options)

可用性

Android 系统可用；iOS、Harmony 系统当前为接口占位，可提供的1.0.0及更高版本。

captureSnapshot

通过 ONVIF GetSnapshotUri 下载抓拍图片，优先用于三端一致的抓拍结果。

uni-app x项目（uvue）中调用示例：

import { captureSnapshot, type ZFOnvifSnapshotOptions } from '@/uni_modules/zf-ONVIFCameraUTS/utssdk/interface.uts'

let options = {
  host: '192.168.1.64',
  username: 'admin',
  password: '',
  includeBase64: false,
  complete: (res : any) => {
    console.log(res)
  }
} as ZFOnvifSnapshotOptions

captureSnapshot(options)

可用性

Android 系统可用；iOS、Harmony 系统当前为接口占位，可提供的1.0.0及更高版本。

downloadRecordVideo

下载指定时间段历史录像。摄像头必须支持 ONVIF Recording/Search/Replay 服务；不支持时会返回结构化错误。

uni-app x项目（uvue）中调用示例：

import { downloadRecordVideo, type ZFOnvifRecordingOptions } from '@/uni_modules/zf-ONVIFCameraUTS/utssdk/interface.uts'

let options = {
  host: '192.168.1.64',
  username: 'admin',
  password: '',
  startTime: '2026-06-13T08:00:00Z',
  endTime: '2026-06-13T08:05:00Z',
  complete: (res : any) => {
    console.log(res)
  }
} as ZFOnvifRecordingOptions

downloadRecordVideo(options)

可用性

Android、iOS、Harmony 系统当前均返回结构化不支持错误，可提供的1.0.0及更高版本。

zf-ONVIFCameraUTS 组件

组件用于承载三端 VLC 预览画面。通过 createZFOnvifCameraContext 获取实例后调用 startPreview、stopVideo、startRecording、stopRecording。

<zf-ONVIFCameraUTS id="onvifCameraView" :options="'-vvv|--network-caching=300'" />

import { createZFOnvifCameraContext, type ZFOnvifConnectionOptions } from '@/uni_modules/zf-ONVIFCameraUTS'

const player = createZFOnvifCameraContext('onvifCameraView', getCurrentInstance()?.proxy)
player?.startPreview({
  host: '192.168.1.64',
  username: 'admin',
  password: '',
  streamUri: 'rtsp://admin:password@192.168.1.64/Streaming/Channels/101'
} as ZFOnvifConnectionOptions)

可用性

Android、iOS、Harmony 系统支持 RTSP 预览；当前流录制和播放器截图能力以各端 VLC 能力为准，可提供的1.0.0及更高版本。