--- name: "IpcPlayer" mode: "component" versionRequirements: - { name: "@ray-js/ray", version: "0.6.9" } title: "IpcPlayer - 实时视频播放" --- ## IpcPlayer > [VERSION] @ray-js/ray >= 0.6.9 ### 描述 实时视频播放组件。基于异层渲染的原生组件，请注意原生组件使用限制。 ### 属性 | 属性 | 类型 | 必填 | 默认值 | 最低版本 | 描述 | | --- | --- | --- | --- | --- | --- | | `deviceId` | `string` | 是 | `""` | - | 设备 id，组件的唯一标识符，必须设置 | | `autoplay` | `boolean` | 否 | `false` | - | 自动播放 | | `muted` | `boolean` | 否 | - | - | 是否静音 | | `clarity` | `"ss" \| "normal" \| "hd" \| "ud" \| "ssp" \| "auto" \| "audio"` | 否 | `"normal"` | - | 清晰度：ss 省流量、normal 标清、hd 高清、ud 超清、ssp 超超清、auto 自动、audio 音频模式 | | `soundMode` | `"speaker" \| "ear"` | 否 | `"speaker"` | - | 声音输出方式：speaker 扬声器、ear 听筒 | | `orientation` | `"vertical" \| "horizontal"` | 否 | `"vertical"` | - | 画面方向：vertical 竖直、horizontal 水平 | | `objectFit` | `"contain" \| "fillCrop"` | 否 | `"contain"` | - | 填充模式：contain 长边填满，fillCrop 铺满裁剪 | | `autoPauseIfNavigate` | `boolean` | 否 | `true` | - | 跳转本小程序其他页面时是否自动暂停实时音视频 | | `autoPauseIfOpenNative` | `boolean` | 否 | `true` | - | 跳转 App 其他原生页面时是否自动暂停实时音视频 | | `rotateZ` | `number` | 否 | `0` | - | 摄像头旋转角度，0~360 | | `scalable` | `boolean` | 否 | `true` | - | 当前是否可缩放 | | `scaleMultiple` | `number` | 否 | `0` | - | 缩放比例，仅在 scalable 为 true 时生效 | | `ptzControllable` | `boolean` | 否 | `true` | - | 是否开启视频区域云平台控制 | | `borderWidth` | `number \| string` | 否 | `0` | - | 边框宽度，单位 px | | `borderStyle` | `"solid" \| "dashed"` | 否 | `"solid"` | - | 边框样式：solid、dashed | | `borderColor` | `string` | 否 | `"#ffffff"` | - | 边框颜色，十六进制 | | `borderRadius` | `number \| string` | 否 | `0` | - | 边框圆角，单位 px | | `backgroundColor` | `string` | 否 | `"#ffffff"` | - | 背景颜色，十六进制 | | `extProps` | `string \| Record` | 否 | - | `@ray-js/ray 1.7.79` | 额外属性配置 | | `onConnectchange` | `(event: IpcPlayerConnectChangeEvent) => void` | 否 | - | - | 当连接状态发生变化时触发，请使用 onConnectChange | | `onPreviewchange` | `(event: IpcPlayerPreviewChangeEvent) => void` | 否 | - | - | 当预览状态发生变化时触发，请使用 onPreviewChange | | `onOnlinechange` | `(event: IpcPlayerOnlineChangeEvent) => void` | 否 | - | - | 当设备在线状态变化时触发，请使用 onOnlineChange | | `onInitdone` | `(event: IpcPlayerInitDoneEvent) => void` | 否 | - | - | 初始化完成时触发，请使用 onInitDone | | `onZoomchange` | `(event: IpcPlayerZoomChangeEvent) => void` | 否 | - | - | 视频缩放比例变化时触发，请使用 onZoomChange | | `onVideotap` | `(event: IpcPlayerVideotapEvent) => void` | 否 | - | - | 点击视频时触发，请使用 onVideoTap | | `onConnectChange` | `(event: IpcPlayerConnectChangeEvent) => void` | 否 | - | - | 当连接状态发生变化时触发，state 为 0 表示连接成功 | | `onPreviewChange` | `(event: IpcPlayerPreviewChangeEvent) => void` | 否 | - | - | 当预览状态发生变化时触发，state 为 1 表示开始预览成功，0 表示结束预览成功 | | `onOnlineChange` | `(event: IpcPlayerOnlineChangeEvent) => void` | 否 | - | - | 当 IPC 设备在线状态变化时触发 | | `onInitDone` | `(event: IpcPlayerInitDoneEvent) => void` | 否 | - | - | 初始化完成时触发 | | `onZoomChange` | `(event: IpcPlayerZoomChangeEvent) => void` | 否 | - | - | 视频缩放比例及当前倍数变化时触发 | | `onVideoTap` | `(event: IpcPlayerVideotapEvent) => void` | 否 | - | - | 点击视频时触发 | | `onError` | `(event: IpcPlayerErrorEvent) => void` | 否 | - | - | 状态异常时触发 | | `onSessionDidDisconnected` | `(event: IpcPlayerSessionDidDisconnectedEvent) => void` | 否 | - | - | 断开连接（⚠️ Android 端未下发，断开连接通过 onConnectChange state < 0 体现） | | `onCameraPreviewFailure` | `(event: IpcPlayerCameraPreviewFailureEvent) => void` | 否 | - | `IPCKit 6.1.4` | 预览失败（P2P sessionStatus < 0 时触发，普通预览与多目共用） | | `onCameraNotifyWeakNetwork` | `(event: IpcPlayerCameraNotifyWeakNetworkEvent) => void` | 否 | - | `IPCKit 6.1.4` | 弱网通知 | | `onCreateViewSuccess` | `(event: IpcPlayerCreateViewSuccessEvent) => void` | 否 | - | `IPCKit 6.2.3` | 异层组件创建成功时触发 | | `onSelectVideoIndex` | `(event: IpcPlayerSelectVideoIndexEvent) => void` | 否 | - | `IPCKit 7.3.3` | 选中视频索引时触发 | | `onLayoutStatusChanged` | `(event: IpcPlayerLayoutStatusChangedEvent) => void` | 否 | - | `IPCKit 7.3.3` | 布局状态改变时触发 | | `onLocalizerViewLocated` | `(event: IpcPlayerLocalizerViewLocatedEvent) => void` | 否 | - | `IPCKit 7.3.3` | 定位器定位时触发 | | `onSwipeAtVideoIndex` | `(event: IpcPlayerSwipeAtVideoIndexEvent) => void` | 否 | - | `IPCKit 7.3.3` | 滑动播放器手势上报、需要转动云台时触发 | | `updateLayout` | `unknown` | 否 | - | - | 用来异层组件通知容器层样式更新 | ### 引用对象 ##### `interface` IpcPlayerConnectChangeEvent | 属性 | 类型 | 描述 | | --- | --- | --- | | `detail` | `IpcPlayerStateDetail` | 事件详情数据 | ##### `interface` IpcPlayerPreviewChangeEvent | 属性 | 类型 | 描述 | | --- | --- | --- | | `detail` | `IpcPlayerStateDetail` | 事件详情数据 | ##### `interface` IpcPlayerOnlineChangeEvent | 属性 | 类型 | 描述 | | --- | --- | --- | | `detail` | `IpcPlayerOnlineChangeDetail` | 事件详情数据 | ##### `interface` IpcPlayerInitDoneEvent | 属性 | 类型 | 描述 | | --- | --- | --- | | `detail` | `IpcPlayerInitDoneDetail` | 事件详情数据 | ##### `interface` IpcPlayerZoomChangeEvent | 属性 | 类型 | 描述 | | --- | --- | --- | | `detail` | `IpcPlayerZoomChangeNormalDetail \| IpcPlayerZoomChangeCloudDetail` | 事件详情数据 | ##### `interface` IpcPlayerVideotapEvent | 属性 | 类型 | 描述 | | --- | --- | --- | | `detail` | `Record` | 事件详情数据 | ##### `interface` IpcPlayerErrorEvent | 属性 | 类型 | 描述 | | --- | --- | --- | | `detail` | `IpcPlayerErrorDetail` | 事件详情数据 | ##### `interface` IpcPlayerSessionDidDisconnectedEvent ```typescript export interface IpcPlayerSessionDidDisconnectedEvent extends BaseEvent { /** 事件类型 */ type: 'sessionDidDisconnected'; } ``` ##### `interface` IpcPlayerCameraPreviewFailureEvent | 属性 | 类型 | 描述 | | --- | --- | --- | | `detail` | `IpcPlayerCameraPreviewFailureDetail` | 事件详情数据 | ##### `interface` IpcPlayerCameraNotifyWeakNetworkEvent | 属性 | 类型 | 描述 | | --- | --- | --- | | `detail` | `IpcPlayerWeakNetworkDetail` | 事件详情数据 | ##### `interface` IpcPlayerCreateViewSuccessEvent ```typescript export interface IpcPlayerCreateViewSuccessEvent extends BaseEvent { /** 事件类型 */ type: 'createViewSuccess'; } ``` ##### `interface` IpcPlayerSelectVideoIndexEvent | 属性 | 类型 | 描述 | | --- | --- | --- | | `detail` | `IpcPlayerSelectVideoIndexDetail` | 事件详情数据 | ##### `interface` IpcPlayerLayoutStatusChangedEvent | 属性 | 类型 | 描述 | | --- | --- | --- | | `detail` | `IpcPlayerLayoutStatusChangedDetail` | 事件详情数据 | ##### `interface` IpcPlayerLocalizerViewLocatedEvent | 属性 | 类型 | 描述 | | --- | --- | --- | | `detail` | `IpcPlayerLocalizerViewLocatedDetail` | 事件详情数据 | ##### `interface` IpcPlayerSwipeAtVideoIndexEvent | 属性 | 类型 | 描述 | | --- | --- | --- | | `detail` | `IpcPlayerSwipeAtVideoIndexDetail` | 事件详情数据 | ##### `interface` IpcPlayerStateDetail | 属性 | 类型 | 描述 | | --- | --- | --- | | `state` | `number` | 连接状态：0 表示连接成功，<0 表示连接异常；预览状态：1 开始预览，0 结束预览 | ##### `interface` BaseEvent | 属性 | 类型 | 描述 | | --- | --- | --- | | `type` | `string` | 事件类型 | | `timeStamp` | `number` | 页面打开到触发事件所经过的毫秒数 | | `target` | `Target` | 触发事件的源组件 | | `currentTarget` | `Target` | 当前组件的一些属性值集合 | | `mark` | `any` | 事件标记数据 | ##### `interface` IpcPlayerOnlineChangeDetail | 属性 | 类型 | 描述 | | --- | --- | --- | | `online` | `boolean` | 是否在线 | ##### `interface` IpcPlayerInitDoneDetail | 属性 | 类型 | 描述 | | --- | --- | --- | | `maxScaleMultiple` | `number` | 最大缩放倍数（可能为空） | | `obtainCameraConfig` | `any` | 设备相机配置（解析后的 JSON 对象） | ##### `interface` IpcPlayerZoomChangeNormalDetail | 属性 | 类型 | 描述 | | --- | --- | --- | | `zoomLevel` | `number` | 当前缩放倍数 | | `scaleMode` | `number` | 自由缩放状态标识 | ##### `interface` IpcPlayerZoomChangeCloudDetail | 属性 | 类型 | 描述 | | --- | --- | --- | | `zoom_level` | `number` | 自由缩放状态标识 | | `scale` | `number` | 当前缩放倍数 | ##### `interface` IpcPlayerErrorDetail | 属性 | 类型 | 描述 | | --- | --- | --- | | `errCode` | `number` | 错误码 | | `errMsg` | `string` | 错误描述 | ##### `interface` IpcPlayerCameraPreviewFailureDetail | 属性 | 类型 | 描述 | | --- | --- | --- | | `errCode` | `number` | 错误码 | | `deviceId` | `string` | 设备 id | ##### `interface` IpcPlayerWeakNetworkDetail | 属性 | 类型 | 描述 | | --- | --- | --- | | `netValue` | `number` | 网络状况值（原生为 Long 类型，可能超 32 位） | | `devId` | `string` | 设备 id | ##### `interface` IpcPlayerSelectVideoIndexDetail | 属性 | 类型 | 描述 | | --- | --- | --- | | `index` | `number` | 镜头索引 | | `name` | `string` | 镜头名称 | | `supportPTZ` | `boolean` | 是否支持云台控制 | | `supportLocalizer` | `boolean` | 是否支持定位器 | | `supportZoom` | `boolean` | 是否支持缩放 | ##### `interface` IpcPlayerLayoutStatusChangedDetail | 属性 | 类型 | 描述 | | --- | --- | --- | | `screenMode` | `number` | 屏幕模式（枚举 ordinal）：0 短屏，1 全屏，2 横屏 | | `layoutStyle` | `number` | 布局样式（枚举 ordinal）：-1 无效，0 画中画，1 平铺，2 宫格，3 缩略图 | ##### `interface` IpcPlayerLocalizerViewLocatedDetail | 属性 | 类型 | 描述 | | --- | --- | --- | | `index` | `string` | 联动的球机 index（注意：此处为 string 类型，与 selectVideoIndex 的 number 不同） | | `coor` | `string` | x、y 坐标位置 | ##### `interface` IpcPlayerSwipeAtVideoIndexDetail | 属性 | 类型 | 描述 | | --- | --- | --- | | `index` | `number` | 滑动的镜头索引 | | `direction` | `number` | 滑动方向：上下左右，枚举 0、1、2、3 | | `isStop` | `number` | 手势状态：1 开始，0 结束 | ##### `interface` Target | 属性 | 类型 | 描述 | | --- | --- | --- | | `id` | `string` | 事件源组件的id | | `dataset` | `Record` | 事件源组件上的 `dataset` 自定义属性组成的集合 | ### 示例代码 #### 基础用法 ```tsx import React from 'react'; import { IpcPlayer, View, Text } from '@ray-js/ray'; export default function () { return ( IPC 实时视频 { console.log('初始化完成，最大缩放倍数:', e.detail.maxScaleMultiple); }} onError={(e) => { console.log('错误:', e.detail); }} /> ); } ``` #### IPC 播放控制 ```tsx import React, { useState } from 'react'; import { IpcPlayer, View, Text, Button, createIpcPlayerContext } from '@ray-js/ray'; export default function () { const [isOnline, setIsOnline] = useState(false); const [connectState, setConnectState] = useState(-1); const [previewState, setPreviewState] = useState(-1); const playerId = 'myIpcPlayer'; const handleStartPreview = () => { const ctx = createIpcPlayerContext(playerId); ctx.startPreview(); }; const handleStopPreview = () => { const ctx = createIpcPlayerContext(playerId); ctx.stopPreview(); }; return ( { console.log('连接状态变化:', e.detail.state); setConnectState(e.detail.state); }} onPreviewChange={(e) => { console.log('预览状态变化:', e.detail.state); setPreviewState(e.detail.state); }} onOnlineChange={(e) => { console.log('在线状态变化:', e.detail.online); setIsOnline(e.detail.online); }} onZoomChange={(e) => { if ('zoomLevel' in e.detail) { console.log('缩放变化:', e.detail.zoomLevel); } }} onVideoTap={() => { console.log('点击视频'); }} onError={(e) => { console.log('错误:', e.detail); }} /> 设备在线: {isOnline ? '是' : '否'} 连接状态: {connectState === 0 ? '已连接' : '未连接'} 预览状态: {previewState === 1 ? '预览中' : '未预览'} ); } ``` ## 错误码 | 值 | 说明 | | ----- | --------------------------------- | | -1000 | 其他未知异常 | | -1001 | connect 失败 | | -1002 | 开启预览失败 | | -1003 | 结束预览失败 | | -1004 | 设置静音失败 | | -1005 | 设置清晰度失败 | | -1006 | 截图失败 | | -1007 | 属性不合法 | | -1008 | 设置参数不合法 | | -1009 | disconnect 失败 | | -1010 | 网络状态不可用 | | -1011 | 设备离线 | | -1012 | 设备被移除 | | -1013 | startTalk fail | | -1014 | StopTalk fail | | -1015 | StartRecord fail | | -1016 | StopRecord fail | | -1017 | IsTalkBacking fail | | -1018 | SetAvailableRockerDirections fail | | -1019 | IsPTZControllable fail | | -1020 | SetTrackingStatus fail | | -1021 | GetVideoInfo fail | ### 相关链接 相关 API：[createIpcPlayerContext](/cn/miniapp/develop/miniapp/api/media/ipc/createIpcContext)。这是基于异层渲染的原生组件, 请注意 [原生组件使用限制](/cn/miniapp/develop/miniapp/component/native-component/native-component)。 ### 常见问题 1. `ipc-player` 默认宽度 300px、高度 225px，可通过 tyss 设置宽高。 2. Tuya MiniApp IDE 上暂不支持。 3. 相关原理请参考 [基于异层渲染的原生组件](/cn/miniapp/develop/miniapp/component/native-component/native-component)。 4. 请注意 [原生组件使用限制](/cn/miniapp/develop/miniapp/component/native-component/native-component)。