单列怎么在窄窗口退成抽屉、双栏怎么在折叠屏展开时长出第三栏、三栏又怎么在窗口被拖窄时自己收回去。

示例仓库:https://atomgit.com/dijun_520/react-native-split-layout

社区引导:框架源码与版本发布见 https://atomgit.com/CPF-RN/ohos_react_native/tree/0.84-main

CPF-RN 鸿蒙社区:https://atomgit.com/CPF-rn


0. 环境与实测设备

项目版本 / 型号
DevEco Studio26.0.0 (26.x)
HarmonyOS SDK / API26.0.0 / API 26
React Native / RNOH0.84.1(@rnoh/react-native-openharmony 0.84.1,C-API 架构)
Node.jsv22.11+
实测设备HarmonyOS 7 PC(MateBook Pro)

两个版本号要特别说明,决定了后面所有"能不能用"的判断:

  • compatibleSdkVersion 5.0.0(12) 是最低兼容。库里的 display.getFoldStatus()、window.on('windowStatusChange') 这些 API 在 12 上只是"存在但不能保证所有设备都支持",所以 ArkTS 侧每一个调用都套了 try/catch,拿不到就降级成 unknown。
  • targetSdkVersion 6.0.0(20) 是编译目标。window.WindowStatusType 的枚举值、2in1 设备的自由窗口行为。

1. “分屏就是把手机版拉宽”

手机上是单列,平板是两栏,那"分屏"不就是把手机版塞进半个屏幕里吗?宽度变了,flexDirection 自己会排。于是第一版写了个 280vp 的固定侧边栏 + flex: 1 的内容区。

真机给我的第一个反馈就很有意思:在 2in1 上把窗口从全屏拖到 420vp,侧边栏死死占着 280vp,内容区只剩 140vp——标题被截成三个字,列表项的副标题挤成一条竖线。

第二个反馈更隐蔽。我把内容区做成"列表 + 详情"的纵向流:列表在上面,点某一项,详情展开在下面。在手机上这没问题(滚动就行)。但在 700vp 的窗口里,用户点了一下列表项,屏幕要往下滚 600vp 才看得到"详情"。

所以这个题目的边界很清楚:

「自适应」不是给固定布局加几个媒体查询,而是先决定"这一宽度下应该有几个窗格",再决定每个窗格的形态——是并排的列,还是浮在内容上的抽屉。 窗格数量的决定权属于宽度,窗格形态的决定权属于"内容还够不够宽"。

拆开就是三件事:

  • 一条宽度 → 窗格数的映射,而且要抗抖动(窗口拖动时宽度是连续变化的流,卡在阈值上会闪);
  • 一条窗格降级顺序:侧边栏展开 → 图标栏 → 覆盖抽屉;详情列 → 详情抽屉;
  • 一套真机才有的输入:自由窗口拖拽、分屏、折叠态、安全区——这些在 iOS/Android 上不存在,只能由 ArkTS 侧供给 JS。

顺手贴一条这次开发里最典型的报错:

ninja: error: Stat(C:/Users/PC/WorkBuddy/.../react-renderer/textlayoutmanager/
platform/harmony/react/renderer/textlayoutmanager/TextLayoutManager.cpp):
Filename longer than 260 characters

2. 效果展示

请添加图片描述

这张是宽度沙盒固定在 420vp 时的样子。顶部状态行不是装饰:compact · 1栏 是 JS 侧 resolveSplitLayout() 的返回值,420vp 是 ArkTS 侧 onAreaChange 量到的真实宽度,自由窗口 是 SplitLayoutWindow TurboModule 推断出来的 windowMode。三者一致,说明"原生测量 → JS 决策 → 重新渲染"这条链路是通的。此时侧边栏不是被隐藏了,而是变成了覆盖抽屉:从左边缘 16vp 的热区横滑可以拉出来,也可以用左上角的按钮打开。

请添加图片描述

窗口拖到 712vp(2in1 上把窗口吸附到右半屏就是现成的 medium 档),侧边栏从抽屉变成真正的 280vp 列,内容区是列表,详情还是抽屉——因为 712 - 280 - 380 已经撑不起第三列,把详情做成常驻列等于把内容区压死。

请添加图片描述

最大化之后三栏成立:侧边栏 280、内容自适应、详情 380。注意右侧详情栏不是"点开才出现",而是常驻——在 1600vp 级别的宽度下,让用户每点一次都开一次抽屉是浪费屏幕。侧边栏此时点收起,会退成 72vp 的图标栏而不是消失,因为宽屏下"消失"会让内容区突然跳位。

三张图对应三个断点,但真正值钱的是中间那些"不是整档"的宽度:拖动窗口时框在 600 附近来回晃,布局不会跟着闪。

除了三档主形态,demo 还能切出四张"边界态",每一张都对应一个必须写进设计文档的行为:

请添加图片描述

请添加图片描述

compact 下点列表卡片:详情整页覆盖单列,靠返回键退出,而不是挤进第三栏

请添加图片描述

3. 原理:窗口是画布,Yoga 是唯一的布局真相

在移动端,"屏幕宽度"是一个常量;在 HarmonyOS 上,它是一条曲线。窗口可以被拖成任意长宽比、可以被拖进分屏、折叠屏可以停在半折状态。

系统能告诉我们的东西,比想象中多:

