Flutter MaterialApp 组件属性第一章

Flutter MaterialApp 组件属性第一章

概述

MaterialApp 是 Flutter 中实现 Material Design 风格应用程序的顶层组件，它是大多数 Flutter 应用程序的入口点。该组件封装了应用程序所需的许多基础功能，包括导航系统、主题管理、本地化支持、路由管理等，为开发者提供了一个完整的应用程序框架。

这里主要讲：Title、onGenerateTitle、restorationScopeId 、debugShowMaterialGrid、showPerformanceOverlay、checkerboardRasterCacheImages、checkerboardOffscreenLayers、showSemanticsDebugger、debugShowCheckedModeBanner、shortcuts、actions、restorationScopeId、scrollBehavior 同时也会聊到Android Activity帮助我们更好的理解Flutter

构造函数

MaterialApp({
  // 基础配置
  Key? key,                                        // 组件唯一标识符
  // 导航器状态管理配置
  GlobalKey<NavigatorState>? navigatorKey,         // 导航器的全局键
  GlobalKey<ScaffoldMessengerState>? scaffoldMessengerKey, // ScaffoldMessenger的全局键
  // 页面路由配置 - 基础路由方式（三选一）
  Widget? home,                                    // 应用的主页面，最简单的路由方式
  Map<String, WidgetBuilder>? routes,             // 命名路由表，适用于静态路由
  String? initialRoute,                           // 初始路由，配合routes使用
  // 页面路由配置 - 高级路由方式（可组合使用）
  RouteFactory? onGenerateRoute,                  // 动态路由生成器，处理未在routes中定义的路由
  InitialRouteListFactory? onGenerateInitialRoutes, // 初始路由列表生成器
  RouteFactory? onUnknownRoute,                   // 未知路由处理器，路由解析失败时调用
  // 导航监听配置
  NotificationListenerCallback<NavigationNotification>? onNavigationNotification, // 导航通知回调
  List<NavigatorObserver> navigatorObservers = const <NavigatorObserver>[], // 导航观察者
  
  // Router API 配置（高级路由，与基础路由互斥）
  RouteInformationProvider? routeInformationProvider, // 路由信息提供者
  RouteInformationParser<Object>? routeInformationParser, // 路由信息解析器
  RouterDelegate<Object>? routerDelegate,          // 路由委托
  BackButtonDispatcher? backButtonDispatcher,     // 返回按钮分发器
  
  // Widget构建配置
  TransitionBuilder? builder,                     // 应用构建器，可用于包装整个应用
  
  // 主题样式配置 - 基础主题
  Color? color,                                   // 应用主色调，用于系统UI
  ThemeData? theme,                               // 浅色主题配置
  ThemeData? darkTheme,                          // 深色主题配置
  ThemeData? highContrastTheme,                  // 高对比度浅色主题，辅助功能
  ThemeData? highContrastDarkTheme,              // 高对比度深色主题，辅助功能
  ThemeMode? themeMode = ThemeMode.system,       // 主题模式选择（浅色/深色/跟随系统）
  Duration themeAnimationDuration = kThemeAnimationDuration, // 主题切换动画时长
  Curve themeAnimationCurve = Curves.linear,     // 主题切换动画曲线
  
  // 国际化配置 - 语言环境
  Locale? locale,                                // 当前语言环境
  Iterable<Locale> supportedLocales = const <Locale>[Locale('en', 'US')], // 支持的语言环境列表
  Iterable<LocalizationsDelegate<dynamic>>? localizationsDelegates, // 本地化委托列表
  // 国际化配置 - 语言环境解析（二选一）
  LocaleListResolutionCallback? localeListResolutionCallback, // 语言环境列表解析回调
  LocaleResolutionCallback? localeResolutionCallback, // 语言环境解析回调
  
 // 应用标题配置 - 二者使用其一即可
  String title = '',                              // 应用标题，静态字符串
  GenerateAppTitle? onGenerateTitle,              // 动态标题生成器，支持国际化

  // 开发调试配置 - 可视化调试工具
  bool debugShowMaterialGrid = false,            // 开发环境可设置为true：显示Material网格
  bool showPerformanceOverlay = false,           // 开发环境可设置为true：显示性能覆盖层
  bool checkerboardRasterCacheImages = false,    // 开发环境可设置为true：显示光栅缓存图像棋盘
  bool checkerboardOffscreenLayers = false,     // 开发环境可设置为true：显示离屏层棋盘
  bool showSemanticsDebugger = false,            // 开发环境可设置为true：显示语义调试器
  bool debugShowCheckedModeBanner = true,        // 开发环境可设置为false：隐藏调试横幅
  
  // 交互快捷键配置  桌面端、Web端
  Map<ShortcutActivator, Intent>? shortcuts,     // 快捷键映射表
  Map<Type, Action<Intent>>? actions,            // 动作映射表
  
  // 状态恢复配置
  String? restorationScopeId,                    // 状态恢复范围ID，启用状态恢复功能
  // 滚动行为配置，自定义滚动效果
  ScrollBehavior? scrollBehavior,                // 滚动行为配置，自定义滚动效果
})

