10 多端适配问题与解决

结论先行：会有适配问题，但大部分集中在“与系统交互的边界”上，而不是 UI 本身。Flutter 自绘保证了控件外观一致，适配工作主要来自：屏幕形态、系统栏与安全区、字体、键盘、返回/手势、权限、原生插件、平台规范差异。

10.1 适配问题全景

类别	是否存在	严重度	主要平台
UI 外观一致性	基本没有（自绘）	低	—
屏幕尺寸 / 折叠屏 / 平板 / 横竖屏	有	中	三端
刘海、挖孔、状态栏、导航栏、手势条	有	中	三端，Android 15+ edge-to-edge
字体与行高	有	中	Android 厂商字体、鸿蒙 HarmonyOS Sans
系统字体缩放（大字模式）	有	中	三端
软键盘	有	中	Android 厂商、鸿蒙
返回键 / 侧滑返回 / 预测性返回	有	中	Android、iOS、鸿蒙各不同
权限模型	有	中	三端各不同
原生插件可用性	有	高	鸿蒙最突出
深色模式	有	低	三端
平台交互规范（iOS 风格 vs Material）	有	低-中	iOS
厂商 ROM 差异（后台限制、推送）	有	中	Android 国产 ROM

10.2 屏幕适配

Flutter 的尺寸单位是逻辑像素（≈ dp），默认行为与 Android 用 dp 布局相同：大屏显示更多内容，而不是等比例放大。

方案 1：响应式布局（推荐）

class ResponsiveFeed extends StatelessWidget {
  const ResponsiveFeed({super.key});

  @override
  Widget build(BuildContext context) {
    final width = MediaQuery.sizeOf(context).width;   // 用 sizeOf，只在尺寸变化时重建
    // 断点参考 Material 3 window size classes
    final columns = width < 600 ? 1 : (width < 840 ? 2 : 3);
    return GridView.builder(
      gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(crossAxisCount: columns),
      itemBuilder: (_, i) => FeedCard(index: i),
    );
  }
}

// 根据父容器而不是屏幕决定布局（组件级响应式）
LayoutBuilder(builder: (context, constraints) {
  return constraints.maxWidth > 600 ? const TwoPaneLayout() : const SinglePaneLayout();
});

注意用 MediaQuery.sizeOf(context)、MediaQuery.paddingOf(context) 等细分方法，而不是 MediaQuery.of(context).size —— 后者会在任何 MediaQuery 属性（如键盘弹出导致的 viewInsets）变化时都触发重建。

方案 2：按设计稿等比缩放

国内项目常用 flutter_screenutil（以 375×812 设计稿为基准缩放）：Container(width: 100.w, height: 50.h)、fontSize: 14.sp。

优点：还原设计稿快。
缺点：平板、折叠屏展开后元素被放得很大；与系统字体缩放叠加时容易溢出。建议只在手机竖屏使用，平板/折叠屏走响应式分支。

折叠屏 / 多窗口 / 平板

折叠屏展开、分屏、自由窗口时，MediaQuery.size 会变化，Widget 会自动重建，无需 Activity 重建（前提是 configChanges 配置齐全，见第 7 章）。
获取折叠铰链位置：MediaQuery.of(context).displayFeatures（Android 依赖 Jetpack WindowManager，Flutter 已内置）。
鸿蒙折叠屏（Mate X 系列、Pura X）：同样通过尺寸变化处理；需在 module.json5 中声明支持的窗口模式，真机验证展开/折叠切换。
横竖屏锁定：

await SystemChrome.setPreferredOrientations([DeviceOrientation.portraitUp]);

10.3 安全区与系统栏

Scaffold(
  body: SafeArea(                 // 避开状态栏、刘海、底部手势条
    bottom: false,                // 底部由自己处理（例如列表需要延伸到底部）
    child: ListView(padding: EdgeInsets.only(bottom: MediaQuery.paddingOf(context).bottom)),
  ),
);

