react-native-tablet-adaptive 把布局输入收窄成 useWindowDimensions() 的一对宽高,hook 不返回 key,工作台的列表 ScrollView 不随布局卸载。内容集中在 RNOH 宿主接线、状态保留路径,以及那个 2,966 字节的空 HAR。

仓库地址:https://atomgit.com/oh-react-native/react-native-tablet-adaptive
版本地址:https://atomgit.com/oh-react-native/ohos_react_native/tree/0.84-main
三方库框架:https://atomgit.com/oh-react-native

0. 环境与实测设备

项版本/型号
React Nativepeer >= 0.76;开发与类型检查使用 0.84.1
React19.2.3(必须与 RN 0.84.1 内置 renderer 精确一致,devDependencies 固定)
RNOH参考基线 @rnoh/react-native-openharmony 0.84.3 / HarmonyOS SDK 26
DevEco Studio26.0.0.821(HarmonyOS SDK 26.0.0 Release / API 26)
语言与构建TypeScript 5.9.3、Babel 7(CJS/ESM 双构建)、Vitest、Node.js 24.12.0
react-native-tablet-adaptive1.0.0(本仓库,npm 包;peer 依赖仅 react 与 react-native,零运行时依赖)
测试Vitest 33 项(布局 29 + 主题 4),纯逻辑测试不 import react-native 运行时
实测设备HUAWEI MateBook Pro S(MOR-W52),HarmonyOS 7.0.0.111(SP15C00E101R9P2),API 26(型号与系统版本未写入仓库验证记录)
真机实测signed HAP 安装启动,工作台在 1100×734 窗口渲染 split list-detail,无 JS bundle 错误

构建、打包和真机记录来自验证记录、验证记录与包检查记录。真机这一轮只做到“装上去、在 1100×734 窗口里渲染出双栏”,旋转与分屏回调没有单独验证。

1. 720×900 的窗口,方向还停在启动时

在 2-in-1 上把窗口从 1100×734 拖到 720×900,页面启动时查过一次 Dimensions.get('screen'),用宽高比定下的方向是 landscape。窗口拖窄了,这个值还是 landscape;屏幕没有转,转的是窗口。按这个缓存值决定布局的页面会继续画双栏:侧轨 88、左右 margin 24、列表 300、gutter 16,按这套 token 算下来,右侧详情只剩 268dp。

窗口变了,方向却没跟着变。Dimensions 本身没坏,问的对象错了:Dimensions.get('screen') 描述屏幕,useWindowDimensions() 描述窗口。2-in-1、分屏、折叠屏展开、桌面窗口拖拽,改的都是后者。

另一个坑是修布局的手法。看到双栏没切单栏,最快的补丁是给根节点加 key={layout.orientation}:key 一变,React 卸载整棵子树再挂载,布局确实会按新值重算。代价是列表滚动归零、选中项回到首条、输入框失焦;key 一换,这些 state 跟着旧子树一起卸载。

库因此把接口收窄:hook 只订阅一对宽高、不返回 key,工作台把列表 ScrollView 一直挂在树上,纯 JS 库按 RNOH 规范带一个空 Package 的 bytecode HAR。

2. 两张截图:双栏与单栏

示例是“田野笔记”工作台,跑在一台连接的 HarmonyOS 真机上。第一张是横屏窗口:

1100×734 横屏:侧轨 + 双栏

窗口 1100×734,提示条读 1100 × 734 · 横屏 · expanded · 12 栏。左侧 88px 深绿侧轨,主体双栏:左列按 listWidth 固定,1100 宽算出来是 374;右列是选中笔记的衬线标题与正文。点左侧任意卡片,右侧详情换内容,列表的 ScrollView 没有被卸载,滚动位置不动。

第二张是切换导航目标之后:

切换导航目标后的列表与详情

点了另一个目标:列表按 item.section === destination.id 过滤,详情同步切到新目标的首条。目标切换、条目选择、布局重算分别走各自的状态路径,互不牵连。整个过程没有页面重载,也没有白屏。

1100×734 是宿主窗口的内容区,比 3120×2080 的屏幕小得多。useWindowDimensions() 跟着窗口走:自由窗口报窗口宽高,分屏报分屏后的宽高,旋转后报交换后的宽高;拖动窗口边缘时 expanded ↔ medium 会在两次拖动之间换档,尺寸提示条是唯一能读出这件事的地方。Dimensions.get('screen') 报的还是 3120×2080,跟这个 1100 宽的窗口对不上。

