上周三凌晨一点，灰度包又把我从床上叫起来，崩溃栈第一行赫然是android.view.WindowManager$BadTokenException: Unable to add window -- token null is not valid; is your activity running?。查下去发现是一个促销弹窗在 Activity 已经finish()之后才被show()出来。这类问题在我做 Android 实现 Dialog 自定义弹窗功能这些年里反复出现，原生AlertDialog满足不了设计稿上那套圆角、渐变遮罩、底部滑入的需求，业务方又要一个能复用的组件，于是就自己从头撸一套。这篇东西记录的就是我踩完坑之后沉淀下来的完整做法：从 Window 层级、主题样式、布局尺寸策略，到一个可直接抄的封装，再到那些文档里绝不会写的排查经验。适合两种情况的人看——刚接触 Dialog 想搞清楚它到底怎么运作的新手，以及已经在用但被圆角、软键盘、崩溃折腾过的老手。
1. 为什么我最终放弃了原生 AlertDialog，改走自定义 Dialog 路线
1.1 三个真实场景暴露的原生短板
原生AlertDialog的定位很明确：系统级的确认框，标题 + 内容 + 两三个按钮。设计稿一旦跳出这个范式，它就撑不住了。我遇到的第一个场景是活动弹窗，要求整块内容是一张带立体渐变的活动图，底部两个圆角按钮紧贴图片下沿，四周 24dp 圆角，遮罩用 60% 黑色。AlertDialog的setView()虽然能塞进去自定义布局，但它的容器自带内边距和dialog_min_widthMajor的最小宽度限制，塞进去的图左右永远留着一条灰边，用setBackgroundDrawable(null)能去掉背景，可内边距还得靠getWindow().getDecorView().setPadding(0,0,0,0)手动抹，抹完又发现弹窗宽度是wrap_content，图片按比例缩放后在不同屏幕上大小飘忽，最后还是要回到window.setLayout()去重新指定尺寸——绕了一大圈，等于把 AlertDialog 拆了重装。
第二个场景是底部抽屉式的分享面板，从屏幕底部滑上来，宽度必须是MATCH_PARENT，圆角只在上面两个角，还要能在弹起时把后面的页面压暗、点击外部区域收起。这个需求本质上是把弹窗当成一个"半屏浮层"在用，AlertDialog的浮动窗口模型（windowIsFloating=true）天生不支持贴边，得改主题关掉浮动属性，那还不如直接继承Dialog干净。
第三个场景最麻烦，是一个带输入框的评论弹窗。键盘弹起来之后，弹窗要跟着上移，输入框不能被挡住，同时弹窗本身高度是自适应的（多行输入会长高）。AlertDialog里处理软键盘要先拿到window.setSoftInputMode(SOFT_INPUT_ADJUST_RESIZE)，但这个标志只有在窗口不是浮动状态、且有足够空间的时候才真正生效，Android 11 之后配合WindowInsets的边距计算又变了逻辑。实测下来，浮动 Dialog 在键盘弹出时更容易出现"窗口被顶出屏幕外一半"或者"键盘遮住按钮"的情况。
这三个场景共同的结论是：只要设计稿超出了"标题 + 文案 + 按钮"的范围，就不要再试图改造AlertDialog，它的封装成本和自定义Dialog差不多，但可控性差一大截。自定义Dialog的核心优势在于你能完整掌控Window——宽度、重力方向、遮罩透明度、进出场动画、背景透明与否、软键盘模式，全都是一行参数的事。
1.2 Dialog、DialogFragment、PopupWindow、BottomSheetDialog 怎么选
这是我最常被问到的问题，其实四者的定位差异非常清晰，选错了后面全是坑。我整理了一张对照表，按我自己项目的实际使用感受填的：
| 方案 | 适用场景 | 生命周期管理 | 状态恢复 | 主要痛点 |
|---|---|---|---|---|
Dialog自定义 | 全屏浮层、底部面板、复杂自定义布局 | 需手动管理，容易泄漏 | 不支持，旋转丢失 | 崩溃、泄漏靠自觉 |
DialogFragment | 需要跟随页面重建的弹窗、复用度高的弹窗 | FragmentManager 托管 | 支持，自动重建 | 通信繁琐，show时机受限 |
PopupWindow | 锚定某个 View 的小气泡、下拉菜单 | 依附于锚点 View | 不支持 | 位置计算难，遮挡问题多 |
BottomSheetDialog | 标准底部抽屉、可拖拽收缩 | Dialog 基础上加行为 | 部分支持 | 拖拽行为与内容滚动冲突 |
我的实际取舍是这样的：需要用 Application 级别的 Context 弹出来、或者弹窗内容完全独立于页面状态的，用自定义Dialog；需要跟随 Activity 重建、或者弹窗内部有表单状态的，一律用DialogFragment。PopupWindow我基本只在做"点击某个图标弹出小菜单"时用，因为它需要一个锚点，位置计算和showAsDropDown的边界翻转逻辑足够写一篇文章。BottomSheetDialog适合标准化的抽屉交互，但你要是在里面放一个竖向RecyclerView，手势冲突会让人抓狂——它想拖拽，列表想滚动，得靠BottomSheetBehavior的isHideable和嵌套滚动开关来协调。
还有一个容易被忽略的点：PopupWindow在 Android 7.0 之前因为PopupWindow内部实现的差异，showAsDropDown在部分机型上会出现位置偏移，需要手动算getLocationOnScreen补偿。如果你的目标版本还覆盖这些老系统，这个坑得提前知道。
一句话总结选型原则：内容驱动选型，而不是反过来。先看你的弹窗长什么样、有什么交互，再回去套上面这张表，别拿着DialogFragment硬做全屏广告页，也别用Dialog去做带复杂表单的注册流程。
2. 自定义 Dialog 的骨架：从 Window 到 View 的完整链路
2.1 Dialog 的内部构造与窗口层级
要写出稳定的自定义弹窗，得先搞清楚Dialog到底帮你做了什么。Dialog本身不是View，它持有的是一个Window（实际是PhoneWindow），Window里挂了一棵DecorView树，你在setContentView()里传进去的布局，最终被塞进DecorView里的内容区域。弹窗显示到屏幕上，靠的是WindowManager.addView(decorView, layoutParams)这一步，而WindowManager是系统服务，它要验证这个窗口的 token 有没有权限——这就是BadTokenException的根源。
Dialog的Window参数里有几个字段决定了弹窗的最终形态，我在调试时经常打印它们确认：
width/height：默认是WRAP_CONTENT，这就是为什么你布局里写match_parent却只占中间一小块。gravity：默认居中，Gravity.BOTTOM就是底部弹窗。dimAmount：后面的遮罩透明度，0 到 1，必须配合FLAG_DIM_BEHIND生效。flags：FLAG_DIM_BEHIND控制遮罩，FLAG_LAYOUT_NO_LIMITS允许超出屏幕边界，FLAG_NOT_FOCUSABLE会让键盘无法弹出。softInputMode：软键盘交互模式，底部输入框弹窗必配。
这些参数的最佳设置时机是show()调用之后——这一点很多人不知道。show()内部会走onStart()，然后才把DecorView真正添加到WindowManager，在此之前你对window的某些属性修改，可能被后续流程覆盖。我实测过setDimAmount：如果在show()之前设置，某些版本上确实生效，但更稳妥的写法是show()之后立刻设置，尤其是你需要动态计算尺寸的时候。而setWindowAnimations则更推荐写进主题，因为它是从windowAnimationStyle属性读的，运行时设置偶尔会失效。
还有一个必须理解的概念是主题。new Dialog(context)用什么主题，取决于传入context的主题里dialogTheme属性的指向，用 Activity 的 context 通常继承Theme.AppCompat.Dialog之类的默认样式，带标题栏、带浅色背景、带最小宽度限制。而用applicationContext创建，会拿到一套Theme.DeviceDefault.Dialog的样式，外观完全不一样，还可能出现Resources$NotFoundException。所以我的规矩是：自定义弹窗一律显式传主题，new Dialog(context, R.style.MyDialogTheme)，绝不让它自己猜。
2.2 构造参数、主题与布局加载的三种写法
构造Dialog有三种常见方式，各有适用场合。第一种是Dialog(Context)，最省事但最不可控，外观依赖宿主主题，只适合临时调试。第二种是Dialog(Context, int themeResId)，我的默认选择，把所有的视觉规则（背景透明、无标题、圆角、动画、遮罩）都写进主题样式里，代码只负责业务逻辑。第三种是Dialog(Context, boolean cancelable, OnCancelListener)，用于你需要在用户点击返回键或外部区域时做额外处理的场景，但cancelable也可以通过setCancelable()设置，所以实际用得不多。
主题的写法是整套方案里最容易被写错的部分。下面这个是我在项目里稳定跑了两年的模板：
<!-- res/values/styles.xml --> <style name="MyDialogTheme" parent="Theme.AppCompat.Dialog"> <!-- 去掉标题栏，否则内容区上方会空出一条 --> <item name="windowNoTitle">true</item> <!-- 保持浮动窗口，配合 gravity 定位 --> <item name="android:windowIsFloating">true</item> <!-- 窗口背景必须透明，否则圆角外侧会露出白色方块 --> <item name="android:windowBackground">@android:color/transparent</item> <!-- 去掉系统自带的窗口边距 --> <item name="android:windowContentOverlay">@null</item> <item name="android:windowMinWidthMajor">0%</item> <item name="android:windowMinWidthMinor">0%</item> <!-- 进出场动画 --> <item name="android:windowAnimationStyle">@style/MyDialogAnim</item> </style> <style name="MyDialogAnim"> <item name="android:windowEnterAnimation">@anim/dialog_fade_in</item> <item name="android:windowExitAnimation">@anim/dialog_fade_out</item> </style>windowMinWidthMajor和windowMinWidthMinor这两行是关键，很多人卡在"我的弹窗宽度怎么改都是那个固定值"，原因就是系统默认给 Dialog 设了 65% 左右的最小宽度，设成 0% 才能自由控制。windowBackground设透明是第二个必踩的坑，不设的话，你布局里写的圆角外面会填充一层默认的浅色，看起来像"圆角没生效"。
动画文件很简单，透明度渐变就够了，底部弹窗再叠一个位移：
<!-- res/anim/dialog_fade_in.xml --> <alpha xmlns:android="http://schemas.android.com/apk/res/android" android:duration="200" android:fromAlpha="0.0" android:toAlpha="1.0" />至于布局加载，setContentView()必须在show()之前调用，否则会抛IllegalStateException。我习惯在构造完成后马上setContentView，把布局膨胀和初始化放在一起，show()只做"显示"这一件事，逻辑上更清楚。
3. 一步步实现一个可复用的自定义弹窗
3.1 样式、遮罩与圆角裁剪的实操细节
遮罩的深浅是设计稿最容易和实现打架的地方。window.setDimAmount(0.6f)设的是遮罩层的 alpha，但前提是窗口有FLAG_DIM_BEHIND标志，而这个标志在Theme.AppCompat.Dialog里默认是开启的。如果你发现设了dimAmount没反应，八成是因为主题被改成了非浮动的windowIsFloating=false，或者你手动clearFlags掉了。我一般在show()之后加一行保险：
window?.apply { addFlags(WindowManager.LayoutParams.FLAG_DIM_BEHIND) setDimAmount(0.6f) }圆角本身不复杂，一个shape就够了：
<!-- res/drawable/bg_dialog_round.xml --> <shape xmlns:android="http://schemas.android.com/apk/res/android" android:shape="rectangle"> <solid android:color="@color/white" /> <corners android:radius="16dp" /> </shape>把它设到布局最外层的background上，弹窗就有圆角了。但真正折磨人的是圆角里的图片——如果最外层是圆角，里面塞一个铺满的ImageView，图片的直角会从圆角处溢出来。这个问题有两种解法：一是给ImageView自己套一层同样的圆角背景（治标，图片内容还是直角），二是用ViewOutlineProvider做真正的裁剪：
imageView.clipToOutline = true imageView.outlineProvider = object : ViewOutlineProvider() { override fun getOutline(view: View, outline: Outline) { outline.setRoundRect(0, 0, view.width, view.height, radiusPx) } }clipToOutline从 API 21 开始支持，对ImageView、WebView、VideoView都有效，是首选方案。要注意setRoundRect里的坐标是相对 View 自身的，radiusPx要提前用dp -> px换算好，别直接传 dp 值进去，否则在高密度屏上圆角会大到离谱。
顺便说一下底部弹窗的圆角方向，只要上面两个角圆：
<corners android:topLeftRadius="16dp" android:topRightRadius="16dp" />3.2 宽高策略与屏幕适配的计算过程
宽度是自定义弹窗最容易翻车的地方。我的策略是：普通居中弹窗用屏宽的固定百分比 + 最大宽度上限，底部弹窗用MATCH_PARENT。直接写死match_parent在居中弹窗上会导致左右贴边，视觉上很奇怪；写死wrap_content又容易被内容撑得忽宽忽窄。
计算的时候不要用resources.displayMetrics.widthPixels了，Android 11 之后多窗口和折叠屏场景下这个值不一定是窗口真实宽度。API 30 以上用WindowMetrics：
val screenWidth = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) { val wm = context.getSystemService(WindowManager::class.java) wm.currentWindowMetrics.bounds.width() } else { context.resources.displayMetrics.widthPixels } val targetWidth = (screenWidth * 0.86f).toInt() .coerceAtMost(dp2px(context, 400f)) // 平板和折叠屏展开时限制最大宽度那个coerceAtMost(400dp)是我在一台折叠屏平板上测试出来的经验值。不加限制的时候，一块 8 英寸的展开屏上，86% 宽度的弹窗会变成一个大白板，内容散得很开，阅读体验极差。居中弹窗的最大宽度我一般控制在 360dp 到 400dp 之间，具体看内容密度。
高度方面，居中弹窗用WRAP_CONTENT让内容自己撑开，但必须给一个上限。我遇到过内容列表超过 30 条的情况，弹窗高度直接顶穿屏幕。做法是在布局里给可滚动区域用android:maxHeight是不生效的——View没有这个属性，得用NestedScrollView包住内容，然后在代码里算最大高度：
val maxHeight = screenHeight - dp2px(context, 160f) // 上下各留 80dp 呼吸空间 rootView.layoutParams?.let { it.height = ViewGroup.LayoutParams.WRAP_CONTENT // 通过约束或者给滚动容器设固定高度来控制 }更稳的做法是用ConstraintLayout给内容区加layout_constraintHeight_max，配一个0dp+ 上下约束的滚动容器，让它自然在到达上限时开始滚动。这个方案在多种屏幕比例上都验证过，比代码里动态算高度可靠。
3.3 完整代码实现与调用方式
这一节给出我在项目里实际用的封装。设计目标是：构造时传布局和主题，链式配置尺寸、重力、取消行为，调用方只关心业务回调。
// Kotlin class AppDialog private constructor( context: Context, layoutRes: Int, themeRes: Int ) : Dialog(context, themeRes) { private val binding = LayoutInflater.from(context).inflate(layoutRes, null) init { setContentView(binding) } override fun show() { super.show() window?.apply { // 透明背景，圆角由布局自己画 setBackgroundDrawable(ColorDrawable(Color.TRANSPARENT)) addFlags(WindowManager.LayoutParams.FLAG_DIM_BEHIND) setDimAmount(0.6f) // 尺寸必须在这里设置，onCreate 之前设会被覆盖 val screenWidth = context.resources.displayMetrics.widthPixels val width = (screenWidth * 0.86f).toInt() .coerceAtMost(dp2px(context, 400f)) setLayout(width, WindowManager.LayoutParams.WRAP_CONTENT) setGravity(Gravity.CENTER) } } fun onConfirm(action: () -> Unit): AppDialog = apply { binding.findViewById<TextView>(R.id.btn_confirm)?.setOnClickListener { action() dismiss() } } fun onCancel(action: () -> Unit): AppDialog = apply { binding.findViewById<TextView>(R.id.btn_cancel)?.setOnClickListener { action() dismiss() } } companion object { fun build(context: Context, layoutRes: Int): AppDialog = AppDialog(context, layoutRes, R.style.MyDialogTheme) fun dp2px(context: Context, dp: Float): Int = (dp * context.resources.displayMetrics.density + 0.5f).toInt() } }调用侧就三行：
AppDialog.build(activity, R.layout.dialog_promo) .onConfirm { startActivity(Intent(activity, DetailActivity::class.java)) } .onCancel { Log.d(TAG, "user canceled") } .show()如果是底部弹窗，只需要换一处——在show()里把重力改成底部、宽度改成撑满，再配一个从底部滑入的动画块：
window?.apply { setLayout( WindowManager.LayoutParams.MATCH_PARENT, WindowManager.LayoutParams.WRAP_CONTENT ) setGravity(Gravity.BOTTOM) // 底部弹窗不做 dim 也常见，看设计稿 windowAnimations = R.style.BottomSheetAnim }<style name="BottomSheetAnim"> <item name="android:windowEnterAnimation">@anim/sheet_slide_in</item> <item name="android:windowExitAnimation">@anim/sheet_slide_out</item> </style><!-- res/anim/sheet_slide_in.xml --> <set xmlns:android="http://schemas.android.com/apk/res/android"> <translate android:duration="250" android:fromYDelta="100%" android:toYDelta="0" /> <alpha android:duration="250" android:fromAlpha="0.5" android:toAlpha="1.0" /> </set>这里有个细节：底部弹窗如果用MATCH_PARENT宽度，最外层布局的background圆角只在上面两个角，下面两个角必须接地，因为它是贴底的。但如果你用了windowIsFloating=true，窗口下方可能留有一条空隙（系统给浮窗加的 inset），看起来就像弹窗悬空了一截。解决办法是主题里加android:windowBackground透明的同时，把android:windowIsFloating设为false，让它变成非浮动窗口，此时尺寸和重力要自己完全接管，setLayout(MATCH_PARENT, WRAP_CONTENT)和Gravity.BOTTOM照样生效。
3.4 软键盘场景的高度与模式配置
带输入框的弹窗是整套方案里最考验细节的部分。核心配置是两件事：softInputMode和窗口是否浮动。我试过的组合里，能稳定工作的写法是：
window?.setSoftInputMode( WindowManager.LayoutParams.SOFT_INPUT_ADJUST_RESIZE or WindowManager.LayoutParams.SOFT_INPUT_STATE_HIDDEN )ADJUST_RESIZE让窗口在键盘弹出时重新计算可用高度，内容跟着上移；STATE_HIDDEN保证弹窗打开时不自动弹键盘，避免那种"页面刚打开键盘就顶上来"的突兀感，用户点了输入框再弹会更自然。
在 Android 11 之后，ADJUST_RESIZE对浮窗的语义有变化，如果你发现键盘弹出后弹窗并没缩小而是被推上去了，那通常是因为窗口是浮动的，系统改为移动窗口而不是压缩窗口。这时候要么把弹窗改成非浮动窗口配合LayoutParams.MATCH_PARENT高度约束，要么监听WindowInsets自己算：
ViewCompat.setOnApplyWindowInsetsListener(rootView) { view, insets -> val imeHeight = insets.getInsets(WindowInsetsCompat.Type.ime()).bottom // 手动调整底部按钮的 margin view.setPadding(0, 0, 0, imeHeight) insets }WindowInsetsCompat从androidx.core来，兼容性比直接用 API 30 的Insets好得多。我建议只要是带输入框的弹窗，一律接这个监听，比自己算屏幕高度减去键盘高度稳，折叠屏和分屏下也不会崩。
还有一个我踩过的坑：输入框在弹窗里，用户点击输入框时如果弹窗本身设了setCanceledOnTouchOutside(true)，有时候会因为焦点切换的时序问题，触摸事件被判定为"外部点击"直接把弹窗关掉，用户刚点开输入法弹窗就没了。我的处理方式是在有输入框的弹窗上关掉外部点击取消，改成只能通过取消按钮或返回键关闭，交互上更可控。
4. 高频坑位与排查实录
4.1 BadTokenException、isShowing 与生命周期管理
BadTokenException是我见过最多的弹窗崩溃，没有之一。它的本质是：WindowManager要求添加窗口的 token 必须是一个还活着的 Activity 的窗口 token，如果你的show()发生在 Activity 已经finish()之后，token 就失效了。触发场景集中在三类：网络请求回调里弹窗、延迟任务（Handler.postDelayed）里弹窗、Application级 Context 创建的 Dialog。
处理方案分两层。第一层是前置检查，在show()之前确认 Activity 状态：
fun showSafely(activity: Activity) { if (activity.isFinishing || activity.isDestroyed) return if (!isShowing) show() }isDestroyed是 API 17 才有的，好在现在最低版本基本都过 21 了，不用担心。第二层是架构层面，凡是可能异步触发的弹窗，一律改成DialogFragment，交给FragmentManager托管，它在 Activity 重建时会自动恢复连接，show()的时机由commit保证在onStart之后执行。如果时机不对，show会抛IllegalStateException: Can not perform this action after onSaveInstanceState，这才是 FragmentManager 的正常拦截，比崩溃好处理得多。
与之相对的是dismiss()的坑。你有没有遇到过IllegalArgumentException: View=DecorView not attached to window manager？这个异常通常发生在onSaveInstanceState之后调用dismiss，或者弹窗已经在别的地方被关掉了再关一次。防御方式是：
fun dismissSafely() { if (isShowing) { try { dismiss() } catch (e: IllegalArgumentException) { // 极端情况下窗口已脱离，忽略 } } }那个try-catch看着不优雅，但它是社区里公认最实用的兜底，因为isShowing也有竞态窗口——你判断完到真正 dismiss 之间，窗口可能已经被系统回收了。
4.2 圆角失效、动画不动、遮罩没反应的成因对照
这几个问题几乎都是"看起来设了但没生效"，我总结了一张速查表，基本都是踩过一次就能记住的：
| 现象 | 根因 | 解决 |
|---|---|---|
| 圆角外侧有白边 | 窗口windowBackground未设透明 | 主题里设@android:color/transparent |
| 宽度改不动 | 系统最小宽度限制 | windowMinWidthMajor/Minor设为 0% |
| 图片溢出圆角 | 未做轮廓裁剪 | clipToOutline+ViewOutlineProvider |
| 遮罩没反应 | 缺FLAG_DIM_BEHIND | addFlags后setDimAmount |
| 动画不执行 | 在show()前设置 | 写进主题或在show()后设置 |
| 背景圆角变成黑块 | 主题继承不当导致背景不透明 | 显式setBackgroundDrawable(透明) |
| 弹窗贴边没有边距 | 浮动窗口的默认 inset | 关掉windowIsFloating或自己设 padding |
还有两个不在表里但值得单独说的。第一个是暗色模式适配，如果你的弹窗内容里写死了#FFFFFF背景和#333333文字，切到深色模式会亮瞎眼。做法是把颜色抽到values/colors.xml和values-night/colors.xml，弹窗主题里引用语义化颜色（@color/dialog_bg、@color/dialog_text_primary），这样系统切换时会自动跟随。
第二个是弹窗内的列表滚动冲突。你在 Dialog 里放RecyclerView，如果外层套了NestedScrollView，同时弹窗高度是WRAP_CONTENT，就会出现"内外都能滚、滚起来卡顿"的现象。根本原因是嵌套滚动没有正确分发。我的做法是弹窗内只允许一层滚动容器：要么用RecyclerView撑满剩余空间（配0dp+ 约束），要么用NestedScrollView包静态内容，绝不让两者叠加。
4.3 多弹窗叠加与优先级管理
业务复杂到一定程度，弹窗会打架：登录失效要弹、版本更新要弹、运营活动要弹、弱网提示要弹，如果各写各的，用户打开 App 一瞬间能连着看到三个弹窗，第二个还会盖在第一个上面，体验直接崩盘。
我的解决思路是引入一个轻量的弹窗调度器，核心就三件事：维护一个队列、保证同一时刻只有一个弹窗在显示、按优先级和去重规则排队。
object DialogDispatcher { private val queue = ArrayDeque<Entry>() private var current: Dialog? = null data class Entry( val key: String, val priority: Int, val dialog: () -> Dialog ) fun enqueue(entry: Entry) { if (queue.any { it.key == entry.key }) return // 同 key 去重 queue.add(entry) queue.sortByDescending { it.priority } pump() } fun onDismissed() { current = null pump() } private fun pump() { if (current != null) return val next = queue.removeFirstOrNull() ?: return val dialog = next.dialog() dialog.setOnDismissListener { onDismissed() } current = dialog dialog.show() } }这里的关键是setOnDismissListener回到调度器，让队列继续往下走。同时所有弹窗调用方都要走enqueue，不再直接show()。这套东西上线之后，弹窗叠加的问题基本绝迹。另外我加了一条规则：同一次冷启动的前 3 秒内，除最高优先级的弹窗之外，其余一律延后，避免打开 App 就是一堆弹窗糊脸。
5. 进阶：把自定义弹窗做成可维护的组件
5.1 用 DialogFragment 承载，解决旋转丢失
前面说自定义Dialog简单直接，但它有一个硬伤：屏幕旋转、Activity 被系统回收重建之后，弹窗会消失，如果弹窗里有用户在输入的内容，全部丢失。这个问题在横竖屏切换频繁的平板上尤其明显。
DialogFragment正好解决这一点。它的用法不复杂：重写onCreateDialog返回你的自定义Dialog，然后用show(fragmentManager, tag)显示。FragmentManager 会在配置变更时保存 Fragment 的状态并重建，弹窗跟着回来。
class AppDialogFragment : DialogFragment() { override fun onCreateDialog(savedInstanceState: Bundle?): Dialog { val dialog = AppDialog.build(requireContext(), R.layout.dialog_promo) // 这里可以恢复之前保存的输入内容 savedInstanceState?.getString("draft")?.let { dialog.findViewById<EditText>(R.id.et_content)?.setText(it) } return dialog } override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setStyle(STYLE_NO_TITLE, R.style.MyDialogTheme) } }这里有个重要的细节：如果你自己已经给Dialog设了主题，setStyle可能会和它冲突，因为DialogFragment会用自己的主题去覆盖。稳妥的做法是二选一——要么用DialogFragment的setStyle传主题，Dialog用默认构造；要么反过来。两个都设的时候，表现取决于版本，很容易"一会儿有圆角一会儿没有"，我在两个项目里都遇到过。
另一个坑是show()的时机。在onSaveInstanceState之后调用show()会抛IllegalStateException，常见于在异步回调里直接弹。官方的show内部用的是commit()，非commitAllowingStateLoss，这是有意的——丢掉弹窗比崩溃好。真要处理这种场景，应该把弹窗的触发时机改到onResume之后再判断一次，而不是用commitAllowingStateLoss掩盖问题。
5.2 内容与展示解耦的参数传递方式
DialogFragment有个官方强烈建议的规范：不要用带参构造函数传数据，因为 Fragment 重建时只会调用无参构造，你的参数会丢。正确做法是通过arguments传Bundle：
companion object { const val ARG_TITLE = "title" const val ARG_CONTENT = "content" fun newInstance(title: String, content: String): AppDialogFragment = AppDialogFragment().apply { arguments = bundleOf( ARG_TITLE to title, ARG_CONTENT to content ) } }Bundle能放的数据类型有限，复杂对象要么实现Serializable或Parcelable（推荐后者，性能好很多），要么就只传一个 ID，让弹窗自己去数据源拿。我通常选后者——传 ID，弹窗内部通过ViewModel或者数据仓库获取内容，这样Bundle体积小，也避免了重建时数据过期的问题。
结果回传也不用传统的回调接口，用FragmentResultListener更省心：
// 发送方 setFragmentResult("promo_result", bundleOf("confirmed" to true)) // 接收方 parentFragmentManager.setFragmentResultListener( "promo_result", viewLifecycleOwner ) { _, bundle -> val confirmed = bundle.getBoolean("confirmed") }这种方式的优势是不依赖强引用，Fragment 重建之后监听依然有效，比持有回调引用安全得多。
5.3 无障碍与细节打磨
组件做到最后，剩下的都是细节。无障碍这块很多人跳过，但它是真实影响评分的项。自定义弹窗需要保证三点：可点击元素的触摸区域不小于 48dp；ImageView这种纯装饰元素要设importantForAccessibility="no"，避免读屏软件读出一堆无意义内容；关闭按钮这种只有图标的控件必须加contentDescription，否则读屏用户根本不知道那是个叉。
焦点管理也值得花点时间。弹窗弹出时，焦点应该落在弹窗的根容器上，关闭时焦点回到触发它的那个控件。前者靠rootView.requestFocus()，后者要靠调用方自己记住。如果做不到焦点归位，键盘用户的 Tab 顺序会乱跳，体验很差。
最后是性能。弹窗里的布局层级我建议控制在 5 层以内，别为了圆角套三层CardView。弹窗呈现的时机一般是用户操作的瞬间，一旦首帧耗时超过 100 毫秒，就能明显感觉到卡顿。图片资源要在弹窗打开前预加载，Glide的preload()或者Glide.with(context).load(url).preload()都行，别等show()之后才开始请求网络。
我在实际项目里最后沉淀下来的做法是：底层一个BaseDialog处理窗口参数、遮罩、圆角、动画这套通用逻辑，上层业务用DialogFragment包装，数据通过Bundle传 ID，结果通过FragmentResultListener回传，所有弹窗统一走调度器排队。这套结构上线两年，弹窗相关的线上崩溃从每月十几起降到了零，新需求接进来基本就是写个布局、调两行链式方法的事。踩过的那些坑现在回头看都不算复杂，但它们分散在主题、窗口参数、生命周期、Fragment 规范这几个不同的知识块里，不实际写一遍很难串起来——这也是我为什么建议新手别一上来就用第三方弹窗库，先自己从零写一个，把Window那套参数摸熟了，以后遇到任何弹窗问题都能一眼定位到大致的层。
