@ 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 以外打开时, 每一个功能都会有一个真实的、有效的倒置 - 所以您不必为每个工程重建它 .
安装
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( 反应)
包装您的应用程序一次 :
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地表的大部分:
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或其他任何地方
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 (服务器侧)
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 在客户端上, 总是先验证其服务器侧, 然后再将其作为认证的用户 :
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组件:
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)
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晶体组件。 它来自专用的子路径和动画捆绑:
"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之星/硬币)
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源(其保留字符比人们所期望的要多). 以此为您构建字符串 :
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)下停留.
深层链接
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 如果它已经是一个有效的短弹.
键盘
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() 都表现得像真正的发射:
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 需要脚本标签数字 :
<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数字 :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 直接说.
许可证
麻省理工学院