📋 参数分类总结表

分类	参数数量	主要用途	属性
页面路由	8个	页面导航和路由管理	第五章
导航状态	4个	导航器状态管理	第四章
主题样式	6个	应用视觉主题配置	第三章
本地化	5个	多语言和地区适配	第二章
开发调试	6个	开发阶段调试工具	debugShowMaterialGrid、showPerformanceOverlay、checkerboardRasterCacheImages、checkerboardOffscreenLayers、showSemanticsDebugger、debugShowCheckedModeBanner
交互快捷键	2个	键盘快捷键支持	shortcuts、actions
状态恢复	1个	应用状态持久化	restorationScopeId （没有找到系统测试体系，待补全）
Title	2个	应用标题设置	title 、 onGenerateTitle
ScrollBehavior	1个	应用滚动行为设置	scrollBehavior

Title属性移动端显示位置详解（包括：onGenerateTitle）

📱 移动端显示位置

Android平台（只有这俩处显示，其余都显示android:label）：

• 应用切换器：双击菜单键时在应用预览界面显示
• 多任务界面：使用手势导航时，在多任务切换界面的应用卡片上方显示

iOS平台：

• 应用切换器：双击Home键（有Home键设备）时，在应用预览卡片上显示title
• 多任务界面：从屏幕底部向上滑动停留（全面屏设备），在应用预览卡片上显示title
• 控制中心：部分iOS版本在控制中心显示当前运行应用时会显示title

❌ 移动端不会显示的位置

1. 桌面图标：主屏幕上的应用图标下方文字（显示的是应用标签，来源见下方说明）
2. 系统设置：Android设置→应用管理 或 iOS设置→通用→iPhone存储空间
3. 应用抽屉：Android应用列表中的应用名称
4. 通知栏：推送通知中显示的应用名称
5. 状态栏：顶部状态栏中不会显示title

📝 桌面图标名称来源权重说明

Android平台权重优先级（权重：高 → 低）：

优先级	权重值	配置文件	配置项	说明
最高	100	AndroidManifest.xml	android:label	直接覆盖所有其他配置
中等	50	strings.xml	app_name	当manifest中label引用时生效
最低	10	pubspec.yaml	name	仅作为默认值，通常被覆盖

iOS平台权重优先级（权重：高 → 低）：

优先级	权重值	配置文件	配置项	说明
最高	100	Info.plist	CFBundleDisplayName	专门用于显示名称
中等	80	Info.plist	CFBundleName	应用包名称
最低	10	pubspec.yaml	name	仅作为默认值

权重规则详解：

• 权重100：无条件优先，即使其他配置存在也会被覆盖
• 权重50-80：当高权重配置不存在时生效
• 权重10：仅在所有原生配置都缺失时作为备用

实际配置示例：

情况1 - Android完整配置：

<!-- AndroidManifest.xml -->
<application android:label="桌面显示名称" ...>

<!-- strings.xml -->
<string name="app_name">应用内部名称</string>

结果：桌面显示"桌面显示名称"（权重100优先）

情况2 - Android引用配置：