3. useWindowDimensions() 是唯一输入

hook 本身很短:订阅宽高,尺寸变了调一次纯函数。

// src/useTabletLayout.ts
import { useMemo } from 'react';
import { useWindowDimensions } from 'react-native';

import { resolveTabletLayout } from './layout';
import type { TabletLayout, TabletLayoutConfig } from './types';

/**
 * Resolve the current layout from the host window.
 *
 * `useWindowDimensions` updates when the window changes size: device rotation,
 * a resized desktop window, foldable unfold, or a split-screen drag. The hook
 * deliberately reads no orientation cache, so the calculation always goes
 * through `resolveTabletLayout`.
 *
 * The hook owns no page state. Callers keep their state in the same component
 * tree, so a rotation re-renders rather than remounts them.
 */
export function useTabletLayout(
  config?: TabletLayoutConfig,
): TabletLayout {
  const { width, height } = useWindowDimensions();
  const railWidth = config?.railWidth;
  const bottomBarHeight = config?.bottomBarHeight;
  const headerHeight = config?.headerHeight;
  const compactHeaderHeight = config?.compactHeaderHeight;

  return useMemo(
    () =>
      resolveTabletLayout(width, height, {
        railWidth,
        bottomBarHeight,
        headerHeight,
        compactHeaderHeight,
      }),
    [
      width,
      height,
      railWidth,
      bottomBarHeight,
      headerHeight,
      compactHeaderHeight,
    ],
  );
}

几处细节是刻意写的。useMemo 的依赖是 width、height 和四个可配置尺寸,config 对象不在其中,宿主每次渲染传一个新对象进来,也不会让布局重算。四个字段单独解构,是因为 config 里只有这四个口子,断点和 listWidth 夹取不在其中。

hook 不读 Dimensions.get('screen'),不读 Platform.OS,不缓存方向。旋转、分屏、折叠屏展开、桌面窗口缩放,最终都只给它一对新宽高。它也不持有页面状态、不返回 key,调用方拿到的是一个普通对象。

在 RNOH 上,窗口尺寸由 RNOH / ArkUI 侧更新到 RN 的 Dimensions,useWindowDimensions() 才会收到新值。宿主如果没有更新 Dimensions,布局不会变化;这是宿主与运行时的行为,库这层没法替它补。

useWindowDimensions() 的更新时机跟窗口事件绑定,不跟“方向”绑定。RNOH 侧把 ArkUI 窗口的尺寸变化派发到 RN 的 Dimensions,hook 订阅的是 Dimensions 的 change;分屏拖分隔条是连续的小步变化,系统旋转是一次跳变,折叠屏展开是窗口跨到另一块屏,三者在 Dimensions 上的表现一样。RN 不会告诉 hook“这是旋转”还是“这是拖拽”,hook 也不需要知道:它只拿最近一次 width/height 重算。连续拖动时 React 可能把多次更新合并到一次渲染,最终看到的是合并后的宽高,通常不会为每一个中间尺寸都渲染一帧;如果宿主把窗口固定成不可缩放,或者 RNOH 没有派发尺寸变化,hook 收不到事件,布局就停在旧值。

分屏和旋转对布局的影响不在同一个维度。分屏首先改的是可用宽度,高度往往不变,所以最容易跨过 840 和 600 这两道宽度断点;旋转同时交换宽高,宽度和高度一起变,可能从 expanded / 12 栏直接掉到 compact / 4 栏,也可能只是 density 从舒适切到紧凑(高度掉到 500 以下)。折叠屏展开更接近“窗口突然变宽”,但短边可能仍然小于 600,isTablet 依旧为 false。useTabletLayout() 不区分这些来源,它只对结果负责;宿主如果要知道“为什么变了”,得自己记录窗口事件。

如果 JS 线程正在跑长任务,Dimensions 的变化会排队,等线程空出来才渲染;这时窗口可能已经又变了一次,hook 读到的是最新值,中间值通常不会补渲染。

4. 纯函数把 1100×734 拆成 16 个字段

resolveTabletLayout 不 import React Native,可以在纯 Node 里跑:

