Mini App 按钮被系统栏挡住，该查 Telegram 哪份文档？
沿着官方 WebApp API 区分视口高度、设备安全区、Telegram 内容安全区与全屏支持，再决定一张布局截图该交给谁处理。
重点监测信号
- 需求方能把 Telegram WebApp version 和 platform 与截图一起提供
- 动态视口与稳定视口、设备安全区与内容安全区被分开记录
- 全屏或旋转事件可在自有测试入口复现
Telegram Mini App 的按钮被刘海、系统栏或 Telegram 控件挡住时，先到官方 WebApp API（应用程序编程接口）里确认五组观察值，再分派修复：version 与 platform、viewportHeight 与 viewportStableHeight、safeAreaInset、contentSafeAreaInset，以及全屏事件结果。截图能证明“看起来被挡住”，不能证明是哪条边界发生了变化。
这条文档路径写给 Mini App 开发公司的项目协调员。他在有权访问的创始人、产品和开发群里筛选需求，需要找的是可在具体客户端复现的布局问题，而不是所有写着“UI broken”的图片。上线方可能一天内就选定排查人员，但依据一张截图立即报价，也可能把 CSS、应用状态和客户端兼容问题交给错误的人。
第一站：WebApp.version 与 WebApp.platform
Telegram 官方 Mini Apps 文档在 WebApp 对象下列出了 version 与 platform。前者表示当前 Telegram 应用可用的 Bot API 版本，后者表示该 Telegram 应用的平台名称。
这两个值应该和截图放在同一条记录里。“iPhone 上有问题”不够，因为对方可能走 Web、旧客户端或不同启动入口。“Android 正常”也不完整，除非是在相同界面状态、相同业务步骤下比较。
协调员不需要索取生产密钥或用户隐私数据。要求对方提供自有测试入口、这两个 WebApp 值、启动位置和复现时间即可。如果连这些信息都没有，这还是一条待补证据的兼容报告，不是完整实施需求。
动态视口和稳定视口解决不同问题
官方 API 定义了两个容易混用的可视高度。
viewportHeight 是当前可见区域高度，会在用户展开或收起 Mini App 时变化。Telegram 特别提醒，它的刷新速度不足以让控件平滑跟随正在移动的下边缘。
viewportStableHeight 是最近一次稳定状态的高度。Telegram 指出，需要把元素固定在底部时，它更合适。相关的 viewportChanged 事件带有 isStateStable，可以判断尺寸变化已经结束还是仍在进行。
因此，分派问题时可以问得很具体：如果按钮只在拖动动画中跳动，稳定后位置正确，先检查动态与稳定视口的使用；如果稳定后仍被遮挡，再继续检查安全区字段与 CSS。没有记录发生时刻和值，同一张截图无法区分这两种情况。
设备安全区与 Telegram 内容安全区不是一回事
safeAreaInset 表示设备安全区，考虑刘海、系统导航栏等设备界面。contentSafeAreaInset 表示可显示内容且不会被 Telegram 自身界面元素遮住的区域。
在全屏或贴边布局中，这个差别很实际：按钮可能已经避开物理刘海，却仍落在 Telegram 控件下面；反过来，无条件叠加两组 inset（边距值）又可能留下过大的空白。协调员应让开发者说明当前 CSS 使用了哪组值，并记录故障当时四个方向的 inset。
官方事件表给出了观察入口：
safeAreaChanged在设备安全区因旋转或屏幕调整而变化时触发；contentSafeAreaChanged在 Telegram 内容安全区变化时触发；- 当前文档把两者标为 Bot API 8.0+，新值通过对应的 WebApp 属性读取。
文档还说明，事件处理器本身不接收 inset 数据。应用应在事件发生后读取更新后的属性。这个细节能避免协调员在交接单里要求一个并不存在的事件字段。
全屏不仅是“看起来像”，还应有事件结果
对 Bot API 8.0+，Telegram 记录了 requestFullscreen()、isFullscreen 属性，以及 fullscreenChanged 与 fullscreenFailed 两个事件。
fullscreenChanged 表示 Mini App 进入或退出全屏，当前状态从 isFullscreen 读取。fullscreenFailed 可以返回 UNSUPPORTED 或 ALREADY_FULLSCREEN。页面没有 Telegram 顶栏，看起来很像全屏，却不能证明调用过哪个方法，也不能证明是否收到失败事件。
交接时应记录：什么动作发起全屏、实际观察到哪个事件、isFullscreen 的值，以及 version/platform。如果 fullscreenFailed 明确返回 UNSUPPORTED，这是有文档支持的兼容边界；如果没有埋点，下一步只是补观察，不能直接断言 Telegram 忽略了请求。
五行交接单比十张无标签截图更有用
一份可进入工程排查的记录可以很短：
- 启动入口：脱敏后的自有测试链接或 Bot 入口；
- 客户端：
WebApp.version、WebApp.platform、方向与时间； - 视口：当前高度、稳定高度和问题出现时的
isStateStable； - 安全区：变化前后的
safeAreaInset、contentSafeAreaInset； - 全屏：发起动作、
isFullscreen和 changed/failed 事件结果。
有了这些标签，再附一张截图或短录屏。账号、私聊和无关群内容应脱敏。目标不是公开用户屏幕，而是把可见遮挡对应到可观察的 API 状态。
例如，授权开发群里可能只出现这样一句：
示意复合消息：“ios 全屏时底部 checkout 按钮被 bar 挡了，desktop 正常，用哪个 inset？”
它给出了平台类别和症状，却没有客户端版本、启动入口、视口状态、inset 值、屏幕方向、CSS、代码权限、项目负责人和联系许可。因为它能对应到官方字段，所以值得项目协调员先看；它仍不能证明某个 inset 或 Telegram 缺陷就是根因。
按第一项缺失观察值分派
缺少版本与平台，先交给复现资料收集；问题只在尺寸变化期间出现，先查视口状态；设备与内容安全区和 CSS 假设不一致，再交给布局工程；全屏返回明确不支持，就应设计兼容方案，而不是承诺所有客户端表现一致。
TOP Prospect 可以把授权群里的消息片段、来源、时间、重复症状和未知项放在一起，帮助协调员先看可复现的讨论，而不是一张脱离上下文的截图。它不能检查 Mini App、运行客户端 JavaScript、进入代码仓库、核实身份或联系发言者。当前生产版新建匹配目标只保存配置，并不会自动生成新候选。
开发者群证据质量文章可帮助区分一手复现信息与转述；原始消息链接检查保护消息出处；论坛主题上下文指南避免把技术回复放错讨论串。产品使用范围见价格页。
关键事实
version与platform描述客户端可用的 Telegram WebApp API 环境。viewportHeight会随手势变化，viewportStableHeight表示最近稳定状态。- Telegram 不建议用
viewportHeight让控件平滑跟随移动边界。 safeAreaInset对应设备系统界面，contentSafeAreaInset对应 Telegram 界面遮挡。- 文档标记为 Bot API 8.0+ 的安全区与全屏事件能提供可观察的变化或失败。
- 截图不能证明根因、项目归属或采购决策权。
常见问题
安全区字段在哪里？
在 Telegram 官方 Mini Apps WebApp API 的 WebApp 属性表与 Mini App 事件表中。
两个安全区字段可以互换吗？
不可以。一个描述设备系统界面边距，另一个描述不会被 Telegram 界面覆盖的内容区域。
底部控件该用哪个高度？
Telegram 指向 viewportStableHeight，并警告 viewportHeight 不足以平滑跟随移动下边缘。
怎样观察全屏不兼容？
Bot API 8.0+ 的 fullscreenFailed 可以返回 UNSUPPORTED。应同时保存事件、客户端版本和平台，不能只看页面外观。
编辑复核于 2026-08-26 完成，依据 Telegram 官方 Mini Apps WebApp API 文档。
常见问题
Telegram Mini App 的安全区字段在哪里？
在 Telegram 官方 Mini Apps WebApp API 中，查看 WebApp 的 safeAreaInset、contentSafeAreaInset 属性和对应事件表。
safeAreaInset 与 contentSafeAreaInset 一样吗？
不一样。前者考虑设备系统界面，后者表示不被 Telegram 界面元素覆盖的内容区域。
底部按钮应该跟随 viewportHeight 吗？
Telegram 警告 viewportHeight 刷新速度不足以让控件平滑跟随移动边界，并指出该场景更适合 viewportStableHeight。
怎样证明客户端不支持全屏？
在 Bot API 8.0+，fullscreenFailed 可以返回 UNSUPPORTED。单独一张截图不能证明该事件或客户端版本。
资料来源与延伸阅读
值得关注的潜在线索 Signal 是怎样被发现的
了解 Top商业线索怎样发现和整理值得核实的 Signal、保留 Telegram 原始上下文、去掉重复消息并安排查看顺序。是否跟进以及下一步做什么，仍由用户决定。