@grammyjs/chat-members

中文文档
1.2.0发布于 2025/03/06MITTypeScriptCommonJS零依赖近 30 天下载 1.3万

GrammY 聊天成员插件

中文使用文档
文档目录5 节
  1. 使用量
  2. 聊天成员过滤器
  3. 储存聊天成员
  4. 阅读聊天成员信息
  5. 主动存储

聊天成员插件 对于格莱姆Y

此插件使其易于工作 ChatMember 对象,通过提供方便的听取自定义过滤器形式变化的方法,并通过存储和更新对象.

使用量

聊天成员过滤器

你可以听两种关于用电报机聊天的更新: chat_member 财务报告和审定财务报表 my_chat_member,它们都具体说明用户的新旧状况.

  • my_chat_member 更新由您的机器人默认接收,它们会通知您在任何聊天中更新的机器人状态,以及屏蔽该机器人的用户;
  • chat_member 只有您在允许的更新列表中明确包含更新内容,才会收到更新信息,它们会通知聊天中用户的任何状态变化 你的机器人是管理者。 。 。 .

过滤器指定了更改前后的状态,允许您对所感兴趣的每一种过渡类型作出反应. 在处理者内部,类型 old_chat_member 财务报告和审定财务报表 new_chat_member 将相应更新.

const bot = new Bot(process.env.BOT_TOKEN!);
const groups = bot.chatType(["group", "supergroup"]);

groups.filter(myChatMemberFilter("out", "regular"), async (ctx) => {
  await ctx.reply("Hello, thank you for adding me to the group!");
});

groups.filter(myChatMemberFilter("out", "admin"), async (ctx) => {
  await ctx.reply("Hello, thank you for adding me to the group as admin!");
});

groups.filter(myChatMemberFilter("regular", "admin"), async (ctx) => {
  await ctx.reply("I was promoted to admin!");
});

groups.filter(myChatMemberFilter("admin", "regular"), async (ctx) => {
  await ctx.reply("I am no longer admin");
});

groups.filter(chatMemberFilter("out", "in"), async (ctx) => {
  const user = ctx.chatMember.new_chat_member.user;
  await ctx.reply(
    `Welcome <b>${escapeHtml(user.first_name)}</> to the group!`,
    { parse_mode: "HTML" },
  );
});

bot.start({
  allowed_updates: [...API_CONSTANTS.DEFAULT_UPDATE_TYPES, "chat_member"],
  onStart: (me) => console.log("Listening to updates as", me.username),
});

过滤器包括常规的Telegram状态(所有者、管理员、成员、限制、左侧、踢出)和一些额外的状态,以方便:

  • 受限 in: 有限制的聊天成员;
  • 限制 出:不是聊天成员,有限制;
  • 在:聊天成员(管理员、创作者、成员、限制 in);
  • 出局:不是聊天成员(左侧、被踢出、被限制出局);
  • 自由:不受限制的聊天成员(管理者、创作者、成员);
  • 管理员:聊天管理员(管理员、创建者);
  • 经常:聊天的非管理员成员(成员,限制 in).

您可以通过一个数组而不是字符串来创建您自定义的聊天成员类型分组 :

groups.filter(
  chatMemberFilter(["restricted", "kicked"], ["free", "left"]),
  async (ctx) => {
    const from = ctx.from;
    const { status: oldStatus, user } = ctx.chatMember.old_chat_member;
    await ctx.reply(
      `<b>${escapeHtml(from.first_name)}</> lifted ` +
        `${oldStatus === "kicked" ? "ban" : "restrictions"} ` +
        `from <b>${escapeHtml(user.first_name)}</>`,
      { parse_mode: "HTML" },
    );
  },
);

示例使用

使用过滤器的最佳方法是选择一组相关的状态,例如"出","正则"和"admin",然后制作一个它们之间的过渡表:

↱出来经常管理员
出来更改禁令加入时加入和促进d
经常退出修改的限制晋升
管理员退出降职权限已更改

指定一个收听器来接收与您的使用大小写相关的所有切换 .

将这些过滤器与 bot.chatType 仅用于特定类型聊天的过渡. 添加一个中间软件来收听所有更新,作为执行共同操作(如更新您的数据库)的一种方式,然后将控制权交给特定的处理器.