<!-- AndroidManifest.xml -->
<application android:label="@string/app_name" ...>

<!-- strings.xml -->
<string name="app_name">我的应用</string>

结果：桌面显示"我的应用"（通过引用使用strings.xml）

情况3 - iOS完整配置：

<!-- Info.plist -->
<key>CFBundleDisplayName</key>
<string>桌面显示名称</string>
<key>CFBundleName</key>
<string>内部包名</string>

结果：桌面显示"桌面显示名称"（CFBundleDisplayName权重100优先）

Android Activity 详解

📱 什么是Activity？

Activity是Android应用程序的四大组件之一（Activity、Service、BroadcastReceiver、ContentProvider），是用户与应用交互的基本单元。

简单理解：

• 一个Activity = 一个屏幕界面
• 每个Activity都代表应用中的一个独立功能模块
• 用户看到的每个页面基本上都对应一个Activity

弹窗与Activity的关系：

• 不是新Activity：弹窗通常不会创建新的Activity
• 在当前Activity之上：弹窗在现有Activity的视图层之上显示
• Activity状态影响：当弹窗显示时，底层Activity会进入onPause()状态

🏗️ Activity架构

Android应用架构
├── Application (应用程序)
│   ├── Activity1 (主界面)
│   ├── Activity2 (设置页面)
│   ├── Activity3 (详情页面)
│   └── Activity4 (登录页面)
├── Service (后台服务)
├── BroadcastReceiver (广播接收器)
└── ContentProvider (内容提供者)

📋 Activity实际例子

以微信应用为例：

界面	Activity名称	功能
聊天列表	MainActivity	显示所有聊天记录
单个聊天	ChatActivity	与特定联系人聊天
朋友圈	TimelineActivity	浏览朋友圈动态
设置页面	SettingsActivity	应用设置功能
个人信息	ProfileActivity	查看/编辑个人资料

🔄 Activity生命周期

完整生命周期：

创建阶段：onCreate() → onStart() → onResume()
                ↓
运行阶段：Activity可见且可交互
                ↓
暂停阶段：onPause() (部分可见，如弹窗覆盖)
                ↓
停止阶段：onStop() (完全不可见：当另外一个activity恢复并遮盖当前activity，导致其对用户不可见时调用。)
                ↓
销毁阶段：onDestroy() (在activity被销毁前所调用的最后一个方法。)

生命周期方法详解：

方法	触发时机	主要作用	状态恢复相关
onCreate()	Activity创建时	初始化UI、绑定数据	恢复保存的状态
onStart()	Activity变为可见时	准备与用户交互	-
onResume()	Activity获得焦点时	开始接收用户输入	-
onPause()	Activity失去焦点时	暂停动画、保存数据	-
onStop()	Activity不可见时	停止耗时操作	-
onRestart()	Activity重新启动时	重新启动Activity	-
onSaveInstanceState()	系统回收前	保存临时状态	⭐核心方法
onRestoreInstanceState()	状态恢复时	恢复保存状态	⭐核心方法
onDestroy()	Activity销毁时	释放资源	-

⚡ Activity被系统回收的场景

什么时候Activity会被系统回收？

1. 内存不足：系统需要为其他应用释放内存
2. 配置变更：屏幕旋转、语言切换等
3. 应用切换：用户切换到其他应用时间过长
4. 系统压力：系统资源紧张时

回收优先级（从高到低）：

1. 空进程 (Empty Process)
2. 缓存进程 (Cached Process) 
3. 服务进程 (Service Process)
4. 可见进程 (Visible Process)
5. 前台进程 (Foreground Process) ← 用户当前使用的应用

从上可以看出Activity的销毁是系统行为（即使菜单栏切换界面、Home键返回桌面、切换应用等），不是我们手动调用的。如何在开发环境避免这种系统行为使其直接回收？开发者选项 中勾选 不保留活动 ，其作用是用户离开后会杀掉 Activity。

💾 状态保存与恢复机制

保存状态流程：

用户操作 → Activity状态改变 → 系统准备回收Activity 
→ 调用onSaveInstanceState() → 状态保存到Bundle 
→ Activity被销毁

