SuperAPI AI 工具集

safe-area-handling

通用与其它

查看项目

更新于 10-15 17:31

技能介绍

用途:解决 Capacitor 应用中内容被状态栏、刘海、灵动岛、挖孔、Home 指示条或 Android 导航/手势栏遮挡的问题,并处理 Android 边到边(edge-to-edge)适配。

主要能力:覆盖 iOS 全屏 WebView 的 env(safe-area-inset-*) 使用、Android Capacitor 8+ 的 SystemBars 核心插件、Android 15/16 强制边到边后的状态栏行为变化,以及横屏、分屏、iPad 窗口化下的侧边内边距问题。

必要用法:在 viewport meta 中加入 viewport-fit=cover;用 CSS 变量回退链读取安全区,例如 --sat: var(--safe-area-inset-top, env(safe-area-inset-top, 0px)),并在布局外壳统一应用,而非逐组件添加。Android 上 --safe-area-inset-* 由 SystemBars 注入,iOS 与 Web 未定义时回退到 env()。图标颜色可用 SystemBars.setStyle({ style: SystemBarsStyle.Dark })。

限制与注意:缺少 viewport-fit=cover 是 env() 为 0 的首要原因;不要与 ios.contentInset: 'always' 叠加,否则内边距翻倍;不要硬编码状态栏高度;安全区会随旋转、分屏、键盘变化,需用 CSS 或 resize 时重读;100vh 包含系统栏区域,建议用 100dvh 或固定外壳的 flex 布局;Ionic 与 Konsta 已自行处理内边距,避免重复。键盘遮挡输入应使用 capacitor-keyboard,Ionic 主题用 ionic-design,Tailwind 配置用 tailwind-capacitor。验证需在真机或模拟器上覆盖灵动岛机型、SE 类机型、iPad 旋转与窗口化、Android 15/16 手势与三键导航及横屏,并检查 Android WebView 版本是否低于 140。