const groups = bot.chatType(["group", "supergroup"]);

groups.on("chat_member", (ctx, next) => {
  // ran on all updates of type chat_member
  const {
    old_chat_member: { status: oldStatus },
    new_chat_member: { user, status },
    from,
    chat,
  } = ctx.chatMember;
  console.log(
    `In group ${chat.id} user ${from.id} changed status of ${user.id}:`,
    `${oldStatus} -> ${status}`,
  );

  // update database data here

  await next();
});

// specific handlers

groups.filter(chatMemberFilter("out", "in"), async (ctx, next) => {
  const { new_chat_member: { user } } = ctx.chatMember;
  await ctx.reply(`Welcome ${user.first_name}!`);
});

储存聊天成员

您可以使用一个有效的 grammY 存储适配器 或执行 StorageAdapter 接口.

import { Bot, Context, MemorySessionStorage } from "grammy";
import type { ChatMember } from "@grammyjs/types";
import { chatMembers, ChatMembersFlavor } from "@grammyjs/chat-members";

type MyContext = Context & ChatMembersFlavor;

const adapter = new MemorySessionStorage<ChatMember>();

const bot = new Bot<MyContext>("<your bot token>");

bot.use(chatMembers(adapter));

bot.start({
  allowed_updates: ["chat_member", "message"],
  onStart: ({ username }) => console.log(`Listening as ${username}`),
});

阅读聊天成员信息

此插件还添加了新 ctx.chatMembers.getChatMember 函数,该函数将检查存储中是否有聊天成员的信息,然后查询电报. 如果聊天成员存在于存储中,则会返回. 否则, ctx.api.getChatMember 将调用,结果将保存到存储器中,使随后的通话更快,并消除了为该用户再次调用电报以及未来聊天的需要.

举个例子:

bot.on("message", async (ctx) => {
  const chatMember = await ctx.chatMembers.getChatMember();

  await ctx.reply(`Hello, ${chatMember.user.first_name}! I see you are a ${chatMember.status} of this chat!`);
});

第二个参数是聊天id,是可选的;如果你不提供它, ctx.chat.id 将改为使用. 请注意,如果你不提供 聊天ID和没有 chat 属性在上下文中(例如:在内部查询更新中),这将产生错误.

主动存储

这个 enableAggressiveStorage 配置选项将在不取决于 chat_member 活动. 对于每次更新,中间软件检查是否 ctx.chat 财务报告和审定财务报表 ctx.from 已存在. 如果两者都这样做,那么它开始呼叫 ctx.chatMembers.getChatMember 将聊天成员信息添加到存储中,以备不存在.

请注意,这意味着需要储存 每次更新,这可能是很多,取决于 多少更新您的机器人收到. 这也有可能 影响你的机器人的性能. 只用这个 痷 知道你在做什么 也不怕风险和后果.

版本与发布记录

@grammyjs/chat-members 共发布 13 个版本,首次发布于 2023/01/17;过去 12 个月发布了 0 个版本。

版本发布日期距今
1.2.0latest2025/03/061.7 年前
1.1.02024/03/272 年前
1.0.122023/12/282 年前
1.0.102023/03/273 年前
1.0.92023/03/103 年前
1.0.82023/02/223 年前

关于 @grammyjs/chat-members 的常见问题

@grammyjs/chat-members 是什么?

GrammY 聊天成员插件

如何安装 @grammyjs/chat-members?

在项目目录运行 npm install @grammyjs/chat-members,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:grammy(^1.19.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@grammyjs/chat-members 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@grammyjs/chat-members 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@grammyjs/chat-members 可以商用吗?

@grammyjs/chat-members 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@grammyjs/chat-members 的下载量有多少?

根据 npm 官方下载统计,@grammyjs/chat-members 在 2026/10/17 – 2026/11/15 这 30 天内被下载 12,925 次,日均约 431 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@grammyjs/chat-members 还在维护吗?

最新版本 1.2.0 发布于 2025/03/06(1.7 年前);至今共发布 13 个版本,其中过去 12 个月发布了 0 个;首次发布于 2023/01/17。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。