布局核心是纯 Dart,鸿蒙侧只带一个可选的窗口指标 HAR。tablet_adaptive 把父级约束当唯一输入,工作台的两个 pane 常驻树上、只切可见性。从 TabletLayoutBuilder 到工作台,再到 ohos/,每个边界都能在源码里找到对应的一段。

仓库地址:https://atomgit.com/lqjmac/tablet_adaptive
版本地址:https://atomgit.com/CPF-Flutter/flutter_flutter/tree/oh-3.41.9-release
三方库框架:https://atomgit.com/oh-Flutter

0. 环境与实测设备

项版本/型号
Flutter(OHOS 分支)3.41.9+ohos-1.0.2,Dart 3.11.5
HarmonyOS SDK / API26.0.0.105 / API 26(OpenHarmony 运行时 7.0.0.105)
DevEco Studio本机 DevEco-Studio.app,自带 hvigor 6.26.4;ohpm 6.0.1
tablet_adaptive1.0.0(本仓库,path / git 依赖;pub publish --dry-run 0 warnings,未发布 pub.dev)
测试库 47 项(布局契约、Builder、工作台、旋转、过滤、空态、语义、键盘、OHOS 桥接)+ 示例 2 项(预览切换 + 1280×800 golden)
实测设备OHOS 2-in-1 模拟器(127.0.0.1:5555,ohos-arm64),OpenHarmony 7.0.0.105,API 26
运行实测窗口内容区 1100×643,横屏 · expanded · 12 栏,侧轨 + 双栏;预览切换 800×1280 → 底部导航 + 2 列卡片

测试数、构建结果和 1100×643 这个窗口读数来自仓库说明与 OpenHarmony 接入说明第 7 节的模拟器记录。

1. 从一次“缩水”说起

最早的 TabletLayoutBuilder 只有一行取尺寸的逻辑:constraints.maxWidth。把工作台放进横向 SingleChildScrollView 试预览时,界面没有异常,没有溢出条纹,工作台直接不见了,只剩下一道零宽的边。

我当时的判断是滚动容器把布局算崩了。打印约束才看到宽是 Infinity;再翻回 resolveTabletLayout 的入口,第一件事就是 _normalizeDimension,非有限值和负数都归零。double.infinity 进来,0 出去,断点自然全落在 compact。

修法是让 Builder 在调用之前补上最近的 MediaQuery 尺寸,纯函数不猜。现在 hasBoundedWidth / hasBoundedHeight 那两行判断就是从这里来的。容易误解的地方也在这里:纯函数对垃圾输入有兜底,错误不会抛,只会给一个“合法但不对”的布局。

2. 跑起来是什么样

示例是「田野笔记」工作台,4 个导航目标、6 条笔记。顶部那枚按钮只在三种预览之间循环:跟随窗口、横屏 1280×800、竖屏 800×1280。它改的是工作台外面那层容器的尺寸,没有调用 SystemChrome,也没有伪造方向。

点「竖屏 800×1280」预览:

800×1280 预览:底部导航 + 两列卡片

预览模式下,工作台被塞进 AspectRatio 包着的 FittedBox,再套一个 SizedBox.fromSize。约束仍然是 1280×800 或 800×1280,只是画的时候整体缩放到可见区域:LayoutBuilder 拿到的是目标尺寸,缩放只发生在绘制那一步。这张里侧轨换成 76px 底部导航,列表全宽、两列卡片,详情走单栏,左上角才出现「返回列表」。

跟随窗口时是这张:

跟随窗口的横屏态

窗口内容区 1100×643,提示条读数是 1100 × 643 · 横屏 · expanded · 12 栏。左侧 88px 侧轨,主体双栏;列表宽度按 round(1100 × 0.34) = 374 取,落在 300–400 区间内,单列卡片;右列是选中笔记的正文。

点「横屏 1280×800」预览:

1280×800 预览:large · 侧轨 · 双栏

1280×800 的预览里侧轨和双栏都回来了,列表宽度算到 400。预览给的是 1280×800 和 800×1280,真实窗口是 1100×643,三者都从 LayoutBuilder 进 resolveTabletLayout;预览切换只改容器约束,列表滚动位置、之前打开的笔记和键盘焦点都还在。