// 状态栏/导航栏样式
AnnotatedRegion<SystemUiOverlayStyle>(
  value: SystemUiOverlayStyle.dark.copyWith(
    statusBarColor: Colors.transparent,
    systemNavigationBarColor: Colors.transparent,
  ),
  child: ...,
);

// 沉浸式（视频全屏播放）
SystemChrome.setEnabledSystemUIMode(SystemUiMode.immersiveSticky);
// 退出时恢复
SystemChrome.setEnabledSystemUIMode(SystemUiMode.edgeToEdge);

Android 15（targetSdk 35+）强制 edge-to-edge，内容默认绘制到系统栏下方。Flutter 新版本默认就是 edge-to-edge，用 SafeArea 处理即可。
屏幕圆角：3.44 起可通过 MediaQueryData.displayCornerRadii 获取，用于全屏卡片圆角贴合。
鸿蒙：SafeArea 的值来自鸿蒙窗口的避让区域（状态栏、导航条、挖孔），老版本 Flutter OH 存在避让区域不准的问题，升级到新版本或在 ArkTS 侧设置窗口全屏布局。

10.4 字体

问题：

Android 各厂商替换了系统字体（MIUI/HyperOS 的 MiSans、ColorOS 的 OPPO Sans 等），中文字体回退链不同，同样的 fontSize 行高、字重渲染不同。
鸿蒙默认字体为 HarmonyOS Sans；iOS 为苹方。
中文与英文/数字混排时基线不齐、行高被撑开。

解决：

// 1. 关键页面内置字体（注意包体积，中文字体可裁剪子集）
ThemeData(fontFamily: 'MyFont');

// 2. 固定行高，消除平台差异
const TextStyle(
  fontSize: 14,
  height: 1.4,                                  // 行高 = fontSize * height
  leadingDistribution: TextLeadingDistribution.even,  // 上下均分行距，文字垂直居中更准
);

// 3. 统一行高策略（避免不同字体的 ascent/descent 影响）
const StrutStyle(fontSize: 14, height: 1.4, forceStrutHeight: true);

字体缩放（系统设置大字体）：

// 限制缩放范围，而不是直接禁用（无障碍需要）
MaterialApp(
  builder: (context, child) {
    final scaler = MediaQuery.textScalerOf(context).clamp(minScaleFactor: 1.0, maxScaleFactor: 1.3);
    return MediaQuery(data: MediaQuery.of(context).copyWith(textScaler: scaler), child: child!);
  },
);

固定高度的容器里放文字是“大字体溢出”的主要原因，优先让容器高度由内容决定。

10.5 软键盘

Scaffold(
  resizeToAvoidBottomInset: true,     // 键盘弹出时缩小 body（默认 true）
  body: SingleChildScrollView(        // 内容可滚动，确保输入框能滚到可见区域
    child: Column(children: [...]),
  ),
);

// 键盘高度
final keyboard = MediaQuery.viewInsetsOf(context).bottom;

// 点击空白收起键盘
GestureDetector(
  onTap: () => FocusScope.of(context).unfocus(),
  behavior: HitTestBehavior.opaque,
  child: ...,
);

常见问题：

Android：windowSoftInputMode 必须是 adjustResize。全屏/沉浸式模式下部分 ROM 不回调键盘高度。
输入法兼容：部分国产输入法在 Flutter 中出现联想词异常、中文输入组合态（composing）问题，确认使用最新稳定版 Flutter；PlatformView 中的原生输入框（WebView 中输入）在 TLHC/HC 下表现不同，HCPP 改善了此类问题。
鸿蒙：早期 Flutter OH 版本存在键盘遮挡、输入法切换异常，升级到新版本；必要时在 ArkTS 侧配置键盘避让模式。

10.6 返回与手势导航

平台	行为	Flutter 处理
Android	返回键/侧边返回手势；Android 14+ 预测性返回动画	自动 pop；拦截用 `PopScope`；开启 `enableOnBackInvokedCallback` 支持预测性返回
iOS	左边缘右滑返回，没有返回键	`CupertinoPageRoute` 支持侧滑；`PopScope(canPop:false)` 会禁用侧滑，谨慎使用
鸿蒙	左右边缘侧滑返回	宿主 `onBackPress` 转发给 Flutter（模板已处理）

