类型定义详解

VmosEdgeClientConfig

设备连接配置接口。

interface VmosEdgeClientConfig {
  /** 设备 IP 地址 */
  ip: string;
  /** 设备唯一标识 */
  deviceId: string;
  /** 端口配置 */
  ports: {
    /** 视频流端口（WebSocket），单控模式必填，群控模式不需要 */
    video?: number;
    /** 音频流端口（WebSocket），⚠️ 暂不支持，请勿配置 */
    audio?: number;
    /** 触控通道端口（WebSocket），必填 */
    touch?: number;
  };
}

字段说明

• deviceId：对应设备信息中的 dbid 字段
• ip：根据网络模式不同，对应不同的字段
  • 局域网模式（network_mode === 'macvlan'）：对应 ip 字段
  • 非局域网模式：对应 hostip 字段
• ports.video：视频流端口
  • 局域网模式：固定为 9999
  • 非局域网模式：对应 tcp_port 字段
• ports.touch：触控通道端口
  • 局域网模式：固定为 9997
  • 非局域网模式：对应 tcp_control_port 字段

配置示例

局域网模式（network_mode === 'macvlan'）

const config: VmosEdgeClientConfig = {
  ip: "192.168.1.100",              // 使用设备的 ip 字段
  deviceId: "EDGE418ASOC2LX9C",     // 使用设备的 dbid 字段
  ports: {
    video: 9999,                     // 局域网模式固定端口
    touch: 9997,                     // 局域网模式固定端口
  },
};

非局域网模式

const config: VmosEdgeClientConfig = {
  ip: "example.com",                // 使用设备的 hostip 字段
  deviceId: "EDGE418ASOC2LX9C",     // 使用设备的 dbid 字段
  ports: {
    video: 22003,                    // 使用设备的 tcp_port 字段
    touch: 24003,                    // 使用设备的 tcp_control_port 字段
  },
};

⚠️ 重要提示：

• audio 端口当前版本暂不支持，配置后不会生效
• 单控模式：video 和 touch 端口都是必填的
• 群控模式：仅需要 touch 端口，video 端口不需要配置
• 网络模式判断：network_mode === 'macvlan' 表示局域网模式，否则为非局域网模式

VmosEdgeClientOptions

客户端初始化选项接口。

interface VmosEdgeClientOptions {
  /** 设备连接配置 */
  config: VmosEdgeClientConfig;
  /** DOM 容器元素 */
  container: HTMLElement;
  /** 是否开启群控模式，默认 false */
  isGroupControl?: boolean;
  /** 断连重试次数，默认 0（不重试） */
  retryCount?: number;
  /** 重试间隔（毫秒），默认 1000 */
  retryInterval?: number;
  /** 视频解码偏好 */
  videoCodecPreference?: "no-preference" | "prefer-hardware" | "prefer-software";
  /** 渲染性能偏好 */
  renderPreference?: "default" | "high-performance" | "low-power";
  /**
   * move 是否保留 hover 状态
   * 默认为 false
   */
  hoverMoveKeep?: boolean;
  /**
   * 滚轮灵敏度配置，通用灵敏度
   * 范围：0.001 - 800，值越大滚动越慢
   * 默认为 200
   */
  scrollSpeedRatio?: number;
}

字段说明

• config：设备连接配置，必填项
• container：DOM 容器元素，用于显示设备画面，必填项
• isGroupControl：是否开启群控模式，默认 false
• retryCount：断连重试次数，默认 0（不重试）
• retryInterval：重试间隔（毫秒），默认 1000
• videoCodecPreference：视频解码偏好
  • "no-preference"：无偏好（默认）
  • "prefer-hardware"：优先使用硬件解码
  • "prefer-software"：优先使用软件解码
• renderPreference：渲染性能偏好
  • "default"：默认模式
  • "high-performance"：高性能模式
  • "low-power"：低功耗模式
• hoverMoveKeep：move 事件是否保留 hover 状态，默认 false
  • false：move 事件不保留 hover 状态（默认）
  • true：move 事件保留 hover 状态
• scrollSpeedRatio：滚轮灵敏度配置，范围 0.001 - 800，值越大滚动越慢，默认 200

使用示例

const client = new VmosEdgeClient({
  container: document.getElementById("container")!,
  config: {
    ip: "192.168.1.100",
    deviceId: "EDGE418ASOC2LX9C",
    ports: {
      video: 9999,
      touch: 9997,
    },
  },
  retryCount: 3,
  retryInterval: 2000,
  hoverMoveKeep: true,
  scrollSpeedRatio: 100, // 设置滚轮灵敏度为 100（滚动更快）
});

VmosEdgeSizeChangedEvent

尺寸变化事件数据。

interface VmosEdgeSizeChangedEvent {
  /** 理想宽度（无白边时的建议容器宽度） */
  idealWidth: number;
  /** 理想高度（无白边时的建议容器高度） */
  idealHeight: number;
  /** 视频源实际宽度 */
  videoWidth: number;
  /** 视频源实际高度 */
  videoHeight: number;
  /** 当前旋转状态：0=竖屏, 1=横屏 */
  rotation: 0 | 1;
}

使用示例：

client.on(VmosEdgeClientEvents.SIZE_CHANGED, (size) => {
  console.log(`视频尺寸: ${size.videoWidth} x ${size.videoHeight}`);
  console.log(`理想容器尺寸: ${size.idealWidth} x ${size.idealHeight}`);
  console.log(`当前方向: ${size.rotation === 0 ? "竖屏" : "横屏"}`);
  
  // 可以根据 idealWidth/idealHeight 调整容器大小以消除黑边
  container.style.width = `${size.idealWidth}px`;
  container.style.height = `${size.idealHeight}px`;
});

VmosEdgeErrorEvent

错误事件数据。

interface VmosEdgeErrorEvent {
  /** 错误类型（VmosEdgeErrorType） */
  type: VmosEdgeErrorType;
  /** 错误代码（VmosEdgeErrorCode） */
  code: VmosEdgeErrorCode;
  /** 错误描述信息 */
  message: string;
  /** 发生错误的端口（如果有） */
  port?: number;
  /** 所有通道的连接状态（如果有） */
  allChannelsStatus?: AllChannelsStatus;
}

相关类型： AllChannelsStatus

使用示例：

client.on(VmosEdgeClientEvents.ERROR, (error) => {
  console.error(`错误类型: ${error.type}`);
  console.error(`错误代码: ${error.code}`);
  console.error(`错误信息: ${error.message}`);
  
  if (error.port) {
    console.error(`错误端口: ${error.port}`);
  }
});

VmosEdgeChannelConnectedEvent

通道连接成功事件数据。

interface VmosEdgeChannelConnectedEvent {
  /** 通道类型 */
  channel: "video" | "audio" | "touch";
  /** 通道端口 */
  port?: number;
  /** 所有通道的连接状态 */
  allChannelsStatus?: AllChannelsStatus;
}

相关类型： AllChannelsStatus

使用示例：

client.on(VmosEdgeClientEvents.CHANNEL_CONNECTED, (event) => {
  console.log(`${event.channel} 通道连接成功，端口: ${event.port}`);
  
  if (event.allChannelsStatus) {
    console.log("所有通道状态:", event.allChannelsStatus);
  }
});

AllChannelsStatus

所有通道的状态信息。

interface AllChannelsStatus {
  video: ChannelStatus;
  audio: ChannelStatus;
  touch: ChannelStatus;
}

相关类型： ChannelStatus

ChannelStatus

通道状态类型。

type ChannelStatus = "disconnected" | "connecting" | "connected" | "error";

相关类型： AllChannelsStatus