// src/layout.ts
export function resolveTabletLayout(
  width: number,
  height: number,
  config: TabletLayoutConfig = {},
): TabletLayout {
  const safeWidth = normalizeDimension(width);
  const safeHeight = normalizeDimension(height);

  const orientation: Orientation =
    safeWidth > safeHeight ? 'landscape' : 'portrait';
  const isTablet = Math.min(safeWidth, safeHeight) >= 600;
  const sizeClass = getSizeClass(safeWidth);
  const density: Density = safeHeight < 500 ? 'compact' : 'comfortable';

  const railWidth = resolveConfigDimension(
    config.railWidth,
    TABLET_LAYOUT_DEFAULTS.railWidth,
  );
  const bottomBarHeight = resolveConfigDimension(
    config.bottomBarHeight,
    TABLET_LAYOUT_DEFAULTS.bottomBarHeight,
  );
  const headerHeight = resolveConfigDimension(
    density === 'compact' ? config.compactHeaderHeight : config.headerHeight,
    density === 'compact'
      ? TABLET_LAYOUT_DEFAULTS.compactHeaderHeight
      : TABLET_LAYOUT_DEFAULTS.headerHeight,
  );

  return {
    width: safeWidth,
    height: safeHeight,
    orientation,
    sizeClass,
    columns: SIZE_CLASS_COLUMNS[sizeClass],
    cardColumns: getCardColumns(safeWidth, orientation),
    margin: SIZE_CLASS_MARGIN[sizeClass],
    gutter: SIZE_CLASS_GUTTER[sizeClass],
    navigation: getNavigation(safeWidth, orientation),
    paneMode: getPaneMode(safeWidth, orientation),
    listWidth: Math.min(400, Math.max(300, Math.round(safeWidth * 0.34))),
    railWidth,
    bottomBarHeight,
    headerHeight,
    density,
    isTablet,
  };
}

入口先归一化:normalizeDimension 把 NaN、Infinity、负数、0 统一成 0;resolveConfigDimension 只接受有限正数,否则回落到 TABLET_LAYOUT_DEFAULTS。0×0 因此返回 compact 默认值,不抛异常。

断点与派生值:

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

导航形态和单双栏各靠一个 || 判断:w >= 840,或 w >= 600 且横屏,走侧轨;w >= 840,或 w >= 720 且横屏,走双栏。列表宽度 clamp(round(w × 0.34), 300, 400),密度只看高度:h < 500 切紧凑,headerHeight 从 64 降到 56。cardColumns 按 1200 / 840 / 600+横屏 / 600 依次落到 4 / 3 / 3 / 2,再往下是 1。

sizeClass 是宽度的函数,isTablet 是短边的函数,两者各算各的。844×390 的手机会拿到 expanded、12 栏、margin 32,同时 isTablet == false、density == compact、headerHeight == 56;RN 侧没有哪一段会因为 isTablet 为 false 就把 sizeClass 降档。宽度够宽就给宽布局,设备标签不参与分档。

几种常见做法的输入和代价:

方案输入问题
Dimensions.get('screen') 算一次方向屏幕窗口拖窄后仍是横屏;缓存不跟窗口走
key={layout.orientation} 强制重挂载方向子树重建,状态全丢
设备型号判断Platform回答不了“此刻窗口多大”
响应式框架包约束引入整框架,与零依赖 npm 库冲突
本库useWindowDimensions() + 纯函数零运行时依赖;同尺寸同布局;状态不重建

边界数字都由 __tests__/layout.test.ts 覆盖:599.9 还是 compact;600×500 横屏有侧轨但仍是单栏;719×400 单栏、720×400 双栏;839.9 宽用底部导航、840 宽用侧轨并进入 expanded;1200 进 large。listWidth 在 1100 宽算出 374,1024×1366 算出 348,1199 和 1200 都夹到 400,390 宽落到下限 300。

配置面只有四个字段:

// src/types.ts
/**
 * Values that may be overridden by a host application. Breakpoints and the
 * 300–400 list width clamp intentionally stay fixed: they are the contract.
 */
export interface TabletLayoutConfig {
  /** Width of the navigation rail. Default 88. */
  railWidth?: number;
  /** Height of the bottom navigation bar. Default 76. */
  bottomBarHeight?: number;
  /** Header height when density is comfortable. Default 64. */
  headerHeight?: number;
  /** Header height when density is compact. Default 56. */
  compactHeaderHeight?: number;
}

