Flutter 弹窗 UI 不刷新？用 StatefulBuilder 解决

问题背景

在使用 Flutter 开发时，通过 showDialog 弹出的对话框，点击内部按钮后 UI 不会实时更新，相信不少开发者都踩过这个坑。

比如我们在弹窗里放了一个下拉选择器或筛选按钮，点击后数据变了，但界面没有任何视觉反馈，用户体验很差。

问题根因

showDialog 创建的弹窗，其 Widget 树与父页面是隔离的。父页面的 setState 只会触发自身 Widget 树的重建，无法让弹窗内部也跟着刷新。

看一个典型的问题代码：

less 复制代码

void _showDialog() {
  showDialog(
    context: context,
    builder: (ctx) => AlertDialog(
      title: Text('选择大小端'),
      content: DropdownButton<Endian>(
        value: _selectedEndian,      // 从父组件传入
        items: [...],
        onChanged: (v) {
          setState(() {
            _selectedEndian = v;      // 更新父状态
          });
          _saveConfig(v);             // 执行业务逻辑
        },
      ),
    ),
  );
}

点击下拉框后，setState 更新了 _selectedEndian，但弹窗的 UI 没有重建，因为 AlertDialog 不在 setState 触发的那棵 Widget 树下。

解决方案：StatefulBuilder

Flutter 官方早就想到了这个问题，提供了 StatefulBuilder 这个 widget，它能在弹窗内部创建独立的状态管理能力。

核心用法

less 复制代码

void _showDialog() {
  showDialog(
    context: context,
    builder: (ctx) => StatefulBuilder(    // 用 StatefulBuilder 包裹弹窗
      builder: (ctx, dialogSetState) {
        return AlertDialog(
          title: Text('选择大小端'),
          content: DropdownButton<Endian>(
            value: _selectedEndian,
            items: [...],
            onChanged: (v) {
              setState(() {
                _selectedEndian = v;
              });
              _saveConfig(v);
              dialogSetState(() {});       // 关键：刷新弹窗 UI
            },
          ),
        );
      },
    ),
  );
}

关键点 ：在 onChanged 回调的最后，调用 dialogSetState(() {})，这会触发 StatefulBuilder 内部的 UI 重建，让弹窗实时响应状态变化。

多个状态同时刷新

如果弹窗里有多个独立的状态需要管理，只需要一个 StatefulBuilder，所有的 dialogSetState 调用都会触发同一个 UI 重建：

less 复制代码

builder: (ctx, dialogSetState) {
  return AlertDialog(
    content: Column(
      children: [
        DropdownButton<Endian>(
          value: _endian,
          onChanged: (v) {
            setState(() => _endian = v);
            dialogSetState(() {});    // 刷新
          },
        ),
        Row(
          children: [
            FilterChip('全部', selected: _filter == 'all'),
            FilterChip('发送', selected: _filter == 'send'),
            FilterChip('接收', selected: _filter == 'recv'),
          ],
        ),
      ],
    ),
  );
}

初始化状态值

弹窗打开时，状态值需要从外部传入。如果希望每次打开弹窗都读取最新值（而非缓存值），可以直接在 builder 里访问父组件的状态：

less 复制代码

builder: (ctx, dialogSetState) {
  return AlertDialog(
    content: DropdownButton<Endian>(
      value: _endian,      // 父组件的当前状态，每次打开都是最新值
      items: [...],
      onChanged: (v) {
        setState(() => _endian = v);
        dialogSetState(() {});
      },
    ),
  );
}

完整示例

less 复制代码

class MyWidget extends StatefulWidget {
  @override
  State<MyWidget> createState() => _MyWidgetState();
}

class _MyWidgetState extends State<MyWidget> {
  Endian _endian = Endian.little;
  String _filter = 'all';

  void _showConfigDialog() {
    showDialog(
      context: context,
      builder: (ctx) => StatefulBuilder(
        builder: (ctx, dialogSetState) {
          return AlertDialog(
            title: Text('设置'),
            content: Column(
              mainAxisSize: MainAxisSize.min,
              children: [
                // 大小端选择
                DropdownButton<Endian>(
                  value: _endian,
                  isExpanded: true,
                  items: Endian.values.map((e) {
                    return DropdownMenuItem(
                      value: e,
                      child: Text(e.label),
                    );
                  }).toList(),
                  onChanged: (v) {
                    setState(() => _endian = v!);
                    _saveEndian(v);
                    dialogSetState(() {});   // 刷新弹窗
                  },
                ),
                SizedBox(height: 16),
                // 筛选按钮
                Row(
                  children: [
                    _buildFilterChip('全部', 'all'),
                    _buildFilterChip('发送', 'send'),
                    _buildFilterChip('接收', 'recv'),
                  ],
                ),
              ],
            ),
            actions: [
              TextButton(
                onPressed: () => Navigator.pop(ctx),
                child: Text('关闭'),
              ),
            ],
          );
        },
      ),
    );
  }

  Widget _buildFilterChip(String label, String value) {
    final isActive = _filter == value;
    return Expanded(
      child: GestureDetector(
        onTap: () {
          setState(() => _filter = value);
          _saveFilter(value);
          // 需要通过 GlobalKey 或其他方式获取 dialogSetState
          // 这里只是示意，实际使用见下一节
        },
        child: Container(
          padding: EdgeInsets.all(8),
          decoration: BoxDecoration(
            color: isActive ? Colors.blue : Colors.grey[200],
            borderRadius: BorderRadius.circular(8),
          ),
          child: Text(
            label,
            style: TextStyle(
              color: isActive ? Colors.white : Colors.black,
            ),
          ),
        ),
      ),
    );
  }
}

进阶：向子组件传递 dialogSetState

如果弹窗内容较复杂，拆分成多个子 widget，需要把 dialogSetState 传递给子组件。有两种方式：

方式一：通过回调传递

less 复制代码

builder: (ctx, dialogSetState) {
  return AlertDialog(
    content: Column(
      children: [
        _buildEndianDropdown(
          value: _endian,
          onChanged: (v) {
            setState(() => _endian = v);
            dialogSetState(() {});   // 传回调
          },
        ),
      ],
    ),
  );
},

Widget _buildEndianDropdown({
  required Endian value,
  required ValueChanged<Endian> onChanged,
}) {
  return DropdownButton<Endian>(
    value: value,
    items: [...],
    onChanged: onChanged,
  );
}

方式二：使用 GlobalKey（不推荐用于此场景）

有些文章会用 GlobalKey<State> 来获取子组件的 state 并调用 setState，但这种方式增加了耦合，不推荐在弹窗场景使用。StatefulBuilder 才是最简洁优雅的方案。

原理浅析

StatefulBuilder 内部创建了一个 StatefulElement，它持有自己的 State 对象。当调用 dialogSetState 时，会触发这个 State 的 build 方法重建，从而更新弹窗 UI。

r 复制代码

showDialog
  └── StatefulBuilder           <- 有独立的 State
        └── AlertDialog          <- 依赖 StatefulBuilder 的 State
              └── DropdownButton  <- 状态变化时调用 dialogSetState 刷新

总结

场景	方案
简单弹窗，单一状态	`StatefulBuilder` + `dialogSetState`
复杂弹窗，多个状态	一个 `StatefulBuilder` 管理所有状态
子组件需要更新弹窗	通过 `ValueChanged` 回调传递 `dialogSetState`
避免使用	`GlobalKey`（过度设计）

StatefulBuilder 是 Flutter 官方提供的轻量级方案，无需引入 Provider、Bloc 等状态管理库，就能优雅解决弹窗 UI 不刷新的问题。