3. 断点只认宽度,方向是算出来的

布局契约的骨架是三档宽度断点加派生规则:

宽度sizeClasscolumnsmargin / gutter
<600compact416 / 8
600–839medium824 / 16
840–1199expanded1232 / 24
>=1200large1240 / 32

导航走侧轨的门槛是 w >= 840,或者 w >= 600 且横屏;其余情况走底部导航。双栏的门槛再高一点:w >= 840,或者 w >= 720 且横屏,达不到就单栏。

列表宽度先算 round(w × 0.34),再夹到 300–400。密度只看高度,h < 500 切紧凑,页头从 64 降到 56。isTablet 要求 min(w, h) >= 600,它只是信息字段,不给 sizeClass 封顶。

方向是算出来的,折叠屏展开、分屏拖拽、2-in-1 窗口缩放都不触发旋转:方向没变,尺寸全变。布局分支如果读 MediaQuery.orientation 或设备型号,这些场景就会停在旧形态。几种做法放在一起看:

方案输入问题
MediaQuery.orientation 分支方向折叠屏/分屏/拖窗不触发旋转
设备型号判断Platform回答不了“此刻容器多大”
条件渲染切换单双栏布局值子树销毁,状态全丢
响应式框架包约束引入整框架运行时,与“可发布三方包”冲突
本库父级约束 + 纯函数可单测、可 golden、状态零丢失

正方形是这条推导的边界:width > height 时是横屏,相等时归竖屏。800×800 的窗口在系统里可以被描述成横屏,也可以被描述成竖屏,引擎必须自己选一个并写进契约;测试里六个正方形尺寸都断言 portrait。跨端对齐时,这个相等时的取舍也要一起对。

resolveTabletLayout 是唯一实现,从归一化到返回值都在一个函数里:

// lib/src/layout/tablet_layout.dart
TabletLayout resolveTabletLayout({
  required double width,
  required double height,
  TabletLayoutConfig config = const TabletLayoutConfig(),
}) {
  final double normalizedWidth = _normalizeDimension(width);
  final double normalizedHeight = _normalizeDimension(height);

  final TabletOrientation orientation = normalizedWidth > normalizedHeight
      ? TabletOrientation.landscape
      : TabletOrientation.portrait;

  final TabletSizeClass sizeClass = switch (normalizedWidth) {
    < 600 => TabletSizeClass.compact,
    < 840 => TabletSizeClass.medium,
    < 1200 => TabletSizeClass.expanded,
    _ => TabletSizeClass.large,
  };

  final int columns = switch (sizeClass) {
    TabletSizeClass.compact => 4,
    TabletSizeClass.medium => 8,
    TabletSizeClass.expanded || TabletSizeClass.large => 12,
  };

  final double margin = switch (sizeClass) {
    TabletSizeClass.compact => 16,
    TabletSizeClass.medium => 24,
    TabletSizeClass.expanded => 32,
    TabletSizeClass.large => 40,
  };

  final double gutter = switch (sizeClass) {
    TabletSizeClass.compact => 8,
    TabletSizeClass.medium => 16,
    TabletSizeClass.expanded => 24,
    TabletSizeClass.large => 32,
  };

  final int cardColumns;
  if (normalizedWidth >= 1200) {
    cardColumns = 4;
  } else if (normalizedWidth >= 840) {
    cardColumns = 3;
  } else if (normalizedWidth >= 600 &&
      orientation == TabletOrientation.landscape) {
    cardColumns = 3;
  } else if (normalizedWidth >= 600) {
    cardColumns = 2;
  } else {
    cardColumns = 1;
  }

  final TabletNavigation navigation;
  if (normalizedWidth >= 840) {
    navigation = TabletNavigation.rail;
  } else if (normalizedWidth >= 600 &&
      orientation == TabletOrientation.landscape) {
    navigation = TabletNavigation.rail;
  } else {
    navigation = TabletNavigation.bottom;
  }

  final TabletPaneMode paneMode;
  if (normalizedWidth >= 840) {
    paneMode = TabletPaneMode.split;
  } else if (normalizedWidth >= 720 &&
      orientation == TabletOrientation.landscape) {
    paneMode = TabletPaneMode.split;
  } else {
    paneMode = TabletPaneMode.single;
  }

  final double proposedListWidth = (normalizedWidth * config.listWidthRatio)
      .roundToDouble();
  final double listWidth = proposedListWidth
      .clamp(config.listWidthMin, config.listWidthMax)
      .toDouble();

  final TabletDensity density = normalizedHeight < config.compactHeightThreshold
      ? TabletDensity.compact
      : TabletDensity.comfortable;

  final double headerHeight = density == TabletDensity.compact
      ? config.compactHeaderHeight
      : config.comfortableHeaderHeight;

  return TabletLayout(
    width: normalizedWidth,
    height: normalizedHeight,
    orientation: orientation,
    sizeClass: sizeClass,
    columns: columns,
    cardColumns: cardColumns,
    margin: margin,
    gutter: gutter,
    navigation: navigation,
    paneMode: paneMode,
    listWidth: listWidth,
    railWidth: config.railWidth,
    bottomBarHeight: config.bottomBarHeight,
    headerHeight: headerHeight,
    density: density,
    isTablet: math.min(normalizedWidth, normalizedHeight) >= 600,
  );
}