恢复状态流程：

用户返回应用 → 系统重新创建Activity → onCreate()接收Bundle参数 
→ 或调用onRestoreInstanceState() → 状态恢复完成

🔧 Activity与Flutter的关系

Flutter应用中的Activity：###

Flutter应用架构
├── MainActivity (唯一的Activity)
│   └── FlutterEngine
│       └── Flutter Widget树
│           ├── MaterialApp
│           ├── 页面1 (Flutter路由)
│           ├── 页面2 (Flutter路由)
│           └── 页面3 (Flutter路由)

关键点：

1. 单Activity架构：Flutter应用通常只有一个MainActivity
2. Flutter路由：页面切换通过Flutter的Navigator实现，不是Activity切换
3. 状态依赖：Flutter的状态恢复仍然依赖MainActivity的生命周期

restorationScopeId 属性详解(包括：restorationId属性)

不要看了，我没找到系统的测试方案

🔧 restorationScopeId 是什么？

restorationScopeId 是 Flutter 中用于标识应用状态恢复范围的属性。它主要用于控制应用状态恢复的范围和行为。

🔧 restorationScopeId 的作用

1. 创建恢复范围：为应用建立状态恢复的边界范围
2. 启用状态恢复：激活Flutter的状态恢复机制
3. 状态持久化：将应用状态保存到系统提供的存储中
4. 自动恢复：应用重启时自动恢复保存的状态

restorationScopeId 保存原理详解

🏗️ 底层架构原理

Flutter状态恢复架构：

应用层 (Flutter App)
├── MaterialApp (restorationScopeId: 'app')
├── Widget Tree (各种有状态的Widget)
└── RestorationMixin (状态恢复接口)

框架层 (Flutter Framework)
├── RestorationManager (全局状态管理器)
├── RestorationBucket (状态存储容器)
├── RestorableProperty (可恢复属性基类)
└── Serialization (序列化机制)

平台层 (Native Platform)
├── Android: Bundle + onSaveInstanceState
├── iOS: State Restoration API + NSCoder
└── Web/Desktop: LocalStorage/SessionStorage

📋 具有restorationScopeId、restorationId属性的Widget

应用级别Widget（restorationScopeId）：

Widget	作用	说明
MaterialApp	Material Design应用根组件	为整个应用设置状态恢复范围
CupertinoApp	iOS风格应用根组件	为整个应用设置状态恢复范围
WidgetsApp	基础应用组件	Flutter应用的最底层根组件

注意区别：

• restorationScopeId：用于应用级别的根组件，定义状态恢复的范围
• restorationId：用于具体的Widget，标识需要恢复状态的组件

📋 具有restorationId属性的常见Widget

滚动组件：

• ListView - 恢复滚动位置
• GridView - 恢复滚动位置
• PageView - 恢复当前页面
• SingleChildScrollView - 恢复滚动位置
• NestedScrollView - 恢复嵌套滚动状态
• CustomScrollView - 恢复自定义滚动状态

输入组件：

• TextField - 恢复输入内容
• TextFormField - 恢复表单输入内容
• DropdownButton - 恢复选择状态
• Checkbox - 恢复勾选状态
• Radio - 恢复选择状态
• Switch - 恢复开关状态

导航组件：

• Navigator - 恢复导航堆栈
• TabBarView - 恢复标签页状态

shortcuts、actions 属性详解（桌面端、Web端）

🎹 shortcuts 是什么？

shortcuts 是 MaterialApp 中用于定义全局快捷键映射的属性。它允许开发者为应用定义键盘快捷键，并将这些快捷键映射到特定的意图(Intent)上，从而触发相应的操作。

📋 基本概念

shortcuts 的核心组件：

组件	类型	作用	示例
ShortcutActivator	快捷键激活器	定义触发快捷键的按键组合	Ctrl+C、Alt+F4
Intent	意图	定义要执行的抽象操作	CopyIntent、PasteIntent
Action	动作	具体执行操作的实现	复制到剪贴板、粘贴内容

🔧 基本用法

