跳到主要内容

IAdapterContext - 适配器上下文

适配器上下文接口提供与即时通讯平台交互的核心功能，是所有适配器都必须实现的通用接口。

卡死线程问题

该接口由于部分实现端存在差异问题，如果你尝试使用await等待异步返回结果，可能会出现卡死线程的问题，请谨慎使用！

接口定义​

declare interface IAdapterContext {
    // 消息发送
    SendGroupMessageAsync(selfId: string, peerId: string, chain: MessageChain, token?: any): Promise<string>;
    SendDirectMessageAsync(selfId: string, peerId: string, chain: MessageChain, token?: any): Promise<string>;
    
    // 用户信息
    GetUserProfileAsync(selfId: string, userId: string, token?: any): Promise<UserProfile>;
    GetGroupMemberInfo(groupId: string, userId: string, token?: any): Promise<MemberInfo>;
    GetGroupMemberList(groupId: string, token?: any): Promise<ArrayLike<MemberInfo>>;
    
    // 群组操作
    GetGroupName(groupId: string, noCache?: boolean, any?: any): Promise<string>;
    SetNickName(slefId: string, userId: string, groupId: string, nickName: string, token?: any): Promise<void>;
    SetGroupAddRequest(flag: string, isInvite: boolean, approve: boolean, reason?: string): Promise<void>;
    KickMember(groupId: string, userId: string, rejectAddRequest?: boolean): Promise<void>;
    SetMute(groupId: string, userId: string, duration: number): Promise<void>;
    
    // 消息操作
    DeleteMessage(messageId: string): Promise<void>;
    
    // 原生操作
    SendRaw(data: string): Promise<void>;
}

消息发送方法​

SendGroupMessageAsync()​

发送群组消息。

语法: SendGroupMessageAsync(selfId: string, peerId: string, chain: MessageChain, token?: any): Promise<string>

参数:

  • selfId - 机器人账号ID
  • peerId - 目标群组ID
  • chain - 消息链对象
  • token - 可选取消令牌

返回值: 返回消息ID的Promise

示例:

const messageId = await context.SendGroupMessageAsync(
    "bot123", 
    "group456", 
    new MessageChain().Text("Hello Group!")
);
logger.info(`消息已发送，ID: ${messageId}`);

SendDirectMessageAsync()​

发送私聊消息。

语法: SendDirectMessageAsync(selfId: string, peerId: string, chain: MessageChain, token?: any): Promise<string>

参数:

  • selfId - 机器人账号ID
  • peerId - 目标用户ID
  • chain - 消息链对象
  • token - 可选取消令牌

返回值: 返回消息ID的Promise

示例:

const messageId = await context.SendDirectMessageAsync(
    "bot123", 
    "user789", 
    new MessageChain().Text("Hello User!")
);

用户信息方法​

GetUserProfileAsync()​

获取用户资料。

语法: GetUserProfileAsync(selfId: string, userId: string, token?: any): Promise<UserProfile>

参数:

  • selfId - 机器人账号ID
  • userId - 目标用户ID
  • token - 可选取消令牌

返回值: 返回用户资料的Promise

示例:

const profile = await context.GetUserProfileAsync("bot123", "user789");
logger.info(`用户: ${profile.Name} (${profile.Id})`);

GetGroupMemberInfo()​

获取群成员信息。

语法: GetGroupMemberInfo(groupId: string, userId: string, token?: any): Promise<MemberInfo>

参数:

  • groupId - 目标群组ID
  • userId - 目标成员ID
  • token - 可选取消令牌

返回值: 返回成员信息的Promise

示例:

const member = await context.GetGroupMemberInfo("group456", "user789");
logger.info(`${member.NickName} 的角色是 ${member.Role}`);

GetGroupMemberList()​

获取群成员列表。

语法: GetGroupMemberList(groupId: string, token?: any): Promise<ArrayLike<MemberInfo>>

参数:

  • groupId - 目标群组ID
  • token - 可选取消令牌

返回值: 返回成员信息列表的Promise

