🔧 基础配置
1. 安装依赖
在 pubspec.yaml 中添加依赖并执行 flutter pub get：
dependencies:
flutter_screenutil: ^5.9.3 # 截至2025年最新稳定版[1,3](@ref)
2. 全局初始化
在 main.dart 的根组件外层包裹 ScreenUtilInit，并设置设计稿基准尺寸：
void main() => runApp(MyApp());
class MyApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
return ScreenUtilInit(
designSize: const Size(375, 812), // 推荐移动端使用iPhone 13尺寸[3](@ref)
minTextAdapt: true, // 文本基于宽/高中较小值适配
splitScreenMode: true, // 支持分屏模式（如折叠屏）
builder: (_, child) => MaterialApp(home: child),
child: const HomePage(),
);
}
}
🎯 核心功能
1. 尺寸适配
- 基础单位
使用 .w（宽度比例）、.h（高度比例）、.r（取宽高较小值，适合圆形元素）：
Container(
width: 200.w, // 设计稿200px宽度
height: 100.h, // 设计稿100px高度
margin: EdgeInsets.all(10.r), // 圆形元素适配
)
- 百分比布局
通过 .sw（屏幕宽度百分比）和 .sh（屏幕高度百分比）简化代码
Container(
width: 0.8.sw, // 屏幕宽度的80%
height: 0.5.sh, // 屏幕高度的50%
)
2. 字体适配
- 动态缩放策略：
Text(
'自适应文本',
style: TextStyle(
fontSize: 24.sp, // 基础适配（受系统字体设置影响）
fontSize: 24.ssp, // 强制跟随系统缩放
fontSize: 24.nsp, // 禁用系统缩放[3](@ref)
),
)
3. 安全区域处理
自动适配刘海屏、全面屏底部安全区
Padding(
padding: EdgeInsets.only(bottom: 20.h + ScreenUtil().bottomBarHeight),
)
4. 横竖屏动态适配
通过 OrientationBuilder 实现布局切换
OrientationBuilder(
builder: (context, orientation) {
return orientation == Orientation.portrait
? _buildPortraitLayout()
: _buildLandscapeLayout();
},
)
⚠️ 注意事项
- 设计稿一致性
- 确保团队统一设计稿尺寸（如375x812）， 避免多版本混乱。
- 使用 .r 替代固定宽高比，防止图片拉伸或模糊。
全局单例初始化
- 仅在根组件初始化一次，避免重复创建导致计算错误。
字体缩放控制
- 若需禁用系统字体缩放，全局设置 allowFontScaling: false。
布局溢出处理
- 结合 SingleChildScrollView 或 Flexible 防止内容超出屏幕。
🛠️ 高级技巧
1. 多设备适配策略
// 平板/手机布局切换
if (ScreenUtil().screenWidth > 600) {
return _buildTabletLayout();
} else {
return _buildPhoneLayout();
}
2. 测试验证
// 平板/手机布局切换
testWidgets('适配测试', (tester) async {
await tester.pumpWidget(ScreenUtilInit(...));
await tester.pumpAndSettle(); // 等待布局稳定
expect(find.byType(Container), matchesGoldenFile('golden.png'));
});
3. 性能优化
- 缓存高频使用尺寸（如 final buttonHeight = 48.h）。
- 避免嵌套过多 .w/.h，优先使用百分比布局。