double _normalizeDimension(double value) {
  if (!value.isFinite || value < 0) {
    return 0;
  }
  return value;
}

TabletLayoutConfig 只暴露侧轨宽、底栏高、两种页头高、列表宽比例与范围、密度阈值,600/840/1200 三个断点本身不开放。断点一旦变成参数,宿主迟早会调出两份互不兼容的契约。

cardColumns 单独算,不走 sizeClass:≥1200 四列、≥840 三列、600–839 的横屏三列、600–839 的竖屏两列、再窄一列。它只在单栏的全宽列表里生效;双栏时列表固定 listWidth,强制单列。

四个数字可以拿契约向量对一遍:720 宽算出 300(round(720 × 0.34) = 245,仍低于下限),1024 宽算出 348,1199 宽夹到 400,1200 宽也是 400。isTablet 用短边,所以 844×390 是 expanded / rail / split、isTablet == false、density == compact、页头 56。宽度够 840 就给宽布局,跟“这块屏幕算不算平板”无关。

非法尺寸在入口归零,0×0 返回 compact 默认值,不抛异常。窗口初始化、容器还没挂载、测试里先 pump 一帧空盒子,都会短暂量到 0;在这里抛异常只会把问题推给调用方。

TabletLayout 实现了逐字段 ==,测试可以拿整个对象当期望值。Builder 没有拿它去重:约束变化就重建,这是 LayoutBuilder 的语义。

4. 无界约束:Builder 里 7 行判断

// lib/src/layout/tablet_layout_builder.dart
class TabletLayoutBuilder extends StatelessWidget {
  /// Creates a builder backed by [LayoutBuilder].
  const TabletLayoutBuilder({
    super.key,
    required this.builder,
    this.config = const TabletLayoutConfig(),
  });

  /// Called with the resolved layout every time the constraints change.
  final TabletLayoutBuilderCallback builder;

  /// Configurable chrome dimensions used by [resolveTabletLayout].
  final TabletLayoutConfig config;

  
  Widget build(BuildContext context) {
    final Size mediaSize = MediaQuery.maybeOf(context)?.size ?? Size.zero;
    return LayoutBuilder(
      builder: (BuildContext context, BoxConstraints constraints) {
        final double width = constraints.hasBoundedWidth
            ? constraints.maxWidth
            : mediaSize.width;
        final double height = constraints.hasBoundedHeight
            ? constraints.maxHeight
            : mediaSize.height;
        return builder(
          context,
          resolveTabletLayout(width: width, height: height, config: config),
        );
      },
    );
  }
}

