HarmonyOS鸿蒙Next中Flutter框架多设备开发指导-区域避让场景

HarmonyOS鸿蒙Next中Flutter框架多设备开发指导-区域避让场景

1.1 场景概述

在多设备应用场景下，不同设备的屏幕形态各异，如直板机、折叠屏、Pad、PC等，同时系统状态栏、导航栏、挖孔区域（前置摄像头）、AI Bar等元素也会占据屏幕空间。为了确保应用内容在各种设备和场景下都能正常显示，不被系统UI元素遮挡，需要实现精准的区域避让功能。本文将详细介绍 RN 区域避让组件的实现原理、适配指导以及具体的场景案例。

1.1.1 使用场景

在多设备应用中，区域避让常用于以下场景：

• 状态栏避让：避免内容被状态栏（时间、电量、信号等）遮挡
• 导航栏避让：避免内容被导航栏（返回、主页、最近任务等）遮挡
• 挖孔区域避让：避免内容被前置摄像头挖孔区域遮挡
• AI Bar避让：避免内容被折叠屏设备的AI Bar遮挡
• 窗口控制按钮避让：避免内容被PC端窗口控制按钮遮挡

1.1.2 常见问题

开发过程中区域避让界面在不同设备上会存在差异，可能会出现以下问题：

• 内容被状态栏、导航栏、挖孔区域遮挡
• 避让区域计算不准确，导致内容显示异常
• 不同设备的避让区域API不一致
• 横竖屏切换时避让区域未更新
• 分屏场景下避让区域计算错误

1.1.3 多设备适配

1.1.3.1 区域避让多设备适配

说明

根据设备类型和屏幕形态，动态调整避让区域：

横向断点	sm	md	lg	xl
属性	适配竖屏手机，避让状态栏、导航栏、挖孔区	适配横屏平板，避让挖孔区	适配折叠屏，避让状态栏、导航栏、挖孔区	适配PC端，避让窗口控制按钮

1.1.3.2 区域避让功能多设备适配

• 适配点1：基于断点实现组件自适应在多设备布局适配，窗口响应（横竖屏、分屏、折叠开合等）

• 适配点2：组件尺寸自适应覆盖拉伸、均分、占比、缩放、延伸、隐藏、折行。

1.2 开发指导

1.2.1 Flutter开发

1.2.1.1 关键能力

Flutter中Image组件自带的fit属性用于控制图片的填充方式；SystemChrome用于控制全屏模式；SafeArea组件用于处理系统UI避让；AnnotatedRegion用于设置状态栏样式；Listener组件用于确保手势事件在最上层响应。

1.2.1.2 指导案例

1. 引入核心库

在pubspec.yaml中添加必要的依赖，并在代码中导入Material库和Services库。

# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter

import 'dart:io';
import 'dart:ui';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

1. 创建应用入口和主题配置

使用void main()作为应用入口，配置MaterialApp主题，设置颜色方案和Material3风格。

void main() {
  runApp(const WindowAvoidance());
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Window Avoidance Demo',
      theme: ThemeData(
      colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
      useMaterial3: true,
    ),
    home: const WindowAvoidancePage(),
    );
  }
}

1. 创建状态管理页面

创建StatefulWidget页面，初始化屏幕方向设置和状态变量。

class WindowAvoidancePage extends StatefulWidget {
  const WindowAvoidancePage({super.key});

  @override
  State<WindowAvoidancePage> createState() => _WindowAvoidancePageState();
}

class _WindowAvoidancePageState extends State<WindowAvoidancePage> {
  bool _isFullScreen = false;
  final TextEditingController _textController = TextEditingController();

  @override
  void initState() {
    super.initState();
    SystemChrome.setPreferredOrientations([
      DeviceOrientation.portraitUp,
      DeviceOrientation.portraitDown,
      DeviceOrientation.landscapeLeft,
      DeviceOrientation.landscapeRight,
    ]);
  }

  @override
  void dispose() {
    _textController.dispose();
    super.dispose();
  }
}

1. 实现全屏切换控制

创建_toggleFullScreen方法，使用SystemChrome.setEnabledSystemUIMode控制全屏模式的进入和退出。

void _toggleFullScreen() {
  setState(() {
    _isFullScreen = !_isFullScreen;
  });

  if (_isFullScreen) {
    SystemChrome.setEnabledSystemUIMode(
      SystemUiMode.manual,
      overlays: [],
    );
  } else {
    SystemChrome.setEnabledSystemUIMode(
    SystemUiMode.manual,
    overlays: SystemUiOverlay.values,
    );
  }
}

1. 实现退出处理逻辑

创建_handleExit方法，处理退出按钮点击事件。如果当前处于全屏状态，先退出全屏再返回上一页。

void _handleExit() {
  if (mounted) {
    if (_isFullScreen) {
      _toggleFullScreen();
    }
    Navigator.of(context).pop();
  }
}

1. 构建ui布局

使用AnnotatedRegion设置状态栏样式，SafeArea控制安全区域避让。通过MediaQuery获取安全边距，使用Stack实现层级布局，关键退出按钮使用Listener确保在最上层响应事件。

@override
Widget build(BuildContext context) {
  final safePadding = _isFullScreen
  ? EdgeInsets.zero
  : MediaQuery.of(context).padding;
  
  return AnnotatedRegion<SystemUiOverlayStyle>(
    value: _isFullScreen
    ? SystemUiOverlayStyle.light
    : SystemUiOverlayStyle.dark,
    child: Scaffold(
      body: SafeArea(
        top: !_isFullScreen,
        bottom: !_isFullScreen,
        left: !_isFullScreen,
        right: !_isFullScreen,
        child: Stack(
          children: [
            // 主内容区域（全屏切换按钮、输入框等）
            Positioned.fill(
              child: Column(
                mainAxisAlignment: MainAxisAlignment.center,
                children: [
                  // ... 全屏切换按钮、输入框等组件
                ],
              ),
            ),
            // 左上角退出按钮 - 使用Listener确保在最上层捕获事件
            Positioned(
              left: 16 + (_isFullScreen ? 0 : safePadding.left),
              top: 16 + (_isFullScreen ? 32 : safePadding.top),
              child: Listener(
                behavior: HitTestBehavior.opaque,
                onPointerDown: (_) => _handleExit(),
                child: Container(
                  padding: const EdgeInsets.all(12),
                  decoration: BoxDecoration(
                    color: Colors.white,
                    borderRadius: BorderRadius.circular(8),
                  ),
                  child: const Icon(Icons.arrow_back, color: Colors.black),
                ),
              ),
            ),
          ],
        ),
      ),
    ),
  );
}

1.2.1.3 示例代码

相机的Sample示例代码地址：example，开发者可以通过该地址查看完整的示例代码，并根据自己的需求进行修改和扩展。