WebToApp 悬浮窗Floating Window模式完全指南配置项详解、系统权限与源码实现原理【免费下载链接】web-to-appThe most full featured web-to-app toolkit on Android, a complete APK workshop that runs entirely on your phone项目地址: https://gitcode.com/GitHub_Trending/web/web-to-app本篇指南围绕 WebToApp 项目中 floating-window.md 所定义的「悬浮窗模式」展开讲解如何在Edit Common Config编辑器中通过Floating window卡片把一个 Web 应用以可自由缩放、可最小化、可吸附屏幕边缘的悬浮窗形态运行在其他应用之上。读完本文你将掌握floatingWindowConfig的全部配置字段、各枚举取值宽高比与边框样式、系统悬浮窗权限的授予流程以及前端配置卡片、运行时服务FloatingWindowService与导出链路ApkConfigJsonFactory之间的完整调用关系。功能概览与适用场景悬浮窗模式的核心能力是不退出当前 App也能同时使用另一个 Web 应用。典型场景包括看视频 / 直播的同时用悬浮小窗继续浏览网页内容聊天类、文档类 Web 应用以画中画Picture-in-Picture形态常驻屏幕角落临时把一个网页最小化为可拖动的圆形按钮需要时一键还原。从 FloatingWindowService.kt 的实现看悬浮窗本质是一个**前台服务foreground service**叠加的TYPE_APPLICATION_OVERLAY窗口窗口内部承载一个完整配置过的 WebView含下载桥、翻译桥、原生桥等能力。因此它不仅适合纯网页也能承载 PHP、Python、Go、Node.js、WordPress 等需要服务端运行时的应用类型。配置入口Edit Common Config 中的 Floating Window 卡片在应用编辑器的Edit Common Config页中找到Floating window卡片打开顶部的启用开关即可进入悬浮窗模式配置。该卡片的 UI 由 FloatingWindowConfigCard.kt 实现卡片内按Size尺寸→ Appearance外观→ Behavior行为→ Advanced高级四个区块组织所有可调项。配置数据在内存中统一建模为FloatingWindowConfig定义于 WebApp.kt所有字段都有默认值这意味着你可以只改其中一两个字段其余行为保持默认。配置项详解Enable —— 总开关对应floatingWindowConfig.enabled默认false。只有该字段为true时导出/运行时才会以悬浮窗形态启动应用关闭则走常规全屏 WebView 模式。Size —— 窗口尺寸与宽高比尺寸相关字段及其默认值如下字段默认值说明windowSizePercent80统一尺寸百分比宽高同步缩放widthPercent/heightPercent80/80独立宽 / 高百分比lockAspectRatiofalse是否锁定宽高比aspectRatioModeFREE宽高比模式见下customAspectRatioWidth/customAspectRatioHeight16/9自定义宽高比仅CUSTOM模式生效在 UI 卡片中宽度滑条范围为30%100%仅当宽高比模式为FREE时才会显示独立的高度滑条。选择任意非FREE的宽高比模式时卡片会自动把lockAspectRatio置为true。FloatingWindowAspectRatioMode枚举WebApp.kt支持以下取值枚举值含义SCREEN跟随屏幕宽高比FREE自由缩放默认RATIO_16_916:9RATIO_9_169:16竖屏视频友好RATIO_4_34:3SQUARE1:1CUSTOM自定义宽:高滑条范围 132文档强调默认是自由缩放lockAspectRatio false、FREE拖拽窗口四角可以任意改变形状一旦锁定宽高比缩放时会被约束在该比例内。从源码看这个逻辑由 FloatingWindowManager.kt 中的resolveAspectRatio()与calculateBoundedAspectSize()实现FREE返回null不约束其余模式返回对应比例值并在宽/高方向做有界换算。值得注意的一个细节是SCREEN模式只有在lockAspectRatio true时才按屏幕比例生效否则会被降级为FREE处理。窗口的实际最小尺寸在运行时也有硬约束拖动缩放手柄时最小宽度为屏幕宽度的 25%、最小高度为屏幕高度的 20%且不会超过屏幕边界见createResizeHandle()与clampWindowParamsToScreen()。Appearance —— 外观字段默认值取值范围说明opacity10030100%悬浮窗整体不透明度cornerRadius16032dp窗口圆角半径borderStyleSUBTLE见下边框样式FloatingBorderStyle枚举WebApp.kt共 4 档其视觉差异在 FloatingWindowManager.kt 的createStyledBackground()中体现枚举值视觉效果NONE无边框SUBTLE2px 深色细边框#333355默认档GLOW3px 亮蓝边框#6666FF视觉上带发光感ACCENT3px 紫色强调边框#8B5CF6不透明度opacity会直接映射到WindowManager.LayoutParams.alphaopacity / 100f属于窗口级透明整窗含 WebView 内容都会随之变淡。Title bar —— 标题栏字段默认值说明showTitleBartrue是否显示标题栏autoHideTitleBarfalse是否自动隐藏标题栏仅显示时生效标题栏高度固定为 40dp布局模仿 macOS 风格左侧是三个「红黄绿」圆形按钮关闭 / 最小化 / 全屏切换中间显示应用名空则显示 WebToApp右侧是返回‹与前进›两个导航按钮。返回/前进按钮的可用态由updateNavigationButtons()根据webView.canGoBack()/canGoForward()实时刷新不可用时置灰、透明度降到 0.35。开启autoHideTitleBar后标题栏会在 3 秒无操作后上滑淡出AUTO_HIDE_TITLE_DELAY_MS 3000L用户一旦触摸窗口任意位置即恢复显示。若关闭标题栏且未锁定位置窗口顶部会出现一条 22dp 高的拖拽条带⠿指示符保证依然可以拖动窗口。Minimized —— 最小化行为字段默认值说明startMinimizedfalse启动时直接进入最小化状态minimizedIconPathnull自定义最小化图标路径minimizedIconSizePercent100最小化按钮尺寸百分比50100minimizedIconEdgeDockingfalse最小化图标是否吸附屏幕边缘最小化按钮的基础尺寸为 56dp乘以minimizedIconSizePercent / 100得到最终大小。图标支持三种来源见loadMinimizedIconBitmap()content://URI、绝对路径、assets/相对路径未配置时使用默认的 图形。开启minimizedIconEdgeDocking后按钮会以 180ms 的带过冲Overshoot动画滑向最近屏幕边缘并只露出 50% 的宽度/高度MINI_BUTTON_EDGE_VISIBLE_RATIO 0.5f形成「贴边收窄」的常驻效果。点击按钮即可还原窗口还原位置由最小化按钮位置反推居中计算。Behavior —— 行为与高级选项字段默认值说明rememberPositiontrue记住窗口位置下次启动恢复edgeSnappingtrue拖动松手时吸附屏幕边缘showResizeHandletrue右下角显示缩放手柄lockPositionfalse锁定位置禁止拖动记住位置窗口坐标写入SharedPreferences文件floating_window_prefs键position_x/position_y下次启动时优先恢复上次坐标并做屏幕边界钳制首次启动默认居中。边缘吸附拖动松手后若窗口任一边距屏幕边缘小于 60pxEDGE_SNAP_THRESHOLD_PX会以 200ms 动画平滑吸附到对应边缘performEdgeSnap()。缩放手柄28dp 大小的◢手柄固定在窗口右下角拖动时按当前宽高比模式实时更新LayoutParams。锁定位置开启后标题栏/拖拽条不再响应拖动手势setupDragHandler只在!config.lockPosition时挂载。这些开关都集中在卡片底部「Advanced」折叠区属于进阶调优项。运行前提系统悬浮窗权限文档明确提示悬浮窗运行需要系统悬浮窗overlay权限。这是 Android 的安全限制不是应用内开关能绕过的。权限的检查与请求封装在 FloatingWindowService.kt 的伴生对象中canDrawOverlays(context)API 23Android 6.0及以上通过Settings.canDrawOverlays()检查以下直接放行requestOverlayPermission(context)跳转Settings.ACTION_MANAGE_OVERLAY_PERMISSION带package:参数引导用户手动授权。在实际启动链中ShellActivity.kt 会先检查权限已授权则直接launchFloatingWindowAndFinish()未授权则发起请求并把启动动作挂起到pendingFloatingWindowLaunch待用户授权返回后onResume中再次检查再补启动。窗口本身使用TYPE_APPLICATION_OVERLAYAndroid 8.0或旧版TYPE_PHONE类型创建并常驻一条低优先级前台通知channelfloating_window_channel可一键关闭悬浮窗。源码级实现从配置到窗口的完整链路1. 配置建模所有配置字段收敛在 FloatingWindowConfig 这一个 data class 中直接以 Gson 序列化传递。它既用于宿主 App 的编辑器也用于导出 APK 后的运行时解析JSON 键名与字段名一一对应。2. 运行时启动链路悬浮窗由前台服务 FloatingWindowService.kt 驱动通过 Intent Extra 传递配置ShellActivity.launchFloatingWindowAndFinish() → startForegroundService(FloatingWindowService, ACTION_SHOW) → 解析 EXTRA_CONFIG(JSON) → FloatingWindowConfig → 组装 WebView 配置器翻译桥/下载桥/原生桥/扩展模块/伪装配置 → FloatingWindowManager.show(config, appName, url)服务支持 4 种动作ACTION_SHOW显示、ACTION_DISMISS关闭并停服、ACTION_MINIMIZE、ACTION_RESTORE后两个供外部如通知、辅助入口控制窗口状态。服务以START_NOT_STICKY返回销毁时会依次停止服务端运行时、释放 WebView、移除全部悬浮视图。3. 服务端运行时应用类型若目标应用属于PHP_APP/PYTHON_APP/GO_APP/NODEJS_APP/WORDPRESS服务会先以about:blank显示空窗口再通过ShellServerLauncher.resolveServerBackedTargetUrl()异步拉起对应服务端运行时拿到真实 URL 后注入 WebViewneedsServerStartup() 协程分支。这意味着悬浮窗模式不是网页专属而是完整复用了 WebToApp 的本地运行时体系。4. 导出与持久化导出 APK 时ApkConfigJsonFactory.kt 会把FloatingWindowConfig全量字段写入floatingWindowConfigJSON 块对应测试 ApkConfigJsonFactoryTest.kt 验证了aspectRatioMode RATIO_16_9、customAspectRatioWidth 21、customAspectRatioHeight 9、minimizedIconSizePercent 70、minimizedIconEdgeDocking true等取值能无损往返。而 ShellWebViewConfig.kt 则展示了从 ShellConfig 反解出运行时FloatingWindowConfig的兼容性处理枚举解析失败时回退到「锁比例则 SCREEN、否则 FREE」的兜底策略边框解析失败回退SUBTLE。限制与注意事项权限是硬前提未授予系统悬浮窗权限时窗口无法显示授权入口在系统设置页代码无法静默获取前台服务限制在 targetSdk 34 上后台直接启动前台服务可能被系统拒绝ShellActivity已捕获该异常并记录日志实际使用建议从应用前台触发焦点与输入法窗口默认FLAG_NOT_FOCUSABLE不抢焦点、不弹输入法当页面内输入框获得焦点时通过注入的IME_FOCUS_TRACKER_JS桥接动态切换焦点状态以唤起输入法失焦后自动释放——这是悬浮窗场景下保证「悬浮但不打扰」的关键设计部分 Web 能力受限从FloatingWindowService的WebViewCallbacks回调可看到文件选择、地理定位、权限请求在悬浮窗中默认被拒绝/关闭属于有意的精简策略尺寸与比例钳制窗口百分比在 30%100% 之间比例锁定后按宽/高方向有界换算不会出现窗口越界或无限缩小。小结悬浮窗模式是 WebToApp 面向「多任务并行」场景的关键能力。通过 Edit Common Config 中的 Floating window 卡片你可以像配置一个桌面级画中画窗口一样精确控制尺寸、宽高比、外观、标题栏、最小化行为与吸附逻辑底层则由FloatingWindowConfig → FloatingWindowService → FloatingWindowManager → WindowManager的四层链路承载从编辑器配置到导出 APK 后的运行时表现保持完全一致。掌握本文的字段语义与权限流程即可在自己的 Web 应用中一键启用可缩放、可最小化、可贴边的悬浮窗体验。【免费下载链接】web-to-appThe most full featured web-to-app toolkit on Android, a complete APK workshop that runs entirely on your phone项目地址: https://gitcode.com/GitHub_Trending/web/web-to-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考