TabletLayoutBuilder.build 里有两个容易看漏的地方。mediaSize 在 build 里读,没放进 LayoutBuilder 的 builder:MediaQuery.maybeOf 建立的是外层 Element 的依赖,媒体尺寸变化时外层会更新,约束变化时只重建内层。宽高分别判断 hasBoundedWidth / hasBoundedHeight,所以“横向滚动、纵向有界”这种半无界场景也成立。

maybeOf 的用处就在这里:widget test 里经常没有 MediaQuery,of 会直接抛。拿不到就 Size.zero,布局退回 compact,至少不会崩。

测试覆盖了这个分支:surface 设成 1200×900,MediaQueryData(size: Size(900, 700)),工作台外面横向、纵向各套一个 SingleChildScrollView,断言拿到的是 900×700、expanded、split。文件是 test/layout/tablet_layout_builder_test.dart,第二项测试。

在滚动容器里,LayoutBuilder 拿到的约束会明确地少一轴。横向 SingleChildScrollView 里,宽度是 double.infinity、hasBoundedWidth == false,高度通常还是父级给的具体值;纵向 ListView 反过来,宽度有界、高度无穷。判断“父级没给约束”不要拿 maxWidth == double.infinity 去比,直接读 constraints.hasBoundedWidth / hasBoundedHeight:isTight 只说明上下界相等,跟有界是两码事。滚动容器嵌套起来,两轴都可能无界,Builder 会同时回退到 MediaQuery;连 MediaQuery 都没有,才落到 Size.zero。

约束描述的是父级允许的空间,最终尺寸未必是这个数。父级套一个 SizedBox(width: 400),窗口 1280 宽,maxWidth 也是 400;放进 Row 的 Expanded,约束又变成剩余宽度。拿约束和 MediaQuery.size 比大小去判断“这算不算全屏”,在分屏和多栏宿主里一定会错。

约束不变时 builder 不会重新执行,resolveTabletLayout 也就不会重算;真正贵的是它返回的子树重建。

反过来说,AdaptiveTabletWorkspace 需要高度有界。它内部是 Column + Expanded,放进不指定高度的 Column 或 ListView,MediaQuery 回退能把布局值算出来,但渲染时 Expanded 仍然拿不到有界高度,会直接报 unbounded height。README 把这条写在接入说明里,代码没有替它兜。

5. 两个 pane 一直在树上

// lib/src/widgets/workspace_chrome.dart
class _PaneVisibility extends StatelessWidget {
  const _PaneVisibility({required this.visible, required this.child});

  final bool visible;
  final Widget child;

  
  Widget build(BuildContext context) {
    return Offstage(
      offstage: !visible,
      child: ExcludeFocus(
        excluding: !visible,
        child: TickerMode(enabled: visible, child: child),
      ),
    );
  }
}

工作台在 _WorkspaceBody.build 里用一个 Stack 装两个 Positioned:列表 pane 的宽度取 min(listWidth, max(0, bodyWidth - gutter)),详情 pane 的左边距是 listPaneWidth + gutter;单栏时两者都取全宽,靠 _PaneVisibility 隐藏其中一个。Offstage 会做 layout,但不 paint、不参与命中测试,子树的 State、ScrollController、FocusNode 都还在。省下的是重建与状态迁移——测量和 layout 照做。

三个组件分工不同。Offstage 管绘制;ExcludeFocus 管键盘,隐藏 pane 里如果还留着焦点,Tab 会跳进看不见的按钮;TickerMode 管帧,隐藏 pane 里的 AnimationController 不该继续走。

条件渲染的破坏发生在 Element 树上。layout.isSplit ? SplitView() : SingleView() 一旦分支改变,旧分支的 Element 被 unmount,State.dispose 马上执行;如果 ScrollController、FocusNode、TextEditingController 是在那个 State 里创建的,它们跟着被释放,列表的 ScrollPosition 也一起没了。AutomaticKeepAliveClientMixin 只对同一个 sliver 里的子项有效,跨分支换 widget 类型救不了;GlobalKey 可以把子树搬到新位置,但要求两边类型和 key 对得上,搬一次会触发 re-parent,调试成本比 Offstage 高。工作台的做法不一样:两个 pane 从不离开树,切换只改 offstage 和 ExcludeFocus。