MaterialApp(
  shortcuts: {
    // Ctrl+N: 新建
    LogicalKeySet(LogicalKeyboardKey.control, LogicalKeyboardKey.keyN): NewIntent(),
    
    // Ctrl+S: 保存
    LogicalKeySet(LogicalKeyboardKey.control, LogicalKeyboardKey.keyS): SaveIntent(),
    
    // Ctrl+Z: 撤销
    LogicalKeySet(LogicalKeyboardKey.control, LogicalKeyboardKey.keyZ): UndoIntent(),
    
    // F5: 刷新
    LogicalKeySet(LogicalKeyboardKey.f5): RefreshIntent(),
    
    // Alt+F4: 退出（Windows风格）
    LogicalKeySet(LogicalKeyboardKey.alt, LogicalKeyboardKey.f4): ExitIntent(),
  },
  actions: {
    NewIntent: NewAction(),
    SaveIntent: SaveAction(),
    UndoIntent: UndoAction(),
    RefreshIntent: RefreshAction(),
    ExitIntent: ExitAction(),
  },
  home: MyHomePage(),
)

🎨 完整示例

1. 定义Intent（意图）：

// 自定义意图类
class NewIntent extends Intent {}
class SaveIntent extends Intent {}
class UndoIntent extends Intent {}
class RefreshIntent extends Intent {}
class ExitIntent extends Intent {}

2. 定义Action（动作）：

// 新建动作
class NewAction extends Action<NewIntent> {
  @override
  void invoke(NewIntent intent) {
    print('执行新建操作');
    // 实际的新建逻辑
  }
}

// 保存动作
class SaveAction extends Action<SaveIntent> {
  @override
  void invoke(SaveIntent intent) {
    print('执行保存操作');
    // 实际的保存逻辑
  }
}

// 撤销动作
class UndoAction extends Action<UndoIntent> {
  @override
  void invoke(UndoIntent intent) {
    print('执行撤销操作');
    // 实际的撤销逻辑
  }
}

🖥️ 平台差异处理

跨平台快捷键适配：

MaterialApp(
  shortcuts: {
    // Windows/Linux: Ctrl+快捷键
    if (Platform.isWindows || Platform.isLinux) ...{
      LogicalKeySet(LogicalKeyboardKey.control, LogicalKeyboardKey.keyN): NewIntent(),
      LogicalKeySet(LogicalKeyboardKey.control, LogicalKeyboardKey.keyS): SaveIntent(),
      LogicalKeySet(LogicalKeyboardKey.alt, LogicalKeyboardKey.f4): ExitIntent(),
    },
    
    // macOS: Cmd+快捷键
    if (Platform.isMacOS) ...{
      LogicalKeySet(LogicalKeyboardKey.meta, LogicalKeyboardKey.keyN): NewIntent(),
      LogicalKeySet(LogicalKeyboardKey.meta, LogicalKeyboardKey.keyS): SaveIntent(),
      LogicalKeySet(LogicalKeyboardKey.meta, LogicalKeyboardKey.keyQ): ExitIntent(),
    },
    
    // 通用快捷键
    LogicalKeySet(LogicalKeyboardKey.f5): RefreshIntent(),
    LogicalKeySet(LogicalKeyboardKey.escape): CancelIntent(),
  },
)

开发调试属性详解

🛠️ 六个开发调试属性的作用

属性	类型	默认值	主要作用
debugShowMaterialGrid	bool	false	显示Material Design网格线，帮助检查布局对齐
showPerformanceOverlay	bool	false	显示性能监控覆盖层，监控FPS和GPU使用情况
checkerboardRasterCacheImages	bool	false	显示光栅缓存图像的棋盘模式，检查图像缓存效果
checkerboardOffscreenLayers	bool	false	显示离屏渲染层的棋盘模式，检查渲染层使用情况
showSemanticsDebugger	bool	false	显示语义调试器，检查无障碍功能实现
debugShowCheckedModeBanner	bool	true	显示/隐藏右上角的DEBUG横幅标识

📋 各属性详细说明

1. debugShowMaterialGrid

