Hooks

ℹ️INFO

hook 在 response 中会自动劫持 event 上下文,也可显式传入,特别是非 response 上下文中调用。通过 useEvent 可获取当前事件和 next 回调。

useMessage

消息发送、删除、编辑、置顶等操作

src/response/**/*/res.ts
import { useEvent, useMessage, Format } from 'alemonjs'
export default async () => {
  const [event] = useEvent()
  const [message] = useMessage()

  // 发送消息
  const format = Format.create().addText('hello word')
  message.send({ format })

  // 删除消息
  await message.delete({ messageId: event.current.MessageId })

  // 编辑消息
  await message.edit({
    format: Format.create().addText('edited'),
    messageId: event.current.MessageId
  })

  // 置顶 / 取消置顶
  await message.pin({ messageId: event.current.MessageId })
  await message.unpin({ messageId: event.current.MessageId })

  // 获取消息详情
  const detail = await message.get({ messageId: event.current.MessageId })
}
方法参数说明
send{ format, replyId? }DataEnums[]发送消息
delete{ messageId? }删除消息
edit{ format, messageId? }编辑消息
pin{ messageId? }置顶消息
unpin{ messageId? }取消置顶
get{ messageId? }获取消息详情

useMention

解析得到被提及(@)的数据

response/**/*/res.ts
import { useMention } from 'alemonjs'
export default async () => {
  const [mention] = useMention()
  // 查找用户类型的 @ 提及,默认排除 bot
  const user = await mention.findOne()
  if (!user.count || !user.data) {
    return // 未找到用户
  }
  console.log('User:', user)
}

find 返回所有匹配的提及用户数组,findOne 返回第一个匹配用户。

支持的过滤选项:

选项类型说明
UserIdstring按用户ID过滤
UserKeystring按用户Key过滤
UserNamestring按用户名过滤
IsMasterboolean是否为主人
IsBotboolean是否为机器人(默认排除)

useSubscribe

订阅模式,在某个事件周期中进行观察

response/**/*/res.ts
import { Format, useMessage, useSubscribe } from 'alemonjs'

export default () => {
  const [message] = useMessage()
  const [subscribe] = useSubscribe(['message.create', 'private.message.create'])

  message.send({
    format: Format.create().addText('请输入密码')
  })

  // 订阅 res 挂载之前的事件
  const sub = subscribe.mount(
    (event, next) => {
      const [message] = useMessage(event)
      const text = event.MessageText

      if (text === '123456') {
        message.send({
          format: Format.create().addText('密码正确')
        })
        clearTimeout(timeout)
      } else if (text == '/close') {
        message.send({
          format: Format.create().addText('取消登录')
        })
        clearTimeout(timeout)
      } else {
        message.send({
          format: Format.create().addText('密码不正确')
        })
        // 保持订阅
        next()
      }
    },
    ['UserId']
  )

  const timeout = setTimeout(() => {
    subscribe.cancel(sub)
    message.send({
      format: Format.create().addText('登录超时')
    })
  }, 1000 * 10)
}

订阅时机

useSubscribe 提供三种订阅时机:

方法说明
subscribe.create(callback, keys)在响应体创建时触发
subscribe.mount(callback, keys)在中间件之后、响应之前触发
subscribe.unmount(callback, keys)在响应之后触发
subscribe.cancel(sub)取消订阅

keys 参数指定用于匹配事件的字段名(如 ['UserId']),只有这些字段值相同的事件才会触发订阅回调。

next 控制

订阅回调中的 next 行为:

- `next()` — 保持订阅
- `next(true)` — 保持订阅且传递给下一个订阅
- `next(true, true)` — 保持订阅且传递给下一个周期

useMember

成员管理:查询、踢出、封禁、禁言、名片等

