React Native 鸿蒙平板适配实战:方向是算出来的,不是查出来的
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 Native | peer >= 0.76;开发与类型检查使用 0.84.1 |
| React | 19.2.3(必须与 RN 0.84.1 内置 renderer 精确一致,devDependencies 固定) |
| RNOH | 参考基线 @rnoh/react-native-openharmony 0.84.3 / HarmonyOS SDK 26 |
| DevEco Studio | 26.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-adaptive | 1.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 · 横屏 · 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 默认值,不抛异常。
断点与派生值:
| 宽度 | sizeClass | columns | margin / gutter |
|---|---|---|---|
| <600 | compact | 4 | 16 / 8 |
| 600–839 | medium | 8 | 24 / 16 |
| 840–1199 | expanded | 12 | 32 / 24 |
| >=1200 | large | 12 | 40 / 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 和小窗口属于原生层与后续测试范围。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐


所有评论(0)