react-native-pip-window 为 React Native 鸿蒙应用提供应用内子窗(SubWindow)和系统画中画(PiPWindow),无需声明全局悬浮窗权限。我用 rn-pip-market-watch 在两种窗口里显示模拟报价、走势和止盈提醒,并在真机与 API 26 模拟器上核对宿主来源、窗口尺寸和按钮回调。
配套实战项目已开源在 abaoge/rn-pip-market-watch,第三方库完整代码已开源在 oh-react-native/react-native-pip-window,有问题可到第三方库仓库提 Issue,也可以来 鸿蒙系统 React Native 开源社区 交流。

前言

🌈 我在做一个鸿蒙 React Native 盯盘页面,想把寒武纪-U 等自选股的报价、分时走势和止盈提醒放进一张小卡片。绝对定位视图受当前页面布局限制。我想让卡片跨页面悬浮,还要支持系统画中画,于是去查鸿蒙窗口接口,看看怎样找到宿主、显示卡片,并把拖拽和点击传回 JS。

我把窗口管理封装进 react-native-pip-window,库内用按钮和文本验证接口。独立工程 rn-pip-market-watch 通过外部依赖接入它,把模拟行情填进通用面板。接好后,我在华为畅享 100 Pro Max 真机和 API 26 模拟器上打开两种小窗,检查了子窗吸附与缩放、行情更新和按钮回传。

一、使用场景与真实痛点

1.1 盯盘页面的三个窗口需求

📱 实战应用 rn-pip-market-watch 内置了寒武纪-U(688256.SH)等自选股的模拟行情,价格与分时点位随定时器跳动,涨跌幅越过 +3.00% 止盈阈值时会亮起橙色告警条。用户边看主列表边盯单只标的时,需要这张小卡片真正脱离主页面布局,按需在应用内伴随悬浮和系统级画中画之间切换。

我把页面的窗口需求拆成三个操作。

  1. 打开子窗后,卡片在右上角显示报价和折线图。主页面仍能切换自选股、点击“模拟拉升”,原有输入焦点也要保留。
  2. 拖动顶部手柄或切换标准、精简尺寸时,插件要更新系统子窗的实际位置和大小。屏幕边缘留出安全距离,方便用户随时点到顶部的关闭按钮。
  3. 切到系统画中画后,小窗用自定义图层显示报价、涨跌角标、柱状图和告警条。上一项、暂停和下一项等控件动作回到 RN 页面,由页面切换标的或暂停刷新。

图 1 从打开子窗画起,接着是移动、调整尺寸、关闭,再启动系统画中画。图下方对应实战工程、浮窗库和鸿蒙窗口的分工。

盯盘页面开启子窗、调整位置并切换系统画中画

图1 小窗操作流程

这两种原生窗口的托管层级并不相同:SubWindow 挂在当前应用的窗口舞台下,适合在应用内部跨页面悬浮展示,自由摆放和自定义按钮都更灵活;PiPWindow 由系统画中画管理器统一托管,拥有系统级小窗层级与标准控制栏。无论处于哪种窗口,卡片上的行情数字会不会继续跳动,都取决于宿主 JS 定时器或数据流是否还在持续推送新状态。

1.2 所用三方库与实战工程分工

📦 本实战工程接入的官方社区双模浮窗库是 oh-react-native/react-native-pip-window(版本 0.1.0,鸿蒙侧 HAR 模块名为 @rnoh/react-native-pip-window)。为了让其他项目能直接拿去复用,这个库没有掺杂任何股票代码、涨跌幅计算或行情界面,只提供领域中立的窗口控制方法与 FloatingPanelPayload 通用面板数据结构。

面板支持标题、副标题、主副文本、角标、色板(涨跌红绿或中性蓝灰)、趋势数值、横幅和最多 4 个自定义按钮。rn-pip-market-watch 通过标准依赖引入该库,把模拟行情映射到这些字段。如果要做接单提醒、体育比分或会议倒计时,可以按业务调整映射内容和按钮标识。表 1 列出了各层的职责。

表1 三层模块分工