事件 / API方向回调对象应用要回答什么
window.on('windowSizeChange')系统 → 应用window.Window画布宽高变了,窗格数要不要改
window.on('windowStatusChange')系统 → 应用window.Window现在是全屏 / 分屏 / 悬浮 / 最大化
display.getFoldStatus()系统 → 应用display 模块折叠屏展开还是半折
window.getWindowAvoidArea()系统 → 应用window.Window状态栏、导航条、刘海吃掉多少边
onAreaChangeArkUI → 组件自定义组件我这个组件的真实可用区域是多少
onLayoutYoga → RN 视图RN 组件RN 认为我占了多少

这里有个很容易写错的分工。我第一版想的是"让原生组件负责摆放三个窗格"——毕竟 ArkUI 有 Row、有 Fraction、有 Divider,摆位置很顺手。写完才发现这是灾难:RN 的视图树是 Yoga 算的,原生再摆一次,两套布局必然会出现 1px 级的分歧,表现为分隔线偏移、抽屉遮罩盖不住、滚动区域和可视区不一致。

Yoga 是唯一的布局真相,ArkTS 不摆位置。

ArkTS 侧的自定义组件 RNCSplitLayout 只做三件事:用 ContentSlot 承载 RN 子树、在窗格边界画 1px 分隔线、在左边缘挂一个横向 PanGesture。它内部是一个 Stack,三个窗格按顺序叠放,位置完全由 Yoga/C++ 决定(见第 6 节坑 9——为什么不能用 ArkTS 去摆子节点)。

第二条原则:

窗格数量由宽度决定,窗格形态由"剩余宽度"决定。

这条看着像废话,但它是"不要把纵向流硬塞进窄分屏"的根。举一组真实数字(sidebarWidth=280、railWidth=72、detailWidth=380、minContentWidth=340):

可用宽度断点侧边栏详情内容区列数
420compactoverlay(0)overlay(0)4201
600mediumexpanded(280)overlay(0)320 → 触发降级2
620mediumexpanded(280)overlay(0)3402
700mediumexpanded(280)overlay(0)4202
900expandedexpanded(280)overlay(0)→ 340 不够 → column?6202
1000expandedexpanded(280)column(380)3403
1600expandedexpanded(280)column(380)9403

注意 600 那一行:断点说"你是 medium,可以有侧边栏",但 600 - 280 = 320 < 340,内容区会被压到不舒适。所以侧边栏先退成 72vp 图标栏(600 - 72 = 528)。

第三条原则是给鸿蒙的:

窗口模式是一等公民,不是日志。

windowMode 和 foldStatus 不只是显示在状态行上的文字。分屏状态下,系统给的高度往往比宽度更紧张,安全区也会变;半折状态下,上半屏和下半屏是两块物理区域,把侧边栏放在折痕上是不可用的。库把这两个值放进 SplitLayoutSnapshot 交给业务,业务可以据此改变内容密度(比如分屏时列表切单列、最大化时切两列网格)——example 里的 DocList 就是这么做的。

这两个细节(降级顺序 + 窗口模式)决定了后面所有的实现。

4. 工程怎么搭

这次整理最关键的变化,是把"能跑"变成"能复用"。三条边界定死:

  • lib 不依赖任何页面:src/ 里没有一处 import example 的东西,resolveSplitLayout() 是纯函数,能单测;
  • 原生模块独立成 HAR:harmony/rn_split_layout 编出 split_layout.har,宿主工程通过 harmony.autolinking 自动链接,不需要手改 oh-package.json5;
  • example 只走公共 API:example/src/App.tsx import 的全部来自 react-native-split-layout,没有一处深路径引用。

目录树(省略 node_modules、oh_modules、build):

react-native-split-layout/
├── package.json                  # 含 harmony.autolinking 声明
├── index.js / index.d.ts          # 包入口与自包含类型
├── src/
│   ├── SplitLayout.tsx            # 主组件:测量、动画、手势、三态渲染
│   ├── breakpoints.ts             # 纯函数:断点 + 迟滞 + 降级顺序
│   ├── hooks.ts                   # useWindowMetrics / useBreakpoint
│   ├── native.ts                  # 原生模块桥(非鸿蒙降级为空实现)
│   ├── context.ts                 # useSplitLayout()
│   ├── types.ts                   # 公共类型
│   └── specs/
│       ├── SplitLayoutNativeComponent.ts   # codegen: Fabric 组件
│       └── NativeSplitLayoutWindow.ts      # codegen: TurboModule
├── harmony/
│   ├── split_layout.har           # 构建产物(12.8 KB)
│   └── rn_split_layout/           # HAR 源码工程
│       ├── index.ets
│       ├── oh-package.json5
│       └── src/main/
│           ├── ets/
│           │   ├── RNCSplitLayout.ets      # 自定义组件:测量/手势/分隔线
│           │   ├── SplitLayoutWindowTurboModule.ets
│           │   ├── SplitLayoutPackage.ets  # 注册
│           │   └── Breakpoints.ets         # 与 JS 1:1 的断点复刻
│           └── cpp/
│               ├── CMakeLists.txt
│               ├── SplitLayoutPackage.h
│               └── generated/              # codegen 产出(5 个 cpp)
└── example/                       # 可直接跑的 RNOH 应用
    ├── src/
    │   ├── App.tsx                # 三档演示 + 宽度沙盒 + 运行时 HUD
    │   ├── components/Sidebar.tsx # 展开态与 72vp 图标栏两套渲染
    │   ├── components/DocList.tsx # 内容区按自身宽度切 1/2 列
    │   └── components/DocDetail.tsx
    └── harmony/                   # 应用工程
        └── entry/src/main/
            ├── ets/                 # RNOHPackagesFactory(自动生成,含本库)
            └── cpp/
                ├── CMakeLists.txt
                └── autolinking.cmake # 自动生成,指向 HAR 的 cpp 目录

