# @grammyjs/chat-members 中文文档

规范地址：https://npmcn.com/package/%40grammyjs/chat-members/

版本：1\.2\.0
npm 元数据更新时间：2025-03-05T17:20:59.590Z
中文译文更新时间：2026-11-16T22:08:48.185Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40grammyjs/chat-members
原文对照：https://npmcn.com/package/%40grammyjs/chat-members/?lang=original
项目主页：https://github.com/grammyjs/chat-members
源码仓库：https://github.com/grammyjs/chat-members

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：31.4 kB，13 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：grammy ^1\.19\.0
- 首次发布：2023-01-16T21:59:45.797Z
- 最新版本发布：2025-03-05T17:20:59.339Z
- 近 30 天下载量：12925（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 0 个）

## 中文简介

GrammY 聊天成员插件

## 安装

```sh
npm install @grammyjs/chat-members
```

也可以使用：`pnpm add @grammyjs/chat-members`、`yarn add @grammyjs/chat-members`、`bun add @grammyjs/chat-members`

## README

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

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

## 使用量

### 聊天成员过滤器

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

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

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

```typescript
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).

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

```typescript
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` 仅用于特定类型聊天的过渡. 添加一个中间软件来收听所有更新,作为执行共同操作(如更新您的数据库)的一种方式,然后将控制权交给特定的处理器.

```typescript
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 [存储适配器](https://grammy.dev/plugins/session.html#known-storage-adapters) 或执行 [`StorageAdapter`](https://deno.land/x/grammy/mod.ts?s=StorageAdapter) 接口.

```typescript
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` 将调用,结果将保存到存储器中,使随后的通话更快,并消除了为该用户再次调用电报以及未来聊天的需要.

举个例子:

```typescript
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 是什么？

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 和提交记录判断。

