HarmonyOS鸿蒙Next中Flutter框架多设备开发指导-图文混排场景

HarmonyOS鸿蒙Next中Flutter框架多设备开发指导-图文混排场景

1.1 场景概述

在移动应用开发中，不同设备的屏幕形态各异，例如刘海屏、全面屏、折叠屏等，系统状态栏、软键盘等元素亦会占据屏幕空间。资讯、电商与文章详情等场景常需同时呈现头图与长正文：用户希望在手机上一屏看清重点图文，在平板上并排浏览、减少无效留白。本文将详细介绍在多设备上图文区域的排列与占比适配方法、图片缩放模式随断点的切换、与系统顶栏及挖孔区避让的协同方式，以及实现原理与具体场景案例。本文对应工程内图文组合示例页。

1.1.1 使用场景

用户在阅读图文详情时，需要首图醒目、正文可顺畅滚动；在宽屏上则希望一屏内同时看到图与文，而不是被窄栏或过度留白打断阅读节奏。下面是不同横向断点下的图文布局示意。

横向断点	sm	md	lg	xl
展示逻辑	主容器 column（base 同 sm）；图约 60% 高、文约 40% 高；图 cover；浅灰底；圆角 0	主容器 row；图 flex: 3、文 flex: 2 + 内边距；图 contain；粉底 #FFC0CB；圆角 20	主容器 row；图 flex: 3、文 flex: 2 + 内边距；图 contain；粉底 #FFC0CB；圆角 20	主容器 row；图 flex: 3、文 flex: 2 + 内边距；图 contain；粉底 #FFC0CB；圆角 20
展示布局

1.1.2 常见问题

图文组合页面在横竖屏与分窗变化时若未按断点拆分策略，容易出现以下问题：

• 大屏仍上下排列，图片过扁、正文行长过短，版面浪费
• 小屏强行左右分栏，图片与文字都过窄，难以阅读
• 图文高度写死像素，分屏或键盘弹出后内容被遮挡或出现大面积空白
• 未对正文区域使用滚动容器，长文溢出屏幕不可读
• 全屏窗口下未做系统栏避让，首图或标题与状态栏

1.1.3 多设备适配

• 适配点 1：在手机竖屏与窄窗下验证纵向堆叠：上图下文比例、图片 cover 与正文 ScrollView 滚动是否顺畅；顶栏避让后首图上缘是否在状态栏/挖孔下方。

图 1-1：手机竖屏下上图下文与正文滚动区域。

图 1-2：手机横屏或窄分窗下同一页高度比例与滚动是否仍可用。

• 适配点 2：在**平板宽度及以上（md 档）**下验证横向分栏：flex 占比、图片 contain 与圆角、侧栏内边距与正文阅读宽度。

图 2-1：md 档 / 平板宽度起左图右文并排与文区滚动。

图 2-2：lg 档及 PC / 特大宽下图文比例与留白（含粉底示意区）是否仍协调。

图 2-3：PC 全屏或大窗下整体布局。

1.2 开发指导

1.2.1 Flutter开发

1.2.1.1 关键能力

1. 响应式布局切换

自动识别屏幕尺寸

• 竖屏小屏模式（xs, sm）：图片和文字垂直堆叠，图片在上，文字在下
• 横屏大屏模式（md, lg, xl）：图片和文字水平并排，左右分布

断点系统

依赖 hadss_adaptive_layout 实现断点能力

// 宽度断点
xs: < 600px
// 小屏手机
sm: 600-840px
// 大屏手机
md: 840-1440px
// 平板竖屏
lg: 1440px+
// 平板横屏/桌面
xl: 更大屏幕

2. 智能尺寸计算

图片尺寸自适应

• 竖屏小屏：
  • 宽度：满屏（100%）
  • 高度：屏幕高度的 40%
• 横屏大屏：
  • 宽度：屏幕宽度的 90%
  • 高度：屏幕高度的 70%

文字区域滚动

• 竖屏模式：整个页面可滚动
• 横屏模式：仅文字区域可滚动

图文比例

xs、sm：上下布局

md：左右布局，图文比例（6:4）

lg、xl：左右布局，图文比例（5:5）

3. 主题适配

深色/浅色模式支持

• 自动检测系统主题
• 动态调整背景色、文字颜色
• 统一使用主应用主题系统

1.2.1.2 指导案例

1. 集成步骤

第一步：添加依赖

