CupertinoPickerDefaultSelectionOverlay

Flutter Cupertino设计风格组件库中的一个专用组件，主要用于为CupertinoPicker提供默认的选择项高亮覆盖效果

CupertinoPickerDefaultSelectionOverlay是Flutter Cupertino设计风格组件库中的一个专用组件，主要用于为CupertinoPicker提供默认的选择项高亮覆盖效果。该组件在iOS风格的滚轮选择器上创建视觉焦点区域，通过半透明遮罩和边框突出显示当前选中的项目，增强用户交互体验。

主要用途和逻辑

视觉反馈: 在CupertinoPicker上显示当前选中项的高亮效果
iOS风格适配: 提供符合iOS设计规范的选中状态视觉表现
非交互性: 该组件本身不处理用户交互，仅负责视觉呈现
自动适配: 根据CupertinoPicker的尺寸和位置自动调整覆盖层布局

使用场景

在iOS风格的日期选择器、时间选择器或选项选择器中
需要突出显示滚轮选择器当前选中项时
构建符合iOS设计规范的移动应用界面
替代自定义选择器覆盖层，使用系统默认样式

示例

基础使用

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

class BasicPickerExample extends StatelessWidget {
  const BasicPickerExample({super.key});

  @override
  Widget build(BuildContext context) {
    return CupertinoApp(
      home: CupertinoPageScaffold(
        navigationBar: const CupertinoNavigationBar(
          middle: Text('基础选择器示例'),
        ),
        child: Center(
          child: SizedBox(
            height: 200,
            child: CupertinoPicker(
              itemExtent: 40,
              children: List.generate(10, (index) => Text('选项 ${index + 1}')),
              onSelectedItemChanged: (index) {
                print('选中了选项: ${index + 1}');
              },
              // 使用默认选择覆盖层
              selectionOverlay: const CupertinoPickerDefaultSelectionOverlay(),
            ),
          ),
        ),
      ),
    );
  }
}

日期选择应用

import 'package:flutter/cupertino.dart';

class DatePickerExample extends StatefulWidget {
  const DatePickerExample({super.key});

  @override
  State<DatePickerExample> createState() => _DatePickerExampleState();
}

class _DatePickerExampleState extends State<DatePickerExample> {
  DateTime selectedDate = DateTime.now();

  @override
  Widget build(BuildContext context) {
    return CupertinoPageScaffold(
      navigationBar: const CupertinoNavigationBar(
        middle: Text('日期选择器'),
      ),
      child: SafeArea(
        child: Column(
          children: [
            const SizedBox(height: 20),
            const Text('选择日期:', style: TextStyle(fontSize: 18)),
            SizedBox(
              height: 180,
              child: CupertinoDatePicker(
                mode: CupertinoDatePickerMode.date,
                initialDateTime: selectedDate,
                onDateTimeChanged: (DateTime newDate) {
                  setState(() {
                    selectedDate = newDate;
                  });
                },
                // 应用默认选择覆盖层
                selectionOverlay: CupertinoPickerDefaultSelectionOverlay(
                  // 可以自定义颜色但不建议，保持iOS原生风格
                  // background: CupertinoColors.systemGrey.withOpacity(0.1),
                ),
              ),
            ),
            Text('已选择: ${selectedDate.toString().split(' ')[0]}'),
          ],
        ),
      ),
    );
  }
}

自定义主题适配

import 'package:flutter/cupertino.dart';

class ThemedPickerExample extends StatelessWidget {
  const ThemedPickerExample({super.key});

  @override
  Widget build(BuildContext context) {
    return CupertinoTheme(
      data: const CupertinoThemeData(
        brightness: Brightness.dark, // 深色主题
      ),
      child: CupertinoPageScaffold(
        navigationBar: const CupertinoNavigationBar(
          middle: Text('深色主题选择器'),
        ),
        child: Center(
          child: Container(
            padding: const EdgeInsets.all(20),
            decoration: BoxDecoration(
              color: CupertinoColors.systemGrey6.darkColor,
              borderRadius: BorderRadius.circular(12),
            ),
            child: SizedBox(
              height: 150,
              child: CupertinoPicker(
                scrollController: FixedExtentScrollController(initialItem: 2),
                itemExtent: 32,
                children: const [
                  Text('红色', style: TextStyle(color: CupertinoColors.systemRed)),
                  Text('蓝色', style: TextStyle(color: CupertinoColors.systemBlue)),
                  Text('绿色', style: TextStyle(color: CupertinoColors.systemGreen)),
                  Text('黄色', style: TextStyle(color: CupertinoColors.systemYellow)),
                ],
                onSelectedItemChanged: (index) {
                  debugPrint('颜色索引: $index');
                },
                selectionOverlay: CupertinoPickerDefaultSelectionOverlay(
                  // 在深色主题下保持合适的对比度
                  background: CupertinoColors.systemGrey.withOpacity(0.2),
                ),
              ),
            ),
          ),
        ),
      ),
    );
  }
}

注意点

常见问题

性能考虑: 该组件是轻量级的视觉组件，对性能影响极小
兼容性警告: 仅适用于CupertinoPicker及其子类，不适用于Material设计的选择器
尺寸适配: 覆盖层会自动适应父组件尺寸，但需要确保父容器有明确的高度约束

优化技巧

避免在快速滚动的场景下频繁重建覆盖层
在自定义主题时保持与iOS设计规范的一致性
对于特殊需求，考虑继承并重写而非直接修改默认样式

最佳实践提示

保持原生体验: 除非有特殊设计需求，否则建议使用默认配置
主题一致性: 确保覆盖层样式与应用的整体设计风格协调
测试验证: 在不同设备和屏幕尺寸上测试覆盖层的显示效果

构造函数

const CupertinoPickerDefaultSelectionOverlay({
  Key? key,
  Color? background,
}) : super(key: key);

属性

属性名	属性类型	说明
background	Color?	覆盖层的背景颜色，通常使用半透明颜色增强视觉效果
key	Key?	组件在widget树中的唯一标识符

关键属性详解

background属性:
- 重要性: 中等 - 主要用于主题定制
- 性能影响: 低 - 颜色变化不会引起重大性能开销
- 使用建议: 建议保持默认值以确保与iOS设计规范一致，仅在需要特殊主题适配时修改

最佳实践: 在大多数情况下，无需自定义background属性，让系统自动选择最适合当前主题的样式即可获得最佳的用户体验。

CupertinoPicker

CupertinoPopupSurface