所属层级对应模块负责内容
鸿蒙系统窗口层@kit.ArkUI(WindowStage、PiPWindow、BuilderNode)提供应用内子窗容器、系统画中画控制器,以及独立于 RN 主视图之外的原生节点渲染能力
通用双模浮窗库react-native-pip-window(HAR 模块 @rnoh/react-native-pip-window)注册 RNPipWindow TurboModule;完成宿主三级查找、屏幕边界钳制与 vp/px 换算;用 FloatingPanelStore 同步驱动子窗页面与画中画自定义节点,并转发窗口与按钮事件
独立实战项目rn-pip-market-watch 盯盘迷你窗作为外部应用引入通用库;维护模拟行情定时器,将报价与 +3.00% 止盈告警映射为通用面板载荷,用串行队列管理双模切换与窗口事件展示

二、双端运行效果与窗口读数

我把实战工程 rn-pip-market-watch 分别安装到华为畅享 100 Pro Max 真机与 HarmonyOS API 26 官方模拟器上,按相同顺序核对了能力探测、应用内子窗拖拽缩放以及系统画中画切换。

2.1 测试环境与数据说明

表2 运行环境基线

项目实际配置
编译与调试工具DevEco Studio 26.0.0,HarmonyOS Emulator 26.0.0.402
React Native 基线React Native 0.84.1 / RNOH 0.84.6
所用通用三方库react-native-pip-window 0.1.0(@rnoh/react-native-pip-window)
配套实战应用rn-pip-market-watch 0.1.0
目标系统 SDKHarmonyOS API 26(26.0.0)
实测真机华为畅享 100 Pro Max(YEW-AL80),OpenHarmony 7.0.0.105 / API 26,1128×2444
实测模拟器Mate 90 Pro 模板,HarmonyOS 7.0.0.107(SP8) / API 26,1280×2832

页面展示的股票价格由实战工程本地定时生成,卡片上方的 #13、#18、#21 是面板推送序号,用来直观确认小窗是否在持续接收新帧。真机与模拟器在不同时刻截图,报价数字本身会有差别;我重点核对的是窗口舞台捕获来源、按屏幕像素密度换算后的真实窗口尺寸,以及原生回调事件是否完整回到 RN 页面。

2.2 真机运行表现

📱 我在真机上打开实战应用“A股盯盘宝”,主屏展示三大指数快照、寒武纪-U 实时分时均价走势与五档买卖盘口,以及“开启页内小窗盯盘 / 桌面画中画盯盘”双模入口与底部自选股列表(图 2)。点击右上角“回执”抽屉核对环境探针,库从 abilityContext.windowStage 取得窗口舞台,isPiPEnabled() 返回 true,说明设备已启用画中画功能。

华为畅享 100 Pro Max 真机 A 股看盘首页与双模盯盘操作区

图2 真机看盘首页

我点按“拉升 +1.4%”让寒武纪-U 的涨幅越过 +3.00% 止盈线,并开启页内盯盘子窗(图 3)。真机的 densityPixels 是 3.0,标准尺寸 232×176 vp 换算为 696×528 px,默认初始位置落在 left=384px、top=264px,支持手势拖拽或四角快捷吸附。

截图里的 #13 帧报价升至 423.41(+3.98%),悬浮小窗实时同步主屏报价与分时折线,亮起金黄色边框和“⚡ 触发止盈线 >= +3.00%”告警条,底部的“‹ 上一只”“暂停”“下一只 ›”完整可见。页面回执流同时收到 SUBWINDOW rectChanged(3)。

华为畅享 100 Pro Max 真机 SubWindow 应用内悬浮盯盘子窗与止盈告警

图3 真机悬浮子窗

接着我关闭子窗,再点击启动系统画中画,屏幕右上方弹出系统级 PiP 小窗(图 4)。自定义节点渲染层在无视频流的情况下绘出了第 #18 帧报价 424.82(+4.33%)、红色柱状缩略图与止盈提示条,页面事件流依次追加了 PIP-START code=0 和 PIP SIZE_CHANGED(2)。真机上从看盘首页开启悬浮盯盘子窗、模拟拉升越过止盈线到浏览自选股列表的连续实录见图 5。