• 作用：在屏幕上显示Material Design的8dp网格线
• 用途：帮助开发者检查UI元素是否符合Material Design规范
• 使用场景：布局调试、设计规范检查
• 建议：仅在开发环境使用，发布时设为false

2. showPerformanceOverlay

• 作用：显示实时性能监控信息（FPS、GPU使用率、内存使用等）
• 用途：监控应用性能，识别性能瓶颈
• 显示内容：帧率图表、GPU使用情况、内存占用
• 建议：性能调优时开启，正常开发时关闭

3. checkerboardRasterCacheImages

• 作用：将使用光栅缓存的图像以棋盘模式显示
• 用途：检查哪些图像被缓存，优化图像渲染性能
• 显示效果：缓存的图像会显示为棋盘图案
• 建议：图像性能优化时使用

4. checkerboardOffscreenLayers

• 作用：将离屏渲染的层以棋盘模式显示
• 用途：识别不必要的离屏渲染，优化渲染性能
• 显示效果：离屏渲染区域显示为棋盘图案
• 建议：渲染性能调试时使用

5. showSemanticsDebugger

• 作用：显示语义树信息，用于无障碍功能调试
• 用途：检查屏幕阅读器能否正确识别UI元素
• 显示内容：语义节点边界、标签、操作等
• 建议：开发无障碍功能时使用

6. debugShowCheckedModeBanner

• 作用：控制是否显示右上角的"DEBUG"横幅
• 用途：标识当前为调试模式
• 显示位置：应用右上角
• 建议：开发时可设为false隐藏，避免截图时出现

🎯 实际使用示例

MaterialApp(
  // 开发调试配置（仅在开发环境使用）
  debugShowMaterialGrid: kDebugMode ? false : false,        // 显示Material网格
  showPerformanceOverlay: kDebugMode ? false : false,       // 显示性能监控
  checkerboardRasterCacheImages: kDebugMode ? false : false, // 显示图像缓存
  checkerboardOffscreenLayers: kDebugMode ? false : false,  // 显示离屏渲染
  showSemanticsDebugger: kDebugMode ? false : false,        // 显示语义调试
  debugShowCheckedModeBanner: kDebugMode ? false : false,   // 隐藏DEBUG横幅
  
  home: MyHomePage(),
)

⚠️ 使用注意事项

1. 仅用于开发环境：这些属性只应在开发和调试时使用
2. 性能影响：开启调试功能会影响应用性能
3. 发布前关闭：发布版本必须将这些属性设为false
4. 按需开启：根据具体调试需求选择性开启，避免同时开启多个

🚀 调试工作流建议

布局调试流程：

1. 开启debugShowMaterialGrid检查对齐
2. 使用showSemanticsDebugger验证无障碍

性能调试流程：

1. 开启showPerformanceOverlay监控整体性能
2. 使用checkerboardRasterCacheImages优化图像缓存
3. 使用checkerboardOffscreenLayers减少不必要渲染

发布准备：

• 将所有调试属性设为false
• 或使用kDebugMode条件控制

scrollBehavior 属性详解

🖱️ scrollBehavior 是什么？

scrollBehavior 是 MaterialApp 中用于定义应用全局滚动行为的属性。它允许开发者自定义滚动物理效果、滚动条样式和滚动交互行为，实现跨平台一致的滚动体验。

🎯 主要作用

1. 统一滚动体验：在不同平台提供一致的滚动行为
2. 自定义滚动效果：修改默认的滚动物理效果和视觉反馈
3. 跨平台兼容：解决不同平台滚动行为的差异
4. 滚动条控制：自定义滚动条的显示和样式

📋 平台默认滚动行为差异

平台	默认滚动物理	边界效果	滚动条	特点
Android	ClampingScrollPhysics	发光效果(Glow)	隐藏	到边界时显示发光（在列表最顶部和最底部下拉、上拉显示白色，半椭圆的效果）
iOS	BouncingScrollPhysics	弹性回弹	隐藏	超出边界时弹性回弹 （在列表最顶部和最底部下拉、上拉显示时弹性回弹）
Web	ClampingScrollPhysics	无特效	显示	传统滚动条显示
桌面	ClampingScrollPhysics	无特效	显示	类似Web的滚动体验

