# @core-ease/telegram-kit 中文文档

规范地址：https://npmcn.com/package/%40core-ease/telegram-kit/

版本：3\.2\.10
npm 元数据更新时间：2026-10-25T17:56:50.705Z
中文译文更新时间：2026-11-14T14:30:49.423Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40core-ease/telegram-kit
原文对照：https://npmcn.com/package/%40core-ease/telegram-kit/?lang=original
项目主页：https://github.com/CoreEase/telegram-kit#readme
源码仓库：https://github.com/CoreEase/telegram-kit

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

- 包体积（解压后）：9.2 MB，121 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0
- 首次发布：2026-07-13T07:35:06.042Z
- 最新版本发布：2026-10-25T17:56:50.209Z
- 近 30 天下载量：2012（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：32（近 12 个月 32 个）

## 中文简介

专业Telegram库 : Mini Apps SDK 被全部捆绑(一个完整的打入了TypeScript的重新实施Telegram的官方电报-web-app.js - 不需要CDN脚本) + 反应钩子,提供者,类型 + Bot API 服务器侧客户端 + 零依赖

## 安装

```sh
npm install @core-ease/telegram-kit
```

也可以使用：`pnpm add @core-ease/telegram-kit`、`yarn add @core-ease/telegram-kit`、`bun add @core-ease/telegram-kit`

## README

# @ core-sease/ telegram- kit (英语)

用于在Telegram上建构的完整工具包: Mini Apps SDK(React hooks + a supports),服务器的Bot API客户端,零依赖性 `.tgs`/Lottie贴子播放器,一个符合标准的QR编码编码器,以及用于Markdown/HTML格式化,深链接,和键盘的小型公用事业.

它可以是框架不可知的地方——普通JS,节点,或者一个 `<script>` 标记所有工作——并给您在实际帮助的地方(Mini Apps hooks,贴子播放器,QR组件)的回放绑定.

## 为什么会这样

Telegram Mini Apps 和 Bot API 项目通常最终粘合在一起 相同的几件事情:读取 `window.Telegram.WebApp`,验证 `initData` 在服务器上,用手构建内置键盘,逃离MarkdownV2等. `@core-ease/telegram-kit` 将所有那些都装入一个被打入文档的 API - 当您的 Mini App 在 Telegram 以外打开时, 每一个功能都会有一个真实的、有效的倒置 - 所以您不必为每个工程重建它 .

## 安装

```bash
npm install @core-ease/telegram-kit
```

反应是一种可选的同级依赖——只有在使用钩子,提供方,或贴子/QR/GramDiamond组件时才需要. 其他一切(bot客户端,QR编码,格式化,链接,服务器侧面验证)在平原节点或浏览器中工作,没有涉及React.

## 软件包结构

源头按照代码排列 _已经_,而不是 npm 子路径导出它:

```
src/
  sdk/       The full Mini Apps SDK: a faithful, modular TypeScript port of
             Telegram's official telegram-web-app.js (no CDN fetch, ever).
             Public entry: sdk/index.ts. Everything else lives under
             sdk/_internal/ (transport, kernel, theme, ui, features, sensors)
             and is an implementation detail - see sdk/README.md.
  core/      Telegram WebApp runtime access (getWebApp, haptics, storages,
             dialogs, location, biometrics, ...) - every function here gets
             the WebApp instance directly from ../sdk (never from
             window.Telegram) and has a real browser-native fallback for
             when the Mini App is opened outside Telegram. See
             core/fallback.ts for the fallback implementations and
             core/dev.ts for dev/local-testing mode.
  react/     Hooks and the TelegramProvider for React-based Mini Apps -
             every hook delegates to core/ rather than re-implementing
             its own copy of the same logic
  ui/        QR code, Gram Diamond WebGL component, and Lottie/TGS players
  utils/     MarkdownV2/HTML formatting, deep links, inline & reply keyboards
  bot/       The Bot API client, update dispatcher, and long-polling helper
  types/     Shared TypeScript types for the WebApp and the Bot API - the
             WebApp types are thin re-exports of the real ../sdk types
             instead of a hand-maintained parallel copy
  _internal/ Implementation details (QR encoding math, Gram Diamond and Lottie
             rendering engines, gzip inflate, HMAC verification, etc.) — not part of the
             public API and can change without notice
```

