Vmos Edge Web SDK

📖 简介

Vmos Edge Web SDK 是一个用于在 Web 浏览器中远程控制 Android 设备的 JavaScript/TypeScript SDK。它提供了视频流渲染、触控事件处理、按键控制、文本输入等功能，让您可以在网页中实时查看和控制 Android 设备。

⚠️ 注意：当前版本暂不支持音频流传输，仅支持视频流和触控控制。

主要特性

• ✅ 实时视频流：支持 WebGL/Canvas 2D 渲染，自动适配最佳性能
• ✅ 低延迟控制：优化的触控事件处理，支持多点触控
• ✅ 设备控制：支持按键、文本输入、剪贴板同步
• ✅ 群控功能：支持同时控制多台设备
• ✅ 事件系统：完善的生命周期和错误处理事件
• ✅ TypeScript 支持：完整的类型定义，提供良好的开发体验

---

📦 安装

npm

npm install @vmosedge/web-sdk

pnpm

pnpm add @vmosedge/web-sdk

yarn

yarn add @vmosedge/web-sdk

---

⚠️ 重要限制说明

🔴 使用环境限制

SDK 目前仅支持以下环境：

• 本地文件协议 file://
• localhost 或 127.0.0.1

⚠️ 不支持 HTTP 和 HTTPS 协议（localhost 除外）

SDK 目前仅支持在本地文件协议（file://）或 localhost 环境下运行。推荐使用 file:// 协议直接打开 HTML 文件，或通过 localhost 访问本地 Web 服务器。

💡 使用方式：

• 方式一（推荐）：在本地创建 HTML 文件，直接在浏览器中打开（file:// 协议）
• 方式二：通过本地 Web 服务器访问，使用 localhost 或 127.0.0.1
• 确保设备端 WebSocket 服务支持 WS 协议连接

🌟 推荐方案：使用桌面应用框架

为了更好的用户体验和功能集成，强烈推荐在客户端应用中使用以下桌面应用框架：

• Electron - 使用 Web 技术构建跨平台桌面应用
• Tauri - 使用 Rust 和 Web 前端构建轻量级桌面应用
• 其他支持 WebView 的桌面应用框架

优势：

• ✅ 可以完全控制运行环境，确保 SDK 正常工作
• ✅ 可以集成更多原生功能（文件系统、系统通知等）
• ✅ 更好的性能和用户体验
• ✅ 可以打包成独立的桌面应用程序
• ✅ 避免浏览器安全策略限制

在这些框架中，SDK 可以正常运行，因为它们提供了类似 file:// 或 localhost 的安全上下文环境。

---

🚀 快速开始

环境检测（推荐）

在使用 SDK 之前，建议先检测当前环境是否支持：

import { VmosEdgeClient } from "@vmosedge/web-sdk";

if (!VmosEdgeClient.isWebCodecsSupported()) {
  console.error("当前环境不支持 SDK 使用");
  console.error("请使用 file:// 协议打开 HTML 文件，或通过 localhost 访问");
  return;
}

// 环境支持，可以继续使用 SDK

最简单的使用示例

局域网模式

import { VmosEdgeClient, VmosEdgeClientEvents } from "@vmosedge/web-sdk";

// 0. 环境检测（推荐）
if (!VmosEdgeClient.isWebCodecsSupported()) {
  console.error("当前环境不支持 SDK 使用，请使用 file:// 协议打开 HTML 文件，或通过 localhost 访问");
  return;
}

// 1. 准备一个 DOM 容器（用于显示设备画面）
const container = document.getElementById("device-container");

// 2. 创建客户端实例（局域网模式：network_mode === 'macvlan'）
const client = new VmosEdgeClient({
  container: container!,
  config: {
    ip: "192.168.1.100",        // 使用设备的 ip 字段
    deviceId: "EDGE418ASOC2LX9C",  // 使用设备的 dbid 字段
    ports: {
      video: 9999,              // 局域网模式固定端口
      touch: 9997,              // 局域网模式固定端口
    },
  },
});

// 3. 监听连接成功事件
client.on(VmosEdgeClientEvents.STARTED, () => {
  console.log("设备连接成功！");
});

// 4. 启动连接
client.start();

非局域网模式

import { VmosEdgeClient, VmosEdgeClientEvents } from "@vmosedge/web-sdk";

// 0. 环境检测（推荐）
if (!VmosEdgeClient.isWebCodecsSupported()) {
  console.error("当前环境不支持 SDK 使用，请使用 file:// 协议打开 HTML 文件，或通过 localhost 访问");
  return;
}

// 1. 准备一个 DOM 容器（用于显示设备画面）
const container = document.getElementById("device-container");