🔧 基本用法

MaterialApp(
  scrollBehavior: CustomScrollBehavior(), // 自定义滚动行为
  home: MyHomePage(),
)

class CustomScrollBehavior extends ScrollBehavior {
  @override
  ScrollPhysics getScrollPhysics(BuildContext context) {
    // 返回自定义的滚动物理效果
    return const BouncingScrollPhysics();
  }
  
  @override
  Widget buildOverscrollIndicator(BuildContext context, Widget child, ScrollableDetails details) {
    // 自定义边界滚动指示器
    return child; // 移除默认的边界效果
  }
  
  @override
  Widget buildScrollbar(BuildContext context, Widget child, ScrollableDetails details) {
    // 自定义滚动条
    return Scrollbar(child: child);
   //  return Scrollbar(
    //  thumbVisibility: true, // 始终显示滚动条
    //   thickness: 8.0,        // 滚动条粗细
    //   radius: Radius.circular(4.0), // 滚动条圆角
    //   child: child,
   //  ); 
  }
}

scrollBehavior 滚动效果测试案例

🧪 完整测试应用

以下是一个完整的测试应用，可以让您直观对比不同滚动行为的效果：

import 'package:flutter/material.dart';
import 'package:flutter/foundation.dart';
import 'dart:io';

void main() {
  runApp(ScrollBehaviorTestApp());
}

class ScrollBehaviorTestApp extends StatefulWidget {
  @override
  _ScrollBehaviorTestAppState createState() => _ScrollBehaviorTestAppState();
}

class _ScrollBehaviorTestAppState extends State<ScrollBehaviorTestApp> {
  ScrollBehaviorType _currentBehavior = ScrollBehaviorType.platformDefault;
  
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: '滚动行为测试',
      scrollBehavior: _getScrollBehavior(_currentBehavior),
      home: ScrollTestHomePage(
        currentBehavior: _currentBehavior,
        onBehaviorChanged: (behavior) {
          setState(() {
            _currentBehavior = behavior;
          });
        },
      ),
    );
  }
  
  ScrollBehavior _getScrollBehavior(ScrollBehaviorType type) {
    switch (type) {
      case ScrollBehaviorType.platformDefault:
        return ScrollBehavior(); // 平台默认
      case ScrollBehaviorType.androidOriginal:
        return AndroidOriginalScrollBehavior();
      case ScrollBehaviorType.iOSBouncing:
        return IOSBouncingScrollBehavior();
      case ScrollBehaviorType.noOverscroll:
        return NoOverscrollScrollBehavior();
      case ScrollBehaviorType.customScrollbar:
        return CustomScrollbarBehavior();
    }
  }
}

enum ScrollBehaviorType {
  platformDefault,
  androidOriginal,
  iOSBouncing,
  noOverscroll,
  customScrollbar,
  desktopOptimized,
}

class ScrollTestHomePage extends StatelessWidget {
  final ScrollBehaviorType currentBehavior;
  final Function(ScrollBehaviorType) onBehaviorChanged;
  