华为畅享 100 Pro Max 真机系统级 PiPWindow 画中画与实时止盈告警覆盖层

图4 真机画中画

真机连续开启页内悬浮盯盘子窗、拉升触发止盈预警与浏览自选股实录

图5 真机悬浮盯盘实录

2.3 模拟器验证与切换演示

💻 换到 API 26 官方 Mate 90 Pro 模拟器后,首页探测结果同样命中 abilityContext.windowStage,系统画中画开关显示就绪(图 6)。

API 26 官方模拟器首页与环境就绪状态

图6 模拟器探测

拉升行情并打开应用内子窗后(图 7),卡片展示第 #11 帧报价 420.70(+3.32%)、分时曲线与止盈提示。由于模拟器屏幕物理宽度为 1280 px、屏幕密度 densityPixels 为 3.5,同一套 232×176 vp 标准尺寸被自动换算成 812×616 px,初始位置落在 left=412px、top=308px,事件流记录了 SUBWINDOW shown(1) 与 SUBWINDOW rectChanged(3)。

API 26 官方模拟器 SubWindow 应用内悬浮子窗效果

图7 模拟器子窗

关闭子窗再切换到系统画中画(图 8),右上角小窗同步展示第 #21 帧报价 421.67(+3.55%)与柱状走势,事件列表写入 PIP SIZE_CHANGED(2) pipWindowSizeChange。

API 26 官方模拟器系统级 PiPWindow 画中画效果与状态日志

图8 模拟器画中画

图 9 是在模拟器上连续录制的 10 秒实操动图(40 帧,4 fps),完整串起了前台常用动作:先打开标准尺寸(812×616 px)子窗,点击“左上吸附”让窗口跳到 left=36px、top=140px,再点紧凑切换缩成精简尺寸(196 vp 宽,即 686×462 px)并恢复标准态;随后关闭子窗记下 SUB-CLOSE code=0,紧接着启动系统画中画记下 PIP-START code=0。这段演示聚焦应用在前台时的手动启停与模式互切,未涉及退回桌面后的后台自动拉起。

API 26 模拟器子窗吸附缩放、关闭与启动画中画演示

图9 双模切换演示

表 3 汇总了两台设备的读数。两边都从同一条路径取到宿主,也都打开了子窗和画中画。窗口像素尺寸随屏幕密度变化,各段操作收到的事件见表。

表3 双端读数对照

核对项华为畅享 100 Pro Max 真机API 26 官方模拟器
系统版本与分辨率OpenHarmony 7.0.0.105,1128×2444(密度 3.0)HarmonyOS 7.0.0.107,1280×2832(密度 3.5)
窗口舞台获取来源abilityContext.windowStageabilityContext.windowStage
子窗标准态像素矩形left=384px, top=264px,696×528 pxleft=412px, top=308px,812×616 px
画中画自定义图层#18 帧(424.82 +4.33%)柱状图与告警条#21 帧(421.67 +3.55%)柱状图与告警条
关键窗口事件回执rectChanged(3) / PIP-START / SIZE_CHANGED(2)shown(1) / SUB-CLOSE / PIP-START / SIZE_CHANGED(2)
全局悬浮窗权限未声明 SYSTEM_FLOAT_WINDOW未声明 SYSTEM_FLOAT_WINDOW

三、原理与核心代码分析

3.1 双模状态共享与宿主三级查找

两种窗口共用一个 FloatingPanelStore 实例。RN 打开窗口或推送行情时,JS 包装层把对象序列化为 JSON 字符串,再传给 RNPipWindow TurboModule。对象按字符串传递,Codegen 无需生成对应的嵌套结构。原生模块合并新字段后,通过 AppStorage 刷新子窗页面,并调用节点控制器更新画中画图层。子窗按钮、手势位移和画中画控件动作经由 DeviceEventEmitter 回到 RN(图 10)。

RN 实战页面、通用面板存储与两种原生窗口的架构关系

图10 三层桥接架构