// 2. 创建客户端实例（非局域网模式）
const client = new VmosEdgeClient({
  container: container!,
  config: {
    ip: "example.com",          // 使用设备的 hostip 字段
    deviceId: "EDGE418ASOC2LX9C",  // 使用设备的 dbid 字段
    ports: {
      video: 22003,             // 使用设备的 tcp_port 字段
      touch: 24003,             // 使用设备的 tcp_control_port 字段
    },
  },
});

// 3. 监听连接成功事件
client.on(VmosEdgeClientEvents.STARTED, () => {
  console.log("设备连接成功！");
});

// 4. 启动连接
client.start();

配置说明

• deviceId：对应设备信息中的 dbid 字段
• ip：
  • 局域网模式（network_mode === 'macvlan'）：使用设备的 ip 字段
  • 非局域网模式：使用设备的 hostip 字段
• ports.video：
  • 局域网模式：固定为 9999
  • 非局域网模式：使用设备的 tcp_port 字段
• ports.touch：
  • 局域网模式：固定为 9997
  • 非局域网模式：使用设备的 tcp_control_port 字段

---

📚 导入导出说明

完整导入列表

SDK 提供了以下导出内容，您可以根据需要选择性导入：

1. 核心类

import { VmosEdgeClient } from "@vmosedge/web-sdk";

// 使用静态方法进行环境检测
VmosEdgeClient.isWebCodecsSupported();

2. 配置类型（TypeScript 类型，用于类型检查）

import type {
  VmosEdgeClientConfig,           // 设备连接配置
  VmosEdgeClientOptions,           // 客户端初始化选项
  VmosEdgeSizeChangedEvent,        // 尺寸变化事件数据
  VmosEdgeErrorEvent,              // 错误事件数据
  VmosEdgeChannelConnectedEvent,   // 通道连接事件数据
  VmosEdgeClientEventMap,          // 事件映射表（高级用法）
  VmosEdgeClientEventListener,     // 事件监听器类型（高级用法）
  VmosEdgeClientEventName,         // 事件名称类型（高级用法）
  ChannelStatus,                   // 通道状态类型
  AllChannelsStatus,               // 所有通道状态类型
} from "@vmosedge/web-sdk";

类型详情：

• VmosEdgeClientConfig - 设备连接配置
• VmosEdgeClientOptions - 客户端初始化选项
• VmosEdgeSizeChangedEvent - 尺寸变化事件数据
• VmosEdgeErrorEvent - 错误事件数据
• VmosEdgeChannelConnectedEvent - 通道连接事件数据
• ChannelStatus - 通道状态类型
• AllChannelsStatus - 所有通道状态类型

3. 枚举和常量（运行时值）

import {
  VmosEdgeClientEvents,    // 事件名称枚举
  VmosEdgeErrorCode,       // 错误代码枚举
  VmosEdgeErrorType,       // 错误类型枚举
} from "@vmosedge/web-sdk";

枚举详情：

• VmosEdgeClientEvents - 事件名称枚举
• VmosEdgeErrorCode - 错误代码枚举
• VmosEdgeErrorType - 错误类型枚举

4. Android 控制相关枚举

import {
  AndroidKeyCode,              // Android 按键码枚举
  AndroidKeyEventAction,       // 按键动作枚举（按下/抬起）
  AndroidMotionEventAction,    // 触摸动作枚举
  AndroidMotionEventButton,    // 触摸按钮枚举
  AndroidMetaState,            // 元键状态枚举（Shift/Ctrl/Alt 等）
} from "@vmosedge/web-sdk";

枚举详情：

• AndroidKeyCode - Android 按键码枚举
• AndroidKeyEventAction - 按键动作枚举
• AndroidMetaState - 元键状态枚举

常用导入组合

基础使用（推荐）

import {
  VmosEdgeClient,
  VmosEdgeClientEvents,
  type VmosEdgeClientConfig,
  type VmosEdgeErrorEvent,
} from "@vmosedge/web-sdk";

完整导入（需要所有功能）

import {
  VmosEdgeClient,
  VmosEdgeClientEvents,
  VmosEdgeErrorCode,
  VmosEdgeErrorType,
  AndroidKeyCode,
  AndroidKeyEventAction,
  type VmosEdgeClientConfig,
  type VmosEdgeClientOptions,
  type VmosEdgeErrorEvent,
  type VmosEdgeSizeChangedEvent,
} from "@vmosedge/web-sdk";

---

📖 文档导航

• 使用示例 - Vue、React、原生 JavaScript 示例
• API 参考 - 完整的 API 方法说明
• 类型定义 - 所有 TypeScript 类型定义
• 事件说明 - 事件系统使用指南
• Android 按键码 - Android 按键码参考
• 错误码说明 - 错误码和错误处理
• 常见问题 - FAQ 和故障排除
• 更新日志 - 版本更新历史