response/**/*/res.ts
import { useEvent, useMember } from 'alemonjs'
export default async () => {
  const [event] = useEvent()
  const [member] = useMember()

  // 获取成员信息
  const info = await member.info({ userId: event.current.UserId })

  // 获取成员列表
  const list = await member.list({ guildId: event.current.GuildId })

  // 搜索成员
  const result = await member.search({ keyword: '管理' })

  // 踢出成员
  await member.kick({ userId: '123' })

  // 封禁 / 解封
  await member.ban({ userId: '123', reason: '违规', duration: 3600 })
  await member.unban({ userId: '123' })

  // 禁言(秒),0 = 解除
  await member.mute({ userId: '123', duration: 60 })

  // 设置管理员
  await member.admin({ userId: '123', enable: true })

  // 设置名片
  await member.card({ userId: '123', card: '新昵称' })

  // 设置专属头衔
  await member.title({ userId: '123', title: 'VIP', duration: -1 })
}
方法参数说明
info{ userId, guildId? }获取成员信息
list{ guildId?, pagination? }获取成员列表
search{ keyword, guildId?, limit? }搜索成员
kick{ userId, guildId? }踢出成员
ban{ userId, guildId?, reason?, duration? }封禁成员
unban{ userId, guildId? }解封成员
mute{ userId, duration, guildId? }禁言成员
admin{ userId, enable, guildId? }设置管理员
card{ userId, card, guildId? }设置名片
title{ userId, title, guildId?, duration? }设置专属头衔

useChannel

频道管理:查询、创建、更新、删除

response/**/*/res.ts
import { useEvent, useChannel } from 'alemonjs'
export default async () => {
  const [event] = useEvent()
  const [channel] = useChannel()

  // 获取频道信息
  const info = await channel.info({ channelId: event.current.ChannelId })

  // 获取频道列表
  const list = await channel.list({ guildId: event.current.GuildId })

  // 创建频道
  await channel.create({ name: '新频道', guildId: event.current.GuildId })

  // 更新频道
  await channel.update({
    channelId: event.current.ChannelId,
    name: '改名',
    topic: '新话题'
  })

  // 删除频道
  await channel.delete({ channelId: event.current.ChannelId })
}
方法参数说明
info{ channelId? }获取频道信息
list{ guildId? }获取频道列表
create{ name, type?, parentId?, guildId? }创建频道
update{ channelId, name?, topic?, position? }更新频道
delete{ channelId }删除频道

useGuild

服务器/公会管理

response/**/*/res.ts
import { useEvent, useGuild } from 'alemonjs'
export default async () => {
  const [event] = useEvent()
  const [guild] = useGuild()

  // 获取服务器信息
  const info = await guild.info({ guildId: event.current.GuildId })

  // 获取服务器列表
  const list = await guild.list()

  // 更新服务器设置
  await guild.update({ name: '新名称' })

  // 退出服务器
  await guild.leave({ guildId: event.current.GuildId })

  // 全员禁言
  await guild.mute({ enable: true })
}
方法参数说明
info{ guildId? }获取服务器信息
list获取服务器列表
update{ name?, guildId? }更新服务器设置
leave{ guildId?, isDismiss? }退出/解散服务器
mute{ enable, guildId? }全员禁言

useRole

角色管理:创建、更新、删除、分配、移除

response/**/*/res.ts
import { useEvent, useRole } from 'alemonjs'
export default async () => {
  const [event] = useEvent()
  const [role] = useRole()

  // 获取角色列表
  const list = await role.list({ guildId: event.current.GuildId })

  // 创建角色
  const created = await role.create({ name: 'VIP', color: 0xff0000 })

  // 更新角色
  await role.update({ roleId: '123', name: '超级VIP' })

  // 删除角色
  await role.delete({ roleId: '123' })

  // 分配 / 移除角色
  await role.assign({ userId: event.current.UserId, roleId: '123' })
  await role.remove({ userId: event.current.UserId, roleId: '123' })
}
方法参数说明
list{ guildId? }获取角色列表
create{ name, color?, permissions?, guildId? }创建角色
update{ roleId, name?, color?, permissions?, guildId? }更新角色
delete{ roleId, guildId? }删除角色
assign{ userId, roleId, guildId? }分配角色
remove{ userId, roleId, guildId? }移除角色

useReaction

表情回应管理