示例:

const members = await context.GetGroupMemberList("group456");
logger.info(`群组共有 ${members.length} 个成员`);

群组操作方法​

GetGroupName()​

获取群名称。

语法: GetGroupName(groupId: string, noCache?: boolean, any?: any): Promise<string>

参数:

  • groupId - 目标群组ID
  • noCache - 是否禁用缓存
  • any - 可选取消令牌

返回值: 返回群名称的Promise

示例:

const groupName = await context.GetGroupName("group456");
logger.info(`群名称: ${groupName}`);

SetNickName()​

设置群成员昵称。

语法: SetNickName(slefId: string, userId: string, groupId: string, nickName: string, token?: any): Promise<void>

参数:

  • slefId - 机器人账号ID（注意参数名拼写）
  • userId - 目标成员ID
  • groupId - 目标群组ID
  • nickName - 新昵称
  • token - 可选取消令牌

返回值: 无返回值的Promise

示例:

await context.SetNickName("bot123", "user789", "group456", "新昵称");

SetGroupAddRequest()​

处理群组加群请求。

语法: SetGroupAddRequest(flag: string, isInvite: boolean, approve: boolean, reason?: string): Promise<void>

参数:

  • flag - 请求标识符
  • isInvite - 是否为邀请请求
  • approve - 是否批准请求
  • reason - 拒绝理由（可选）

返回值: 无返回值的Promise

示例:

// 批准加群请求
await context.SetGroupAddRequest("request123", false, true);

// 拒绝加群请求
await context.SetGroupAddRequest("request456", false, false, "不符合入群条件");

KickMember()​

踢出群成员。

语法: KickMember(groupId: string, userId: string, rejectAddRequest?: boolean): Promise<void>

参数:

  • groupId - 目标群组ID
  • userId - 目标成员ID
  • rejectAddRequest - 是否拒绝再次加群请求（可选）

返回值: 无返回值的Promise

示例:

await context.KickMember("group456", "user789", true);

SetMute()​

禁言群成员。

语法: SetMute(groupId: string, userId: string, duration: number): Promise<void>

参数:

  • groupId - 目标群组ID
  • userId - 目标成员ID
  • duration - 禁言时长（秒）

返回值: 无返回值的Promise

示例:

// 禁言10分钟
await context.SetMute("group456", "user789", 600);

// 解除禁言
await context.SetMute("group456", "user789", 0);

消息操作方法​

DeleteMessage()​

撤回消息。

语法: DeleteMessage(messageId: string): Promise<void>

参数:

  • messageId - 目标消息ID

返回值: 无返回值的Promise

示例:

await context.DeleteMessage("msg123");

原生操作方法​

SendRaw()​

发送原生数据包。

语法: SendRaw(data: string): Promise<void>

参数:

  • data - 原生数据包

返回值: 无返回值的Promise

示例:

const rawData = JSON.stringify({
    action: "custom_action",
    params: { key: "value" }
});
await context.SendRaw(rawData);

使用示例​

群组管理机器人​

// 处理群消息事件
bus.on("group_message_event", async (event) => {
    const { AdapterContext: context, SelfId, PeerId, SenderId, RawMessage } = event;
    
    if (RawMessage === "/群信息") {
        const groupName = await context.GetGroupName(PeerId);
        const members = await context.GetGroupMemberList(PeerId);
        
        const reply = new MessageChain()
            .Text(`群名称: ${groupName}`)
            .NextLine()
            .Text(`成员数量: ${members.length}`);
            
        await context.SendGroupMessageAsync(SelfId, PeerId, reply);
    }
});

注意事项​

  1. 异步操作: 所有方法都返回 Promise，需要使用 await
  2. 错误处理: 建议使用 try-catch 处理可能的异常
  3. 权限检查: 某些操作需要机器人具有相应权限
  4. 参数拼写: 注意 SetNickName 方法中的 slefId 参数拼写
  5. 平台差异: 不同适配器可能对某些功能有不同的实现
Copyright © 2024-2025 易栈