焦点也需要单独处理。隐藏 pane 里的按钮如果还能被 Tab 命中,键盘用户会走进一块看不见的区域;ExcludeFocus 把整棵子树的 focusability 关掉,Offstage 同时把语义树收起来。滚动位置不用额外保存:ScrollController 还挂在原来的 Scrollable 上,Offset 没变,重新可见时自然停在原处。

状态字段都在 _AdaptiveTabletWorkspaceState 里:_destinationId、_selectedItemId、_singleDetailVisible。两个 ScrollController 也在 State 里创建,dispose 里释放。

单双栏切换有一个一帧的边界。_syncPaneMode 在 build 里比较上一次的 paneMode,发现 split → single 就让本次构建的 justShrank 为 true;showDetail 的表达式是 layout.isSplit || (_singleDetailVisible && !justShrank),所以缩回单栏的那一帧先显示列表。post-frame 再把 _singleDetailVisible 清掉,否则下一帧它又会被重新打开。

_syncPaneMode 在 build 里改 _lastPaneMode,没有 setState。这个写法不算教科书式,但它只是记录“这次构建看到了什么”,不触发重建;真正要改 UI 的清理放在 addPostFrameCallback 里,并且用 _singleDetailResetScheduled 防重入。

滚动重置也放在 post-frame:_resetDetailScroll 调 jumpTo(0) 之前先看 hasClients,详情 pane 刚出现的那一帧 controller 还没挂上。切换导航目标时列表回到顶部;打开新条目时详情回到顶部;单纯旋转两者都不动。

didUpdateWidget 处理数据源变化:目标被删掉就回到第一个;选中的条目如果不在当前 section 里就清空。PopScope 把系统返回接到 _hideSingleDetail,单栏详情下返回键先回列表,不会直接退出页面。

6. 把这些行为写成测试

// test/workspace/adaptive_tablet_workspace_test.dart
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:tablet_adaptive/tablet_adaptive.dart';

import 'support/workspace_fixture.dart';

void main() {
  Future<void> pumpWorkspace(WidgetTester tester, {required Size size}) async {
    await tester.binding.setSurfaceSize(size);
    addTearDown(() => tester.binding.setSurfaceSize(null));
    await tester.pumpWidget(
      MaterialApp(
        home: Scaffold(
          body: AdaptiveTabletWorkspace(
            destinations: testDestinations,
            items: testItems,
            title: '田野笔记',
            eyebrow: 'FIELD NOTES · 平板工作台',
          ),
        ),
      ),
    );
    await tester.pumpAndSettle();
  }

  Future<void> resize(WidgetTester tester, Size size) async {
    await tester.binding.setSurfaceSize(size);
    await tester.pumpAndSettle();
  }

  testWidgets('resizing split to single returns to the list', (
    WidgetTester tester,
  ) async {
    await pumpWorkspace(tester, size: const Size(1280, 800));
    expect(find.byKey(TabletWorkspaceKeys.detail), findsOneWidget);

    await resize(tester, const Size(800, 1280));

    expect(find.byKey(TabletWorkspaceKeys.bottomBar), findsOneWidget);
    expect(find.byKey(TabletWorkspaceKeys.detail), findsNothing);
    expect(find.byKey(TabletWorkspaceKeys.back), findsNothing);
    expect(find.byKey(TabletWorkspaceKeys.list), findsOneWidget);

    // Expanding again restores split mode and the state held by the workspace.
    await resize(tester, const Size(1280, 800));
    expect(find.byKey(TabletWorkspaceKeys.detail), findsOneWidget);
    expect(find.byKey(TabletWorkspaceKeys.back), findsNothing);
    expect(find.text('双栏不是把屏幕切成两半'), findsNWidgets(2));
  });
}

同一文件里的旋转往返用例也走 tester.binding.setSurfaceSize,改的是测试窗口的约束,不调用屏幕旋转 API。pumpAndSettle 之后用 find.byKey 数节点,旋转往返那项断言三件事:单栏打开详情 → 转双栏时详情还在、返回按钮消失、标题在列表和详情里各出现一次;再转回单栏时详情消失、列表回来。