创建子窗前,库需要取得应用的 WindowStage 或主窗口句柄。不同 RNOH 宿主提供窗口的方式有差别,我在 RNPipWindowTurboModule.ts 里用 resolveWindowHost() 依次查找 uiAbilityContext.windowStage、全局存储和最近激活的窗口。查询最后一级时会排除已打开的同名子窗,避免把它当作主窗。

private async resolveWindowHost(): Promise<ResolvedWindowHost> {
  const abilityCtx = this.ctx.uiAbilityContext as common.UIAbilityContext | undefined;

  // 路径 1:优先读取 UIAbilityContext 自带的 windowStage
  if (abilityCtx?.windowStage) {
    const directStage = abilityCtx.windowStage;
    FloatingPanelStore.saveWindowStageToStorage(directStage);
    this.windowStageSource = 'abilityContext.windowStage';
    return {
      windowStage: directStage,
      mainWindow: this.resolveMainWindowFromStage(directStage),
      source: this.windowStageSource,
    };
  }

  // 路径 2:回退读取宿主 EntryAbility 存入 AppStorage 的舞台实例
  const storedStage = FloatingPanelStore.getWindowStageFromStorage();
  if (storedStage) {
    this.windowStageSource = 'appStorage.windowStage';
    return {
      windowStage: storedStage,
      mainWindow: this.resolveMainWindowFromStage(storedStage),
      source: this.windowStageSource,
    };
  }

  // 路径 3:未暴露舞台时通过 window.getLastWindow 定位主窗口,并排除悬浮子窗自身
  if (abilityCtx) {
    try {
      if (this.cachedMainWindow) {
        this.windowStageSource = 'cachedMainWindow';
        return { windowStage: undefined, mainWindow: this.cachedMainWindow, source: this.windowStageSource };
      }
      const lastWin = await window.getLastWindow(abilityCtx);
      if (lastWin.getWindowProperties().name !== this.subWindowName) {
        this.cachedMainWindow = lastWin;
        this.windowStageSource = 'window.getLastWindow';
        return { windowStage: undefined, mainWindow: lastWin, source: this.windowStageSource };
      }
    } catch {
      // 三条路径均未取到宿主时返回空结果,交由调用方返回明确错误码
    }
  }

  this.windowStageSource = 'unavailable';
  return { windowStage: undefined, mainWindow: undefined, source: 'unavailable' };
}

这段方法里调用的 resolveMainWindowFromStage() 定义在同一个类上方,负责同步取出并缓存主窗口实例,供后续获取 UIContext 创建画中画节点时复用。方法返回的 source 字符串也会透传给 getCapabilities(),在调试页面一眼就能看出当前命中的是哪一级宿主。

3.2 命名路由子窗与画中画自定义面板

拿到窗口宿主后,子窗与系统画中画沿着各自的系统接口完成创建、装载、刷新和销毁,完整调用时序见图 11。

子窗和画中画的能力检查、开启、更新与关闭流程

图11 双模调用流程

先看应用内 SubWindow 这一侧。模块通过舞台创建出子窗实例并算出不越界的初始像素矩形后,交由同文件的 configureAndShowSubWindow() 完成界面挂载与窗口属性设置:

private async configureAndShowSubWindow(
  createdWin: window.Window,
  rect: SubWindowRectSnapshot,
  focusable: boolean,
  keepScreenOn: boolean,
  cornerRadiusVp: number
): Promise<void> {
  // 先固定子窗像素尺寸与初始位置,再通过命名路由挂载 HAR 包内的卡片页面
  await createdWin.resize(rect.width, rect.height);
  await createdWin.moveWindowTo(rect.left, rect.top);
  await createdWin.loadContentByName(ROUTE_FLOATING_SUBWINDOW_PAGE);
  // 将窗口底板设为全透明,避免圆角卡片四角露出系统默认浅色背景
  await createdWin.setWindowBackgroundColor('#00000000');
  await createdWin.setWindowFocusable(focusable);
  await createdWin.setWindowKeepScreenOn(keepScreenOn);

  if (deviceInfo.sdkApiVersion >= 17) {
    try {
      await createdWin.setWindowCornerRadius(cornerRadiusVp);
    } catch {
      // 部分窗口容器不支持硬件圆角时由页面内层圆角兜底
    }
  }

  // API 20+ 显示子窗时不抢夺主页面焦点,保证背后 RN 页面可正常点击输入
  if (deviceInfo.sdkApiVersion >= 20) {
    await createdWin.showWindow({ focusOnShow: false });
  } else {
    await createdWin.showWindow();
  }
}

