CupertinoDialogRoute

用于实现iOS风格对话框路由的组件

CupertinoDialogRoute是Flutter中用于实现iOS风格对话框路由的组件，继承自PopupRoute。它专门管理模态对话框的显示和消失动画，提供符合Apple设计规范的过渡效果(如从底部滑入、淡入淡出)。其核心逻辑是通过Navigator将对话框作为路由堆栈的一层覆盖在现有页面上，支持手势关闭(向下滑动)和自定义内容。

使用场景

操作确认弹窗: 如删除确认、支付确认等需要用户决策的场景。
信息输入对话框: 例如登录时输入用户名/密码的模态弹窗。
底部动作菜单: 类似iOS的ActionSheet，从底部弹出选项列表。
自定义提示框: 替代默认Dialog，实现与iOS原生UI一致的交互动画。

示例

基础对话框

import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';

void showBasicDialog(BuildContext context) {
  Navigator.of(context).push(
    CupertinoDialogRoute(
      builder: (context) => CupertinoAlertDialog(
        title: Text("提示"),
        content: Text("确定要删除此项吗？"),
        actions: [
          CupertinoDialogAction(
            child: Text("取消"),
            onPressed: () => Navigator.pop(context),
          ),
          CupertinoDialogAction(
            child: Text("确定"),
            onPressed: () {
              // 执行删除逻辑
              Navigator.pop(context);
            },
          ),
        ],
      ),
    ),
  );
}

// 在按钮中调用：
ElevatedButton(
  onPressed: () => showBasicDialog(context),
  child: Text("打开对话框"),
);

底部动作菜单

void showActionSheet(BuildContext context) {
  Navigator.of(context).push(
    CupertinoDialogRoute(
      builder: (context) => CupertinoActionSheet(
        title: Text("选择操作"),
        message: Text("请选择一个选项"),
        actions: [
          CupertinoActionSheetAction(
            child: Text("拍照"),
            onPressed: () {
              // 处理拍照逻辑
              Navigator.pop(context);
            },
          ),
          CupertinoActionSheetAction(
            child: Text("从相册选择"),
            onPressed: () {
              // 处理相册逻辑
              Navigator.pop(context);
            },
          ),
        ],
        cancelButton: CupertinoActionSheetAction(
          child: Text("取消"),
          isDefaultAction: true,
          onPressed: () => Navigator.pop(context),
        ),
      ),
    ),
  );
}

自定义对话框

void showCustomDialog(BuildContext context) {
  TextEditingController controller = TextEditingController();
  Navigator.of(context).push(
    CupertinoDialogRoute(
      builder: (context) => Container(
        height: 200,
        padding: EdgeInsets.all(20),
        child: Column(
          children: [
            Text("请输入备注"),
            CupertinoTextField(
              controller: controller,
              placeholder: "备注内容",
            ),
            SizedBox(height: 20),
            Row(
              mainAxisAlignment: MainAxisAlignment.end,
              children: [
                CupertinoButton(
                  child: Text("取消"),
                  onPressed: () => Navigator.pop(context),
                ),
                CupertinoButton(
                  child: Text("保存"),
                  onPressed: () {
                    print("保存内容: ${controller.text}");
                    Navigator.pop(context);
                  },
                ),
              ],
            ),
          ],
        ),
      ),
    ),
  );
}

注意点

常见问题

路由堆栈管理

必须通过Navigator.pop(context)关闭对话框，否则会导致路由泄漏。
避免在对话框内嵌套Navigator操作，可能引发动画冲突。

性能瓶颈

对话框内容过多时(如长列表)，需使用ListView.builder避免一次性渲染所有元素。
复杂动画可能影响帧率，建议通过DevTools检查性能。

兼容性警告：

在非iOS平台使用时，需测试动画流畅性(Android 可能缺少原生手势支持)。
与MaterialApp混用时，确保theme不会覆盖Cupertino样式。

优化技巧

手势优化: 通过barrierDismissible控制是否允许点击遮罩关闭(默认true)。
动画定制: 重写transitionDuration调整动画速度，避免过快或过慢。
内存管理: 在对话框内使用StatefulWidget时，在dispose中释放控制器(如TextEditingController)。

最佳实践

优先使用CupertinoAlertDialog或CupertinoActionSheet作为内容，以保持iOS设计一致性。
通过barrierColor设置半透明遮罩颜色(如Colors.black54)，增强视觉层次。
在对话框显示时禁用后方页面的交互，防止用户同时触发多个操作。

构造函数

CupertinoDialogRoute({
  required WidgetBuilder builder,      // 对话框内容构建器
  Color? barrierColor,                 // 遮罩层颜色（默认半透明黑）
  bool barrierDismissible = true,      // 是否允许点击遮罩关闭
  String? barrierLabel,                // 语义化标签（用于无障碍功能）
  Duration transitionDuration = const Duration(milliseconds: 250), // 动画时长
  RouteTransitionsBuilder? transitionsBuilder, // 自定义过渡动画
})

属性

属性名	属性类型	说明
`builder`	`WidgetBuilder`	必需，构建对话框内容的回调函数。
`barrierColor`	`Color?`	遮罩层颜色，默认为半透明黑色（`Colors.black54`）。
`barrierDismissible`	`bool`	控制是否允许通过点击遮罩或返回键关闭对话框，默认为 `true`。
`barrierLabel`	`String?`	用于无障碍服务的标签，描述遮罩作用（如 "关闭对话框"）。
`transitionDuration`	`Duration`	对话框打开/关闭的动画时长，默认 250 毫秒。
`transitionsBuilder`	`RouteTransitionsBuilder?`	自定义动画构造器，可覆盖默认的滑动淡入效果。

关键属性详解

barrierDismissible

性能影响: 设为false时可防止误操作，但可能增加用户操作步骤。
常用场景: 关键操作(如支付确认)建议设置为false，强制用户明确选择。

transitionDuration

优化提示: 缩短时长可提升交互响应速度，但过短(如<100ms)会导致动画生硬。
适配建议: 根据内容高度调整——较高对话框可适当延长动画时间(如300ms)。

builder

核心逻辑: 内容构建器在路由动画开始前被调用，需避免在此处执行耗时操作(如网络请求)。
最佳实践: 通过FutureBuilder或预加载数据延迟构建复杂内容。

CupertinoDialogAction

CupertinoDynamicColor