Flutter/Dart跨页面传递数据时编译报错的问题排查与修复

问题根因 #

• 构造函数不符合Flutter Widget编写规范：自定义Widget构造函数未显式声明命名参数列表，final修饰的Widget成员变量未在构造阶段完成初始化，直接传入参数会触发「命名参数不存在」「final字段未初始化」「const构造函数非法调用」三类编译错误。
• 参数接收位置错误：误将路由参数的接收变量定义在页面对应的State类（即报错信息中的_ListFromCSVState）中。路由参数是绑定在Widget实例上的属性，State类需要通过widget.xxx访问Widget持有的属性，直接在State类中声明未初始化的字段，就会触发「getter不存在」「setter不存在」的报错。
• RouteSettings传参链路断裂：页面跳转时未将参数挂载到RouteSettings的arguments字段，目标页面无法通过上下文拿到传入的参数。

可直接运行的修复代码 #

1. 主页面跳转传参逻辑 #

修正Navigator.push的写法，将参数统一挂载到RouteSettings中：

// 主页面「New Game」按钮点击逻辑
ElevatedButton(
  onPressed: () {
    Navigator.push(
      context,
      MaterialPageRoute(
        builder: (context) => const NewGameRoute(),
        // 核心：参数统一放在RouteSettings的arguments字段传递
        settings: RouteSettings(
          arguments: {
            '_listCount': 0,
            'assetPath': 'images/01.jpg',
          },
        ),
      ),
    );
  },
  child: const Text('New Game'),
)

2. 目标页面接收参数逻辑 #

注意接收参数的变量定义在State类中，通过生命周期方法从路由上下文取值，若你的State类名为_ListFromCSVState，仅需替换对应类名即可：

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

  @override
  State<NewGameRoute> createState() => _NewGameRouteState();
}

class _NewGameRouteState extends State<NewGameRoute> {
  // 用late修饰延迟初始化，避免final字段未初始化报错
  late int _listCount;
  late String assetPath;

  @override
  void didChangeDependencies() {
    super.didChangeDependencies();
    // 从RouteSettings中取出参数并做类型转换
    final routeArgs = ModalRoute.of(context)!.settings.arguments as Map<String, dynamic>;
    _listCount = routeArgs['_listCount'] as int;
    assetPath = routeArgs['assetPath'] as String;
  }

  @override
  Widget build(BuildContext context) {
    // 页面后续逻辑可直接调用_listCount、assetPath
    return Scaffold(
      appBar: AppBar(title: const Text('New Game')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Image.asset(assetPath),
            Text('初始列表数量：$_listCount'),
          ],
        ),
      ),
    );
  }
}

若偏好构造函数直接传参、不使用RouteSettings的写法，仅需调整两处：

1. 跳转时直接给Widget构造函数传参：NewGameRoute(listCount: 0, assetPath: "images/01.jpg")
2. Widget类显式声明命名参数：

class NewGameRoute extends StatefulWidget {
  const NewGameRoute({
    super.key,
    required this.listCount,
    required this.assetPath,
  });
  final int listCount;
  final String assetPath;

  @override
  State<NewGameRoute> createState() => _NewGameRouteState();
}

该写法下State类不需要单独存参数，直接通过widget.listCount、widget.assetPath即可访问传入值。

报错规避要点 #

• 自定义Widget的所有final成员变量，必须在构造函数中通过this.xxx的形式完成初始化；const构造函数要求类的所有成员变量都是final类型，否则会触发const构造非法的编译错误。
• 必传的命名参数必须加required关键字标注，否则会触发命名参数校验失败的错误。
• 禁止在State类中定义和Widget侧重名的参数字段，Widget持有的属性统一通过widget.属性名访问。
• 通过RouteSettings取参数的逻辑不要直接写在build方法中，放在didChangeDependencies生命周期执行可以保证ModalRoute已经正确挂载到上下文，避免空指针错误。

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