断点、listWidth 的 300–400 夹取、密度阈值写死在 layout.ts 里,不开放覆盖。原因不复杂:一旦允许宿主改断点,A 页面用默认的 840、B 页面改成 900,同一台设备上会出现两套“平板布局”,同一个宽度在两个页面会给出两种 sizeClass。侧轨宽度、底栏高度、两档页头高度是视觉 chrome,改它们不影响“这个宽度该用哪种布局”。

TABLET_LAYOUT_DEFAULTS 也是公开导出,测试里有一处 toEqual({ railWidth: 88, bottomBarHeight: 76, headerHeight: 64, compactHeaderHeight: 56 });改默认值会同时影响文档和测试,漂移会立刻暴露。

5. RNOH 侧:窗口变化从哪来,HAR 为什么是空的

示例宿主是一个标准 RNOH 工程。example/harmony/entry/src/main/ets/pages/Index.ets 里,RNApp 把 RN 实例挂到 ArkUI 的页面上:

// example/harmony/entry/src/main/ets/pages/Index.ets
build() {
  Column() {
    if (this.coreContext) {
      if (this.coreContext.isDebugModeEnabled) {
        RNOHErrorDialog({ ctx: this.coreContext })
      }
      RNApp({
        rnInstanceConfig: {
          createRNPackages,
          enableNDKTextMeasuring: true,
          enableBackgroundExecutor: false,
          enableCAPIArchitecture: true,
          arkTsComponentNames: []
        },
        appKey: 'TabletAdaptiveExample',
        wrappedCustomRNComponentBuilder: customComponentBuilder,
        jsBundleProvider: new AnyJSBundleProvider([
          new ResourceJSBundleProvider(this.coreContext.uiAbilityContext.resourceManager, 'bundle.harmony.js'),
          new MetroJSBundleProvider()
        ])
      })
    }
  }
  .width('100%')
  .height('100%')
}

AnyJSBundleProvider 先找 rawfile/ 里的 bundle.harmony.js,找不到才退回 MetroJSBundleProvider。顺序不能反:DevEco 直接 Run 只编译 ArkTS 与原生壳,不会打 JS bundle;没有离线 bundle 时,应用回落到 localhost:8081,Metro 没启动就是红屏。npm run build:example 先构建库、再用 Metro 把 bundle.harmony.js(1.1 MB)写进 rawfile/,最后调 hvigor 出 HAP。

窗口尺寸的变化发生在这层之上。RNOH 把 ArkUI 窗口的变化更新到 RN 的 Dimensions,useWindowDimensions() 重新发值,useTabletLayout() 重算。库本身不调原生窗口 API,也不注册窗口监听,只消费 RN 已经给到的那一对宽高。

另一边是它在 RNOH 生态里的包声明:

// harmony/rn_tablet_adaptive/src/main/ets/TabletAdaptivePackage.ets
import {
  AnyThreadTurboModule,
  AnyThreadTurboModuleContext,
  RNOHPackage,
} from '@rnoh/react-native-openharmony';

/**
 * tablet-adaptive-rn is a pure React Native view library. The adaptive layout
 * is rendered by RNOH's View/Text/ScrollView primitives, so the autolinked
 * package has no TurboModule of its own. The HAR exists so the npm package is
 * a normal, discoverable RNOH third-party package.
 */
export class TabletAdaptivePackage extends RNOHPackage {
  override getAnyThreadTurboModuleFactoryByNameMap(): Map<
    string,
    (ctx: AnyThreadTurboModuleContext) => AnyThreadTurboModule | null
  > {
    return new Map<string, (ctx: AnyThreadTurboModuleContext) => AnyThreadTurboModule | null>();
  }
}

getAnyThreadTurboModuleFactoryByNameMap() 返回一个空 Map。没有 TurboModule、没有原生视图、没有 C++,HAR 存在的意义是让 RNOH autolinking 识别这个包、让 DevEco 识别工程、让版本化有落点。package.json 里对应的元数据只有三行有效信息:

"harmony": {
  "alias": "tablet-adaptive-rn",
  "autolinking": {
    "ohPackageName": "@rnoh/tablet-adaptive-rn",
    "etsPackageClassName": "TabletAdaptivePackage"
  }
}

