一、理解 Flet 中的 AlertDialog 模态对话框
概念与模态行为
AlertDialog 是 Flet 提供的模态对话框组件，用于在当前界面上覆盖一层遮罩，强制用户在完成对话框中的操作前不能与背景界面交互。模态对话框的核心特征是阻塞背景页面的交互，确保用户关注对话框的提示、确认或输入。
在设计对话框时，明确的标题、简洁的内容区和清晰的操作按钮能够提升可用性，让用户快速做出决策。通过正确使用 AlertDialog，可以提升界面的一致性和用户体验。
二、在 Flet 应用中创建 AlertDialog 的基本结构
核心参数与构成
AlertDialog 由标题、内容和操作按钮组成，三者组合定义了对话框的含义和可执行的行为。Flet 还支持对话框的样式、 padding 等细节的微调。
下面给出一个最小可运行的示例，演示在按钮点击后显示一个简单的模态对话框：标题、内容和取消/确定两个按钮。
# 最小示例：在按钮点击后显示模态对话框
import flet as ftdef main(page: ft.Page):def show_dialog(e):dialog = ft.AlertDialog(title=ft.Text("请确认操作"),content=ft.Text("此操作将对数据产生影响，是否继续？"),actions=[ft.TextButton("取消", on_click=lambda e: (setattr(page, "dialog", None), page.update())),ft.TextButton("确定", on_click=lambda e: (setattr(page, "dialog", None), page.update()))],)page.dialog = dialogpage.update()page.add(ft.ElevatedButton("显示模态对话框", on_click=show_dialog))ft.app(target=main)
三、正确显示模态对话框并处理返回值
流程步骤与事件绑定
触发点明确：通过点击按钮等交互触发对话框显示；将对话框赋值给 page.dialog，再调用 page.update() 让界面重新渲染，浏览器或设备将自动绘制遮罩层并阻塞背景交互。
在对话框按钮中处理结果时，应使用清晰的回调逻辑，确保用户操作能够正确地影响后续流程。下面给出一个带结果返回的示例，演示如何根据用户选择执行不同的逻辑：
# 显示对话框并根据用户选择进行分支
import flet as ftdef main(page: ft.Page):result = {"value": None}def on_click(e):dialog = ft.AlertDialog(title=ft.Text("确认操作"),content=ft.Text("确认删除这条记录吗？"),actions=[ft.TextButton("否", on_click=lambda e: (result.__setitem__("value", False), setattr(page, "dialog", None), page.update())),ft.TextButton("是", on_click=lambda e: (result.__setitem__("value", True), setattr(page, "dialog", None), page.update()))],)page.dialog = dialogpage.update()# 这里可以继续等待结果或在后续逻辑中读取 result["value"]page.add(ft.ElevatedButton("删除记录", on_click=on_click))ft.app(target=main)
四、进阶：返回值处理与异步场景
处理用户选择与异步逻辑
在需要等待对话框结果的场景中，建议使用明确的返回值机制，确保对话框关闭后，代码能够继续按返回值进行分支处理。将结果保存在一个可变对象或闭包作用域中，并在按钮回调中更新该结果即可。
以下示例展示了一个更具可读性的实现：在对话框结束后，根据 result 值执行后续操作（例如调用 API、更新界面等）。
import flet as ftdef main(page: ft.Page):result = {"confirmed": None}async def show_and_wait(e):# 这里我们模拟一个简单的异步等待，实际应用中可以是 API 调用等dialog = ft.AlertDialog(title=ft.Text("确认执行"),content=ft.Text("请确认以继续执行此操作。"),actions=[ft.TextButton("取消", on_click=lambda e: (result.__setitem__("confirmed", False), setattr(page, "dialog", None), page.update())),ft.TextButton("继续", on_click=lambda e: (result.__setitem__("confirmed", True), setattr(page, "dialog", None), page.update()))],)page.dialog = dialogpage.update()# 若需要真正的异步等待，可在后续逻辑中检查 result["confirmed"]page.add(ft.ElevatedButton("执行操作", on_click=show_and_wait))ft.app(target=main)
五、无障碍性与可访问性最佳实践
焦点管理与屏幕阅读器支持
对话框应具备可聚焦的标题与可操作的按钮，确保屏幕阅读器能正确朗读对话框内容。实现中要保证对话框在显示时能够接管初始焦点，便于用户快速完成操作。
此外，对话框中的文本对比度应充足，按钮文本清晰、描述性强；对于键盘导航，确保通过 Tab 键能够顺序遍历标题、内容和动作按钮。
六、定制化与跨设备适配
样式、尺寸与响应式设计
AlertDialog 的外观和布局应适应不同屏幕尺寸，在较小设备上保持可读性与可点击区域的足够大小。通过设置对话框的标题、内容和按钮的对比度、边距和字体大小，可以实现跨设备的一致性体验。
在设计时，可以结合设备宽度动态调整对话框的宽度与内容排布，确保在手机、平板与桌面端都具备良好读写体验。以下示例展示如何在不同屏幕下维持良好排布：
# 通过容器自适应布局对话框内容
import flet as ftdef main(page: ft.Page):def show_dialog(e):dialog = ft.AlertDialog(title=ft.Text("警告"),content=ft.Column([ft.Text("检测到潜在问题，请确认是否继续。"),ft.Text("注：此操作可能影响数据一致性。")], alignment=ft.MainAxisAlignment.CENTER),actions=[ft.TextButton("取消", on_click=lambda e: (setattr(page, "dialog", None), page.update())),ft.TextButton("继续", on_click=lambda e: (setattr(page, "dialog", None), page.update()))],# 通过宽度或内容自适应实现响应式inset_padding=ft.Padding(20, 12, 20, 12),)page.dialog = dialogpage.update()page.add(ft.ElevatedButton("显示自适应对话框", on_click=show_dialog))ft.app(target=main)
七、常见问题与排错指南
对话框不显示、遮罩层覆盖、事件传递异常
对话框不显示通常与 page.dialog 未正确赋值或 page.update() 未执行有关，请确认对话框对象已经被分配到 page.dialog，并在赋值后调用 page.update()。
遮罩层覆盖但内容无法交互可能是由于对话框层级被其他控件覆盖，建议在对话框显示时确保其层级优先级不被打断，并避免在对话框未关闭前重新触发新的对话框。
事件传递异常如按钮回调未能正确关闭对话框，通常是回调函数中对 page.dialog 的赋值与页面更新顺序有误，请确保在按钮点击时先设置 page.dialog = None，然后再调用 page.update()。