库一共 47 项测试,其中布局契约有 12 组向量;Builder 3 项;工作台的这组还覆盖了单栏进详情、双栏不出现返回按钮、切目标过滤、空态、键盘 Enter、语义 role 和隐藏尺寸条。示例 2 项,一项是预览循环,另一项对着 example/test/goldens/demo_landscape.png 做逐像素比对。

47 项里,边界值集中在纯函数和 Builder:599.9 / 600 / 839.9 / 840 / 1199.9 / 1200 六个宽度点,499.9 / 500 两个高度点,720 / 940 / 1024 / 1200 / 1600 五个 listWidth 采样,外加 NaN、±Infinity、负数、0×0 和正方形。工作台测的是 1280×800 与 800×1280 两个档位下的节点存在性、语义、键盘和状态往返;Host 测的是 1100×643 的模拟 payload、插件缺失和平台异常。只能上目标设备验证的是另一批:系统实际下发的新约束、Songti SC 的回退、安全区和输入法占位、拖窗时的帧率,以及版面在目标设备字体下的实际渲染。这些没有哪一项能靠单测替代:单测证明的是函数在给定输入下的输出,证明不了窗口管理器会不会把新尺寸送进来。

golden 那项有个 skip: !hasCjkFont:跑测试的机器上没有 /System/Library/Fonts/Supplemental/Arial Unicode.ttf 时直接跳过。中文渲染成方框的话,逐像素比对没有意义。

7. 包结构和鸿蒙侧的可选插件

包按职责分四层:layout/ 里的纯函数只依赖 flutter/foundation 与 dart:math,同目录的 Builder 额外依赖 flutter/widgets;workspace/ 只放数据模型和视觉 tokens,widgets/ 负责组合绘制,platform/ 是唯一接触 MethodChannel 的目录。这条分层规则是硬的:布局引擎 import 不到 platform/,所以它能在纯 Dart 测试里离线跑,鸿蒙桥接坏了也牵连不到布局。

包结构

ohos/ 是可选的 HAR,example/ 是宿主工程和 golden,test/ 按 lib/ 的结构镜像,tool/ 放构建脚本。颜色、字体、圆角都收在 TabletWorkspaceStyle 里,宿主用一个 style: 参数整体换肤;默认是暖纸底 #F2EFE8、深绿侧轨 #16352E、衬线标题 Songti SC。

7.1 插件只给窗口快照

通道名 dev.lqjmac/tablet_adaptive,只处理一个方法:

// ohos/src/main/ets/components/plugin/TabletAdaptivePlugin.ets
  async onMethodCall(call: MethodCall, result: MethodResult): Promise<void> {
    if (call.method !== 'getWindowMetrics') {
      result.notImplemented();
      return;
    }
    if (this.context === null) {
      result.error('no_context', 'Application context is not attached', null);
      return;
    }
    try {
      const win = await window.getLastWindow(this.context);
      const rect = win.getWindowProperties().windowRect;
      const density = display.getDefaultDisplaySync().densityPixels;
      const width = rect.width / density;
      const height = rect.height / density;
      result.success({
        width: width,
        height: height,
        density: density,
        orientation: width > height ? 'landscape' : 'portrait',
      });
    } catch (error) {
      result.error('window_metrics_failed', JSON.stringify(error), null);
    }
  }

插件把 windowRect 的像素宽高除以 densityPixels 得到 vp,方向也在这里算一次。它不申请权限,不改窗口,不参与布局。

Dart 侧对应的是 HarmonyWindowMetricsHost.query():非 OHOS 平台直接返回 null;MissingPluginException 和 PlatformException 都被吞掉。isHarmonyOS 判断的是 defaultTargetPlatform.name == 'ohos',测试里用 debugIsHarmonyOS 强制走 OHOS 分支。

这个通道适合在第一帧之前记一行日志,或者给埋点补一个原生窗口快照。拿它驱动布局就错了:第一帧之前拿到的窗口尺寸和 Flutter 实际收到的约束并不在同一时刻。

