自定义ListTile集成Flutter FormBuilder CheckboxListTile调试模式断言错误

问题根源 #

调试模式触发的Leading widget consumes entire tile width断言，是因为ListTile布局时检测到leading组件的宽度等于整个tile的宽度，违反了布局约束。你的场景里存在两个可能的触发点：自定义ListTile的leading/trailing中的Checkbox，以及FormBuilderCheckbox内部依赖的CheckboxListTile。

具体解决方法 #

1. 修复FormBuilderCheckbox内部的CheckboxListTile布局 #

FormBuilderCheckbox默认用CheckboxListTile实现，可通过调整其布局参数避免断言：

// 修改FormBuilderCheckbox中的CheckboxListTile配置
CheckboxListTile(
  dense: true,
  title: title,
  value: tristate ? state.value : (state.value ?? false),
  // 添加内容内边距，避免leading占满tile宽度
  contentPadding: EdgeInsets.symmetric(horizontal: 8.0),
  // 强制设置标题与leading的间距，确保布局计算正常
  horizontalTitleGap: 8.0,
)

2. 调整自定义ListTile中Checkbox的布局 #

虽然你的自定义Checkbox已经用SizedBox(width:35)包裹，但仍需确保它不会占满整个tile宽度：

// 修改_getLeading方法，添加右侧内边距
Widget? _getLeading() {
  ...
  if (widget.showCheckbox) {
    return Padding(
      padding: EdgeInsets.only(right: 8.0),
      child: _getCheckbox(),
    );
  }
  return null;
}

// 修改_getTrailing中的Checkbox，添加左侧内边距
Widget? _getTrailing() {
  return Row(
    mainAxisSize: MainAxisSize.min,
    children: <Widget>[
      if (widget.showCheckbox && widget.leadingIcon != null)
        Padding(
          padding: EdgeInsets.only(left: 8.0),
          child: _getCheckbox(),
        )
      ...
    ],
  );
}

如果你的自定义ListTile是继承自系统ListTile，还可以显式设置horizontalTitleGap参数：

class CustomListTile extends ListTile {
  CustomListTile({
    super.key,
    // 其他参数...
    super.horizontalTitleGap = 8.0, // 固定标题与leading的间距
  }) : super(...);
}

3. 替换CheckboxListTile为自定义布局（彻底解决） #

嵌套ListTile（自定义ListTile + CheckboxListTile）容易引发布局冲突，建议直接用Checkbox + Text的组合替代CheckboxListTile：

// 修改FormBuilderCheckbox的builder实现
builder: (FormFieldState<bool?> field) {
  final state = field as _FormBuilderCheckboxState;
  return InputDecorator(
    decoration: state.decoration,
    child: Row(
      mainAxisSize: MainAxisSize.min,
      children: [
        Checkbox(
          value: tristate ? state.value : (state.value ?? false),
          onChanged: state.didChange,
        ),
        SizedBox(width: 8.0),
        title,
      ],
    ),
  );
},

这种方式完全脱离ListTile的布局约束，从根源上避免断言触发。

4. 临时应急方案（不推荐） #

如果以上方法都无法快速生效，可在调试模式下临时禁用全局断言：

void main() {
  debugDisableAsserts = true;
  runApp(MyApp());
}

注意：此方法会禁用所有调试断言，不利于排查其他潜在问题，仅作为临时应急使用。

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