HAR 是 bytecode HAR,2,966 bytes,byteCodeHar: true、compatibleSdkVersion 21,内容只有 Index.d.ets、ets/modules.abc、sourceMaps.map、oh-package.json5、src/main/module.json 和 TabletAdaptivePackage.d.ets。它随 npm tarball 发布,宿主 autolinking 读到 harmony.autolinking 就集成,不需要在宿主手写原生代码。实际布局仍由 RN 的 View、Text、ScrollView 绘制。

HAR 里放的是编译后的 ets/modules.abc,ArkTS 源码不在包内;resOptions.copyCodeResource.enable = false 关掉了源码复制,和审核通过的 spatial-glass-rn 形态一致。

仓库里三个目录对应三种打开方式:根目录看库源码,harmony/ 是 HAR 工程(没有 entry,不能 Run),example/harmony 才是示例 HAP 宿主:

仓库三个目录

6. 旋转时组件树不动,动的是选中态

hook 不返回 key,工作台也没有在根节点上绑 key。旋转前后是同一棵组件树,useState 的初始值只跑一次,之后靠 useLayoutEffect 处理单双栏切换。

// src/AdaptiveTabletWorkspace.tsx
const previousPaneMode = useRef<PaneMode>(layout.paneMode);

useLayoutEffect(() => {
  const previous = previousPaneMode.current;
  if (previous === layout.paneMode) {
    return;
  }
  previousPaneMode.current = layout.paneMode;
  setSelectedItemId((current) =>
    resolvePaneSelection({
      paneMode: layout.paneMode,
      selectedId: current,
      firstItemId,
    }),
  );
}, [firstItemId, layout.paneMode]);

useLayoutEffect(() => {
  if (layout.paneMode !== 'split') {
    return;
  }
  setSelectedItemId((current) => {
    if (
      current !== null &&
      filteredItems.some((item) => item.id === current)
    ) {
      return current;
    }
    return firstItemId;
  });
}, [filteredItems, firstItemId, layout.paneMode]);

previousPaneMode 用 useRef 记住上一次的 paneMode,值没变就直接 return,同样的布局重渲染不会重复改选中项。双栏里当前目标换了一批条目时,另一段 effect 兜底:原来选中的 id 还在就保留,不在了补首条。两个 effect 都写成 useLayoutEffect,在绘制前跑,选中态先定下来,不会先闪一帧空详情。

resolvePaneSelection 是个纯函数,规则单独可测:单栏返回 null(回列表),双栏优先保留 selectedId,没有就取 firstItemId,两个都没有返回 null。切换导航目标时,handleSelectDestination 也调它,把 selectedId 显式传 null,于是双栏落到新目标首条、单栏回到列表。

滚动位置靠“不卸载”保住。列表 ScrollView 一直挂载,单栏详情态只是用 display: none 把它藏起来:

// src/AdaptiveTabletWorkspace.tsx
const listVisible = split || selectedItem === null;
const detailVisible = split || selectedItem !== null;

const listVisibility = {
  display: listVisible ? ('flex' as const) : ('none' as const),
};

listVisible 为 false 时,列表子树还在,只是不参与布局,也不进无障碍树:accessibilityElementsHidden 和 importantForAccessibility 同步设成隐藏。布局从双栏切到单栏、再切回来,ScrollView 实例没换,滚动位置就留在原地。详情 ScrollView 是条件渲染的,离开详情会卸载,所以这里只承诺列表滚动尽量保留,不承诺详情滚动位置。

display:none 和卸载的区别在原生滚动容器上很实在。ScrollView 的 content offset 存在原生视图里,React state 里没有它;卸载会把原生视图和 offset 一起销毁,重新挂载后从 0 开始,想在挂载后恢复就得拿 ref、等 layout、再 scrollTo,中间还会闪一帧。用 display:none 把列表留在树上,offset 不会因为卸载被清零,切回来通常还是原来的位置;能不能完全保持,取决于平台对 display:none 的处理,仓库说明用的词是“尽量保留”。代价是列表子树的 React 元素和原生视图一直占着内存。工作台是参考实现,列表全量渲染、没有虚拟化,所以这个代价可控;真接几千条数据时,应该换 FlatList,滚动位置就得自己存、自己恢复。