dependencies:
  hadss_adaptive_layout: ^latest_version

第二步：创建页面入口

import 'package:flutter/material.dart';
import 'package:multidevice_adaption_sample/graphic_text_layout/screens/responsive_home_screen.dart';

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

  @override
  Widget build(BuildContext context) {
  return const ResponsiveHomeScreen();
}
}

第三步：初始化断点系统

@override
void initState() {
  super.initState();
  // 初始化在didChangeDependencies中进行
}

@override
void didChangeDependencies() {
  super.didChangeDependencies();
  _initializeBreakpoints();
}

Future<void> _initializeBreakpoints() async {
  if (_isInitialized) return; // 防止重复初始化

  await BreakpointConstants.initialize();

  if (mounted) {
    setState(() {
      _currentWidthBreakpoint = BreakpointConstants.getCurrentWidthBreakpoint();
      _currentHeightBreakpoint = BreakpointConstants.getCurrentHeightBreakpoint();
      _isInitialized = true;
    });

    // 监听断点变化
    BreakpointConstants.addBreakpointCallback((breakpointData) {
      if (mounted) {
        setState(() {
          _currentWidthBreakpoint = breakpointData.widthBreakpoint;
          _currentHeightBreakpoint = breakpointData.heightBreakpoint;
        });
      }
    });
  }
}

2. 布局切换实现

判断布局类型

final isHorizontalLayout = ScreenUtils.isHorizontalLayout(_currentWidthBreakpoint);

return isHorizontalLayout
  ? _buildHorizontalLayout(screenWidth, screenHeight)
  : _buildVerticalLayout(screenWidth, screenHeight);

横屏布局

Widget _buildHorizontalLayout(double screenWidth, double screenHeight) {
  final imageWidthRatio = ScreenUtils.getImageWidthRatio(_currentWidthBreakpoint);
  final imageFlex = (imageWidthRatio * 10).toInt();
  final textFlex = 10 - imageFlex;
  
  return Row(
    children: [
      Expanded(
        flex: imageFlex,
        child: Container(
          padding: const EdgeInsets.only(left: 16, right: 8),
          child: ImageContainer(...),
        ),
      ),
      Expanded(
        flex: textFlex,
        child: Container(
        padding: const EdgeInsets.only(left: 8, right: 16),
        child: TextContainer(enableScroll: true),
        ),
      ),
    ],
  );
}

竖屏布局

Widget _buildVerticalLayout(double screenWidth, double screenHeight) {
  return SingleChildScrollView(
    controller: _verticalScrollController,
    child: Column(
      children: [
        Container(
          padding: ScreenUtils.isSmallScreen(_currentWidthBreakpoint)
          ? const EdgeInsets.only(bottom: 8)
          : const EdgeInsets.all(8),
          child: ImageContainer(...),
        ),
        Container(
          padding: const EdgeInsets.all(8),
          child: TextContainer(enableScroll: false),
        ),
      ],
    ),
  );
}

3. 尺寸计算

图片尺寸计算

static double getImageWidth(WidthBreakpoint widthBreakpoint,
HeightBreakpoint heightBreakpoint, double screenWidth) {
  final isSmall = isSmallScreen(widthBreakpoint);
  
  if (isSmall) {
    return double.infinity; // 竖屏小屏时，图片宽度满屏
  } else {
    return 0.9 * screenWidth; // 横屏时，图片宽度90%
  }
}

static double getImageHeight(WidthBreakpoint widthBreakpoint,
HeightBreakpoint heightBreakpoint, double screenHeight) {
  final isSmall = isSmallScreen(widthBreakpoint);
  
  if (isSmall) {
    return screenHeight * 0.4; // 竖版屏时，图片高度40%
  } else {
    return 0.7 * screenHeight; // 横屏时，图片高度70%
  }
}

4. 主题适配

获取主题颜色

final brightness = MediaQuery.of(context).platformBrightness;
final backgroundColor = brightness == Brightness.light
  ? AppThemes.lightTheme.scaffoldBackgroundColor
  : AppThemes.darkTheme.scaffoldBackgroundColor;
final containerColor = brightness == Brightness.light
  ? AppThemes.lightTheme.cardColor
  : AppThemes.darkTheme.cardColor;

5. 资源管理

清理资源

@override
void dispose() {
  _verticalScrollController.dispose();
  BreakpointConstants.dispose();
  super.dispose();
}

1.2.1.3 示例代码

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