这里有两个直接决定观感和交互的小细节:一是子窗默认带有系统浅色背景板,必须在 loadContentByName 加载完命名路由页面后立刻把窗口背景刷成 #00000000 全透明,卡片四角的圆角才不会露出白边;二是同时设置窗口不可获焦与 { focusOnShow: false },既允许子窗内部响应手指点击和拖动,又不会在弹出瞬间把主页面的输入焦点抢走。子窗页面内部的 Canvas 分时折线在绘制前还会检查点位极差:若最高价与最低价相等(开盘横盘),自动按画布高度的一半居中画水平线,避免除零算出无效坐标。

再看系统级 PiPWindow 这一侧。鸿蒙画中画控制器原本面向视频流播放设计,创建配置要求传入表面渲染控制器。在盯盘这类纯数据面板场景里,我们在 PipCustomUIController.ets 中先创建一个表面类型的空 XComponent 满足底层入参要求,真正的行情卡片则通过继承 NodeController 的控制器挂载到画中画自定义图层上:

export class PipPanelCustomUIController extends NodeController {
  private builderNode: BuilderNode<[PipPanelCardParams]> | null = null;
  private currentParams: PipPanelCardParams;

  constructor(initialState: FloatingPanelState) {
    super();
    this.currentParams = PipPanelCardParams.fromState(initialState);
  }

  makeNode(uiContext: UIContext): FrameNode | null {
    // 首次挂载时构建自定义面板节点树,非视频流场景无需推流即可渲染卡片
    if (!this.builderNode) {
      this.builderNode = new BuilderNode<[PipPanelCardParams]>(uiContext);
      this.builderNode.build(wrapBuilder<[PipPanelCardParams]>(buildPipPanelOverlay), this.currentParams);
    }
    return this.builderNode.getFrameNode();
  }

  updatePanelState(state: FloatingPanelState): void {
    // 后续状态刷新直接原地更新节点参数,避免反复重建 FrameNode
    this.currentParams = PipPanelCardParams.fromState(state);
    if (this.builderNode) {
      this.builderNode.update(this.currentParams);
    }
  }

  dispose(): void {
    if (this.builderNode) {
      try {
        this.builderNode.dispose();
      } catch {
        // 节点已由系统回收时忽略重复释放异常
      }
      this.builderNode = null;
    }
  }
}

同文件上方的 buildPipPanelOverlay 构建函数负责排版小窗里的标题、主价格、涨跌角标、10 根归一化高度的柱状缩略图和底部告警条(柱状图遍历键值拼接了当前主色调,涨跌红绿翻转时能立刻触发柱体换色)。系统拉起画中画时调用一次 makeNode() 拿到 FrameNode,此后每次行情跳动只需调用 updatePanelState() 原地更新参数即可。

3.3 手势拖拽防跳变与位置保持

拖动子窗时,窗口和组件原点都会跟着手指移动。若每帧按组件自己的 offsetX / offsetY 计算位移,下一帧就会拿新的原点作比较,偏移可能互相抵消,让小窗来回抖动。

解决办法是在 FloatingSubWindowPage.ets 按下第一帧时优先锁定手指相对于整块物理屏幕的全局坐标 displayX / displayY,并在后续移动帧严格保持同一套屏幕坐标系,换算成物理像素后过滤掉不足 1 像素的微抖动:

private handleDragUpdate(event: GestureEvent): void {
  const now = Date.now();
  // 16ms 节流避免高频窗口位移 IPC 积压
  if (now - this.lastDragEmitTime < 16) {
    return;
  }

  let curX = event.offsetX;
  let curY = event.offsetY;
  if (this.usingDisplayCoords) {
    const firstFinger = event.fingerList && event.fingerList.length > 0 ? event.fingerList[0] : undefined;
    if (
      !firstFinger ||
      typeof firstFinger.displayX !== 'number' ||
      typeof firstFinger.displayY !== 'number'
    ) {
      // 起始帧已锁定屏幕坐标系,单帧缺失屏幕坐标时跳过,防止与局部 offsetX 混算引起窗口跳变
      return;
    }
    curX = firstFinger.displayX;
    curY = firstFinger.displayY;
  }

  const dxVp = curX - this.lastDragX;
  const dyVp = curY - this.lastDragY;
  this.lastDragX = curX;
  this.lastDragY = curY;

  const uiCtx = this.getUIContext();
  const dxPx = Math.round(uiCtx.vp2px(dxVp));
  const dyPx = Math.round(uiCtx.vp2px(dyVp));
  // 过滤不足 1 像素的微幅抖动,减少无效跨层位移调用
  if (Math.abs(dxPx) < 1 && Math.abs(dyPx) < 1) {
    return;
  }
  this.lastDragEmitTime = now;
  FloatingPanelStore.dispatchAction({
    source: 'subwindow',
    action: 'drag_delta',
    deltaX: dxPx,
    deltaY: dyPx,
    panelId: this.panelState.panelId,
    timestamp: now,
  });
}

位移增量传到 TurboModule 后,如果每一帧都等上一次 moveWindowTo() 走完再去反查窗口矩形,系统窗口服务还没刷新完就会读回旧坐标,拖起来依然发粘。因此模块层在内存里维护了预期位置 pendingSubWindowLeft 与 pendingSubWindowTop,把连续到达的像素增量串行合并并经过安全边距钳制(左右预留 8 vp、顶部避开状态栏预留 36 vp)后再下发移动指令。此外,当子窗已经处于打开状态、用户只是切换精简或标准尺寸而再次调用 openSubWindow(未显式传新的横纵坐标)时,模块会直接沿用当前拖好的窗口位置调整宽高,不会把用户刚摆好的小窗弹回右上角默认起点。

四、踩坑与边界条件

4.1 免全局悬浮窗权限与能力预检

我核对了通用库 HAR 模块与实战工程宿主的 module.json5 清单,两边都没有声明受限权限 ohos.permission.SYSTEM_FLOAT_WINDOW,宿主仅保留加载 RN 包所需的常规网络权限。这是因为应用内子窗只在当前应用的窗口舞台内部活动,而跨出应用桌面的小窗完全交由系统受控的 PiPWindow 承载,两条路都不走任意全局悬浮窗通道,包内单测也会自动扫描配置文件防止误加受限权限。

⚠️ 免权限并不代表任何设备状态都能直接弹窗。业务调用前仍应先调 getCapabilities() 和 isPiPSupported() 做前置检查:当设备缺少窗口会话能力或用户在系统设置里关掉了画中画开关时,预检会返回诊断提示码 801;到了真正执行打开子窗或启动画中画时,还要检查返回 JSON 里的 ok 字段与原生错误码。另外,本文全部构建与实测均基于 API 26 完成,源码里针对 API 12 控件事件、API 17 窗口圆角、API 20 非抢焦展示和 API 22 贴边吸附所写的版本分支,只是按各接口起始版本做的保护判断,不等同于已在低版本系统上逐个做过实机回归。

4.2 命名路由丢失与模板控制组配对

第一次把悬浮子窗页面打进独立 HAR 包联调时,调用 loadContentByName('RNPipFloatingSubWindow') 直接报了 1300002 页面加载失败。排查编译产物才发现,子窗页面虽然标记了命名路由入口,但因为没有任何已编译代码用静态导入引用过这个文件,构建工具直接把它当成无用模块裁掉了。我在 RNPipWindowPackage.ets 入口顶部补上静态导入 ./FloatingSubWindowPage,并在包初始化阶段调用 registerPipRuntimeSupport() 提前绑好全局存储适配器,子窗路由才稳定加载成功。

