Flutter AppBarTheme构造函数弃用导致主题报错如何解决

问题背景 #

跟随公开教程《Flutter Course - Full Tutorial for Beginners (Build iOS and Android Apps)》实操到视频43分47秒位置时出现报错：
原本期望全局配置项目AppBar的文本主题，实现逻辑为将自定义TextStyle常量AppBarTextStyle作为TextTheme构造函数入参，再把生成的TextTheme实例传入AppBarTheme，但配置完全不生效。
涉及的两个文件原始代码如下：

// app.dart
import 'package:flutter/material.dart';
import 'screens/location_detail/location_detail.dart';
import 'style.dart';

class App extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: LocationDetail(),
      theme: ThemeData(
        appBarTheme: AppBarTheme(
          textTheme: TextTheme(title: AppBarTextStyle),
        ),
      ),
    );
  }
}

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

const LargeTextSize = 26.0;
const MediumTextSize = 20.0;
const bodytextSize = 16.0;

const String FontNameDefault = "Montserrat";

const AppBarTextStyle = TextStyle(
  fontFamily: FontNameDefault,
  fontWeight: FontWeight.w300,
  fontSize: MediumTextSize,
  color: Colors.white,
);

查阅官方文档发现，教程录制后AppBarTheme的原有textTheme配置已被标记弃用，弃用提示如下：

@Deprecated('This property is no longer used, please use systemOverlayStyle instead. ' 'This feature was deprecated after v2.4.0-0.0.pre.')

按照提示替换为systemOverlayStyle配置后依然触发报错，无法实现预期效果。

问题原因 #

该问题由Flutter版本迭代带来的API变更导致，官方给出的弃用提示存在误导性：systemOverlayStyle仅用于配置状态栏的明暗、颜色等系统层UI样式，完全不负责AppBar内部的文本样式配置，属于典型的配置项匹配错误。
在Flutter v2.4.0-0.0.pre及之后的版本中，旧的AppBarTheme.textTheme参数被彻底移除，AppBar的文本样式拆分到了两个独立参数下：

• titleTextStyle：控制AppBar标题的文本样式
• toolbarTextStyle：控制AppBar工具栏内其他元素（返回按钮、操作按钮文字、leading图标旁文字等）的文本样式
  同时旧版本TextTheme的title字段也在后续迭代中更名为titleLarge，哪怕硬套旧的嵌套写法也会因为字段名变更无法生效。

修复方案 #

直接删除废弃的textTheme配置，将自定义文本样式赋值给对应的新参数即可，不需要嵌套TextTheme实例，修改后的app.dart代码如下：

// app.dart
import 'package:flutter/material.dart';
import 'screens/location_detail/location_detail.dart';
import 'style.dart';

class App extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: LocationDetail(),
      theme: ThemeData(
        appBarTheme: AppBarTheme(
          // 配置AppBar标题样式
          titleTextStyle: AppBarTextStyle,
          // 如需统一AppBar上其他文字/图标颜色，可按需配置backgroundColor、foregroundColor
          // backgroundColor: Colors.blueAccent,
          // foregroundColor: Colors.white,
          // 如需统一工具栏其他文本样式，打开下方注释即可
          // toolbarTextStyle: AppBarTextStyle,
        ),
      ),
    );
  }
}

修改后热重载即可全局生效所有AppBar的标题文本样式。

补充说明 #

如果使用Flutter 3.16及以上版本开启了Material3设计规范，AppBarTheme.foregroundColor会作为AppBar内所有文字、图标的默认fallback颜色，优先级低于单独配置的titleTextStyle、toolbarTextStyle，可以根据实际需求搭配使用。

内容的提问来源于stack exchange，提问作者Advaith Vijayakumar