最小接入只要三步。第一步,package.json 里声明 autolinking(这步是本库自己带的,业务不用写):

"harmony": {
  "alias": "react-native-split-layout",
  "autolinking": {
    "etsPackageClassName": "SplitLayoutPackage",
    "cppPackageClassName": "SplitLayoutPackage",
    "cmakeLibraryTargetName": "rnoh_split_layout",
    "ohPackageName": "@react-native-ohos/react-native-split-layout"
  }
}

第二步,业务里用它。核心只有四个 prop:三个宽度 + 一个最小内容宽度:

// example/src/App.tsx
<SplitLayout
  sidebarWidth={280}
  sidebarRailWidth={72}
  detailWidth={380}
  minContentWidth={340}
  collapsed={collapsed}
  onCollapsedChange={setCollapsed}
  detailVisible={detailVisible}
  onSnapshot={setSnapshot}
  sidebar={state => (
    <Sidebar
      mode={state.sidebarMode}          // 'expanded' | 'rail' | 'overlay'
      onCollapse={() => state.setCollapsed(true)}
      onClose={state.closeSidebar}
    />
  )}
  detail={selected ? <DocDetail doc={selected} onBack={() => setDetailOpen(false)} /> : null}
>
  <DocList docs={docs} selectedId={selectedId} onSelect={handleSelect} />
</SplitLayout>

第三步,需要的话读窗口上下文:

const metrics = useWindowMetrics();   // 来自 TurboModule 的实时窗口信息
// { windowWidth, windowHeight, density, windowMode, foldStatus, isSplitScreen, safeArea* }

通道协议有两层。TurboModule 负责"拉":getWindowMetrics() 返回一个快照,startObserving() 之后通过 DeviceEventEmitter 推 SplitLayoutWindowMetrics 事件。Fabric 组件事件负责"推":原生组件每次 onAreaChange 都会发 nativeLayout,边缘手势结束会发 edgeSwipe。两条线都是 Object 载荷,形状固定:

{ "width": 700.0, "height": 860.0, "density": 2.0, "breakpoint": "medium", "columns": 2 }
{ "direction": "open", "deltaX": 63.5 }

容易被忽略的窗口期有两个,我在实现里都做了缓冲:

  • 首帧没有测量值。原生组件挂载到 onAreaChange 第一次回调之间有一帧,此时 width 是 0。如果直接按 0 去解析布局,会先渲染一次 compact 再跳到 expanded,视觉上就是"闪一下"。解决方式是宽度来源有优先级:原生测量 → windowWidth → useWindowDimensions(),并且 width <= 0 时不出快照。
  • 动画不能被测量打断。窗口拖动时 onAreaChange 可能一帧来好几次,如果每次都重启 Animated.timing,侧边栏会变成"抖动的橡皮筋"。解决方式是动画只在解析后的宽度变化时启动(resolution.sidebarWidth),而不是在原始测量值变化时启动。

5. 把代码讲透

5.1 resolveSplitLayout:一个纯函数钉死降级顺序

src/breakpoints.ts 是这个库的心脏,它不 import 任何 React、不 import 任何 RN,因此可以在 Node 里直接跑:

// src/breakpoints.ts - resolveSplitLayout()
let sidebarMode: SidebarMode = 'hidden';
if (hasSidebar) {
  if (breakpoint === 'compact' || overlaySidebar) {
    sidebarMode = 'overlay';
  } else if (collapsed) {
    sidebarMode = collapsedBehavior === 'hidden' ? 'hidden' : 'rail';
  } else {
    sidebarMode = 'expanded';
  }
}

// Degrade the sidebar until the content pane can breathe.
if (sidebarMode === 'expanded' && width - sidebarWidth < minContentWidth) {
  sidebarMode = 'rail';
}
if (sidebarMode === 'rail' && width - sidebarRailWidth < minContentWidth) {
  sidebarMode = 'overlay';
}

三个细节值得单独说。

第一,降级是"逐级试探",不是"一次判断"。 很多实现会写成 if (width > x) expanded else overlay,中间那档 72vp 的图标栏就丢了。图标栏是很实用的中间态:它保住了"导航一直可见",又不吃掉内容宽度。写成两次独立判断,才能保证 600vp 这种"展开不够、图标栏够"的宽度落在正确的档位上。

第二,detail 的判定用的是"降级后的侧边栏宽度"。 也就是 available = width - sidebarOccupied,而不是 width - sidebarWidth,顺序错了会出现"侧边栏已经退成图标栏,详情还按 280 去算,结果内容区算出负数"的 bug。

// src/breakpoints.ts - detail 段
let detailMode: DetailMode = 'hidden';
if (hasDetail) {
  detailMode = 'overlay';
  if (detailPresentation !== 'overlay' && breakpoint !== 'compact') {
    const available = width - sidebarOccupied;
    const fitsColumn = available - detailWidth >= minContentWidth;
    if (fitsColumn || detailPresentation === 'column') {
      detailMode = 'column';
    }
  }
}

