跳到主要内容
版本：1.5.0

WebSocket API 文档

WebSocket API 为 EasyBot 插件提供了完整的 WebSocket 客户端和服务端功能，支持实时双向通信。

WebSocket 客户端​

CreateClient()​

功能: 创建 WebSocket 客户端

语法: CreateClient(url: string, id?: string): string

参数:

  • url (string): WebSocket 服务器地址
  • id (string, 可选): 客户端ID，为空则自动生成

返回值: string - 客户端ID

示例:

const clientId = ws.CreateClient("ws://localhost:8080", "my-client");
logger.info("客户端ID:", clientId);

ConnectAsync()​

功能: 连接 WebSocket 服务器

语法: ConnectAsync(id: string): Promise<boolean>

参数:

  • id (string): 客户端ID

返回值: Promise<boolean> - 是否连接成功

示例:

const connected = await ws.ConnectAsync("my-client");
if (connected) {
    logger.info("连接成功");
}

DisconnectAsync()​

功能: 断开 WebSocket 连接

语法: DisconnectAsync(id: string): Promise<boolean>

参数:

  • id (string): 客户端ID

返回值: Promise<boolean> - 是否断开成功

示例:

const disconnected = await ws.DisconnectAsync("my-client");

SendTextAsync()​

功能: 发送文本消息

语法: SendTextAsync(id: string, message: string): Promise<boolean>

参数:

  • id (string): 客户端ID
  • message (string): 消息内容

返回值: Promise<boolean> - 是否发送成功

示例:

const sent = await ws.SendTextAsync("my-client", "Hello Server!");

SendBinaryAsync()​

功能: 发送二进制消息

语法: SendBinaryAsync(id: string, data: Uint8Array): Promise<boolean>

参数:

  • id (string): 客户端ID
  • data (Uint8Array): 二进制数据

返回值: Promise<boolean> - 是否发送成功

示例:

const binaryData = new Uint8Array([1, 2, 3, 4]);
const sent = await ws.SendBinaryAsync("my-client", binaryData);

SetMessageCallback()​

功能: 设置消息接收回调

语法: SetMessageCallback(id: string, callback: (message: string, data: Uint8Array | null) => void): boolean

参数:

  • id (string): 客户端ID
  • callback (function): 回调函数

返回值: boolean - 是否设置成功

示例:

ws.SetMessageCallback("my-client", (message, data) => {
    if (message) {
        logger.info("收到文本消息:", message);
    }
    if (data) {
        logger.info("收到二进制数据:", data);
    }
});

SetStateCallback()​

功能: 设置连接状态变化回调

语法: SetStateCallback(id: string, callback: (state: number) => void): boolean

参数:

  • id (string): 客户端ID
  • callback (function): 回调函数

返回值: boolean - 是否设置成功

示例:

ws.SetStateCallback("my-client", (state) => {
    logger.info("连接状态变化:", state);
});

GetClientState()​

功能: 获取客户端状态

语法: GetClientState(id: string): number

参数:

  • id (string): 客户端ID

返回值: number - 客户端状态

示例:

const state = ws.GetClientState("my-client");
logger.info("当前状态:", state);

DestroyClientAsync()​

功能: 销毁客户端

语法: DestroyClientAsync(id: string): Promise<boolean>

参数:

  • id (string): 客户端ID

返回值: Promise<boolean> - 是否销毁成功

示例:

const destroyed = await ws.DestroyClientAsync("my-client");

GetClientIds()​

功能: 获取所有客户端ID

语法: GetClientIds(): string[]

返回值: string[] - 客户端ID列表

示例:

const clientIds = ws.GetClientIds();
logger.info("所有客户端:", clientIds);

WebSocket 服务端​

CreateServer()​

功能: 创建 WebSocket 服务器

语法: CreateServer(port: number, id?: string, host?: string, path?: string): string

参数:

  • port (number): 监听端口
  • id (string, 可选): 服务器ID，为空则自动生成
  • host (string, 可选): 监听地址，默认为 localhost
  • path (string, 可选): 监听路径，默认为 "/"

返回值: string - 服务器ID

示例:

const serverId = ws.CreateServer(8080, "my-server", "localhost", "/ws");

StartServerAsync()​

功能: 启动 WebSocket 服务器

语法: StartServerAsync(id: string): Promise<boolean>

参数:

  • id (string): 服务器ID

返回值: Promise<boolean> - 是否启动成功

示例:

const started = await ws.StartServerAsync("my-server");

StopServerAsync()​

功能: 停止 WebSocket 服务器

语法: StopServerAsync(id: string): Promise<boolean>

参数:

  • id (string): 服务器ID

返回值: Promise<boolean> - 是否停止成功

示例:

const stopped = await ws.StopServerAsync("my-server");

SendToClientAsync()​

功能: 向指定客户端发送文本消息

语法: SendToClientAsync(serverId: string, clientId: string, message: string): Promise<boolean>

参数:

  • serverId (string): 服务器ID
  • clientId (string): 客户端ID
  • message (string): 消息内容

返回值: Promise<boolean> - 是否发送成功

示例:

const sent = await ws.SendToClientAsync("my-server", "client-123", "Hello Client!");

SendBinaryToClientAsync()​

功能: 向指定客户端发送二进制消息

语法: SendBinaryToClientAsync(serverId: string, clientId: string, data: Uint8Array): Promise<boolean>

参数:

  • serverId (string): 服务器ID
  • clientId (string): 客户端ID
  • data (Uint8Array): 二进制数据

返回值: Promise<boolean> - 是否发送成功

示例:

const data = new Uint8Array([5, 6, 7, 8]);
const sent = await ws.SendBinaryToClientAsync("my-server", "client-123", data);

BroadcastAsync()​

功能: 广播文本消息给所有客户端

语法: BroadcastAsync(serverId: string, message: string): Promise<boolean>

参数:

  • serverId (string): 服务器ID
  • message (string): 消息内容

返回值: Promise<boolean> - 是否发送成功

示例:

const sent = await ws.BroadcastAsync("my-server", "广播消息给所有客户端");

BroadcastBinaryAsync()​

功能: 广播二进制消息给所有客户端

语法: BroadcastBinaryAsync(serverId: string, data: Uint8Array): Promise<boolean>

参数:

  • serverId (string): 服务器ID
  • data (Uint8Array): 二进制数据

返回值: Promise<boolean> - 是否发送成功

示例:

const data = new Uint8Array([9, 10, 11, 12]);
const sent = await ws.BroadcastBinaryAsync("my-server", data);

SetConnectionCallback()​

功能: 设置客户端连接回调

语法: SetConnectionCallback(serverId: string, callback: (clientId: string) => void): boolean

参数:

  • serverId (string): 服务器ID
  • callback (function): 回调函数

返回值: boolean - 是否设置成功

示例:

ws.SetConnectionCallback("my-server", (clientId) => {
    logger.info("客户端连接:", clientId);
});

SetDisconnectionCallback()​

功能: 设置客户端断开连接回调

语法: SetDisconnectionCallback(serverId: string, callback: (clientId: string, status: number | null, description: string | null) => void): boolean

参数:

  • serverId (string): 服务器ID
  • callback (function): 回调函数

返回值: boolean - 是否设置成功

示例:

ws.SetDisconnectionCallback("my-server", (clientId, status, description) => {
    logger.info("客户端断开:", clientId, status, description);
});

SetServerMessageCallback()​

功能: 设置消息接收回调

语法: SetServerMessageCallback(serverId: string, callback: (clientId: string, message: string, data: Uint8Array | null) => void): boolean

参数:

  • serverId (string): 服务器ID
  • callback (function): 回调函数

返回值: boolean - 是否设置成功

示例:

ws.SetServerMessageCallback("my-server", (clientId, message, data) => {
    logger.info("收到消息来自:", clientId);
    if (message) logger.info("文本:", message);
    if (data) logger.info("二进制数据长度:", data.length);
});

IsServerRunning()​

功能: 获取服务器状态

语法: IsServerRunning(serverId: string): boolean

参数:

  • serverId (string): 服务器ID

返回值: boolean - 服务器是否运行中

示例:

if (ws.IsServerRunning("my-server")) {
    logger.info("服务器正在运行");
}

GetServerClients()​

功能: 获取服务器的客户端列表

语法: GetServerClients(serverId: string): string[]

参数:

  • serverId (string): 服务器ID

返回值: string[] - 客户端ID列表

示例:

const clients = ws.GetServerClients("my-server");
logger.info("连接的客户端:", clients);

DestroyServerAsync()​

功能: 销毁服务器

语法: DestroyServerAsync(serverId: string): Promise<boolean>

参数:

  • serverId (string): 服务器ID

返回值: Promise<boolean> - 是否销毁成功

示例:

const destroyed = await ws.DestroyServerAsync("my-server");

GetServerIds()​

功能: 获取所有服务器ID

语法: GetServerIds(): string[]

返回值: string[] - 服务器ID列表

示例:

const serverIds = ws.GetServerIds();
logger.info("所有服务器:", serverIds);

使用示例​

WebSocket 客户端示例​

// 创建并连接客户端
const clientId = ws.CreateClient("ws://localhost:8080");

// 设置回调
ws.SetMessageCallback(clientId, (message, data) => {
    logger.info("收到消息:", message);
});

ws.SetStateCallback(clientId, (state) => {
    logger.info("连接状态:", state);
});

// 连接服务器
const connected = await ws.ConnectAsync(clientId);
if (connected) {
    // 发送消息
    await ws.SendTextAsync(clientId, "Hello Server!");
}

WebSocket 服务端示例​

// 创建并启动服务器
const serverId = ws.CreateServer(8080, "chat-server");

// 设置回调
ws.SetConnectionCallback(serverId, (clientId) => {
    logger.info("新客户端连接:", clientId);
    ws.SendToClientAsync(serverId, clientId, "欢迎连接!");
});

ws.SetServerMessageCallback(serverId, (clientId, message, data) => {
    logger.info(`客户端 ${clientId} 发送:`, message);
    // 广播给所有客户端
    ws.BroadcastAsync(serverId, `${clientId}: ${message}`);
});

ws.SetDisconnectionCallback(serverId, (clientId) => {
    logger.info("客户端断开:", clientId);
});

// 启动服务器
await ws.StartServerAsync(serverId);

聊天室示例​

// 创建聊天服务器
const chatServer = ws.CreateServer(9000, "chat-room");

// 存储客户端信息
const clients = new Map<string, { name: string }>();

ws.SetConnectionCallback(chatServer, (clientId) => {
    clients.set(clientId, { name: `用户${clientId.slice(-4)}` });
    
    // 通知其他用户有新用户加入
    const joinMessage = `${clients.get(clientId)?.name} 加入了聊天室`;
    ws.BroadcastAsync(chatServer, joinMessage);
});

ws.SetServerMessageCallback(chatServer, (clientId, message) => {
    const client = clients.get(clientId);
    if (client && message) {
        // 广播聊天消息
        const chatMessage = `${client.name}: ${message}`;
        ws.BroadcastAsync(chatServer, chatMessage);
    }
});

ws.SetDisconnectionCallback(chatServer, (clientId) => {
    const client = clients.get(clientId);
    if (client) {
        const leaveMessage = `${client.name} 离开了聊天室`;
        ws.BroadcastAsync(chatServer, leaveMessage);
        clients.delete(clientId);
    }
});

await ws.StartServerAsync(chatServer);
logger.info("聊天室服务器已启动在端口 9000");

注意事项​

  1. 异步操作: 连接、发送、断开等操作都是异步的
  2. 状态管理: 注意检查连接状态再进行操作
  3. 资源清理: 使用完毕后记得销毁客户端和服务器
  4. 错误处理: 对异步操作进行适当的错误处理
  5. 端口冲突: 确保服务器端口未被占用
  6. 权限要求: 监听所有网络接口可能需要管理员权限

最佳实践​

  • 使用有意义的ID便于管理
  • 设置适当的回调函数处理各种事件
  • 在插件卸载时清理所有WebSocket资源
  • 对消息进行适当的验证和处理
  • 考虑连接重试机制提高稳定性
Copyright © 2024-2025 易栈