Flutter ShadCN UI 中解决底部表单键盘遮挡问题

问题描述

在使用 Flutter ShadCN UI 库时，开发者可能会遇到一个常见问题：当使用底部弹出的表单(Sheet)包含输入字段时，软键盘会遮挡输入框内容。这种情况在移动端开发中尤为常见，特别是在 Android 设备上。

问题重现

通过创建一个简单的表单组件，包含两个输入字段（一个数字输入和一个多行文本输入），当点击输入框时，键盘会从底部弹出，但不会自动调整布局，导致输入框被键盘遮挡。

解决方案

Flutter ShadCN UI 库在 v0.5.1 版本中已经优化了这个问题。正确的实现方式如下：

1. 不需要手动添加滚动视图：与传统的 Flutter 解决方案不同，ShadCN UI 已经内置了处理键盘遮挡的逻辑

2. 简化组件结构：直接使用 ShadSheet 组件，不需要额外包裹 SingleChildScrollView

3. 自动调整布局：组件会自动处理键盘弹出时的布局调整

最佳实践代码

class ExpensesSheet extends StatefulWidget {
  const ExpensesSheet({super.key, required this.side});

  final ShadSheetSide side;

  @override
  State<ExpensesSheet> createState() => _ExpensesSheetState();
}

class _ExpensesSheetState extends State<ExpensesSheet> {
  final formKey = GlobalKey<ShadFormState>();
  final TextEditingController _expenses = TextEditingController();
  final TextEditingController _note = TextEditingController();

  @override
  void dispose() {
    _expenses.dispose();
    _note.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return ShadSheet(
      title: const Text('支出记录'),
      description: const Text("记录您的日常支出"),
      content: ShadForm(
        key: formKey,
        child: ConstrainedBox(
          constraints: const BoxConstraints(maxWidth: 350),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            mainAxisSize: MainAxisSize.min,
            children: [
              ShadInputFormField(
                id: 'expense',
                controller: _expenses,
                label: const Text('金额'),
                placeholder: const Text('例如: 500000'),
                keyboardType: TextInputType.number,
                inputFormatters: [FilteringTextInputFormatter.digitsOnly],
                validator: (v) {
                  if (v.length < 2) {
                    return '请输入有效金额';
                  }
                  return null;
                },
              ),
              const SizedBox(height: 16),
              ShadInputFormField(
                id: 'note',
                controller: _note,
                label: const Text('备注'),
                maxLines: 3,
              ),
            ],
          ),
        ),
      ),
      actions: [
        ShadButton(onPressed: () async {}, text: const Text('保存')),
      ],
    );
  }
}

技术原理

Flutter ShadCN UI 库在处理底部表单时，内部已经实现了以下机制：

1. 自动检测键盘状态：通过 MediaQuery 获取键盘高度
2. 动态调整布局：根据键盘高度自动调整表单位置
3. 优化用户体验：确保输入框始终可见，不被键盘遮挡

注意事项

1. 版本要求：确保使用 v0.5.1 或更高版本
2. 控制器管理：记得在 dispose 方法中释放 TextEditingController
3. 表单验证：合理设置验证逻辑，提升用户体验

通过这种方式，开发者可以轻松创建不会被键盘遮挡的底部表单，提供更好的用户体验。