系统画中画那边踩到的则是模板与控制组的配对限制。鸿蒙画中画的视频播放模板 VIDEO_PLAY 只接受上下曲或快进快退控制组,直播模板 VIDEO_LIVE 只接受播放暂停或静音控制组,两边混传会在创建控制器时直接报错。通用库在解析 controlGroups 参数时,除了限制最多传入 3 个控制组外,遇到业务层传空数组或省略该字段时会自动按所选模板回退到默认的上下切换或播放暂停控制组。还有一种常见情况是用户还没开启画中画,就先在主页面点了“暂停盯盘”更新播放态:此时模块会先把最新的播放布尔值存进 FloatingPanelStore,再返回 1300012 告知当前尚无活跃控制器,等用户稍后点开画中画时就能直接按最新暂停态初始化。

4.3 热重载回调保护与退出销毁顺序

热重载时,如果新 TurboModule 已经绑定动作回调,旧实例随后执行 __onDestroy__() 并清空全局回调,就会把新监听也删掉,子窗按钮随之失效。我让每个实例保存自己的 boundActionHandler,销毁时只解绑同一引用。画中画的 BuilderNode 则要等异步 stopPiP() 结束再释放,避免系统退场时访问已销毁的节点。

public override __onDestroy__(): void {
  this.destroyed = true;
  // 仅解绑当前实例注册的回调,避免 RN 热重载时误删新实例刚绑定的处理器
  FloatingPanelStore.unregisterActionHandler(this.boundActionHandler);
  void this.safeDestroySubWindowInstance(this.subWindow);
  const activeController = this.pipController;
  this.pipActive = false;
  if (activeController) {
    // 等待系统画中画完成退场后再释放底层渲染节点,防止提前销毁引发渲染异常
    activeController
      .stopPiP()
      .catch(() => {})
      .finally(() => {
        this.cleanupPiPResources();
      });
  } else {
    this.cleanupPiPResources();
  }
}

💡 需要注意,RNOH 的 __onDestroy__() 本身是同步生命周期钩子,外层宿主不会停下来等待里面的异步关窗 Promise 跑完。因此业务页面在正常卸载退出前,应当先清理自己的行情刷新定时器,再显式调用关闭方法把子窗和画中画收干净,把模块销毁钩子留作异常退出的最后一道保险。

五、结论与可直接复用的建议

接入 react-native-pip-window 后,库负责查找宿主、加载子窗路由、用 BuilderNode 绘制画中画卡片,并处理拖拽跳变。业务页面把数据映射成面板字段,再按需要开启相应的小窗。

5.1 安装依赖与宿主工程连接

通用三方库源码托管在官方社区仓库 oh-react-native/react-native-pip-window(版本 0.1.0),配套盯盘实战工程公开在 abaoge/rn-pip-market-watch(版本 0.1.0)。在自有 RN 鸿蒙项目根目录执行以下命令即可安装官方三方库:

npm install --legacy-peer-deps 'git+https://atomgit.com/oh-react-native/react-native-pip-window.git'

安装依赖后,对照官方库 README 与实战工程完成三处鸿蒙宿主连接即可:

  1. 在宿主 harmony/entry/oh-package.json5 中添加本地依赖 @rnoh/react-native-pip-window 指向包内 harmony/pip_window 目录,保持与宿主 RNOH 0.84.6 版本一致。
  2. 在 ArkTS 包工厂中注册 new RNPipWindowPackage(ctx),并在 C++ CMakeLists.txt 与 PackageProvider.cpp 中挂载子目录 rnoh_pip_window(若宿主已开启自动链接,先核对生成文件避免重复注册)。
  3. 打包时启用 @react-native-oh/react-native-harmony 的 Metro 配置,使包内的 index.harmony.js 入口生效。

5.2 业务字段映射与双模串行切换

业务代码建议拆成两小层:先写一个纯函数(可参考实战工程 src/marketPayloadMapper.ts),把标的报价、涨跌幅和阈值判断填进 FloatingPanelPayload 的文本、色板、折点数组与底部最多 4 个动作按钮;再用一条轻量 Promise 串行队列把模式切换、数据推送和退出清理串起来。下面是实战工程 src/marketWindowClient.ts 中的双模切换核心函数 switchMarketWindow():