第三,columns 是"算出来的",不是"传进来的"。 它等于 1 + 侧边栏是否占位 + 详情是否占位。这看起来只是个小工具,但它保证了 columns 和实际占位永远一致——否则会出现"传了 3,实际只显示 2 栏"这种原生分隔线画错位置的问题。

一个反直觉的坑:contentConstrained 不能用来判断"要不要降级"。它只是"我确实没能满足你的要求"的标记——比如业务显式传了 detailPresentation="column",或者窗口窄到图标栏都放不下。用它去驱动降级会导致降级逻辑自我触发。

5.2 谁说了算:三路测量的优先级

宽度有四个来源,必须定优先级,否则会出现"三处数字互相打架":

// src/SplitLayout.tsx - 宽度来源优先级
// 1. 原生 onAreaChange(鸿蒙,最准:这是 ArkUI 给组件的真实可用区域)
// 2. windowMetrics.windowWidth(TurboModule,窗口级真相,但含安全区)
// 3. useWindowDimensions()(RN 自己的窗口尺寸,跨端兜底)
// 4. 0(首帧,不出快照)

为什么不直接用 useWindowDimensions()?因为在鸿蒙上它给的经常是窗口宽度,而 <SplitLayout> 可能被嵌在一个已经有了 padding、或者已经被侧边导航挤过的容器里。这时候窗口宽度是对的,组件宽度是错的,按窗口宽度算出来的三栏会把内容推出屏幕。

为什么不只用 onAreaChange?因为它只在挂载后才有值。首帧必须有个假设值,否则第一帧永远是 compact。

真正值钱的是中间这一段:断点的迟滞。窗口拖动时宽度是连续流,卡在 600 附近会来回穿越阈值,布局就会闪。8vp 的迟滞把这件事解决了:

// src/breakpoints.ts - getStableBreakpoint()
const next = getBreakpoint(width, breakpoints);
if (previous === undefined || previous === next || hysteresis <= 0) {
  return next;
}
const previousIndex = order.indexOf(previous);
const nextIndex = order.indexOf(next);
if (nextIndex > previousIndex) {
  // 变大:必须超出阈值 hysteresis 才升级
  return width >= threshold + hysteresis ? next : previous;
}
// 变小:必须低于阈值 hysteresis 才降级
return width <= threshold - hysteresis ? next : previous;

三个细节值得单独说。

第一,迟滞是"单边"的,不是"双边对称的"。 升级要多 8vp,降级要少 8vp,中间形成一个 16vp 的死区。如果只做单边(比如升级 +8、降级也 +8),死区就不存在了。

第二,迟滞只作用于断点,不作用于降级。 降级(侧边栏 expanded → rail)是宽度算数的,width - 280 < 340 就是 340 就是不行,多 1vp 才行。这里不能加死区,否则会出现"图标栏明明放得下却还是抽屉"。

第三,previous 必须存在 ref 里,不能用 state。 用 state 会引入一次额外的渲染,而这一次渲染里 previous 已经变了,迟滞等于失效。代码里是 previousBreakpoint.current。

5.3 ArkTS 侧只做三件事:测量、手势、分隔线

原生组件的实现有 186 行,但只做三件事。第一件是测量:

// harmony/rn_split_layout/src/main/ets/RNCSplitLayout.ets - build()
.onAreaChange((_oldArea: Area, newArea: Area) => {
  const width: number = RNCSplitLayout.lengthToVp(newArea.width);
  const height: number = RNCSplitLayout.lengthToVp(newArea.height);
  this.areaWidth = width;
  this.areaHeight = height;
  this.reportLayout(width, height);
})

newArea.width 的类型是 Length,实际值是 "700.00vp" 这样的字符串(不是数字),所以必须先 parseFloat。这个坑很隐蔽:直接 Number(newArea.width) 在部分版本上会得到 NaN,而 NaN 传过桥之后在 JS 侧表现成 undefined,最终表现是"布局永远停在 compact"。

上报前还做了去重,避免每帧都过桥:

// RNCSplitLayout.ets - reportLayout()
const key: string = `${Math.round(width)}|${Math.round(height)}|${columns}|${breakpoint}`;
if (key === this.lastReportKey) {
  return;
}
this.lastReportKey = key;
this.eventEmitter?.emit('nativeLayout', { width, height, density, breakpoint, columns });

第二件是分隔线。这里刻意不用 Divider 去做布局,而是用 position() 把一条竖线钉在窗格边界上:

// RNCSplitLayout.ets - buildDividers()
Divider()
  .vertical(true)
  .strokeWidth(1)
  .color(this.descriptorWrapper.props.dividerColor ?? '#E2E8F0')
  .height('100%')
  .position({ x: this.descriptorWrapper.props.sidebarWidth, y: 0 })
  .hitTestBehavior(HitTestMode.None)

三个细节值得单独说。

第一,x 用的是 JS 算出来的"实际占位宽度",不是业务传的 sidebarWidth prop。 JS 侧传进来时已经把 resolution.sidebarWidth(展开 280 / 图标栏 72 / 抽屉 0)算好了,所以原生这边不需要再判断一次——判断逻辑只有一份,在纯函数里。