response/**/*/res.ts
import { useEvent, useReaction } from 'alemonjs'
export default async () => {
  const [event] = useEvent()
  const [reaction] = useReaction()

  // 添加表情回应
  await reaction.add({ emojiId: '👍' })

  // 移除表情回应
  await reaction.remove({ emojiId: '👍', messageId: event.current.MessageId })

  // 获取回应用户列表
  const list = await reaction.list({ emojiId: '👍', limit: 20 })
}
方法参数说明
add{ emojiId, messageId? }添加表情回应
remove{ emojiId, messageId? }移除表情回应
list{ emojiId, messageId?, limit? }获取回应用户列表

useMe

获取当前 Bot 自身信息

response/**/*/res.ts
import { useMe } from 'alemonjs'
export default async () => {
  const [me] = useMe()

  const info = await me.info()
  const guilds = await me.guilds()
  const threads = await me.threads()
  const friends = await me.friends()
}
方法说明
info获取 Bot 个人信息
guilds获取加入的服务器列表
threads获取私聊线程列表
friends获取好友列表

useUser

用户信息查询(无需服务器上下文)

response/**/*/res.ts
import { useEvent, useUser } from 'alemonjs'
export default async () => {
  const [event] = useEvent()
  const [user] = useUser()
  const info = await user.info({ userId: event.current.UserId })
}
方法参数说明
info{ userId }获取用户信息

useRequest

处理好友请求、入群请求等

response/**/*/res.ts
import { useRequest } from 'alemonjs'
export default async () => {
  const [request] = useRequest()

  // 同意好友请求
  await request.friend({ flag: 'xxx', approve: true, remark: '备注' })

  // 同意入群请求
  await request.guild({ flag: 'xxx', subType: 'add', approve: true })
}
方法参数说明
friend{ flag, approve, remark? }处理好友请求
guild{ flag, subType, approve, reason? }处理入群/服务器请求

useMedia

媒体管理:上传、发送图片/音频/视频/文件

response/**/*/res.ts
import { useMedia } from 'alemonjs'
export default async () => {
  const [media] = useMedia()

  // 上传媒体(仅上传,不发送)
  await media.upload({ type: 'image', url: 'https://example.com/img.png' })

  // 发送媒体到频道
  await media.sendChannel({ type: 'image', url: 'https://example.com/img.png' })

  // 发送媒体到用户
  await media.sendUser({
    userId: '123',
    type: 'audio',
    url: 'https://example.com/a.mp3'
  })
}
方法参数说明
upload{ type, url?, data?, name? }上传媒体文件
sendChannel{ type, url?, data?, name?, channelId? }发送到频道
sendUser{ userId, type, url?, data?, name? }发送到用户

type 可选值:'image' | 'audio' | 'video' | 'file'

useHistory

消息历史记录

response/**/*/res.ts
import { useEvent, useHistory } from 'alemonjs'
export default async () => {
  const [event] = useEvent()
  const [history] = useHistory()
  const messages = await history.list({
    limit: 50,
    before: event.current.MessageId
  })
}
方法参数说明
list{ channelId?, limit?, before?, after? }获取消息历史

usePermission

频道权限管理

response/**/*/res.ts
import { useEvent, usePermission } from 'alemonjs'
export default async () => {
  const [event] = useEvent()
  const [permission] = usePermission()

  // 获取权限
  const perm = await permission.get({ userId: event.current.UserId })

  // 设置权限
  await permission.set({ userId: event.current.UserId, allow: '1', deny: '0' })
}
方法参数说明
get{ userId, channelId? }获取权限
set{ userId, allow?, deny?, channelId? }设置权限

useAnnounce

频道公告管理

response/**/*/res.ts
import { useEvent, useAnnounce } from 'alemonjs'
export default async () => {
  const [event] = useEvent()
  const [announce] = useAnnounce()

  // 设置公告
  await announce.set({ messageId: event.current.MessageId })

  // 删除公告
  await announce.remove({ messageId: event.current.MessageId })
}
方法参数说明
set{ messageId, channelId?, guildId? }设置公告
remove{ messageId?, guildId? }删除公告

useClient

映射平台原生接口类,用于调用平台特有 API

src/response/**/*/res.ts
import { API, platform } from '@alemonjs/qq-bot'
import { useEvent, useClient } from 'alemonjs'
export default () => {
  const [event] = useEvent()
  if (event.current.Platform === platform) {
    const [client] = useClient(API)
    client.usersMe()
  }
}