telegram web app 的 html 限制包括：仅支持 https 请求、禁用 document.write/window.open/notification 等 api，localstorage 不可靠，geolocation 需显式授权；必须通过 webapp.initdata 获取用户身份，js 需等 webapp.ready() 后调用 sdk；视口高度应使用 webapp.viewportstableheight；所有交互须用 webapp 提供的方法（如 opentelegramlink/senddata/showalert）；本地 http/file 协议无法初始化 sdk，调试必须部署到 https 域名并真机测试。
Telegram Web App 的 HTML 限制有哪些
Telegram Web App 不是普通网页，它运行在 Telegram 客户端内嵌的 WebView 中（iOS 用 WKWebView，Android 用 Chromium-based WebView），所以很多浏览器 API 被禁用或行为异常。document.write、window.open、localStorage（部分版本不可写）、Notification、Geolocation（需显式授权且常被拦截）基本不能用。更关键的是：**所有网络请求必须走 HTTPS，且跨域策略由 Telegram 控制，不是标准 CORS**。
常见错误现象：Failed to execute 'fetch' on 'Window': Request scheme 'http' is not supported；SecurityError: localStorage is not available for this document；点击按钮无响应——其实是 onclick 绑定成功了，但后续调用的 WebApp.showAlert 因未初始化而静默失败。
- 必须通过
WebApp.initData或WebApp initDataUnsafe获取用户身份，不能依赖 Cookie 或 Session - 所有 JS 必须等
WebApp.ready()后才能调用 SDK 方法，否则多数接口返回undefined或抛错 - 页面尺寸由 Telegram 控制：
WebApp.viewportStableHeight才是可靠视口高度，window.innerHeight在键盘弹出/收起时严重滞后
如何正确加载和初始化 WebApp SDK
别直接写 <script src="https://telegram.org/js/telegram-web-app.js"></script> 就完事。Telegram 官方 SDK 不提供 CDN 版本，实际应使用 <script async src="https://telegram.org/js/telegram-web-app.js"></script>（这是唯一合法入口），但它只挂载全局 WebApp 对象，不自动执行任何逻辑。
初始化必须手动触发，且时机敏感：
- 在
中加载 SDK 脚本后，**不要立即调用WebApp.ready()**——脚本可能未就绪 - 推荐写法：监听
DOMContentLoaded，再用setTimeout(..., 0)或queueMicrotask确保 SDK 已注入 - 必须检查
WebApp.initData是否存在，空值意味着没从 Telegram 内打开（比如直接粘贴 URL 测试），此时应跳转提示页或降级渲染
示例片段：
document.addEventListener('DOMContentLoaded', () => {
if (typeof WebApp === 'undefined') return;
queueMicrotask(() => {
if (WebApp.initData) {
WebApp.ready();
WebApp.expand(); // 主动撑满视口
} else {
document.body.innerHTML = '<p>请在 Telegram 中打开</p><div class="aritcle_card flexRow artxards">
<div class="artcardd flexRow">
<a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill5806" title="html-deploy"><img
src="https://img.php.cn/upload/skill/000/000/081/179066538882434.jpg" alt="html-deploy" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
<div class="aritcle_card_info flexColumn">
<a rel="nofollow" href="/xiazai/skill5806" title="html-deploy" class="overflowclass">html-deploy</a>
<p class="overflowclass">使用 htmlcode.fun 将 HTML 内容或文件部署到网页，适用于用户要求“部署到网页”“托管此 HTML”“生成此前端...的实时链接”等场景。</p>
</div>
<a rel="nofollow" href="/xiazai/skill5806" title="html-deploy" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span>
</a>
</div>
</div>';
}
});
});
HTML 元素如何适配 Telegram 的交互规范
Telegram Web App 强制接管了原生滚动、弹窗、导航等行为。你写的 <button></button> 没问题，但 <a href="/next"></a> 会直接跳出 Web App（变成外部浏览器打开），input[type="file"] 在 iOS 上几乎不可用，textarea 长按菜单会被 Telegram 截获。
核心原则：**放弃“网页思维”，只用 Web App 提供的交互通道**。
- 跳转用
WebApp.openTelegramLink('https://t.me/username')，不是window.location - 表单提交后，用
WebApp.sendData(JSON.stringify(payload))把数据传回 Bot，而不是发 AJAX - 弹窗统一用
WebApp.showAlert()/WebApp.showConfirm()，别自己写 modal - 颜色主题要响应
WebApp.colorScheme（'light'/'dark'），并监听themeChanged事件重绘
容易踩的坑：WebApp.close() 只在用户主动点击「关闭」按钮时才生效，JS 主动调用无效；WebApp.setHeaderColor('#2a88f0') 在深色模式下可能被忽略，得配合 WebApp.setBackgroundColor() 一起设。
为什么本地开发时样式错乱、按钮点不动
根本原因：本地 file:// 协议或 HTTP 服务（如 localhost:3000）无法触发 Telegram SDK 初始化。SDK 只在 https://t.me/yourbot/app 这类合法上下文中注入 WebApp 对象并开放 API。
调试必须走真实链路：
- 部署到 HTTPS 域名（哪怕只是 Vercel/Cloudflare Pages 的免费域名），然后在 BotFather 设置
/setwebapp指向该地址 - 真机测试！模拟器或桌面 Telegram Desktop 对 Web App 支持极差，尤其是键盘弹出逻辑和 viewport 计算
- 开启 Telegram 的开发者工具：Android 上长按任意消息 → “Developer mode”，iOS 上设置 → “Data and Storage” → “Developer Mode” → 开启后摇动手机唤出调试面板
最常被忽略的一点：Telegram 会缓存 Web App 的 JS/CSS 资源，且不遵循 Cache-Control。改完代码后，务必强制刷新——在 Telegram 内长按页面空白处，选 “Reload”（不是下拉刷新），否则永远在跑旧版本。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