窗口 resize 和 MediaQuery 是两回事。MediaQuery.size 描述的是 Flutter 视图,通常等于窗口内容区;LayoutBuilder 的约束描述的是工作台这个盒子,已经被 Scaffold、SafeArea、页头和边距削过一轮。2-in-1 拖动窗口时两者一起变,数值不同;键盘弹起、系统栏显隐时,MediaQuery.viewInsets / padding 变,盒子的约束可能不变。工作台只吃盒子的约束,排的是“这块地方”,屏幕比它宽一圈。反过来,拿 MediaQuery.size 算断点,分屏里只占半个窗口的页面会被当成全屏,栏数和导航形态都会偏大。

鸿蒙的窗口尺寸以像素给到,除掉 density 才是 vp;windowRect 是窗口的,LayoutBuilder 的约束是盒子的,中间还隔着 Scaffold、SafeArea 和页头。拿插件返回值反推断点时,先把 density 除掉,再和当前盒子的约束对一遍。两个数对不上,先查宿主有没有把工作台放进带内边距的容器,或者 SafeArea 又削掉一圈,别急着怀疑布局函数。

7.2 宿主侧的两条限制

有两处跟代码无关、但不做就失效的配置。module.json5 的 deviceTypes 要包含 tablet / 2in1,否则平板或 2-in-1 上可能装不上;ability 不能锁死 portrait 或 landscape,方向锁死后系统不会再给新的窗口约束,LayoutBuilder 永远看到同一个尺寸。

8. 构建、验证和没绕过去的问题

cd flutter && flutter pub get && flutter analyze && flutter test
cd example && flutter pub get && flutter analyze && flutter test
cd .. && ./tool/build_ohos.sh

OpenHarmony 接入说明第 7.2 节记的结果:

flutter analyze(包根 / example)  无 issue
flutter test(包根)               47 个用例通过
flutter test(example)            2 个用例通过(预览切换 + 1280×800 golden)
flutter pub publish --dry-run      通过,0 warnings
./tool/build_ohos.sh               unsigned HAP;未配置签名,命令在签名检查处非零退出
hdc install -r entry-default-unsigned.hap   安装成功
aa start -a EntryAbility -b com.lqjmac.tablet_adaptive_example   启动成功

build_ohos.sh 优先用 DevEco 自带的 hvigor,找不到才回退到 PATH 里的版本;CI 里把 DEVECO_HOME 显式设好,别依赖默认安装路径。命令行工具自带的 6.21.2 会报 00306042 Specification Limit Violation,要求 SDK 版本写成 '5.0.0(12)' 的形式;换到 6.26.4 就过了。问题出在工具链版本,跟项目配置无关。

示例的 signingConfigs 是空的。flutter build hap --debug 走到签名检查会以非零码退出,但 unsigned HAP 已经产出,hdc install -r 能装。这个行为容易误判成构建失败,CI 里要按产物判断,不能只看退出码。

macOS 宿主没跑完:首次构建下载 engine 超时,进程被终止;验证记录里如实留着。

9. 现在还差什么

包还没有发布到 pub.dev,publish --dry-run 0 warnings 只说明元数据能过。现在用 path 或 git 依赖接入,要求 Flutter >=3.41.0、Dart ^3.11.0:

dependencies:
  tablet_adaptive:
    path: ../flutter
    # 或者:
    # tablet_adaptive:
    #   git:
    #     url: https://atomgit.com/lqjmac/tablet_adaptive.git
    #     ref: v1.0.0

当前验证停在 OHOS 2-in-1 模拟器(127.0.0.1:5555,ohos-arm64,OpenHarmony 7.0.0.105):unsigned HAP 安装并启动,窗口内容区 1100×643 走侧轨双栏;预览 800×1280 走底部导航加两列卡片。手机、折叠屏的字体、安全区、输入法和窗口缩放还没有在目标设备上过一遍;三栏模式、RTL 和高对比度也还在路线图里。

仓库说明的验证表、doc/ 下三张运行截图和 tool/ 里的构建脚本是上面这些读数的出处;OpenHarmony 接入说明第 7 节记录了模拟器地址、窗口读数和 HAP 安装命令。

Logo

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。

更多推荐