第二,hitTestBehavior(HitTestMode.None) 是必须的。 少了这一行,这条 1px 的线会吃掉它下面那一像素的点击事件,表现为"列表最右边一行点不动"。

第三,分隔线不能在抽屉态画。 抽屉是浮在内容上的,画一条线在 x=0 会变成"屏幕最左边有一条竖线"。所以条件是 columns > 1 && sidebarWidth > 0。

第三件是边缘手势。PanGesture 只挂在左侧 16vp 的热区上,而且只在抽屉态启用:

// RNCSplitLayout.ets - buildEdgeHotspot()
Row()
  .width(EDGE_HOTSPOT_WIDTH)
  .height('100%')
  .position({ x: 0, y: 0 })
  .backgroundColor(Color.Transparent)
  .hitTestBehavior(HitTestMode.Transparent)
  .gesture(
    PanGesture({ direction: PanDirection.Horizontal, distance: 4 })
      .onActionEnd((event: GestureEvent) => {
        const offsetX: number = event.offsetX;
        if (offsetX > SWIPE_TRIGGER) {
          this.eventEmitter?.emit('edgeSwipe', { direction: 'open', deltaX: offsetX });
        } else if (offsetX < -SWIPE_TRIGGER) {
          this.eventEmitter?.emit('edgeSwipe', { direction: 'close', deltaX: offsetX });
        }
      })
  )

反直觉的地方在于 hitTestBehavior:HitTestMode.Transparent 表示"我自己能接收手势,但不阻止下面的组件也接收"。如果写成默认的 Default,这 16vp 会变成一条"死区",列表里的项滑不动;如果写成 None,手势又收不到。

JS 侧还有一份 PanResponder 作为兜底,因为 iOS/Android 没有 ArkTS;鸿蒙上如果把 nativeGestures 关掉,也会用它。两份实现共用同一套"打开/关闭"语义,避免出现"鸿蒙能滑、安卓不能滑"的割裂。

5.4 动画与遮罩:抽屉不是"多一栏"

抽屉态最容易写错的地方是:把它当成"宽度为 0 的一栏"。于是你会看到"抽屉打开时内容区被挤窄 280vp"——这不是抽屉,这是把双栏塞进单列。

正确的做法是两层:内容区永远按 sidebarOccupied = 0 布局(抽屉不占位),抽屉自己用 translateX 从屏幕外滑进来,中间夹一层可点击的遮罩:

// src/SplitLayout.tsx(节选)
const overlayWidth = Math.min(sidebarWidth, Math.max(0, width * 0.92));
const overlayTranslate = overlayProgress.interpolate({
  inputRange: [0, 1],
  outputRange: [-overlayWidth, 0],
});

三个细节值得单独说。

第一,抽屉宽度有上限 width * 0.92。 小折叠屏展开后可能只有 500vp,280vp 的抽屉会盖掉一半以上;留 8% 的"内容缝"是为了让用户知道"后面还有东西",也是返回手势的视觉锚点。

第二,遮罩必须能被读屏点到。 代码里给了 accessibilityLabel="Close navigation panel",并且用 Pressable 而不是 View + onTouchStart——这样 TalkBack/屏幕朗读能把它识别成一个可操作的目标。

第三,返回键要有优先级。 鸿蒙的 BackHandler 默认是"退出应用",抽屉打开时按返回应该是"关抽屉"。这一层是在 useEffect 里注册的,且在 overlayOpen 为 false 时不注册,避免吃掉正常的返回。

动画曲线用的是 Easing.bezier(0.2, 0, 0, 1)、260ms。这个组合不是随便挑的:0.2,0,0,1 是"起步快、收尾极慢"的曲线,视觉上像"被吸过去",适合抽屉;260ms 是"比系统默认 300ms 略快"的手感,在窗口拖拽这种连续操作里不会显得拖沓。

5.5 codegen 与事件协议:onNativeLayout 为什么变成 nativeLayout

JS 侧 spec 写的是:

// src/specs/SplitLayoutNativeComponent.ts
onNativeLayout?: DirectEventHandler<NativeLayoutEvent>;
onEdgeSwipe?: DirectEventHandler<NativeEdgeSwipeEvent>;

按习惯,ArkTS 侧 emit 的时候写 onNativeLayout,结果永远收不到。原因:RNOH 的 codegen 在生成 ArkTS 事件表时,会把 on 前缀剥掉,生成的事件名是 nativeLayout 和 edgeSwipe。

// harmony/.../RNCSplitLayout.ets(正确写法)
this.eventEmitter?.emit('nativeLayout', { width, height, density, breakpoint, columns });

三个细节值得单独说。

第一,这个不一致不会报错,只会静默失败。 emit 一个不存在的事件名在 ArkTS 侧是合法的,JS 侧就是不触发,没有任何日志。我是靠"原生日志打了、JS 没收到"才定位到的。

第二,属性访问要带两层前缀。 在 DescriptorWrapper 上直接 this.descriptorWrapper.mediumBreakpoint 是拿不到的(TypeScript 会直接报 Property 'mediumBreakpoint' does not exist),正确写法是 this.descriptorWrapper.props.mediumBreakpoint。

第三,@Builder 不能在 ForEach 里直接调。 我最初想把三个子节点用 ForEach 循环出来:

