# @grammyjs/types 中文文档

规范地址：https://npmcn.com/package/%40grammyjs/types/

版本：5\.0\.0
npm 元数据更新时间：2026-08-25T12:28:48.288Z
中文译文更新时间：2026-11-16T22:00:32.902Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：572 kB，19 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2021-03-26T22:01:24.789Z
- 最新版本发布：2026-08-25T12:28:48.080Z
- 近 30 天下载量：15565859（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：105（近 12 个月 11 个）

## 中文简介

电报 grammY 的 Bot API 类型声明

## 安装

```sh
npm install @grammyjs/types
```

也可以使用：`pnpm add @grammyjs/types`、`yarn add @grammyjs/types`、`bun add @grammyjs/types`

## README

# 电报 grammY 的 Bot API 类型

[格莱姆Y](https://github.com/grammyjs/grammY) 使写Telegram bots变得容易。 看看这个!

这个软件包只是为完整的Telegram Bot API提供类型说明,并旨在使其可用于grammY. 里面没有可操作的代码 .

此软件包最初基于 `typegram`,但从更新到Telegram Bot API 5.1, `typegram` 不再直接更新。 相反,这个软件包得到维护,其更新被传送回 `typegram`。因此,两个软件包目前都与Telegram Bot API保持最新状态.

## 可用类型

一般来说,这个包裹只是暴露了巨大的负载 `interface`s 对应 **类型** 用于整个Telegram Bot API.

注意 API 规格有时只对一个类型的多个变体有一个名称,例如有多个不同的 `Update`你可以接受,但他们都叫 `Update`。 。 。 . 如果您需要访问一个 `Update`,提及 `Update.MessageUpdate` 他们的兄弟姐妹.

事实上,这种模式被用于各种类型,即:

-   `CallbackQuery`
-   `Chat`
-   `ChatFullInfo`
-   `InlineKeyboardButton`
-   `KeyboardButton`
-   `Message`
-   `MessageEntity`
-   `Location`
-   `Update`

自然,当API规格实际上是建模类型成为结合(例如. `InlineQueryResult`),这里也反映为工会类型. 这些类型没有关闭.

## 可用方法

除类型外,此软件包还为您提供了另一种类型 `Telegram` 包含所有可用的 **方法** (原始内容存档于2018-09-21). IAPI. 这个问题没有进一步的结构,但是如果你能想出合理的东西,请在问题中提出,或者直接打开公关. 在格拉姆年,这些类型是定义 `bot.api.raw` 对象.

每个方法只取一个单一的参数,其结构与Telegram所期望的对象相对应. 帮助类型 `Opts<M>` (何处) `M` 是方法名)允许grammY直接访问该类型.

## 处理 JSON 序列化对象

Telegram Bot API的一些方法预计将与载荷属性所含的JSON系列化物体相呼应,而不是JSON实际载荷. 换句话说,这些物体被序列化了两次——第一次是为了与文件保持一致,第二次是有效载荷实际被送入POST机体到API服务器.

最突出的例子就是 `reply_markup` 属性,在多种不同方法中出现,但在整个API中可以找到十几个其他类似属性.

严格地说 `@grammyjs/types` 类型不准确反映. 而不是使用 `string` 作为类型, `@grammyjs/types` 使用对象本身的类型,从而忽略了序列化步骤. 例如,没有宣布 `reply_markup: string`,它宣布财产为 `reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply` 因为这是应该 序列化到 `string` 在调用相应的方法之前.

这有道理,因为grammY使用环绕Telegram Bot API的包装码中的类型,暴露为 `bot.raw.api`。 。 。 . 这种包装码会自动为所需的属性做必要的JSON序列化. 使用 grammY 写的 Bots 则不需要考虑哪些属性需要序列化,哪些属性不需要序列化. 鉴于此 `@grammyjs/types` 指对象本身,而不是其序列字符串,包装码现在可以简单地暴露 `@grammyjs/types` 给它的消费者,而不必改变它们.

