WebChat适配器API

WebChat适配器(webchat-adapter.js)是WebChatQQ的核心组件，负责处理消息转发、用户管理和群组映射等功能。本文档详细介绍了适配器的API及其使用方法。

适配器概述

WebChat适配器是一个Node.js模块，它通过WebSocket协议提供实时通信服务，实现了网页客户端与QQ群之间的消息互通。

主要职责

1. 管理WebSocket连接
2. 处理用户加入/离开群聊
3. 消息转发和存储
4. 群组映射管理
5. 文件传输和管理
6. 提供各种交互命令支持

类定义

class WebChatAdapter {
  id = "webchat";
  name = "网页群聊";
  path = "data/webchat/";
  port = 8088;
  clients = {};
  groups = {};
  historySize = 100;
  botName = "滢滢Bris";
  groupMappings = {};
  groupPasswords = {};
  
  // 添加管理员列表，只有管理员可以修改密码
  adminIds = ["admin"];
  
  // ...其他属性和方法
}

核心属性

属性名	类型	描述
id	String	适配器唯一标识符
name	String	适配器名称
path	String	数据存储路径
port	Number	WebSocket服务器端口
clients	Object	存储所有客户端连接信息
groups	Object	存储所有群组信息和历史记录
historySize	Number	每个群组保存的历史消息数量
botName	String	机器人名称
groupMappings	Object	网页群与QQ群的映射关系
groupPasswords	Object	群组密码配置
adminIds	Array	管理员ID列表

核心方法

配置管理

loadConfig()

加载配置文件，包括群映射和密码配置。

返回值: Promise<void>

示例:

await adapter.loadConfig();

saveConfig()

保存当前配置到文件。

返回值: Promise<void>

示例:

await adapter.saveConfig();

群组密码管理

setGroupPassword(groupId, password)

设置或更新群组密码。

参数:

• groupId (String): 群组ID
• password (String): 新密码，传入null或空字符串将移除密码

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

示例:

await adapter.setGroupPassword('1', 'mypassword123');

verifyGroupPassword(groupId, password)

验证群组密码是否正确。

参数:

• groupId (String): 群组ID
• password (String): 要验证的密码

返回值: boolean - 密码是否正确

示例:

const isValid = adapter.verifyGroupPassword('1', 'inputPassword');

消息发送

sendGroupMsg(data, msgYunzaiFormat)

向指定群组发送消息。

参数:

• data (Object): 包含群组ID的数据对象
• msgYunzaiFormat (Array|Object): 消息内容，支持文本和图片

返回值: Promise<Object> - 包含消息ID的对象

示例:

await adapter.sendGroupMsg(
  { group_id: '1' },
  [{ type: 'text', text: '你好，世界！' }]
);

broadcast(message)

向所有连接的客户端广播消息。

参数:

• message (Object): 要广播的消息对象

返回值: void

示例:

adapter.broadcast({ type: 'announcement', content: '服务器维护通知' });

broadcastToGroup(groupId, message)

向特定群组的所有成员广播消息。

参数:

• groupId (String): 群组ID
• message (Object): 要广播的消息对象

返回值: void

示例:

adapter.broadcastToGroup('1', {
  type: 'groupMsg',
  sender: { user_id: 'bot', nickname: '系统' },
  message: [{ type: 'text', data: { text: '欢迎加入群聊！' } }]
});

历史记录管理

saveGroupHistory(groupId, messageDetails)

保存消息到群组历史记录。

参数:

• groupId (String): 群组ID
• messageDetails (Object): 消息详情对象

返回值: Promise<void>

示例:

await adapter.saveGroupHistory('1', {
  type: 'groupMsg',
  time: Date.now(),
  msgId: 'msg123',
  sender: { user_id: 'user1', nickname: '用户1' },
  message: [{ type: 'text', data: { text: '你好！' } }]
});

事件处理

适配器通过WebSocket连接处理以下事件：

1. 连接事件: 客户端连接到服务器
2. 消息事件: 接收并处理客户端消息
3. 关闭事件: 处理客户端断开连接
4. 错误事件: 处理连接错误

使用示例

// 创建和初始化适配器
const adapter = new WebChatAdapter();
await adapter.load();

// 设置群组密码
await adapter.setGroupPassword('1', 'password123');

// 向群组发送消息
await adapter.sendGroupMsg(
  { group_id: '1' },
  [{ type: 'text', text: '系统通知：服务器将于明日维护' }]
);

// 关闭适配器
await adapter.shutdown();

高级功能

适配器还提供以下高级功能：

1. QQ头像代理: 处理QQ头像的获取和缓存
2. 群文件管理: 支持查看、下载和上传群文件
3. 戳一戳功能: 支持在QQ群中实现戳一戳交互
4. 群成员获取: 从QQ群获取成员列表和信息

有关这些高级功能的详细API，请参考相应的文档页面。