统一的页面转场：

ThemeData(
  pageTransitionsTheme: const PageTransitionsTheme(builders: {
    TargetPlatform.android: PredictiveBackPageTransitionsBuilder(),
    TargetPlatform.iOS: CupertinoPageTransitionsBuilder(),
  }),
);

10.7 权限

三端权限模型不同，统一封装：

Future<bool> ensureCamera() async {
  var status = await Permission.camera.status;
  if (status.isGranted) return true;
  status = await Permission.camera.request();
  if (status.isPermanentlyDenied) {
    await openAppSettings();      // 引导去设置页
    return false;
  }
  return status.isGranted;
}

Android：AndroidManifest.xml 声明；Android 13 媒体权限拆分为 READ_MEDIA_IMAGES/VIDEO/AUDIO；Android 14 部分照片访问（READ_MEDIA_VISUAL_USER_SELECTED）。
iOS：Info.plist 写用途说明；iOS 的拒绝通常是永久的，需要引导到设置。
鸿蒙：module.json5 的 requestPermissions 声明（含 reason 和 usedScene），使用社区适配版 permission_handler。鸿蒙对隐私更严格，部分能力（如读取相册）推荐使用系统 Picker 免权限访问。
国内合规：首次启动隐私协议弹窗同意前，不得初始化会采集设备信息的 SDK，也不能调用敏感 API。Flutter 插件可能在注册时（onAttachedToEngine）就读取设备信息，要检查三方插件的初始化时机。

10.8 平台差异化 UI

// 根据平台选择组件
Widget adaptiveSwitch(bool v, ValueChanged<bool> onChanged) =>
    Switch.adaptive(value: v, onChanged: onChanged);   // iOS 显示 Cupertino 风格

// 自定义判断
final platform = Theme.of(context).platform;           // 可在测试中覆写
if (platform == TargetPlatform.iOS) { /* ... */ }

国内 App 通常三端使用同一套自定义设计，只在少数交互上做差异（对话框样式、日期选择器、分享面板、滚动回弹）。Flutter 的滚动物理在 iOS 上自动是 BouncingScrollPhysics，Android/鸿蒙上是 ClampingScrollPhysics。

10.9 深色模式

使用 ThemeData + darkTheme + ThemeMode.system（第 5 章）。
所有颜色从 Theme.of(context).colorScheme 或自定义 ThemeExtension 中取，禁止硬编码。
图片资源在深色下可能需要替换或降低亮度。
原生侧（启动页、原生页面、PlatformView 中的控件）也要同步适配，否则会出现“白闪”。

10.10 Android 厂商 ROM 问题

问题	解决
部分机型 Vulkan 驱动问题导致花屏/闪退	Flutter 会对已知问题设备回退 OpenGL ES；遇到新机型问题，收集机型信息提交 issue，临时可在该机型上关闭 Impeller
高刷屏只跑 60Hz	Android 需原生侧设置 `preferredDisplayModeId` 或 `Surface.setFrameRate`，可用 `flutter_displaymode` 插件
后台被杀、推送收不到	与 Flutter 无关，属于原生层问题，按原生方案接入厂商推送
低端机内存小	限制图片缓存、降低动画复杂度（第 11 章）

10.11 适配测试清单

[ ] 小屏（360dp 宽）、大屏手机、平板、折叠屏展开/折叠切换
[ ] 系统字体最大、最小
[ ] 深色模式
[ ] 横屏（视频播放页）
[ ] 刘海屏/挖孔屏、全面屏手势与三键导航
[ ] 键盘弹出遮挡（登录、评论输入框）
[ ] 返回键 / 侧滑返回 / 预测性返回
[ ] 权限拒绝、永久拒绝后的流程
[ ] 弱网、断网
[ ] 鸿蒙真机全流程
[ ] RTL 语言（如有海外需求）