选中项、滚动位置、焦点在重排时的处理并不一样。选中项是 React state,布局变化只触发重渲染,state 本身不丢;但 paneMode 一变,useLayoutEffect 会按契约改它:单栏清空、双栏保留或补首条。滚动位置没有进 state,靠列表不卸载保留;详情滚动在离开详情时随组件卸载消失,这是有意的。焦点最脆:列表卡片因为列表常驻,DOM 节点和原生视图都还在,焦点通常能留住;单栏的返回按钮在切到双栏时会卸载,Web 上的 DOM 焦点会掉到 body,原生端交给 Pressable 和辅助功能管理。工作台没有写显式的焦点恢复,只在列表常驻这一点上受益;硬件键盘的焦点行为由原生端管理。

无障碍语义单独走一路。导航容器是 role="navigation",目标项是 tab,当前项用 accessibilityState.selected 表达;卡片是 button,带 label、hint、selected 状态和 activate 动作。尺寸和对比度也有硬指标:导航项最小高度 56,底部导航项、返回按钮和卡片的触控目标不小于 44×44,正文墨色与纸色对比度满足 WCAG AA,暖橙只做非文本装饰。RN 0.84 核心没有 aria-current,所以当前目标只能靠 selected 状态和标签里的“当前目标”表达;Web 上额外监听 Enter/Space,原生端交给 Pressable 与辅助功能动作。这条差异由原生端和 Web 分别处理。

7. 33 项测试与构建数字

测试只打纯逻辑,不渲染组件树,也不 import react-native 运行时:

// __tests__/layout.test.ts
describe('resolveTabletLayout — breakpoint boundaries', () => {
  it('keeps 599.9 below the medium breakpoint', () => {
    const layout = resolveTabletLayout(599.9, 960);
    expect(layout.sizeClass).toBe('compact');
    expect(layout.cardColumns).toBe(1);
    expect(layout.navigation).toBe('bottom');
    expect(layout.paneMode).toBe('single');
  });

  it('uses a rail but no split at 600dp landscape', () => {
    const layout = resolveTabletLayout(600, 500);
    expect(layout.sizeClass).toBe('medium');
    expect(layout.cardColumns).toBe(3);
    expect(layout.navigation).toBe('rail');
    expect(layout.paneMode).toBe('single');
  });

  it('needs 720dp for the landscape split rule', () => {
    expect(resolveTabletLayout(719, 400).paneMode).toBe('single');
    expect(resolveTabletLayout(720, 400).paneMode).toBe('split');
  });

  it('needs 840dp for the expanded rail rule in portrait', () => {
    expect(resolveTabletLayout(839.9, 1000).navigation).toBe('bottom');
    expect(resolveTabletLayout(840, 1000).navigation).toBe('rail');
    const expanded = resolveTabletLayout(840, 1000);
    expect(expanded.sizeClass).toBe('expanded');
    expect(expanded.paneMode).toBe('split');
    expect(expanded.cardColumns).toBe(3);
  });
});

npm run verify 的顺序是 tsc --noEmit、vitest run、Babel 双格式构建、tsc -p tsconfig.types.json。最近一次输出:

Test Files  2 passed (2)
     Tests  33 passed (33)

33 项里布局 29、主题 4。布局测试覆盖 12 组基准向量、断点边界(599.9 / 600 / 720 / 840 / 1200)、0 与非法尺寸、正方形、isTablet、density、配置覆盖,以及 resolvePaneSelection、formatLayoutSummary 这些辅助函数。主题测试覆盖默认 token、覆盖合并和返回值不可变。

测试覆盖的边界到纯函数为止。33 项里没有组件渲染测试,useTabletLayout 的订阅、AdaptiveTabletWorkspace 的选中态迁移、ScrollView 的滚动位置、无障碍树都没有自动化断言;这些要么需要 RN 运行时和渲染器,要么需要真机。layout.test.ts 能保证同一对宽高算出同一份 token,theme.test.ts 能保证主题合并不改原对象,但它们保证不了 RNOH 是否派发了 Dimensions 变化,也保证不了原生 ScrollView 在 display:none 后保不保 offset。真机验证覆盖 1100×734 的 split 渲染;旋转、分屏、折叠屏、安全区、硬件键盘和 RTL 要么本来就不在纯 JS 层,要么是当前测试策略选择不引入渲染器。如果以后加组件测试,需要引入 RN 测试渲染器,测试就不再是纯 Node 环境。

