AestheticDialogs 1.x 到 2.0 迁移完全指南从 XML Builder 到声明式 Compose 对话框【免费下载链接】AestheticDialogs An Android Library built with Jetpack Compose for fluid, beautiful, custom Dialogs.项目地址: https://gitcode.com/gh_mirrors/ae/AestheticDialogsAestheticDialogs 是一个基于 Jetpack Compose 的 Android 自定义对话框库。它的 2.0 版本是一次彻底重写不再依赖 XML 布局与 Builder 模式而是用声明式 Compose 对话框取代一切。如果你还在 1.x 上调用show()和dismiss()这篇迁移指南会带你一步步切换到 2.0理解三个核心变化并完成风格与属性的逐一映射。1.x 与 2.0 的核心差异先建立正确的心智模型 2.0 没有兼容层也没有废弃过渡期——因为 1.x 的 API 需要传入Activity、膨胀 XML 布局并返回一个句柄这些概念在 Composable 世界里都不存在。迁移前请先接受三个观念上的变化变化1.x 的做法2.0 的做法可见性调用show()/dismiss()对话框自己消失由你的状态驱动在组合中它才显示所有信号包括Dismissed都只是请求由你决定下一步深色模式每次调用setDarkMode(true)应用外层包一次AestheticDialogsTheme整个库自动跟随系统设置横幅通知5 种边缘锚定样式被当作模态窗口不再是对话框AestheticNotificationHost把它渲染成覆盖层不再拦截焦点与返回手势一句话总结对话框从你让它出现变成它是 UI 状态的一部分。迁移第一步更换依赖坐标2.0 发布在 Maven Central不再走 JitPack所以可以删掉maven { url https://jitpack.io }这一行dependencies { implementation(com.gabrielthecode:aestheticdialogs:2.0.0) }注意两个硬性要求minSdk从 19 提升到24且模块需要启用 Compose。如果还没上 Compose可以继续留在1.3.8不动——2.0 不会破坏它只是不再继续开发。风格迁移对照表八个 1.x 样式去了哪里这是迁移中最高频的查询官方对照表如下1.x 风格2.0 去向DialogStyle.FLATFeedbackDialogUiModel.Flat→AestheticFeedbackDialogDialogStyle.FLASHFeedbackDialogUiModel.Flash→AestheticFeedbackDialogDialogStyle.TOASTERNotificationUiModel.Toaster→AestheticNotificationHostDialogStyle.RAINBOWNotificationUiModel.Rainbow→AestheticNotificationHostDialogStyle.CONNECTIFYNotificationUiModel.Connectify→AestheticNotificationHostDialogStyle.EMOJINotificationUiModel.Emoji→AestheticNotificationHostDialogStyle.EMOTIONNotificationUiModel.Emotion→AestheticNotificationHostDialogStyle.DRAKE已移除用FeedbackDialogUiModel.Flat替代为什么 DRAKE 被移除它内置的两张图片是受版权保护的音乐视频截帧被重分发在一个 Apache-2.0 许可证的库里而且文字直接烧录在图片中setTitle/setMessage对它是无效的无法本地化、无法被读屏朗读。如果你用过它Flat反馈对话框是最接近的替代同样的模态卡片、同样的状态色调且文字完全由你控制。属性逐一对应Builder 方法去哪了1.x 的链式 Builder 方法在 2.0 中全部有了新归宿1.x 方法2.0 等价写法.setTitle(s)UI model 的title s.setMessage(s)message s.setDarkMode(b)应用外层AestheticDialogsTheme(darkTheme b).setCancelable(false)dismissBehavior DialogDismissBehavior.Blocking.setGravity(g)对话框自动居中自适应横幅改用AestheticNotificationHost的alignment.setDuration(ms)AestheticNotificationHost的autoDismissMillis.setAnimation(a)横幅的animation模态对话框只保留一个进入过渡.setOnClickListener { }onSignal { … }DialogType.SUCCESS/ERROR/…DialogTone.Success/Error/Warning/Info另有Neutral一个值得注意的细节setCancelable在 2.0 被拆成了两个独立开关dismissOnBackPress与dismissOnClickOutside因为 1.x 把按返回键和点外部混为一谈。提醒如果你阻止了关闭请务必给对话框留一个可见的出口按钮——没有出口的全局阻断对话框是个陷阱。动画从 16 种精简到 5 种1.x 的SPIN、WINDMILL、SPLIT、DIAGONAL等旋转类动画被移除2.0 只保留横幅用的Slide、Fade、Scale、SlideHorizontal、None。更重要的是当系统开启移除动画设置时2.0 的一切过渡会自动降级为瞬时切换而 1.x 的旋转动画没有任何降级的办法。横幅通知的新写法不再抢走焦点1.x 里 Toaster 等横幅被渲染成模态窗口结果是一条信息性提示会压暗屏幕、抢走焦点、吞掉返回手势。2.0 把它变成一个覆盖在内容之上的可组合项Box(Modifier.fillMaxSize()) { HomeContent() AestheticNotificationHost( notification uiState.banner, // 设为 null 即关闭带退场动画 onSignal { viewModel.dismissBanner() }, alignment NotificationAlignment.Top, autoDismissMillis 4_000, ) }迁移后横幅成为实时区域live region读屏器会主动播报它而用户的焦点、返回手势和触摸输入全程不受影响。两个小改动能帮你避开 1.x 的坑EMOTION现在需要你自己传时间戳。1.x 在内部硬编码了 24 小时格式无视用户的 12/24 小时偏好与区域设置现在请用本地化格式化器自行生成。EMOJI接受一个字符而非图片例如emoji 省略时库会按色调自动选一个。迁移的回报五个 1.x 没有的对话框家族升级后你不仅是在换写法还白得五个全新的对话框家族——它们与原有的反馈对话框共享同一套框架、主题和无障碍保障Confirmation 确认框Default与Destructive两种变体破坏性操作的警示配色是保证出来的不会误发成一个中性按钮。Alert 警告框错误、离线、权限不足都是同一个对话框换个色调和文案杜绝三个几乎一样的组件。Selection 选择框单选/多选、搜索、空状态齐全长列表惰性加载操作行固定。Input 输入框打开即聚焦、键盘 Done 即确认、密码可见性切换在旋转后保持。Content 富内容框中间内容换成你的任意 Composable框架、遮罩、无障碍面板仍由设计系统兜底。长文本与大屏被修好的隐性行为1.x 的对话框固定 300×290dp超长内容被静默截断2.0 改为自适应宽度 滚动你在 1.x 里没看到过的文字现在会显示出来平板上也不再是手机同款小卡片。字体放大到 200% 时布局同样成立且所有可点击区域不低于 48dp。迁移后检查清单 ✅所有.setCancelable(false)的位置确认都有可见的操作按钮出口原本手动置灰按钮模拟加载中的代码删掉改用isConfirming true按钮自带转圈并锁定整个对话框长文本对话框原本被截断的内容现在会完整出现检查排版大屏设备对话框宽度不再固定 300dp验证平板布局横幅的 12/24 小时时间格式已本地化参考资料与源码导航官方迁移文档docs/MIGRATION.md1.x 架构审计报告每个样式为什么这样改docs/ARCHITECTURE_AUDIT.md2.0 架构详解Component → Variant → Primitive → Tokens 四层docs/ARCHITECTURE.md组件源码目录aestheticdialogs/src/main/java/com/thecode/aestheticdialogs/示例目录应用只用公开 API 消费库是最好的迁移参照app/src/main/java/com/thecode/sample/文档配图生成脚本scripts/generate-docs-images.sh迁移的本质只有一句话把命令式地展示一个 XML 卡片换成声明式地渲染一段状态。按对照表逐一替换调用点、给阻断对话框留出出口、让横幅回到覆盖层你就能拿到 2.0 的自适应宽度、真实深色模式、动效降级与完整的无障碍保障。【免费下载链接】AestheticDialogs An Android Library built with Jetpack Compose for fluid, beautiful, custom Dialogs.项目地址: https://gitcode.com/gh_mirrors/ae/AestheticDialogs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考