Flutter/Dart中initState无法异步加载JSON导致构建报错的解决方法

针对你遇到的RangeError (index)问题，本质是UI构建时异步加载的JSON数据还没返回，列表为空但UI已经在尝试渲染列表项。这里给你几个适合新手的解决方案：

方案一：用FutureBuilder处理异步状态 #

这是最直接的方式，FutureBuilder会自动监听异步任务的状态，根据不同状态返回对应的UI：

class UpgradeTab extends StatefulWidget {
  @override
  _UpgradeTabState createState() => _UpgradeTabState();
}

class _UpgradeTabState extends State<UpgradeTab> {
  late Future<List<dynamic>> _axeListFuture;

  @override
  void initState() {
    super.initState();
    // 初始化异步任务，无需给initState加async
    _axeListFuture = loadAxeData();
  }

  // JSON加载方法
  Future<List<dynamic>> loadAxeData() async {
    String jsonString = await rootBundle.loadString('assets/axes.json');
    return jsonDecode(jsonString);
  }

  @override
  Widget build(BuildContext context) {
    return FutureBuilder<List<dynamic>>(
      future: _axeListFuture,
      builder: (context, snapshot) {
        if (snapshot.connectionState == ConnectionState.waiting) {
          // 数据加载中，显示加载提示
          return Center(child: CircularProgressIndicator());
        } else if (snapshot.hasError) {
          // 加载出错，显示错误信息
          return Center(child: Text('加载失败: ${snapshot.error}'));
        } else if (!snapshot.hasData || snapshot.data!.isEmpty) {
          // 无数据时的占位UI
          return Center(child: Text('暂无升级项'));
        } else {
          // 数据就绪，渲染升级项列表
          List<dynamic> axeList = snapshot.data!;
          return ListView.builder(
            itemCount: axeList.length,
            itemBuilder: (context, index) {
              return ListTile(
                title: Text(axeList[index]['name']),
                subtitle: Text('价格: ${axeList[index]['cost']}'),
              );
            },
          );
        }
      },
    );
  }
}

方案二：手动管理加载状态+setState更新 #

如果你不想用FutureBuilder，可以在状态里维护一个加载状态标记，异步加载完成后调用setState刷新UI：

class UpgradeTab extends StatefulWidget {
  @override
  _UpgradeTabState createState() => _UpgradeTabState();
}

class _UpgradeTabState extends State<UpgradeTab> {
  List<dynamic> _axeList = [];
  bool _isLoading = true;

  @override
  void initState() {
    super.initState();
    // 调用异步加载方法，无需给initState加async
    _loadAxeData();
  }

  void _loadAxeData() async {
    String jsonString = await rootBundle.loadString('assets/axes.json');
    List<dynamic> data = jsonDecode(jsonString);
    // 加载完成后更新状态，触发build刷新
    setState(() {
      _axeList = data;
      _isLoading = false;
    });
  }

  @override
  Widget build(BuildContext context) {
    if (_isLoading) {
      return Center(child: CircularProgressIndicator());
    }
    if (_axeList.isEmpty) {
      return Center(child: Text('暂无升级项'));
    }
    return ListView.builder(
      itemCount: _axeList.length,
      itemBuilder: (context, index) {
        return ListTile(
          title: Text(_axeList[index]['name']),
          subtitle: Text('价格: ${_axeList[index]['cost']}'),
        );
      },
    );
  }
}

核心逻辑说明 #

• 方案一的FutureBuilder会自动处理异步任务的各个阶段（等待、成功、失败），避免在数据未就绪时渲染依赖数据的UI。
• 方案二通过_isLoading标记控制build时的UI输出，只有当数据加载完成后才渲染列表，从根源避免空列表的索引错误。

另外注意：不要尝试给initState加async关键字——Flutter的生命周期方法不允许异步返回值，这会导致框架无法正确管理组件状态。

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