因此,为了反映这一点,对所有方法的描述进行了调整,即JSDoc的评论没有提及JSON的序列化(与其官方对应部分相反).

## 自定义 `InputFile`

Telegram Bot API 允许 bots 发送文件 [三种不同方式](https://core.telegram.org/bots/api#sending-files)。 。 。 . 其中两种方法是: `string`\- 无论是 `file_id` 或者一个URL. 然而,第三个选项是使用多段/窗体数据将文件上传到服务器.

前两种发送文件的手段已经由跨库的类型说明所覆盖. 在所有地点 `file_id` 或允许一个 URL,相应的属性允许 `string`。 。 。 .

我们现在将研究与直接上传文件有关的类型声明. grammY 自动翻译呼叫到 `sendDocument` ,在提供多段/窗体数据上传 `InputFile` 对象 `document` 参数对象的属性.

`@grammyjs/types` 不需要知道您想要支持哪些对象 `InputFile`编号. 因此,类型 `InputFile` 此库中没有定义.

相反,grammY指定了它自己的版本什么是 `InputFile` ,因此自动调整 `@grammyjs/types` 带有自定义 `InputFile` 类型用于所有受影响的方法和接口. 这可以通过在所有受影响的类型中添加一个类型参数来实现. grammY 然后导入类型 将这些类型与版本的 `InputFile`,然后再出口调整过的类别. 因此,您应当如本文所述,始终导入Bot API: [https://grammy.dev/guide/api.html#类型定义- for-the-api](https://grammy.dev/guide/api.html#type-definitions-for-the-api)。 。 。 .

## 与 Bot API 的区别

一些文档字符串有意与网站所写的内容不同. 实际类型定义本身从未有不同.

1.  无格式化 . 我们利用JSDoc的减值能力不是为了便于复制,从而减少维护工作.
2.  没有提及 `JSON-serialized`。 。 。 . 由于基础库处理序列化,这些字从解释中删除.
3.  没有提到超过2^31的整数,但没有提到2^51. JS里所有的数字都是64位浮点,所以这无关紧要. 注意JS比特操作员将数字投向了32位整数并回放,但我们故意忽略这一点,因为使用比特操作员在标识或文件尺寸上的人应该知道自己在做什么,他们也应该知道这是个坏主意.
4.  没有 `More info on Sending Files »`。 。 。 . 文件处理被基础库取出. 而且,没有链接, 它的无用反正. 关于请求聊天、用户、付款和游戏的更多信息链接也是如此.
5.  没有图像 . 包含图像的文档字符串也会被调整,以便在没有图像的情况下变得合理.

## 捐款

这是德诺计划. 所有文件均为发布于 [https://deno.land/x/grammy 类型](https://deno.land/x/grammy_types)。 。 。 . 这个项目使用 [deno2 节点](https://github.com/fromdeno/deno2node) 以发送声明文件,然后在npm上公布.

如果要进行这项工作,则不需要安装Node.js. 你也不应该跑 `npm install`。 。 。 . 你们只需要 [德诺](https://deno.land/) 和本Repo中建议的 VSCode 扩展.

运行 `deno task` 以查看可用的开发脚本.

## 常见问题

### @grammyjs/types 是什么？

电报 grammY 的 Bot API 类型声明

### 如何安装 @grammyjs/types？

在项目目录运行 npm install @grammyjs/types，或使用 pnpm add / yarn add / bun add。

### @grammyjs/types 支持 TypeScript 吗？

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

### @grammyjs/types 支持 ESM 还是 CommonJS？

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

### @grammyjs/types 可以商用吗？

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

### @grammyjs/types 的下载量有多少？

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

### @grammyjs/types 还在维护吗？

最新版本 5\.0\.0 发布于 2026/08/25（2 个月前）；至今共发布 105 个版本，其中过去 12 个月发布了 11 个；首次发布于 2021/03/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