// 错误写法,编译器报 "does not meet UI component syntax"
ForEach(this.descriptorWrapper.childrenTags, (tag: number) => {
  this.ctx.wrappedRNComponentBuilder.builder(this.ctx, tag)
})

正确写法是三条独立的分支判断(子节点最多 3 个:sidebar / content / detail),这样 ArkUI 才能在编译期确定组件树形状。

6. 踩坑与经验

坑 1:hvigor 报 CMake Error,但只说"Configuring incomplete",一句原因都不给。

现象:assembleHap 跑到 BuildNativeWithCmake 就失败,日志里只有:

> hvigor WARN: CMake Error: Generator: execution of make failed. Make command was:
  C:/Users/PC/Python312/Scripts/ninja.exe -v cmTC_7e210
-- Configuring incomplete, errors occurred!
> hvigor ERROR: 00303300 Configuration Error
Error Message: Exceptions happened while executing ... cmake.exe ...

output.log 里也停在同一行,Configuring incomplete 前面没有任何 CMake Error at ...。

排查过程:一开始以为是 ninja 版本问题,单独拿最小工程 check_include_file 跑通了,排除。后来才反应过来——hvigor 把 cmake 的 stderr 吞了,只有少数几行会以 WARN: 前缀透出来。真正的错误在 stderr 里,而 output.log 只记 stdout。

修复:给 hvigor 加 --debug,错误就出来了(就是坑 2):

hvigorw.js --mode module -p product=default -p buildMode=debug assembleHap --no-daemon --debug

教训:hvigor 的默认日志不是"少",是"丢"。遇到 Configuration Error + undefined,先加 --debug

坑 2:ffrt::ffrt_cpp target not found。

有了 --debug,真正的错误终于露出来:

CMake Error at .../third-party/rn/CMakeLists.txt:301 (target_link_libraries):
  Target "reactnative" links to:

    ffrt::ffrt_cpp

  but the target was not found.  Possible reasons include:
    * There is a typo in the target name.
    * A find_package call is missing for an IMPORTED target.
    * An ALIAS target is missing.

同一个错误还有两份:react_renderer_uimanager、react_renderer_core。

排查过程:ffrt::ffrt_cpp 是 RNOH 的第三方依赖 @ppd/ffrt 提供的 C++ 接口(Function Flow Runtime)。我一开始以为 ohpm install 装好了就自动有 target。翻包才发现:@ppd/ffrt@1.1.10 的 HAR 里只有 libs/arm64-v8a/libffrt_cpp.so 和 include/,没有 CMakeLists.txt,所以 hvigor 生成不出对应的 imported target,summary.cmake 是 0 字节的空文件。

修复:在应用侧 entry/src/main/cpp/CMakeLists.txt 里自己声明这个 target(在 add_subdirectory(rnoh) 之前):

if(NOT TARGET ffrt::ffrt_cpp)
    set(FFRT_PACKAGE_DIR "${OH_MODULES_DIR}/@ppd/ffrt")
    add_library(ffrt::ffrt_cpp SHARED IMPORTED GLOBAL)
    set_target_properties(ffrt::ffrt_cpp PROPERTIES
        IMPORTED_LOCATION "${FFRT_PACKAGE_DIR}/libs/${OHOS_ARCH}/libffrt_cpp.so"
        INTERFACE_INCLUDE_DIRECTORIES "${FFRT_PACKAGE_DIR}/include"
    )
endif()

同时把 libffrt_cpp.so、libc++_shared.so 拷进 entry/libs/arm64-v8a/,否则链接通过、运行期 .so 不在 HAP 里。

教训::: 形式的 target 只可能来自 find_package 或 imported target。HAR 里没有 CMakeLists

坑 3:Filename longer than 260 characters——一个跟布局毫无关系的拦路虎。

这个错误是最气人的。CMake 配置全部通过,ninja 一跑就退:

ninja: error: Stat(C:/Users/PC/WorkBuddy/2026-11-13-16-39-00/react-native-split-layout/
example/harmony/oh_modules/@rnoh/react-native-openharmony/src/main/cpp/patches/
react_native_core/react/renderer/textlayoutmanager/platform/harmony/react/renderer/
textlayoutmanager/TextLayoutManager.cpp): Filename longer than 260 characters

排查过程:先怀疑是 oh_modules 里的符号链接,后来才意识到是绝对路径总长超过 Windows 的 260 字符限制。CMake 其实早就警告过,只是警告埋在几千行日志里:

The object file directory
  C:/Users/PC/WorkBuddy/.../entry/.cxx/default/default/debug/arm64-v8a/rn/...
has 242 characters.  The maximum full path to an object file is 250 characters
(see CMAKE_OBJECT_PATH_MAX). Object file LegacyViewManagerInteropViewProps.cpp.o
cannot be safely placed under this directory. The build may not work correctly.

242 + 38(文件名)= 280,超了。

修复:把工程搬到一个短路径上再构建。这里我先走了错路,值得写出来——

第一反应是建 junction(软链接),不用管理员权限,一句就行:

New-Item -ItemType Junction -Path C:\ex -Target "C:\Users\PC\...\react-native-split-layout\example"
cd C:\ex\harmony
hvigorw assembleHap --no-daemon

没用。 因为 hvigor 在算 CMake 参数时会先做一次 realpath 解析,C:\ex\harmony\entry 被还原成 C:\Users\PC\WorkBuddy\...\example\harmony\entry 再传给 CMake,.cxx 目录和 -I 路径全都是长路径,260 照样爆。