构建链的数字:npm install 装 861 个包;Babel 把 6 个模块编到 lib/commonjs 与 lib/module;tsc 生成 6 个声明文件;npm pack 62 个文件、89,206 bytes,解包 405,483 bytes,verify:package 通过;HAR 构建 BUILD SUCCESSFUL in 5 s 278 ms,产物 2,966 bytes;示例 HAP BUILD SUCCESSFUL in 2 min 37 s,unsigned 38 MB,里面带 1.1 MB 的 bundle.harmony.js。

真机安装:

hdc install -r example/harmony/entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.lqjmac.tabletadaptivern

结果是在 1100×734 窗口里渲染出 split list-detail,没有 JS bundle 错误。

8. 红屏、assert.h 与那几个改坏的版本

react 差一个小版本,真机红屏。react-native@0.84.1 只声明 peer 范围 react: ^19.2.3,我装了 19.2.9,启动直接报:

Error: Incompatible React versions: The "react" and "react-native-renderer"
packages must have the exact same version.

peer 范围是兼容承诺,React 运行时要求的是精确一致。修复是把 react 固定到 19.2.3,与 RN 内置 renderer 同版本。

#include <assert.h> 编出上千个错。RNOH 自带 src/main/cpp/RNOH/Assert.h 并把该目录加进 include 路径;macOS APFS 大小写不敏感,#include <assert.h> 捡到的是 RNOH 的 Assert.h,它不定义标准 assert 宏,Boost、double-conversion、jsi 全线报 use of undeclared identifier 'assert'。修复是 example/harmony/entry/src/main/cpp/compat/assert.h 恢复 musl 的 assert.h,CMake 里用 include_directories(BEFORE ...) 把它排到 RNOH 目录前面。

DevEco Run 出来的应用红屏。HAP 里没有离线 bundle,回落到 localhost:8081,Metro 没启动就加载失败。修复是 Run 之前先 npm run build:example。

首装用了 --ignore-scripts,prepare 没跑,lib/ 不存在,npm pack 内容不对。修复是用 npm pack --dry-run 单独验证 prepare 构建路径,确认产出与正常安装一致。

844×390 手机横屏被判进 expanded / 12 栏。宽度够 840 就是 expanded,isTablet == false 只是信息标记,不给 sizeClass 封顶。这条由 layout.test.ts 的 29 项布局测试兜着。

key={layout.orientation} 这个做法很直接:旋转后布局“不对”,改 key 强制重挂载最快,代价是滚动、选中、焦点全丢。修复是 hook 不返回 key、文档写禁令,正确做法是保持组件树,让布局值流过样式。

想给断点开配置口子。“万一宿主想改 840 到 900 呢?”改了就没有统一契约:两页两个断点,sizeClass 和栏数各算各的。修复是把配置面收窄到四个尺寸字段。

9. 现在怎么用、还差什么

安装:

npm install react-native-tablet-adaptive

Metro 走 package.json 的 "react-native": "./src/index.ts" 直接编译 TS 源码;Node 消费者走条件导出拿 lib/commonjs 或 lib/module;类型由根 index.d.ts 指向 lib/typescript。

跑示例:

npm run build:example        # 库构建 + Metro bundle + hvigor HAP
# DevEco 打开 example/harmony 点 Run;或命令行:
hdc install -r example/harmony/entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.lqjmac.tabletadaptivern

文档在仓库里:仓库说明写 API 全表、布局规则与横竖屏策略;OpenHarmony 接入说明写 RNOH 集成、HAR 说明与基线;布局契约文档管断点取舍与状态保留契约;验证记录存构建、打包、HAR、真机运行全记录;__tests__/ 下是 33 项纯逻辑测试(布局 29 + 主题 4)。

当前版本在 Node 24.12.0、RN 0.84.1、RNOH 0.84.3、DevEco 26.0.0.821(SDK 26)环境验证:npm run verify 通过,33 项测试通过,npm pack 62 文件 89,206 bytes、verify:package PASS;HAR 与示例 HAP 都构建成功。

库能保证的是同一对宽高得到同一份布局,以及布局变化时组件树不被重建。真机验证覆盖 1100×734 的双栏渲染;旋转、分屏、SafeAreaView、硬件键盘、serif 回退、RTL 和小窗口属于原生层与后续测试范围。

Logo

开源鸿蒙跨平台开发社区汇聚开发者与厂商,共建“一次开发,多端部署”的开源生态,致力于降低跨端开发门槛,推动万物智联创新。

更多推荐