  const ScrollTestHomePage({
    Key? key,
    required this.currentBehavior,
    required this.onBehaviorChanged,
  }) : super(key: key);
  
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('滚动行为测试'),
        backgroundColor: Colors.blue,
      ),
      body: Column(
        children: [
          // 滚动行为选择器
          Container(
            padding: EdgeInsets.all(16),
            color: Colors.grey[100],
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Text(
                  '当前滚动行为: ${_getBehaviorName(currentBehavior)}',
                  style: TextStyle(fontSize: 16, fontWeight: FontWeight.bold),
                ),
                SizedBox(height: 10),
                Wrap(
                  spacing: 8,
                  children: ScrollBehaviorType.values.map((type) {
                    return ChoiceChip(
                      label: Text(_getBehaviorName(type)),
                      selected: currentBehavior == type,
                      onSelected: (selected) {
                        if (selected) onBehaviorChanged(type);
                      },
                    );
                  }).toList(),
                ),
              ],
            ),
          ),
          
          // 测试说明
          Container(
            padding: EdgeInsets.all(16),
            color: Colors.blue[50],
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Text('📱 测试方法:', style: TextStyle(fontWeight: FontWeight.bold)),
                Text('1. 选择不同的滚动行为'),
                Text('2. 滚动下方列表到顶部或底部'),
                Text('3. 观察边界滚动效果的差异'),
                Text('4. 注意滚动条的显示情况'),
              ],
            ),
          ),
          
          // 滚动测试区域
          Expanded(
            child: ListView.builder(
              itemCount: 50,
              itemBuilder: (context, index) {
                return Card(
                  margin: EdgeInsets.symmetric(horizontal: 16, vertical: 4),
                  child: ListTile(
                    leading: CircleAvatar(
                      backgroundColor: Colors.blue,
                      child: Text('${index + 1}'),
                    ),
                    title: Text('测试项目 ${index + 1}'),
                    subtitle: Text('滚动到边界查看效果差异'),
                    trailing: Icon(Icons.arrow_forward_ios),
                  ),
                );
              },
            ),
          ),
        ],
      ),
    );
  }
  
  String _getBehaviorName(ScrollBehaviorType type) {
    switch (type) {
      case ScrollBehaviorType.platformDefault:
        return '平台默认';
      case ScrollBehaviorType.androidOriginal:
        return 'Android原生';
      case ScrollBehaviorType.iOSBouncing:
        return 'iOS弹性';
      case ScrollBehaviorType.noOverscroll:
        return '无边界效果';
      case ScrollBehaviorType.customScrollbar:
        return '自定义滚动条';
    }
  }
}

// 1. Android原生滚动行为
class AndroidOriginalScrollBehavior extends ScrollBehavior {
  @override
  ScrollPhysics getScrollPhysics(BuildContext context) {
    return ClampingScrollPhysics(); // Android原生的夹紧物理效果
  }
  
  @override
  Widget buildOverscrollIndicator(BuildContext context, Widget child, ScrollableDetails details) {
    // 显示Android原生的发光效果
    return GlowingOverscrollIndicator(
      axisDirection: details.direction,
      color: Colors.blue, // 自定义发光颜色
      child: child,
    );
  }
}

// 2. iOS弹性滚动行为
class IOSBouncingScrollBehavior extends ScrollBehavior {
  @override
  ScrollPhysics getScrollPhysics(BuildContext context) {
    return BouncingScrollPhysics(); // iOS的弹性物理效果
  }
  
  @override
  Widget buildOverscrollIndicator(BuildContext context, Widget child, ScrollableDetails details) {
    return child; // iOS不显示额外的边界指示器
  }
}

// 3. 无边界效果滚动行为
class NoOverscrollScrollBehavior extends ScrollBehavior {
  @override
  ScrollPhysics getScrollPhysics(BuildContext context) {
    return ClampingScrollPhysics();
  }
  
  @override
  Widget buildOverscrollIndicator(BuildContext context, Widget child, ScrollableDetails details) {
    return child; // 完全移除边界效果
  }
}

// 4. 自定义滚动条行为
class CustomScrollbarBehavior extends ScrollBehavior {
  @override
  Widget buildScrollbar(BuildContext context, Widget child, ScrollableDetails details) {
    return Scrollbar(
      controller: details.controller,
      thumbVisibility: true, // 始终显示滚动条
      thickness: 12.0,       // 较粗的滚动条
      radius: Radius.circular(6.0),
      trackVisibility: true, // 显示滚动轨道
      child: child,
    );
  }
  
  @override
  ScrollPhysics getScrollPhysics(BuildContext context) {
    return BouncingScrollPhysics();
  }
}

🔍 观察要点

滚动物理效果：

• ClampingScrollPhysics：到边界立即停止
• BouncingScrollPhysics：可以超出边界并弹回

边界视觉反馈：

• GlowingOverscrollIndicator：Android的发光效果
• 无指示器：干净的边界体验

通过这个完整的测试案例，您可以直观地对比不同滚动行为的效果，帮助选择最适合您应用的滚动体验。