这些都不影响您如何导入软件包——请参看下面的章节。 密码库本身是怎样设置的 以防你浏览源头或打开公关.

## 快速启动 — Mini App( 反应)

包装您的应用程序一次 :

```tsx
import { TelegramProvider, useTelegram } from "@core-ease/telegram-kit";

function App() {
  return (
    <TelegramProvider options={{ autoExpand: true }}>
      <Home />
    </TelegramProvider>
  );
}

function Home() {
  const { user, colorScheme, inTelegram } = useTelegram();

  if (!inTelegram) return <p>Open this from a Telegram chat.</p>;

  return (
    <p>
      Hey {user?.first_name}, you're on {colorScheme} mode.
    </p>
  );
}
```

`TelegramProvider` 电话 `WebApp.ready()`,扩展窗口,读取当前用户,并跟踪您的颜色方案. `options` 还接受 `onReady`, (中文(简体) ), `onUserReady`, (中文(简体) ), `loadingComponent`, (中文(简体) ), `notInTelegramComponent`, (中文(简体) ), `allowOutsideTelegram`, (中文(简体) ), `autoDisableVerticalSwipes`,以及 `autoEnableClosingConfirmation`。 。 。 .

从那里,钩子覆盖了WebApp地表的大部分:

```tsx
import {
  useTelegramMainButton,
  useTelegramBackButton,
  useHapticFeedback,
  useShowConfirm,
  useCloudStorage,
} from "@core-ease/telegram-kit";

function CheckoutButton() {
  const haptic = useHapticFeedback();
  const confirm = useShowConfirm();

  useTelegramMainButton({
    text: "Confirm order",
    onClick: async () => {
      if (await confirm("Place this order?")) {
        haptic.notification("success");
      }
    },
  });

  return null;
}
```

总共约有40个钩子——主/后/后/后扣、云/装置/安全储存、生物鉴别、加速计/陀螺仪、取景器和安全区、全屏、主题、剪贴板、QR扫描等。 它们都从软件包根导出,所以你的编辑器自动完成是浏览它们最快的方法.

## 核心( 不需要反应)

香草JS、Vue或其他任何地方

```ts
import { getWebApp, isInTelegram, haptic, cloudStorage, dialog } from "@core-ease/telegram-kit";

if (isInTelegram()) {
  await dialog.showConfirm("Continue?");
  await cloudStorage.setItem("draft", JSON.stringify(formState));
  haptic.impact("medium");
}
```

本单元还有: `openTelegramLink`, (中文(简体) ), `openInvoice`, (中文(简体) ), `shareToStory`, (中文(简体) ), `requestContact`, (中文(简体) ), `scanQr`, (中文(简体) ), `downloadFile`, (中文(简体) ), `getUserDisplayName`, (中文(简体) ), `getUserAvatarUrl`,其余的WebApp则表面为平面功能.

## Bot API (服务器侧)

```ts
import { TelegramBot, Dispatcher, TelegramPoller } from "@core-ease/telegram-kit/bot";

const bot = new TelegramBot({ token: process.env.BOT_TOKEN! });

const dispatcher = new Dispatcher()
  .onCommand("start", (msg) => bot.sendMessage({ chat_id: msg.chat.id, text: "Welcome!" }))
  .onMessage((msg) => bot.sendMessage({ chat_id: msg.chat.id, text: `You said: ${msg.text}` }));

const poller = new TelegramPoller((params) => bot.getUpdates(params), dispatcher.toHandler());

poller.start();
```