export function switchMarketWindow(
  mode: 'subwindow' | 'pip',
  payload: FloatingPanelPayload,
  pipOptions?: SwitchPiPOptions
): Promise<PipOperationResult> {
  return enqueue(async () => {
    if (mode === 'subwindow') {
      const caps = parsePipWindowResult<PipCapabilitiesResult>(await getCapabilities());
      if (caps?.ok !== true || caps.windowStageAvailable !== true) {
        throw new Error('无法取得子窗宿主,请检查原生注册和 WindowStage');
      }
      // 先确认目标窗口能力可用再关闭旧窗口,避免不支持时丢掉当前画面
      requireSuccess(await stopPiP(), '停止画中画');
      return requireSuccess(
        await openSubWindow({
          windowName: 'rn_pip_mini_market',
          title: '实时盯盘迷你窗',
          compact: Boolean(payload.compact),
          cornerRadius: 14,
          focusable: false,
          keepScreenOn: true,
          payload,
        }),
        '打开子窗'
      );
    }

    // 画中画分支同样先确认系统开关就绪,再收起应用内子窗并启动画中画
    const support = parsePipWindowResult<PiPSupportResult>(await isPiPSupported());
    if (support?.ok !== true || support.supported !== true) {
      throw new Error(`画中画不可用:${support?.reason ?? '能力探测返回无效'}`);
    }
    requireSuccess(await closeSubWindow(), '关闭子窗');
    return requireSuccess(
      await startPiP({
        payload,
        templateType: pipOptions?.templateType ?? PiPTemplateType.VIDEO_PLAY,
        controlGroups: [], // 传空数组使用当前模板默认的上下切换或播放暂停控制组
        useCustomUI: true,
        autoStartEnabled: pipOptions?.autoStartEnabled ?? false,
        cornerAdsorptionEnabled: true,
        contentWidth: 1600,
        contentHeight: 1000,
      }),
      '启动画中画'
    );
  });
}

同文件上方的排队与校验函数负责逐条串行执行并检查原生返回的 JSON 回执(仅当 ok 为真时放行,否则抛出错误码与原因)。在页面挂载期间,同时订阅 onWindowStateChange 与 onWindowAction 两个监听函数:子窗底部按钮会原样回传你在按钮列表里定义的动作标识(如上一只、暂停盯盘),系统画中画控制栏则会发回上一项、播放暂停切换、下一项等标准动作名,合并进同一个分支更新业务状态,并在组件卸载前移除监听、调用 closeMarketWindows() 清理窗口即可。

5.3 常用参数与适用边界

表4 常用配置说明

配置或场景使用建议
子窗坐标与尺寸单位省略横纵坐标与宽高时自动按屏幕密度换算 232×176 vp(compact: true 为 196×132 vp);显式传入坐标宽高时单位为物理像素 px,圆角 cornerRadius 单位为 vp。
画中画自定义图层与比例useCustomUI: true 启用内置通用卡片覆盖层;contentWidth 与 contentHeight 用于声明画中画宽高比,最终小窗物理大小由系统按比例裁定。
控制组传参支持传入 VideoPlayControlGroup 或 VideoLiveControlGroup 枚举;传空数组 [] 时自动挂载当前模板默认控制组。
前台启动约束startPiP() 必须在应用处于前台时调用;已退至后台再主动调用会被系统拒绝,需要退后台自动进画中画时须在前台提前配置自动启动条件。
已验证设备边界已在华为畅享 100 Pro Max 真机与 API 26 官方直板机模拟器完成前台双模实测;折叠屏分栏、2in1 自由多窗及后台长时保活刷新需按具体业务另行验证。

关于系统级画中画的更多生命周期约束与 navigationId 路由绑定条件,可进一步查阅华为官方画中画开发指南与 PiPWindow 接口说明。

小结

现在我能在主页面旁拖动、缩放盯盘卡片,也能切到画中画继续看报价和止盈提醒。接好两种窗口后,库统一管理窗口宿主、坐标和回调,页面继续处理报价和按钮动作。其他 RN 项目可以沿用窗口接口,再接上自己的数据。后台行情刷新和折叠屏多窗还要结合具体场景验证。

Logo

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

更多推荐