1. 项目概述为什么我们需要一份窗口参数“速查手册”在 Android 应用开发中窗口Window是承载一切视觉交互的基石。无论是 Activity 的主窗口还是悬浮窗、对话框、Toast其背后都离不开一套精密的参数体系在控制。然而WindowManager.LayoutParams这个类里密密麻麻的参数常常让开发者感到头疼。gravity、flags、type、format……每个参数都像是一个旋钮调对了窗口如臂使指调错了轻则布局错乱重则引发崩溃或安全漏洞。我自己在早期开发悬浮球、画中画、自定义 Toast 或者系统级弹窗时就没少在这上面栽跟头。比如想做一个始终置顶的悬浮按钮却发现在某些手机上点击会穿透想做一个半透明的蒙层却发现背后的内容无法交互。这些问题归根结底是对窗口参数的理解不够透彻。网上的资料要么过于零散要么只讲某个特定场景缺乏一份系统性的、能放在手边随时查阅的“参数地图”。因此我决定结合自己多年的踩坑经验整理这份《Android 窗口常见参数汇总》。这不仅仅是一份 API 罗列更是一份融合了使用场景、参数组合、避坑指南的实战手册。无论你是想实现一个酷炫的悬浮窗还是仅仅想让你的 Dialog 表现得更“听话”这篇文章都能为你提供清晰的路径和可靠的参考。2. 窗口参数体系核心框架解析在深入每个参数之前我们必须先理解 Android 窗口系统的层级模型。这就像一栋大楼窗口参数决定了你的“房间”位于哪一层、有多大、窗户朝哪开、别人能不能进来。2.1 Window、WindowManager 与 LayoutParams 的关系简单来说Window是一个抽象概念代表一个可绘制的界面区域。WindowManager是系统服务负责管理和操作这些窗口比如添加、更新、移除。而WindowManager.LayoutParams以下简称LayoutParams就是递给WindowManager的“施工图纸”详细说明了这个窗口的所有属性。当你调用getWindow().getAttributes()或new WindowManager.LayoutParams()时你就在操作这份图纸。所有的窗口行为几乎都通过修改这份图纸上的参数来实现。2.2 参数分类Type、Flags、Gravity 与尺寸LayoutParams的参数虽多但可以归纳为几个核心类别它们共同决定了窗口的“身份”、“行为”、“位置”和“外观”。类型Type决定了窗口的层级Z-order。系统预定义了从TYPE_APPLICATION应用普通窗口到TYPE_SYSTEM_ALERT系统警告窗口等一系列常量。层级越高窗口越靠前显示。这是窗口参数中最关键也最容易出错的部分。标志Flags控制窗口的交互行为和显示特性。例如是否可点击FLAG_NOT_TOUCHABLE是否保持屏幕常亮FLAG_KEEP_SCREEN_ON是否允许窗口超出屏幕FLAG_LAYOUT_NO_LIMITS。重力Gravity决定了窗口在屏幕上的初始锚点位置。它和x、y参数配合使用。例如Gravity.LEFT | Gravity.TOP表示窗口的左上角将位于(x, y)坐标点。尺寸与格式width、height定义窗口宽高可以是具体像素值也可以是MATCH_PARENT、WRAP_CONTENT。format定义像素格式如PixelFormat.TRANSLUCENT用于透明背景它会影响渲染效率。理解这个框架后我们再逐一拆解每个核心参数并配上实战代码和场景分析。3. 核心参数深度剖析与实战应用3.1 窗口类型Type定义你的窗口“阶层”窗口类型是LayoutParams中最首要的参数它用一个整型值表示值越大窗口在 Z 轴上的层级越高越能覆盖其他窗口。从 Android 8.0API 26开始窗口类型管理变得更加严格主要分为应用窗口、子窗口和系统窗口三大类。常见类型详解TYPE_APPLICATION(默认值2): 标准应用窗口。Activity 的主窗口就是此类型。它必须依附于一个 Activity。TYPE_APPLICATION_PANEL/TYPE_APPLICATION_SUB_PANEL(1000-1999): 应用子窗口。必须指定token通常来自父窗口并显示在父窗口之上。常用于应用内的弹出菜单、自定义对话框。TYPE_APPLICATION_OVERLAY(2038):这是实现全局悬浮窗的关键类型。从 Android 8.0 起旧的TYPE_SYSTEM_ALERT等类型不再对普通应用开放TYPE_APPLICATION_OVERLAY成为唯一选择。它不需要Activity但需要动态申请SYSTEM_ALERT_WINDOW权限并且窗口会显示在所有其他应用之上但仍在系统状态栏和导航栏之下。重要提示使用TYPE_APPLICATION_OVERLAY时必须确保LayoutParams的type字段精确设置为2038。在代码中应始终使用WindowManager.LayoutParams.TYPE_APPLICATION_OVERLAY这个常量而非硬编码数字以保证兼容性。TYPE_TOAST(2005): 用于系统 Toast。在 Android 7.1API 25及以前应用可以模拟 Toast 实现无需权限的悬浮窗但后续版本此漏洞已被修复。现在普通应用已无法直接使用此类型。实战场景创建一个全局悬浮按钮// 在 Service 或拥有悬浮窗权限的上下文中 val layoutParams WindowManager.LayoutParams().apply { // 关键设置为 OVERLAY 类型 type WindowManager.LayoutParams.TYPE_APPLICATION_OVERLAY // 其他参数设置... width WindowManager.LayoutParams.WRAP_CONTENT height WindowManager.LayoutParams.WRAP_CONTENT flags ... gravity Gravity.START or Gravity.TOP x 100 y 300 } val floatView LayoutInflater.from(context).inflate(R.layout.float_button, null) windowManager.addView(floatView, layoutParams)避坑经验权限是前提使用TYPE_APPLICATION_OVERLAY必须在 Manifest 声明uses-permission android:nameandroid.permission.SYSTEM_ALERT_WINDOW /并在运行时动态申请和检查。部分国产 ROM 对此权限管理极其严格可能需要引导用户手动在系统设置中开启。层级限制TYPE_APPLICATION_OVERLAY窗口无法覆盖系统状态栏、导航栏、输入法以及锁屏界面。不要试图用它来做“全屏覆盖”式的恶意应用。Token 依赖TYPE_APPLICATION及其子窗口类型必须关联一个有效的token通常来自 Activity。如果你在非 Activity 上下文如 Service中创建这类窗口会导致BadTokenException。3.2 窗口标志Flags精细控制窗口行为Flags 通过位运算|进行组合可以同时启用多个特性。它们是实现特定交互效果的法宝。核心 Flags 解析Flag 常量值作用与场景注意事项FLAG_NOT_FOCUSABLE8窗口不获取输入焦点。用户点击时焦点和软键盘会传递给下层的窗口。悬浮窗标配。防止悬浮窗拦截全局触摸事件。常与FLAG_NOT_TOUCH_MODAL搭配。FLAG_NOT_TOUCH_MODAL16窗口区域外的触摸事件传递给下层窗口区域内的事件自己处理。实现非模态、可穿透点击的悬浮窗关键。必须和FLAG_NOT_FOCUSABLE一起使用。FLAG_WATCH_OUTSIDE_TOUCH0x40000允许接收发生在窗口区域外的触摸事件MotionEvent.ACTION_OUTSIDE。用于实现“点击外部关闭”的逻辑但只能收到 DOWN 事件且坐标可能不准确。FLAG_LAYOUT_NO_LIMITS512允许窗口内容延伸到屏幕边界之外。可用于实现“可部分拖出屏幕”的悬浮窗。设置后x/y可以为负值。FLAG_LAYOUT_IN_SCREEN1024窗口占用的区域将包含系统装饰栏状态栏占据的空间。常用于希望窗口从状态栏下边缘开始布局的场景。FLAG_KEEP_SCREEN_ON128只要窗口可见就保持屏幕常亮。用于视频播放、导航等场景。更推荐在 View 层级使用setKeepScreenOn。FLAG_DIM_BEHIND2使窗口后面的所有内容变暗。实现 Dialog 的背景遮罩效果。需要通过dimAmount参数0.0-1.0控制变暗程度。FLAG_SECURE8192禁止截屏、录屏并阻止内容出现在非安全显示器上。用于支付、隐私等敏感界面。在addView后设置此 Flag 可能无效需在创建时指定。实战场景实现一个可交互且不干扰其他操作的悬浮窗layoutParams.flags (WindowManager.LayoutParams.FLAG_NOT_FOCUSABLE or WindowManager.LayoutParams.FLAG_NOT_TOUCH_MODAL or WindowManager.LayoutParams.FLAG_WATCH_OUTSIDE_TOUCH) // 解释 // FLAG_NOT_FOCUSABLE: 悬浮窗不抢焦点下层应用可正常操作。 // FLAG_NOT_TOUCH_MODAL: 悬浮窗区域外点击穿透区域内可拖动。 // FLAG_WATCH_OUTSIDE_TOUCH: 监听外部点击用于实现“点击悬浮窗外部区域关闭”的逻辑。避坑经验Flag 组合的副作用FLAG_NOT_TOUCHABLE完全不可点击与FLAG_NOT_FOCUSABLE、FLAG_NOT_TOUCH_MODAL是互斥的。一旦设置了FLAG_NOT_TOUCHABLE窗口将完全无法响应任何触摸事件。FLAG_WATCH_OUTSIDE_TOUCH的局限它只能收到ACTION_OUTSIDE的 DOWN 事件没有 MOVE 和 UP 事件且坐标是相对于屏幕的原始坐标处理起来比较麻烦。对于复杂的“外部点击关闭”逻辑有时不如直接在下层窗口添加一个透明遮罩 View 来得可靠。动态更新 Flags通过windowManager.updateViewLayout(view, newLayoutParams)可以动态更新参数。但请注意某些 Flag如FLAG_SECURE可能在窗口添加后无法生效。3.3 重力Gravity、坐标x, y与尺寸width, height这部分参数决定了窗口的几何属性。gravity: 定义了x和y值的参考系。默认是Gravity.LEFT | Gravity.TOP即(x, y)表示窗口左上角的位置。如果设置为Gravity.CENTER那么(x, y)就表示窗口中心的坐标。在结合FLAG_LAYOUT_NO_LIMITS时理解 gravity 尤为重要。x / y: 窗口的初始位置偏移量单位是像素。其意义由gravity决定。注意这里的坐标系原点(0,0)是屏幕的左上角不包括系统状态栏。width / height: 可以是具体的像素值也可以是MATCH_PARENT、WRAP_CONTENT或WindowManager.LayoutParams中定义的一些特殊常量如MATCH_PARENT、WRAP_CONTENT。特殊尺寸常量WindowManager.LayoutParams.MATCH_PARENT: 充满父容器通常是整个屏幕。WindowManager.LayoutParams.WRAP_CONTENT: 包裹内容。WindowManager.LayoutParams.TYPE_APPLICATION_OVERLAY的默认限制对于悬浮窗类型其width和height默认不能设为MATCH_PARENT必须指定具体值或WRAP_CONTENT。这是系统为防止恶意应用全屏覆盖而做的限制。实战场景将悬浮窗定位到屏幕右下角val metrics DisplayMetrics() windowManager.defaultDisplay.getMetrics(metrics) val screenWidth metrics.widthPixels val screenHeight metrics.heightPixels layoutParams.apply { gravity Gravity.END or Gravity.BOTTOM // 锚点设为右下角 x 0 // 因为 gravity 是 ENDx0 表示距离屏幕右边缘 0 像素即紧贴右边缘 y 0 // 因为 gravity 是 BOTTOMy0 表示距离屏幕下边缘 0 像素即紧贴下边缘 // 如果要留出边距可以设置 x -dpToPx(16), y -dpToPx(16) width WindowManager.LayoutParams.WRAP_CONTENT height WindowManager.LayoutParams.WRAP_CONTENT }3.4 其他关键参数format: 像素格式。最常用的是PixelFormat.TRANSLUCENT用于支持透明背景的窗口。对于不透明的窗口通常可以设置为PixelFormat.OPAQUE或PixelFormat.RGB_565等。注意设置透明格式可能会带来额外的性能开销。alpha: 窗口的整体透明度范围 0.0f完全透明到 1.0f完全不透明。注意此属性在 Android 4.0 以下版本可能不支持。dimAmount: 当FLAG_DIM_BEHIND启用时此值控制后面内容的变暗程度0.0f - 1.0f。0.0 不变暗1.0 完全变黑。softInputMode: 控制软键盘与窗口的交互方式。这是另一个庞大的话题常见值有SOFT_INPUT_STATE_VISIBLE进入时显示键盘、SOFT_INPUT_ADJUST_RESIZE窗口调整大小以适应键盘、SOFT_INPUT_ADJUST_PAN窗口平移以适应键盘。通常对 Activity 的主窗口设置更有效。4. 典型场景参数配置模板光讲理论不够这里提供几个高频场景的“开箱即用”参数模板。4.1 场景一全屏沉浸式 Activity 窗口// 在 Activity 的 onCreate 中调用 window.apply { // 1. 清除系统装饰状态栏、导航栏 decorView.systemUiVisibility (View.SYSTEM_UI_FLAG_FULLSCREEN or View.SYSTEM_UI_FLAG_HIDE_NAVIGATION or View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY) // 2. 设置窗口标志允许内容延伸到状态栏/导航栏后面 addFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN) addFlags(WindowManager.LayoutParams.FLAG_LAYOUT_NO_LIMITS) // 关键允许内容全屏绘制 // 3. 设置透明状态栏和导航栏Android 5.0 效果更佳 statusBarColor Color.TRANSPARENT navigationBarColor Color.TRANSPARENT // 4. 确保内容可绘制到系统栏区域 decorView.setOnApplyWindowInsetsListener { v, insets - // 处理 insets调整你的内容布局 v.onApplyWindowInsets(insets) } }4.2 场景二应用内模态对话框Dialogval dialog Dialog(context).apply { // 1. 设置内容视图 setContentView(R.layout.dialog_custom) // 2. 获取 Window 并设置参数 window?.apply { // 类型应用子窗口 attributes attributes?.apply { type WindowManager.LayoutParams.TYPE_APPLICATION // 尺寸 width WindowManager.LayoutParams.MATCH_PARENT // 或具体值 height WindowManager.LayoutParams.WRAP_CONTENT // 位置居中 gravity Gravity.CENTER // 行为背景变暗可点击外部取消需Dialog自身支持 flags flags or WindowManager.LayoutParams.FLAG_DIM_BEHIND dimAmount 0.5f // 半透明遮罩 } // 3. 设置进入退出动画 setWindowAnimations(R.style.DialogAnimation) } // 4. 其他Dialog属性 setCancelable(true) setCanceledOnTouchOutside(true) } dialog.show()4.3 场景三全局可拖动、可穿透点击的悬浮窗这是最复杂的场景参数组合至关重要。fun createOverlayLayoutParams(): WindowManager.LayoutParams { return WindowManager.LayoutParams().apply { // ---- 身份与层级 ---- type WindowManager.LayoutParams.TYPE_APPLICATION_OVERLAY // API 26 // 对于旧版本兼容需处理权限差异 // if (Build.VERSION.SDK_INT Build.VERSION_CODES.O) { // type WindowManager.LayoutParams.TYPE_APPLICATION_OVERLAY // } else { // type WindowManager.LayoutParams.TYPE_SYSTEM_ALERT // } // ---- 尺寸与格式 ---- width WindowManager.LayoutParams.WRAP_CONTENT height WindowManager.LayoutParams.WRAP_CONTENT format PixelFormat.TRANSLUCENT // 支持透明背景 // ---- 行为标志核心组合---- flags (WindowManager.LayoutParams.FLAG_NOT_FOCUSABLE // 不获取焦点下层应用可操作 or WindowManager.LayoutParams.FLAG_NOT_TOUCH_MODAL // 非模态区域外点击穿透 // or WindowManager.LayoutParams.FLAG_WATCH_OUTSIDE_TOUCH // 可选监听外部点击 or WindowManager.LayoutParams.FLAG_LAYOUT_NO_LIMITS) // 可选允许拖出屏幕 // ---- 初始位置 ---- gravity Gravity.START or Gravity.TOP x 100 // 初始X偏移 y 100 // 初始Y偏移 } } // 使用在 Service 中 val floatView // ... 初始化你的悬浮窗视图 val params createOverlayLayoutParams() windowManager.addView(floatView, params) // 实现拖动在 floatView 的 OnTouchListener 中 floatView.setOnTouchListener { v, event - when (event.action) { MotionEvent.ACTION_DOWN - { // 记录触摸点相对视图左上角的偏移 downX event.rawX - params.x downY event.rawY - params.y } MotionEvent.ACTION_MOVE - { // 更新窗口位置 params.x (event.rawX - downX).toInt() params.y (event.rawY - downY).toInt() windowManager.updateViewLayout(floatView, params) } } true // 消费事件使拖动流畅 }5. 疑难杂症排查与性能优化即使参数设置正确在实际开发中仍会遇到各种奇怪的问题。这里记录一些典型的“坑”和解决方案。5.1 常见问题速查表问题现象可能原因排查与解决方案悬浮窗无法显示1. 未申请或未授予SYSTEM_ALERT_WINDOW权限。2.type设置错误如低于 API 26 用了TYPE_APPLICATION_OVERLAY。3. 在后台线程更新 UI。1. 使用Settings.canDrawOverlays(context)检查权限并引导用户开启。2. 根据 API 版本使用正确的 type。3. 确保addView和updateViewLayout在主线程调用。悬浮窗点击无响应1. 设置了FLAG_NOT_TOUCHABLE。2. 悬浮窗视图本身或其子 View 设置了clickablefalse或拦截了事件。3. 窗口width/height为 0。1. 检查 flags确保未设置FLAG_NOT_TOUCHABLE。2. 检查 View 的onTouchEvent和onInterceptTouchEvent。3. 确保视图有有效尺寸。悬浮窗点击事件穿透到下层应用未正确设置FLAG_NOT_FOCUSABLE和FLAG_NOT_TOUCH_MODAL。确保 flags 包含 FLAG_NOT_FOCUSABLE窗口位置更新无效或闪烁1. 频繁调用updateViewLayout如每帧更新。2.x/y值计算有误如坐标系混淆。1. 对拖动等操作进行节流避免高频更新。2. 使用event.rawX/Y屏幕坐标而非event.x/y视图坐标计算偏移。窗口背景变黑或不透明format未设置为PixelFormat.TRANSLUCENT或视图背景未设为透明。1. 设置params.format PixelFormat.TRANSLUCENT。2. 检查根布局背景是否为android:color/transparent或#00000000。在 Android 10 上悬浮窗无法在其他应用上方显示从 Android 10 开始对SYSTEM_ALERT_WINDOW权限的管理更加严格。除了动态申请部分系统如 MIUI、EMUI需要在“应用信息-权限-显示悬浮窗”中单独开启甚至需要在“特殊权限”中设置。必须提供清晰的引导。BadTokenException异常尝试使用TYPE_APPLICATION或其子类型但未提供有效的 Activity token或在错误的上下文如 Service中创建。确保窗口类型与上下文匹配。应用内窗口使用 Activity 的 token全局悬浮窗使用TYPE_APPLICATION_OVERLAY并在合适的上下文如 Service中创建。5.2 性能与内存优化建议视图层级扁平化悬浮窗的 View 树应尽可能简单。过度复杂的布局和频繁的测量/布局measure/layout会导致拖拽卡顿。考虑使用自定义 View 进行绘制。避免频繁更新布局参数windowManager.updateViewLayout()是一个相对昂贵的操作。在实现拖拽时不要在每个ACTION_MOVE事件中都调用可以适当节流或者积累一定的位移后再更新。及时移除视图当悬浮窗不再需要时如 Service 销毁时务必调用windowManager.removeView(view)。否则会导致内存泄漏和视图残留。谨慎使用动画在悬浮窗上运行复杂的属性动画可能会引起性能问题尤其是在低端设备上。优先使用ViewPropertyAnimator或硬件加速层。处理好配置变更屏幕旋转、分辨率变化会导致窗口坐标系改变。需要监听Configuration变化并重新计算和更新悬浮窗的位置否则悬浮窗可能会显示在错误的位置。5.3 关于“滑动窗口”与“模态窗口”的延伸思考在提供的热词中出现了“滑动窗口”和“模态窗口”。在 Android 窗口上下文中它们有特定含义滑动窗口通常不是指一个系统窗口类型而是一种交互设计模式。例如一个可以从屏幕边缘滑出如侧边栏导航或可拖动的悬浮窗。其实现核心就是结合OnTouchListener监听手势并动态更新LayoutParams中的x和y坐标。模态窗口指一种阻断式窗口它要求用户必须与之交互后才能继续操作后面的内容。系统AlertDialog就是典型的模态窗口。在参数上它通常不会设置FLAG_NOT_FOCUSABLE和FLAG_NOT_TOUCH_MODAL以确保自己能获取焦点并拦截所有触摸事件。同时常配合FLAG_DIM_BEHIND来突出显示。理解这些概念有助于我们在设计窗口交互时选择正确的参数组合。一个可滑动的侧边栏可能是应用子窗口TYPE_APPLICATION_PANEL而一个可拖动的全局工具则必须是TYPE_APPLICATION_OVERLAY。窗口参数是 Android GUI 系统的底层控制枢纽精确地理解并组合它们是实现高级 UI 特效和交互的基础。这份汇总旨在将散落各处的知识点串联成网并提供经过验证的实战模板。在实际开发中最有效的学习方式仍然是亲手实验创建一个测试项目修改参数观察现象并对照本文分析原因。当你能够预判参数改变带来的效果时你就真正掌握了 Android 窗口的奥秘。