真正生效的做法是物理复制:

robocopy "C:\Users\PC\...\example" "C:\rsl\example" /E /XD build .cxx .hvigor
cd C:\rsl\example\harmony
hvigorw --mode module -p product=default -p buildMode=debug assembleHap --no-daemon

工程根从 82 字符降到 14 字符,CMAKE_OBJECT_PATH_MAX 那条警告消失,TextLayoutManager.cpp 等几个最深编译单元全部进了安全区。

代价是这份副本要重新装依赖(node_modules 和 oh_modules 加起来 1.2 GB),所以我把它当"构建沙盒"用:源码改在真实仓库里,验证时才同步过去。

教训:RNOH 的 C++ 目录层级本来就深(oh_modules/@rnoh/.../third-party/rn/ReactCommon/...),工程根目录一旦放在用户目录深处,260 一定超。这不是"可能有问题",是"一定有问题"。

坑 4:打 HAR 时 Fatal process out of memory。

hvigor assembleHar 跑到一半直接崩,报 Node 的 OOM。修复是给 Node 加堆:

export NODE_OPTIONS="--max-old-space-size=6144"

教训:HAR 打包会把整个 ArkTS 工程 + codegen 产物做一次全量分析,默认 4G 堆不够。

坑 5:Metro 端口 8081 被占,构建却继续跑。

日志第一行就是:

[metro] [Fail]TCP Port listen failed at 8081

但构建没停,后面照样 CompileArkTS 成功。原因是 debug 构建里 Metro 只用于 bundle 任务,而 example 已经把 JS 预打包成 entry/src/main/resources/rawfile/hermes_bundle.hbc,运行期根本不连 Metro。

顺带一个真实的坑:react-native bundle-harmony 找不到 hermesc,报 Cannot find hermesc。修复是显式指定:

react-native bundle-harmony --dev false --entry-file index.js \
  --bundle-output entry/src/main/resources/rawfile/hermes_bundle.hbc \
  --js-engine hermes --hermesc-dir ./node_modules/hermes-compiler/hermesc

教训:真机验证不要依赖 Metro。把 hbc 打进 rawfile,安装即跑,省掉"服务没起/端口不对/局域网不通"三类问题。

坑 6:ohpm install 卡在 @ppd/ffrt 下载。

ohpm install --all 反复超时,日志停在拉取 @ppd/ffrt。换 --ft 参数、换网络都没稳过。

修复:直接下 HAR 手动展平到 oh_modules/@ppd/ffrt/,并按 oh-package-lock.json5 补三条记录。@ppd/ffrt 的 HAR 是 package/ 套一层的结构,必须把 package/* 提上来,否则 oh_modules/@ppd/ffrt/package/src/... 这种路径会让 CMake 的 add_subdirectory 找不到东西。

教训:ohpm 的网络问题不要硬刚,HAR 是可以手动装配的;但装配完必须让目录结构跟 ohpm 装出来的一模一样。

坑 7:createDescriptorWrapperFactoryByDescriptorType 的签名写错。

ArkTS 编译报签名不匹配。修复是照抄 RNOH 的类型:

import type { DescriptorWrapperFactoryByDescriptorTypeCtx }
  from '@rnoh/react-native-openharmony/ts';

override createDescriptorWrapperFactoryByDescriptorType(
  ctx: DescriptorWrapperFactoryByDescriptorTypeCtx
) { /* ... */ }

教训:RNOH 的 Package 接口签名在 0.84 上跟 0.72 时代不一样了,别照老文章抄。

坑 8:Property 'windowStatusType' does not exist on type 'WindowProperties'。

我想直接读窗口状态类型,结果当前 SDK 的 WindowProperties 上没有这个字段。

修复:用窗口矩形与屏幕宽度的比值推断:

// SplitLayoutWindowTurboModule.ets - inferWindowMode()
const ratio = windowRect.width / display.width;
if (ratio >= 0.97) return 'maximized';
if (ratio >= 0.33 && ratio <= 0.67) return 'split-screen';
return 'floating';

教训:鸿蒙的窗口 API 在不同 API 级别上字段名会变。能算出来的,就不要硬读;算不出来的,一定要 try/catch 兜到 unknown。

坑 9(本库最隐蔽的一个):C-API 架构下,ArkTS 容器组件拿不到子节点的 descriptor。

现象:真机上组件不崩溃,但子树一片空白。真机日志给出了完整证据链——

[RNOH_ARK] child mutation INSERT_CHILD index=0 tag=346
[RNOH_ARK] childTagAt rev=4 tags=[346,530,636,638] first=-1   # wrapper 查不到

tag 明明 CREATE 过、INSERT 过,findDescriptorWrapperByTag(346) 却返回 undefined。我最初的实现是仿照 RNDrawerLayoutAndroid,在 build() 里用 ctx.wrappedRNComponentBuilder.builder(ctx, tag) 渲染子节点,结果第一版直接崩了 Cannot read property type_ of undefined(buildRNComponentForTag 对查不到的 wrapper 做了 ! 非空断言);加了防御性判空后,变成"不崩了但永远渲染不出来"。

翻开 RNOH 源码才看到答案。C-API 模式默认开启 PARTIAL_SYNC_OF_DESCRIPTOR_REGISTRY(MountingManagerCAPI.cpp 的 getArkTSMutations):