`TelegramBot` 涵盖Bot API方法(`sendMessage`, (中文(简体) ), `sendPhoto`, (中文(简体) ), `editMessageText`, (中文(简体) ), `answerCallbackQuery`, (中文(简体) ), `setWebhook`,等等)带有已键入的参数和已键入的响应,并扔出一个 `TelegramApiError` (与 `errorCode` 财务报告和审定财务报表 `description`当API拒绝一个电话。 如果你宁可做个网球比赛 也不要做长票 打电话 `dispatcher.toHandler()(update)` 从您的 HTTP 处理器中选择 `TelegramPoller`。 。 。 .

## 正在验证 `initData` 在服务器上

永远不要信任 `initData` 在客户端上, 总是先验证其服务器侧, 然后再将其作为认证的用户 :

```ts
import { validateInitData } from "@core-ease/telegram-kit/server";

const result = await validateInitData(initDataFromClient, process.env.BOT_TOKEN!, {
  maxAgeSeconds: 3600,
});

if (!result.valid) {
  // result.reason: 'invalid_hash' | 'expired' | 'missing_hash' | 'malformed'
  throw new Error("Invalid Telegram session");
}

// result.user, result.startParam, result.authDate are ready to use
```

还有一个同步的 `validateInitDataSync` 如果你不是在同步上下文中——相同的选项,相同的结果形状.

## QR 代码

零依赖性ISO/IEC 18004编码器外加有样式的React组件:

```tsx
import { QRCode, encodeQRCode, qrCodeToSVG } from "@core-ease/telegram-kit/qr";

// as a component
<QRCode value="https://t.me/your_bot" size={256} dotColor="#111" logo="/logo.png" />;

// or just get raw SVG / matrix data, no React needed
const svg = qrCodeToSVG("https://t.me/your_bot", { size: 512, color: "#000" });
const { modules } = encodeQRCode("https://t.me/your_bot", { errorCorrectionLevel: "M" });
```

`QRCode` 支持自定义的点/角形状,一个自动大小夹住的标志,使其永远不中断可扫描性,圆角,以及 a `downloadQRCode(svgRef.current, { format: 'png' | 'svg' })` 帮助导出它 .

## 动画贴花 (TGS/Lottie)

```tsx
import { TgsPlayer } from "@core-ease/telegram-kit/tgs";

<TgsPlayer src="/stickers/wave.tgs" autoplay loop style={{ width: 128, height: 128 }} />;
```

`TgsPlayer` 验证文件实际上是符合Telegram的动画标签( 设置) `strict={false}` 以跳过支票。 如果你在制作一个普通的洛蒂JSON动画而不是一个 `.tgs` 文件, 使用 `LottiePlayer` 从 `@core-ease/telegram-kit/lottie` ——同道具,无TGS验证. 两者都可以从 `@core-ease/telegram-kit/animation`。 。 。 .

## 格子钻石

`GramDiamond` 是反应/WebGL2晶体组件。 它来自专用的子路径和动画捆绑:

```tsx
"use client";
import { GramDiamond } from "@core-ease/telegram-kit/gram-diamond";

<GramDiamond
  variant="interactive"
  appearance="blue"
  width={220}
  height={220}
  animationMode="continuous"
  animateOnAppear
/>;
```

本构成部分还支持 `white` 财务报告和审定财务报表 `cool` 外观 `premium` 变体、拖放/tap 交互和必须控制 `GramDiamondHandle`。它在浏览器中需要WebGL2。 遮蔽器使用恒定索引分支作为锚地数据来避免移动的WebGL链接器不相容,而不会改变制成的几何或动画值. `GramDiamond` 也被导出 `@core-ease/telegram-kit/animation`。 。 。 .

## PremiumStar (由Telegram iOS公司发行的WebGL2之星/硬币)

```tsx
import { PremiumStar } from "@core-ease/telegram-kit/premium-star";

<PremiumStar variant="stars" width={200} height={200} />     // gold star (Stars purchase page)
<PremiumStar variant="premium" width={200} height={200} />   // violet star (Premium page)
<PremiumStar variant="business" width={200} height={200} />  // coin (Business)
```

## 格式化信件( MarkdownV2 / HTML)

手取出MarkdownV2是一个常见的bug源(其保留字符比人们所期望的要多). 以此为您构建字符串 :

```ts
import { md, html } from "@core-ease/telegram-kit/format";

const text = md.text(
  "Hello ",
  md.bold(user.first_name),
  "! Your order ",
  md.code(orderId),
  " is ready.",
);
await bot.sendMessage({ chat_id, text: text.toString(), parse_mode: "MarkdownV2" });
```

两者 `md` 财务报告和审定财务报表 `html` 支助 `bold`, (中文(简体) ), `italic`, (中文(简体) ), `underline`, (中文(简体) ), `strikethrough`, (中文(简体) ), `spoiler`, (中文(简体) ), `code`, (中文(简体) ), `pre`, (中文(简体) ), `link`, (中文(简体) ), `mentionUser`,以及 `customEmoji`· ; `html` 另外,还有 `blockquote` 财务报告和审定财务报表 `expandableBlockquote`。你通过到的一切都自动逃脱,除非它已经是一个格式化的碎片,所以筑巢 `md.bold(md.italic('x'))` 工作如预期. `TELEGRAM_TEXT_LIMITS` 财务报告和审定财务报表 `truncateText` 用于在Telegram的长度限制(代理-pair-security)下停留.

## 深层链接

```ts
import {
  buildStartLink,
  buildStartAppLink,
  parseTelegramLink,
} from "@core-ease/telegram-kit/links";

buildStartLink({ botUsername: "your_bot", data: "ref_42" });
// -> https://t.me/your_bot?start=cmVmXzQy

buildStartAppLink({ botUsername: "your_bot", appName: "shop", startParam: "sku_123" });
// -> https://t.me/your_bot/shop?startapp=sku_123

parseTelegramLink("https://t.me/your_bot/shop?startapp=sku_123");
// -> { type: 'mini-app', username: 'your_bot', appName: 'shop', startParam: 'sku_123' }
```

`start`编号 :`startapp` 参数只允许 `A-Z a-z 0-9 _ -` 最多64个字符——通过 `data` 它会给你编码为基数64url;通过 `startParam` 如果它已经是一个有效的短弹.

## 键盘

```ts
import { InlineKeyboardBuilder, ReplyKeyboardBuilder } from "@core-ease/telegram-kit/keyboards";

const keyboard = new InlineKeyboardBuilder()
  .text("Yes", "confirm:yes")
  .text("No", "confirm:no")
  .row()
  .url("Docs", "https://example.com")
  .build();

await bot.sendMessage({ chat_id, text: "Confirm?", reply_markup: keyboard });
```

`InlineKeyboardBuilder.columns(buttons, perRow)` 是网格布局的快捷键. `removeKeyboard()` 财务报告和审定财务报表 `forceReply()` 覆盖其余的回复标记类型.

## 开发外部电报

`WebApp` 在Telegram客户端之外不存在,这让本地开发感到痛苦. 即使没有打电话 `installDevMode()`,每个 `@core-ease/telegram-kit` 函数已降解为真实的浏览器- 本地当量( 见 `core/fallback.ts`) - 因此钩和核心功能在框外的普通浏览器标签中工作. `installDevMode()` 更进一步,播下假用户/主题/会议,因此 `getWebApp().initDataUnsafe.user`,主题,和 `isInTelegram()` 都表现得像真正的发射:

```ts
import { installDevMode } from "@core-ease/telegram-kit/dev";

// Call this before anything else touches getWebApp() - hooks, <TelegramProvider>,
// or any core/index.ts function. It seeds a fake user/theme/session through the
// exact same code path a real Telegram launch uses, so every feature (storage,
// haptics, dialogs, location, ...) keeps working through its browser-native
// fallback instead of hanging or warning.
if (process.env.NODE_ENV === "development") {
  installDevMode({ user: { id: 1, first_name: "Dev" } });
}
```

在生产过程中不要运送这个——在像上面一样的环境检查后门.

## 用不着捆绑

还有一个普通的浏览器 显示所有的东西 `TelegramKit` 全球。 它将迷你Apps SDK本身捆绑起来 所以 **无外部 `telegram.org` 需要脚本标签**数字 :

```html
<script src="https://unpkg.com/@core-ease/telegram-kit/dist/browser.global.js"></script>
<script>
  const { encodeQRCode, buildStartLink, isInTelegram, getWebApp } = TelegramKit;
  console.log(getWebApp()?.platform);
</script>
```

此构建包括核心, QR, 格式化, 链接, 键盘, dev模式, 以及被捆绑的迷你 Apps SDK - 而不是依赖 React 的棋子, 因为平原中没有 React `<script>` 上下文.

## 捆绑的迷你Apps SDK

`@core-ease/telegram-kit` 曾经很薄 _类型_ 环绕Telegram自己的 `https://telegram.org/js/telegram-web-app.js`,你不得不通过一个 `<script>` 标签。 该脚本现在作为忠实的一行为一行的行为端口销售,下方为: `@core-ease/telegram-kit/sdk` (来源: `src/sdk/`,公开条目 `src/sdk/index.ts`执行 `src/sdk/_internal/`) (中文(简体) ).

实际上,这意味着:

-   **没有依赖CDN,永远.** 刚刚 `import '@core-ease/telegram-kit'` (或 `/core`,或 `/hooks`)和第一个呼叫 `getWebApp()` - 每一个钩子和核心功能 为你 - 设置 `window.Telegram.WebApp` 当地。 网络上没有任何东西被取走,从进口软件包(SSR-security)上也没有任何东西急于运行.
    
-   **`core/`, (中文(简体) ), `react/hooks.ts`,以及 `<TelegramProvider>` 全部直接读取 SDK** - 说吧 `getWebApp()` 内 `core/index.ts` 获取 `WebApp` 实例 `../sdk`是因为 `bootstrapTelegramWebApp()`,从未从 `window.Telegram`每一个代表 `core/` 而不是重新执行它自己的同一电话副本.
    
-   **每个功能都有真正的浏览器倒回.** 在Telegram以外打开(或以dev模式打开,或针对一个更老客户端),存储返回到 `localStorage`,杂乱 `navigator.vibrate`,位置改为 `navigator.geolocation`剪贴板改为 `navigator.clipboard`,文件下载到平原 `<a download>`对话框 `window.alert/confirm/prompt`,全屏/定向到标准全屏/Screen定向API,并共享到Web Share API - 见 `src/core/fallback.ts`. 没有任何有意义的浏览器等同功能(生物计量、emoji状态、Telegram-count actions,.)的呼叫可以预测地解决,而不是挂起或用控制台警告拒绝.
    
-   **每个本地事件、版本门和验证规则** 从正式的脚本完全保存在 SDK 层本身 - 见 `src/sdk/README.md` 用于模块分解和忠诚说明.
    
-   **高级使用 :** 如果您需要直接输入的 SDK 类, 而不是通过 `core/`从 `@core-ease/telegram-kit/sdk`数字 :
    
    ```ts
    import { bootstrapTelegramWebApp } from "@core-ease/telegram-kit/sdk";
    
    const { webApp } = bootstrapTelegramWebApp();
    webApp.MainButton.setText("Continue").show();
    ```
    

## 类型脚本

所有东西都用TypeScript和船用它自己写的 `.d.ts` 文件 - 没有 `@types` 需要软件包。 完整的 Bot API 类型表面(`Message`, (中文(简体) ), `Update`, (中文(简体) ), `InlineKeyboardMarkup`,每个 `SendXParams` 导出自 `@core-ease/telegram-kit/bot` 财务报告和审定财务报表 `@core-ease/telegram-kit` 直接说.

## 许可证

麻省理工学院

## 常见问题

### @core-ease/telegram-kit 是什么？

专业Telegram库 : Mini Apps SDK 被全部捆绑\(一个完整的打入了TypeScript的重新实施Telegram的官方电报-web-app\.js - 不需要CDN脚本\) \+ 反应钩子,提供者,类型 \+ Bot API 服务器侧客户端 \+ 零依赖

### 如何安装 @core-ease/telegram-kit？

在项目目录运行 npm install @core-ease/telegram-kit，或使用 pnpm add / yarn add / bun add。

### @core-ease/telegram-kit 支持 TypeScript 吗？

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

### @core-ease/telegram-kit 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @core-ease/telegram-kit 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @core-ease/telegram-kit 可以商用吗？

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

### @core-ease/telegram-kit 的下载量有多少？

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

### @core-ease/telegram-kit 还在维护吗？

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