case ShadowViewMutation::Create:
  isArkTSMutation = !isCAPIComponent(mutation.newChildShadowView);  // View 是 CAPI 组件
  break;
case ShadowViewMutation::Insert:
  isArkTSMutation = !isCAPIComponentByTag(mutation.parentTag) || ...; // 父是 ArkTS 组件 → 转发
  break;

普通 View 子节点的 CREATE/UPDATE 根本不会同步进 ArkTS 侧的 DescriptorRegistry,但 INSERT 会(因为父节点是 ArkTS 组件)。所以 ArkTS 侧"知道有哪些孩子、却不知道孩子长什么样"——childrenTags 有值、wrapper 为空,是架构设计而非 bug。RNOH 自己的容器组件(RNDrawerLayoutChildWrapperView)和 RNSurface 都是用同一种方式承载子树的:

// harmony/rn_split_layout/src/main/ets/RNCSplitLayout.ets - build()
Stack({ alignContent: Alignment.TopStart }) {
  // 所有 RN 子节点由 C++ 侧定位/动画(Yoga 是唯一布局真相),ArkTS 只负责"挂载点"
  ContentSlot(this.ctx.getContentForTag(this.tag))
  this.buildDividers()
  this.buildEdgeHotspot()
}

修复后整个组件反而变简单了:连 childrenTags 都不用读,三个窗格的定位、zIndex、translateX 动画全部由 JS → Yoga → C++ 一条链完成,ArkTS 只画分隔线和边缘热区。

教训:写 ArkTS 自定义组件前,先确认目标架构(C-API vs 非 C-API)。C-API 下"渲染 RN 子树"只有 ContentSlot 一条正路;任何用 wrappedRNComponentBuilder 直接渲染子 tag 的写法,要么崩在 undefined.type_,要么永远空白。

7. 现在怎么用

装依赖:

npm i react-native-split-layout

鸿蒙侧不需要手动 link。package.json 里的 harmony.autolinking 会让 hvigor 插件在构建时自动做三件事:把 harmony/split_layout.har 写进 oh-package.json5、在 RNOHPackagesFactory.ets 里生成 new SplitLayoutPackage(ctx)、在 autolinking.cmake 里生成 add_subdirectory(.../src/main/cpp ./rnoh_split_layout)。iOS/Android 上它会自动退化成 onLayout + PanResponder,不需要任何原生配置。


总结:

本文围绕基于 RNOH(React Native HarmonyOS)0.84.1、C-API 架构开发的 react-native-split-layout 分屏布局库展开,完整落地了鸿蒙 PC/2in1 设备自由窗口场景下的自适应多窗格方案,解决了传统固定布局、简单媒体查询无法适配窗口拖拽、分屏、折叠态变化的痛点。和移动端屏幕尺寸固定的逻辑不同,鸿蒙自由窗口的画布宽度是动态可变的连续值,布局不能简单依靠 flexDirection 切换,核心思路是先由当前可用宽度判定窗格档位,再基于剩余可用宽度执行逐级降级,以此保证内容区始终保有舒适的最小展示宽度,避免内容被挤压截断、交互失效。

整套方案确立三条核心设计原则:Yoga 作为唯一布局真相,ArkTS 侧不再参与窗格位置排布,仅承担组件区域测量、边缘侧滑手势、分隔线绘制三类轻量能力,规避两套布局引擎带来的1px错位、遮罩与滚动区域不匹配等问题;窗格数量由窗口宽度决定,窗格形态由扣除侧边栏后的剩余宽度决定,形成一套可复用的降级链路,侧边栏按展开态→图标轨道栏→覆盖抽屉逐级降级,详情栏在空间充足时常驻并排,空间不足则降级为浮层抽屉;窗口模式、折叠状态、安全区信息作为一等输入,由 TurboModule 持续上报给 JS 层,业务可以根据分屏、悬浮、最大化、半折折叠态差异化调整内容密度,适配鸿蒙2in1设备独有的硬件形态。

在实现上,方案把布局决策抽象为纯函数 resolveSplitLayout,脱离 React 运行时即可单测验证,清晰定义断点、最小内容宽度、迟滞阈值等参数。为了解决窗口拖动穿越阈值时布局频繁闪烁的问题,引入单边迟滞机制,升级和降级使用不同阈值,生成稳定死区,同时迟滞只作用于断点切换,不干扰宽度不足时的自动降级逻辑。宽度来源设置优先级,优先使用 ArkTS onAreaChange 拿到的组件真实区域尺寸,其次是窗口级指标,兜底 RN 原生 useWindowDimensions,解决组件嵌套容器内窗口尺寸不准、首帧渲染闪烁的问题。

原生与 JS 的通信分为两条通道:TurboModule 负责窗口指标的拉取与事件推送,Fabric 自定义组件负责上报组件区域尺寸和边缘手势事件,同时做上报去重,避免高频测量事件反复触发渲染、打断动画。抽屉实现采用浮层方案,抽屉不占用布局流宽度,依靠 translateX 位移动画弹出,搭配遮罩、返回键拦截、读屏无障碍适配,和占位式侧边栏区分开;侧边边缘热区使用特殊的 HitTestMode.Transparent,兼顾手势接收和底层列表滚动交互,同时保留 JS 侧 PanResponder 兜底,实现跨端兼容。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