1. 鸿蒙化适配先搞清楚你面对的是什么1.1 你搜的“pip”到底是哪个 pip今天想认真聊一个最近让我折腾了大半周的题目Flutter 三方库 pip 的鸿蒙化适配。先别急着搜错方向这个 pip 不是 Python 的包管理工具而是 Flutter 生态里一个专门做画中画Picture-in-Picture的三方库。我们内部做视频播放类模拟项目时一直用它实现“视频悬浮窗”和“多任务并行交互”这类能力产品需求一句话用户点一下“悬浮播放”视频就缩到屏幕角落继续播切到其他应用也不中断。这种交互听起来不复杂但在 Flutter 侧有一个绕不开的坎Flutter 是跨端 UI 框架它自己掌握着整块渲染表面而画中画本质上是系统级窗口能力需要把 Flutter 的画面“借”给系统让系统去画一个小窗。原生单端实现 PiP 的方式网上能搜到很多但到了鸿蒙环境里窗口模型、生命周期管理、纹理共享都有一套自己的逻辑直接照搬别的平台代码行不通。这篇文章我会站在一个插件作者的视角把整条适配路径拆开讲标准 PiP 模式有哪些隐藏规则、悬浮窗和多任务交互怎么设计、从零到一个能跑的鸿蒙版插件要经历哪些流程。适合正在给 Flutter 项目做鸿蒙化适配的开发者也适合对画中画底层原理感兴趣的同学。先给大家交个底这类适配百分之七十的工作量在接口拆解百分之三十在踩坑踩坑部分我会放在后面集中说。1.2 鸿蒙化适配到底在改哪个层面如果只是把 Android 插件的代码复制一份到鸿蒙工程里大概率是跑不起来的。鸿蒙的窗口模型继承了一套更严格的窗口归属逻辑尤其是新的 Stage 模型下Application、Ability、Window 之间的绑定关系、前后台切换时机都比传统单 Activity 应用多出许多约束。Flutter 在鸿蒙上依赖引擎提供的渲染表面而插件要做的事是把这一层渲染能力和系统画中画窗口能力桥接起来。具体来说适配要处理三层能力映射把 Flutter 侧的startPiP、updatePiP、stopPiP这类方法对应到鸿蒙系统画中画服务的创建、更新、销毁动作。生命周期桥接Flutter 引擎自己无法感知鸿蒙应用何时进入后台、何时回到前台需要平台侧把onBackground、onForeground、onDestroy这些事件转发给 Dart。事件回流画中画窗口上的按钮点击、窗口位置拖动、模式变化甚至系统可能主动回收窗口都要以事件形式通知到 Dart 业务层。这三层看着简单真正做起来会发现每一层都有不少细节。比如能力映射不能只做一对一转发因为系统对画中画窗口尺寸、比例、资源类型都有约束Dart 传进来的参数要先在原生侧校验生命周期桥接不能等 Flutter 引擎自己反应很多时机要在原生回调里主动记录状态否则一次前后台切换就能把事件顺序打乱。这也是为什么很多 Flutter 插件到了鸿蒙侧要重新设计一遍协议而不是简单替换接口名。1.3 方案选型为什么不直接在 ArkUI 里重写一套有人可能会问鸿蒙原生已经支持画中画何必还去适配 Flutter 插件直接在 ArkUI 里重写一个原生悬浮窗页面不就行了表面看确实可以但业务现实是我们项目里的播放器状态、数据模型、操作日志全都在 Dart 侧重写一套意味着同一套视频播放逻辑要维护两份后面任何一个交互逻辑变动都要同步改两个端成本非常高。所以我的最终方案是走平台通道Dart 侧保留统一接口鸿蒙原生侧负责具体窗口逻辑。通信采用两条通道一条是MethodChannel处理启动、更新、停止这类同步操作另一条是EventChannel处理平台侧到 Dart 侧的事件流。这样做的好处是接口清晰、调试方便也能保持现有 Flutter 插件体系里的使用习惯。如果团队里跨端协议很强也可以考虑用 Pigeon 自动生成通道代码减少手写字符串协议带来的拼写错误我们项目时间紧MethodChannel 足够直接就先用了它。选型还有一个隐性问题通道参数不能设计得太重。你不可能把视频流地址、播放进度、清晰度列表全塞进一次调用里正确做法是只传必要标识和尺寸参数业务数据仍然通过 Dart 层自己的状态管理器去拿。通道越轻后面排查问题越容易。2. 核心细节标准画中画到底有哪些隐藏规则2.1 窗口尺寸不是你想设就能设我一开始照着 Android 的习惯在创建画中画窗口时直接把宽高写成像素值传进去很快发现系统会忽略掉一部分参数。鸿蒙的画中画窗口有一套默认比例约束常见的有竖屏 9:16、横屏 16:9也允许自定义比例但都存在一个合理区间。如果传入的比例超出区间系统一般不直接报错而是选择回退到默认比例或者把窗口强制压缩到贴近安全区的位置视觉效果就很怪。实际项目里我们前端配置的视频比例是灵活的有的内容是短视频竖屏有的是长视频横屏。为了不在运行时让用户看到窗口突然变形我在 Dart 侧增加了一个比例校验方法先根据视频模块的原始尺寸计算出目标宽高比再和平台侧反馈的支持区间做对比超范围就直接用系统默认比例。窗口默认位置通常在屏幕右下角用户拖动后会有吸附效果。如果你的产品不希望用户随意拖动平台侧可以关闭窗口手势但要注意关闭后也别把窗口摆在不合理位置比如压住导航栏。另外要分清“标准 PiP 模式”和“自由悬浮窗模式”这两个概念在鸿蒙上不是一回事。标准 PiP 窗口由系统接管有固定的贴边逻辑、缩放能力和控制面板适配成本低适合视频播放这类强系统接管场景自由悬浮窗自由度更高但要处理权限、层级、避让区域等问题维护成本高。我们最终选择标准 PiP 模式做视频小窗只在特殊运营位用自由悬浮窗避免一把抓导致适配失控。2.2 悬浮窗的层级、焦点与用户感知画中画窗口的层级天然比普通应用窗口高但这不代表它可以在屏幕任意位置肆意遮挡。系统会限制窗口不能盖住状态栏、导航栏、关键系统提示区域。从用户感知上讲PiP 窗口最好能做到“看得见但不打扰”画面清晰展示、控制按钮响应灵敏同时不能影响主应用当前页面的操作。容易被忽略的是焦点问题。默认情况下 PiP 窗口不会主动抢焦点但它能接收点击事件。用户点击小窗里的画面时很可能发生一次焦点短暂切换如果处理不好会出现点一下小窗后主页面突然暂停、键盘弹出来、或快捷键失效的怪现象。我的做法是平台侧维护一个“当前 PiP 窗口是否持有焦点”的状态并在 Dart 侧响应用户交互时屏蔽主页面快捷键和焦点变化。简单说就是让 PiP 窗口像是一个独立的轻量级场景不打扰底层页面的运转。窗口上的控制面板也要提前想清楚。播放、暂停、关闭、下一集这类按钮优先使用系统能力或者原生组件实现而不是放到 Flutter 纹理里做。因为系统控制面板是窗口的一部分生命周期和层级完全由系统掌握如果你自己手绘一个控制层就要自己去处理点击命中、焦点变化、动画时机调试成本会明显增加。我们一开始图省事把控制按钮都做在 Flutter 层后来频繁出现点击不灵、动画卡顿的问题换成原生控制面板后一夜消停。2.3 多任务并行下的状态机与回调时序画中画能力的核心价值是“多任务并行”它的状态机比普通页面要复杂。应用在前台、应用在后台、PiP 窗口创建中、PiP 窗口已显示、PiP 窗口被销毁这些状态是流动的而且会穿插用户操作和系统干预。我建议在动手写代码前先和原生同事把状态转移表整理出来否则后面事件一多Dart 侧根本不知道该依据哪个状态去刷新界面。下面是一张我在项目里实际用到的状态简化表触发事件PiP 窗口状态Dart 侧回调用户点击“悬浮播放”窗口创建中显示加载状态onPiPStarting窗口创建成功并显示窗口已显示进入可交互状态onPiPStarted用户按下 Home 或切到其他应用主应用后台PiP 窗口继续播放onAppBackground用户点击小窗中“恢复全屏”窗口退出主应用回到前台onPiPStopped用户直接关闭小窗窗口销毁释放资源onPiPDestroyed这个表格看着简单真正实现时有个很关键的时序问题EventChannel的事件发送通常是在原生异步线程里完成的不能在平台侧同步等待 Dart 返回否则容易出现通道阻塞。正确做法是原生侧先把状态记录到自己的状态字段里再通过事件通道广播出去Dart 侧收到事件后也不要马上反过来调用同步方法而是先更新本地状态再在下一轮 UI 刷新时决定是否需要调用updatePiP。这样能避免“Dart 收到开始事件后立刻调用更新方法而平台侧窗口还没完全创建好”的竞态问题。3. 实操从空工程到一个能用的鸿蒙版 pip 插件3.1 第一步搭建插件的鸿蒙侧工程骨架Flutter 工程本身要支持鸿蒙侧插件需要在插件工程里新建harmonyos目录并在插件的声明文件里把 harmonyos 平台注册进去。目录结构大概长这样my_pip_plugin/ lib/ pip_controller.dart harmonyos/ entry/src/main/ets/plugins/PiPPlugin.ets entry/src/main/ets/plugins/PiPManager.etsPiPPlugin.ets负责在应用启动时注册通道PiPManager.ets负责真正创建、更新、销毁画中画窗口。注意不同版本的 Flutter 鸿蒙化支持方案对插件目录的要求并不完全相同有的版本还需要在pubspec.yaml的plugin字段里声明harmonyos平台标识具体字段以官方说明为准。我先按最常规的方式搭后面若遇到平台识别不到插件优先检查声明字段和构建产物。还有一点容易被新手遗忘鸿蒙侧的插件实施类必须绑定到正确的 Ability 生命周期上。如果只在某个初始化函数里注册通道而该函数没有持有 Ability 的上下文后面创建窗口时拿不到窗口管理对象就会莫名其妙抛空指针。我习惯在PiPPlugin初始化时把UIAbilityContext存成成员变量后续所有系统调用都从它身上获取避免多次扫描上下文。3.2 第二步Dart 侧统一接口与通道协议Dart 侧不要把所有逻辑都堆在MethodChannel的invokeMethod调用里最好先抽象一个接口层。我设计了一个很小的PiPPlatform抽象类abstract class PiPPlatform { Futurevoid startPiP(PiPConfig config); Futurevoid updatePiP(PiPConfig config); Futurevoid stopPiP(); StreamPiPEvent get piPEvents; }然后提供一个默认的MethodChannelPiPPlatform实现通道名我用了flutter_pip把startPiP、updatePiP、stopPiP映射成三个invokeMethod调用。通道参数越简单越好我的PiPConfig只保留width、height、aspectRatio、videoId四个字段业务侧需要拿到视频信息时再去自己的数据仓库查不通过通道传大量状态。事件通道的设计同样要简单。我只定义两类事件一类是状态变化事件stateChanged比如启动完成、退出完成另一类是用户行为事件pipAction比如播放键被点击、暂停键被点击、窗口位置变化。用枚举字符串区分事件类型Dart 侧统一收口到一个StreamController由页面对应的控制器订阅。这一步不复杂但值得多花点时间因为协议一旦中途改Dart 和原生两侧都要同步调整很麻烦。3.3 第三步ArkTS 侧实现画中画控制器ArkTS 侧核心是PiPManager。初始化时它负责保存UIAbilityContext注册系统画中画服务并建立EventChannel的事件发送能力。为了让 PiP 窗口显示 Flutter 渲染画面平台侧需要拿到 Flutter 引擎传递过来的纹理信息然后在画中画窗口创建时把纹理绑定进去。绑定时机很重要必须在窗口创建前确认纹理有效否则窗口上会黑屏。我最终写出来的控制器方法签名类似这样import { window } from kit.ArkUI; class PiPManager { private pipWindow: window.PiPWindow | null null; startPip(params: Recordstring, Object): void { if (this.pipWindow) { this.stopPip(); } const config: window.PiPConfig { width: params.width as number, height: params.height as number, aspectRatio: params.aspectRatio as number, textureId: params.textureId as number, }; this.pipWindow window.createPiPWindow(config); this.pipWindow.on(stateChanged, (state) { this.sendEvent(stateChanged, state); }); this.pipWindow.on(userAction, (action) { this.sendEvent(pipAction, action); }); this.pipWindow.start(); } }上面这段代码是示例骨架不同 SDK 版本的 API 名称、参数类型都有可能有差异你需要以自己手中的发行版为准。我想强调的核心设计是PiPManager持有唯一的pipWindow引用任何操作都先判断当前窗口是否存在状态变化和用户行为统一走sendEvent发送到 Dart不在原生侧做业务判断。这样做能保证 Flutter 侧始终是唯一决策者原生侧只是执行窗口动作。3.4 第四步一次完整的拉起与恢复流程跑通一个流程比看一百页接口文档都有用。我以我们的视频播放页为例把完整流程串一遍用户点击 Flutter 页面的“悬浮播放”按钮。Dart 层组装PiPConfig调用startPiP。MethodChannel把参数传到 ArkTS 侧的PiPManager。PiPManager先检查当前是否有已存在的 PiP 窗口有就先关闭再创建新窗口。创建窗口的同时把 Flutter 引擎传入的纹理 ID 绑定到窗口上。窗口创建成功后原生侧通过EventChannel发出stateChanged: startedDart 收到后把页面标记为“画中画模式”。用户按 Home 键应用进入后台PiP 窗口继续显示画面不中断。用户点击 PiP 窗口上的播放/暂停键事件回到 Dart由 Dart 修改播放器状态。用户点击“恢复全屏”或系统设置中的放大按钮PiP 窗口退出主应用回到前台Dart 收到stateChanged: stopped页面恢复正常布局。这条链路里最容易出问题的是第 5 步和第 8 步。第 5 步需要纹理 ID 先于窗口创建被确认有效我建议在 Dart 侧调用startPiP前先向平台侧注册纹理并在回调里拿到纹理 ID 后再创建窗口第 8 步则要注意用户行为事件的线程事件回调可能发生在任意线程不要在回调里直接做耗时的 UI 更新而是回调到 Dart 后切回主线程处理。3.5 跑通后一定要过的验证清单插件能跑起来和能在复杂场景下稳定工作是两码事。我在内部阶段总结了下面这份验证清单每一条都是踩过坑后补进去的首次拉起 PiP 窗口后Flutter 内容能正常渲染没有黑屏、花屏或明显掉帧。应用进入后台PiP 窗口继续播放声音不中断。在 PiP 状态下点击控制面板按钮事件能准确回到 Dart 层日志确认回调正常。反复进行“进入 PiP - 退出 PiP - 再次进入”的压力操作不会崩溃不会闪退。拖动 PiP 窗口到屏幕边缘窗口吸附位置正确不会超出安全区。如果应用内有多个视频播放页同一时刻只允许存在一个 PiP 窗口打开新的画中画前旧的必须被正确关闭。横竖屏切换后PiP 窗口比例能跟着修正不会出现画面拉伸或黑边。这份清单不用一次全过但每一条都应该在项目迭代中持续回归。尤其是反复进入退出的场景很多偶发问题藏在这里比如窗口销毁不彻底导致二次创建失败、事件回调重复触发导致 Dart 状态错乱。它看起来不产生新功能但真出了问题排查成本是最高的。4. 避坑实录我在适配中遇到的高频问题4.1 黑屏Flutter 纹理与系统悬浮窗的冲突黑屏是最常遇到、也最让人头疼的问题。我第一次跑通 PiP 时窗口能弹出来但内部画面是黑的Flutter 的 UI 明明在正常渲染小窗里却什么都没有。排查了很久最后定位到是纹理绑定时机不对Flutter 引擎的纹理 ID 在窗口创建那一刻还没有完全准备好系统窗口拿到的是一块空纹理。解决方案是在创建 PiP 窗口前先向 Flutter 引擎发起一次“纹理同步”请求等引擎确认纹理有效后再执行窗口创建。如果在应用退到后台后黑屏则可能是 Flutter 渲染线程被系统挂起窗口拿到的纹理解锁失败这时候需要在原生侧尝试恢复渲染表面或者重新请求一次新纹理。坦诚说这个问题没有一劳永逸的答案因为你面对的是一个跨端渲染与系统窗口的交叉地带只能靠日志和多次实测定位。4.2 生命周期回调收不到MethodChannel 用来做主动调用很顺手但 EventChannel 在应用处于后台时事件可能不会及时送达 Dart。原因是 Flutter 引擎在后台会降低调度频率Dart 消息队列的消费时机变得不可控。这会导致一个现象PiP 窗口明明已经启动成功了Dart 侧却迟迟收不到started事件页面上一直显示加载状态。我的做法是平台侧不做“发完就忘”而是把最近一次的关键状态存到原生侧字段里等应用下次切换到前台时再补发一次最新状态到 Dart。同时在startPiP调用成功后原生侧主动回调一次当前完整状态而不只是依赖事件流。这样即使事件在后台被延迟Dart 侧也能在恢复前台时拿到准确信息。4.3 旋转屏和折叠屏对窗口尺寸的干扰屏幕旋转后单 Activity 自适应的 Flutter 页面会重新布局但 PiP 窗口还保留着旧比例画面就会拉变形。更麻烦的是折叠屏设备在展开和折叠状态下屏幕像素尺寸和比例可能完全不同预设的窗口初始位置也要跟着改。建议做法是在 Dart 侧监听系统的屏幕尺寸变化通知比如通过MediaQuery或者原始分辨率变化再调用updatePiP把新的窗口比例同步给平台侧。平台侧不要自己去猜宽高比而是以 Dart 传过来的最新值为准。这个机制类似一个远程遥控器Dart 是遥控器开关原生是接收指令的电视机谁也别越权决策。4.4 拉起失败权限与后台校验在鸿蒙上画中画窗口创建本身是允许的但在某些设备上仍然受“后台弹出界面”权限约束。如果你的应用在前台时创建 PiP 没问题一旦切到后台再发起创建系统可能直接拦截。避免的办法是尽量保证所有 PiP 创建动作都发生在应用前台阶段或者至少由用户在页面内的明确点击触发而不是某个后台定时任务自动触发。另外提醒一点画中画窗口数量一般被系统限制为一个。如果业务代码没有做好状态判断用户在两个视频页之间快速切换连续调用两次startPiP第二次创建很可能直接失败。正统做法是每次创建前先执行一次“吞掉旧窗口”的逻辑也就是先stopPiP等旧窗口销毁完成再创建新窗口中间加个防抖状态避免重复触发。4.5 常见问题速查表问题可能原因解决方向PiP 窗口黑屏纹理未绑定或渲染线程挂起创建前请求纹理同步必要时刷新渲染表面事件回调丢失EventChannel 在后台延迟原生侧缓存状态前台补发关键事件画面拉伸变形屏幕旋转或折叠状态变化监听尺寸变化调用updatePiP更新比例拉起小窗失败后台权限限制或多个 PiP 实例并存前台触发创建先关旧的再开新的点击小窗影响主页面PiP 窗口短暂获取焦点平台侧维护焦点状态Dart 侧屏蔽快捷键反复进入退出崩溃窗口销毁不彻底事件重复触发增加防抖统一窗口状态判断表格只是一个起点真实环境里的问题组合千奇百怪。我遇到过一个非常隐蔽的问题PiP 窗口销毁后Dart 侧还保留着旧的TextureId下一次创建窗口时用了这个失效纹理导致第二次进入画中画时画面闪烁。最后靠每次startPiP前都强制重新获取纹理 ID 才解决。最后分享一点个人体会。做鸿蒙化 Flutter 插件适配最艰难的往往不是写代码而是分清“系统本来就能做什么”和“必须由你连接什么”。系统窗口能力很强但它不认识 Flutter 的纹理也不认识 Dart 的状态你的插件本质上就是一个翻译器既要忠实传递指令也要做好异常保护。我建议所有接手类似任务的开发者先花半天时间把原生画中画的完整状态流转跑熟再回来对照 Flutter 插件架构顺序反了会反复走弯路。如果你也在做类似适配有什么我没遇到的坑欢迎私下交流多交流比对着文档猜要高效得多。 
长河君 · 2026/10/17 18:51:44 · 阅读 1.2k Flutter三方库pip鸿蒙化适配：画中画插件从移植到落地全解析
1. 鸿蒙化适配先搞清楚你面对的是什么1.1 你搜的“pip”到底是哪个 pip今天想认真聊一个最近让我折腾了大半周的题目Flutter 三方库 pip 的鸿蒙化适配。先别急着搜错方向这个 pip 不是 Python 的包管理工具而是 Flutter 生态里一个专门做画中画Picture-in-Picture的三方库。我们内部做视频播放类模拟项目时一直用它实现“视频悬浮窗”和“多任务并行交互”这类能力产品需求一句话用户点一下“悬浮播放”视频就缩到屏幕角落继续播切到其他应用也不中断。这种交互听起来不复杂但在 Flutter 侧有一个绕不开的坎Flutter 是跨端 UI 框架它自己掌握着整块渲染表面而画中画本质上是系统级窗口能力需要把 Flutter 的画面“借”给系统让系统去画一个小窗。原生单端实现 PiP 的方式网上能搜到很多但到了鸿蒙环境里窗口模型、生命周期管理、纹理共享都有一套自己的逻辑直接照搬别的平台代码行不通。这篇文章我会站在一个插件作者的视角把整条适配路径拆开讲标准 PiP 模式有哪些隐藏规则、悬浮窗和多任务交互怎么设计、从零到一个能跑的鸿蒙版插件要经历哪些流程。适合正在给 Flutter 项目做鸿蒙化适配的开发者也适合对画中画底层原理感兴趣的同学。先给大家交个底这类适配百分之七十的工作量在接口拆解百分之三十在踩坑踩坑部分我会放在后面集中说。1.2 鸿蒙化适配到底在改哪个层面如果只是把 Android 插件的代码复制一份到鸿蒙工程里大概率是跑不起来的。鸿蒙的窗口模型继承了一套更严格的窗口归属逻辑尤其是新的 Stage 模型下Application、Ability、Window 之间的绑定关系、前后台切换时机都比传统单 Activity 应用多出许多约束。Flutter 在鸿蒙上依赖引擎提供的渲染表面而插件要做的事是把这一层渲染能力和系统画中画窗口能力桥接起来。具体来说适配要处理三层能力映射把 Flutter 侧的startPiP、updatePiP、stopPiP这类方法对应到鸿蒙系统画中画服务的创建、更新、销毁动作。生命周期桥接Flutter 引擎自己无法感知鸿蒙应用何时进入后台、何时回到前台需要平台侧把onBackground、onForeground、onDestroy这些事件转发给 Dart。事件回流画中画窗口上的按钮点击、窗口位置拖动、模式变化甚至系统可能主动回收窗口都要以事件形式通知到 Dart 业务层。这三层看着简单真正做起来会发现每一层都有不少细节。比如能力映射不能只做一对一转发因为系统对画中画窗口尺寸、比例、资源类型都有约束Dart 传进来的参数要先在原生侧校验生命周期桥接不能等 Flutter 引擎自己反应很多时机要在原生回调里主动记录状态否则一次前后台切换就能把事件顺序打乱。这也是为什么很多 Flutter 插件到了鸿蒙侧要重新设计一遍协议而不是简单替换接口名。1.3 方案选型为什么不直接在 ArkUI 里重写一套有人可能会问鸿蒙原生已经支持画中画何必还去适配 Flutter 插件直接在 ArkUI 里重写一个原生悬浮窗页面不就行了表面看确实可以但业务现实是我们项目里的播放器状态、数据模型、操作日志全都在 Dart 侧重写一套意味着同一套视频播放逻辑要维护两份后面任何一个交互逻辑变动都要同步改两个端成本非常高。所以我的最终方案是走平台通道Dart 侧保留统一接口鸿蒙原生侧负责具体窗口逻辑。通信采用两条通道一条是MethodChannel处理启动、更新、停止这类同步操作另一条是EventChannel处理平台侧到 Dart 侧的事件流。这样做的好处是接口清晰、调试方便也能保持现有 Flutter 插件体系里的使用习惯。如果团队里跨端协议很强也可以考虑用 Pigeon 自动生成通道代码减少手写字符串协议带来的拼写错误我们项目时间紧MethodChannel 足够直接就先用了它。选型还有一个隐性问题通道参数不能设计得太重。你不可能把视频流地址、播放进度、清晰度列表全塞进一次调用里正确做法是只传必要标识和尺寸参数业务数据仍然通过 Dart 层自己的状态管理器去拿。通道越轻后面排查问题越容易。2. 核心细节标准画中画到底有哪些隐藏规则2.1 窗口尺寸不是你想设就能设我一开始照着 Android 的习惯在创建画中画窗口时直接把宽高写成像素值传进去很快发现系统会忽略掉一部分参数。鸿蒙的画中画窗口有一套默认比例约束常见的有竖屏 9:16、横屏 16:9也允许自定义比例但都存在一个合理区间。如果传入的比例超出区间系统一般不直接报错而是选择回退到默认比例或者把窗口强制压缩到贴近安全区的位置视觉效果就很怪。实际项目里我们前端配置的视频比例是灵活的有的内容是短视频竖屏有的是长视频横屏。为了不在运行时让用户看到窗口突然变形我在 Dart 侧增加了一个比例校验方法先根据视频模块的原始尺寸计算出目标宽高比再和平台侧反馈的支持区间做对比超范围就直接用系统默认比例。窗口默认位置通常在屏幕右下角用户拖动后会有吸附效果。如果你的产品不希望用户随意拖动平台侧可以关闭窗口手势但要注意关闭后也别把窗口摆在不合理位置比如压住导航栏。另外要分清“标准 PiP 模式”和“自由悬浮窗模式”这两个概念在鸿蒙上不是一回事。标准 PiP 窗口由系统接管有固定的贴边逻辑、缩放能力和控制面板适配成本低适合视频播放这类强系统接管场景自由悬浮窗自由度更高但要处理权限、层级、避让区域等问题维护成本高。我们最终选择标准 PiP 模式做视频小窗只在特殊运营位用自由悬浮窗避免一把抓导致适配失控。2.2 悬浮窗的层级、焦点与用户感知画中画窗口的层级天然比普通应用窗口高但这不代表它可以在屏幕任意位置肆意遮挡。系统会限制窗口不能盖住状态栏、导航栏、关键系统提示区域。从用户感知上讲PiP 窗口最好能做到“看得见但不打扰”画面清晰展示、控制按钮响应灵敏同时不能影响主应用当前页面的操作。容易被忽略的是焦点问题。默认情况下 PiP 窗口不会主动抢焦点但它能接收点击事件。用户点击小窗里的画面时很可能发生一次焦点短暂切换如果处理不好会出现点一下小窗后主页面突然暂停、键盘弹出来、或快捷键失效的怪现象。我的做法是平台侧维护一个“当前 PiP 窗口是否持有焦点”的状态并在 Dart 侧响应用户交互时屏蔽主页面快捷键和焦点变化。简单说就是让 PiP 窗口像是一个独立的轻量级场景不打扰底层页面的运转。窗口上的控制面板也要提前想清楚。播放、暂停、关闭、下一集这类按钮优先使用系统能力或者原生组件实现而不是放到 Flutter 纹理里做。因为系统控制面板是窗口的一部分生命周期和层级完全由系统掌握如果你自己手绘一个控制层就要自己去处理点击命中、焦点变化、动画时机调试成本会明显增加。我们一开始图省事把控制按钮都做在 Flutter 层后来频繁出现点击不灵、动画卡顿的问题换成原生控制面板后一夜消停。2.3 多任务并行下的状态机与回调时序画中画能力的核心价值是“多任务并行”它的状态机比普通页面要复杂。应用在前台、应用在后台、PiP 窗口创建中、PiP 窗口已显示、PiP 窗口被销毁这些状态是流动的而且会穿插用户操作和系统干预。我建议在动手写代码前先和原生同事把状态转移表整理出来否则后面事件一多Dart 侧根本不知道该依据哪个状态去刷新界面。下面是一张我在项目里实际用到的状态简化表触发事件PiP 窗口状态Dart 侧回调用户点击“悬浮播放”窗口创建中显示加载状态onPiPStarting窗口创建成功并显示窗口已显示进入可交互状态onPiPStarted用户按下 Home 或切到其他应用主应用后台PiP 窗口继续播放onAppBackground用户点击小窗中“恢复全屏”窗口退出主应用回到前台onPiPStopped用户直接关闭小窗窗口销毁释放资源onPiPDestroyed这个表格看着简单真正实现时有个很关键的时序问题EventChannel的事件发送通常是在原生异步线程里完成的不能在平台侧同步等待 Dart 返回否则容易出现通道阻塞。正确做法是原生侧先把状态记录到自己的状态字段里再通过事件通道广播出去Dart 侧收到事件后也不要马上反过来调用同步方法而是先更新本地状态再在下一轮 UI 刷新时决定是否需要调用updatePiP。这样能避免“Dart 收到开始事件后立刻调用更新方法而平台侧窗口还没完全创建好”的竞态问题。3. 实操从空工程到一个能用的鸿蒙版 pip 插件3.1 第一步搭建插件的鸿蒙侧工程骨架Flutter 工程本身要支持鸿蒙侧插件需要在插件工程里新建harmonyos目录并在插件的声明文件里把 harmonyos 平台注册进去。目录结构大概长这样my_pip_plugin/ lib/ pip_controller.dart harmonyos/ entry/src/main/ets/plugins/PiPPlugin.ets entry/src/main/ets/plugins/PiPManager.etsPiPPlugin.ets负责在应用启动时注册通道PiPManager.ets负责真正创建、更新、销毁画中画窗口。注意不同版本的 Flutter 鸿蒙化支持方案对插件目录的要求并不完全相同有的版本还需要在pubspec.yaml的plugin字段里声明harmonyos平台标识具体字段以官方说明为准。我先按最常规的方式搭后面若遇到平台识别不到插件优先检查声明字段和构建产物。还有一点容易被新手遗忘鸿蒙侧的插件实施类必须绑定到正确的 Ability 生命周期上。如果只在某个初始化函数里注册通道而该函数没有持有 Ability 的上下文后面创建窗口时拿不到窗口管理对象就会莫名其妙抛空指针。我习惯在PiPPlugin初始化时把UIAbilityContext存成成员变量后续所有系统调用都从它身上获取避免多次扫描上下文。3.2 第二步Dart 侧统一接口与通道协议Dart 侧不要把所有逻辑都堆在MethodChannel的invokeMethod调用里最好先抽象一个接口层。我设计了一个很小的PiPPlatform抽象类abstract class PiPPlatform { Futurevoid startPiP(PiPConfig config); Futurevoid updatePiP(PiPConfig config); Futurevoid stopPiP(); StreamPiPEvent get piPEvents; }然后提供一个默认的MethodChannelPiPPlatform实现通道名我用了flutter_pip把startPiP、updatePiP、stopPiP映射成三个invokeMethod调用。通道参数越简单越好我的PiPConfig只保留width、height、aspectRatio、videoId四个字段业务侧需要拿到视频信息时再去自己的数据仓库查不通过通道传大量状态。事件通道的设计同样要简单。我只定义两类事件一类是状态变化事件stateChanged比如启动完成、退出完成另一类是用户行为事件pipAction比如播放键被点击、暂停键被点击、窗口位置变化。用枚举字符串区分事件类型Dart 侧统一收口到一个StreamController由页面对应的控制器订阅。这一步不复杂但值得多花点时间因为协议一旦中途改Dart 和原生两侧都要同步调整很麻烦。3.3 第三步ArkTS 侧实现画中画控制器ArkTS 侧核心是PiPManager。初始化时它负责保存UIAbilityContext注册系统画中画服务并建立EventChannel的事件发送能力。为了让 PiP 窗口显示 Flutter 渲染画面平台侧需要拿到 Flutter 引擎传递过来的纹理信息然后在画中画窗口创建时把纹理绑定进去。绑定时机很重要必须在窗口创建前确认纹理有效否则窗口上会黑屏。我最终写出来的控制器方法签名类似这样import { window } from kit.ArkUI; class PiPManager { private pipWindow: window.PiPWindow | null null; startPip(params: Recordstring, Object): void { if (this.pipWindow) { this.stopPip(); } const config: window.PiPConfig { width: params.width as number, height: params.height as number, aspectRatio: params.aspectRatio as number, textureId: params.textureId as number, }; this.pipWindow window.createPiPWindow(config); this.pipWindow.on(stateChanged, (state) { this.sendEvent(stateChanged, state); }); this.pipWindow.on(userAction, (action) { this.sendEvent(pipAction, action); }); this.pipWindow.start(); } }上面这段代码是示例骨架不同 SDK 版本的 API 名称、参数类型都有可能有差异你需要以自己手中的发行版为准。我想强调的核心设计是PiPManager持有唯一的pipWindow引用任何操作都先判断当前窗口是否存在状态变化和用户行为统一走sendEvent发送到 Dart不在原生侧做业务判断。这样做能保证 Flutter 侧始终是唯一决策者原生侧只是执行窗口动作。3.4 第四步一次完整的拉起与恢复流程跑通一个流程比看一百页接口文档都有用。我以我们的视频播放页为例把完整流程串一遍用户点击 Flutter 页面的“悬浮播放”按钮。Dart 层组装PiPConfig调用startPiP。MethodChannel把参数传到 ArkTS 侧的PiPManager。PiPManager先检查当前是否有已存在的 PiP 窗口有就先关闭再创建新窗口。创建窗口的同时把 Flutter 引擎传入的纹理 ID 绑定到窗口上。窗口创建成功后原生侧通过EventChannel发出stateChanged: startedDart 收到后把页面标记为“画中画模式”。用户按 Home 键应用进入后台PiP 窗口继续显示画面不中断。用户点击 PiP 窗口上的播放/暂停键事件回到 Dart由 Dart 修改播放器状态。用户点击“恢复全屏”或系统设置中的放大按钮PiP 窗口退出主应用回到前台Dart 收到stateChanged: stopped页面恢复正常布局。这条链路里最容易出问题的是第 5 步和第 8 步。第 5 步需要纹理 ID 先于窗口创建被确认有效我建议在 Dart 侧调用startPiP前先向平台侧注册纹理并在回调里拿到纹理 ID 后再创建窗口第 8 步则要注意用户行为事件的线程事件回调可能发生在任意线程不要在回调里直接做耗时的 UI 更新而是回调到 Dart 后切回主线程处理。3.5 跑通后一定要过的验证清单插件能跑起来和能在复杂场景下稳定工作是两码事。我在内部阶段总结了下面这份验证清单每一条都是踩过坑后补进去的首次拉起 PiP 窗口后Flutter 内容能正常渲染没有黑屏、花屏或明显掉帧。应用进入后台PiP 窗口继续播放声音不中断。在 PiP 状态下点击控制面板按钮事件能准确回到 Dart 层日志确认回调正常。反复进行“进入 PiP - 退出 PiP - 再次进入”的压力操作不会崩溃不会闪退。拖动 PiP 窗口到屏幕边缘窗口吸附位置正确不会超出安全区。如果应用内有多个视频播放页同一时刻只允许存在一个 PiP 窗口打开新的画中画前旧的必须被正确关闭。横竖屏切换后PiP 窗口比例能跟着修正不会出现画面拉伸或黑边。这份清单不用一次全过但每一条都应该在项目迭代中持续回归。尤其是反复进入退出的场景很多偶发问题藏在这里比如窗口销毁不彻底导致二次创建失败、事件回调重复触发导致 Dart 状态错乱。它看起来不产生新功能但真出了问题排查成本是最高的。4. 避坑实录我在适配中遇到的高频问题4.1 黑屏Flutter 纹理与系统悬浮窗的冲突黑屏是最常遇到、也最让人头疼的问题。我第一次跑通 PiP 时窗口能弹出来但内部画面是黑的Flutter 的 UI 明明在正常渲染小窗里却什么都没有。排查了很久最后定位到是纹理绑定时机不对Flutter 引擎的纹理 ID 在窗口创建那一刻还没有完全准备好系统窗口拿到的是一块空纹理。解决方案是在创建 PiP 窗口前先向 Flutter 引擎发起一次“纹理同步”请求等引擎确认纹理有效后再执行窗口创建。如果在应用退到后台后黑屏则可能是 Flutter 渲染线程被系统挂起窗口拿到的纹理解锁失败这时候需要在原生侧尝试恢复渲染表面或者重新请求一次新纹理。坦诚说这个问题没有一劳永逸的答案因为你面对的是一个跨端渲染与系统窗口的交叉地带只能靠日志和多次实测定位。4.2 生命周期回调收不到MethodChannel 用来做主动调用很顺手但 EventChannel 在应用处于后台时事件可能不会及时送达 Dart。原因是 Flutter 引擎在后台会降低调度频率Dart 消息队列的消费时机变得不可控。这会导致一个现象PiP 窗口明明已经启动成功了Dart 侧却迟迟收不到started事件页面上一直显示加载状态。我的做法是平台侧不做“发完就忘”而是把最近一次的关键状态存到原生侧字段里等应用下次切换到前台时再补发一次最新状态到 Dart。同时在startPiP调用成功后原生侧主动回调一次当前完整状态而不只是依赖事件流。这样即使事件在后台被延迟Dart 侧也能在恢复前台时拿到准确信息。4.3 旋转屏和折叠屏对窗口尺寸的干扰屏幕旋转后单 Activity 自适应的 Flutter 页面会重新布局但 PiP 窗口还保留着旧比例画面就会拉变形。更麻烦的是折叠屏设备在展开和折叠状态下屏幕像素尺寸和比例可能完全不同预设的窗口初始位置也要跟着改。建议做法是在 Dart 侧监听系统的屏幕尺寸变化通知比如通过MediaQuery或者原始分辨率变化再调用updatePiP把新的窗口比例同步给平台侧。平台侧不要自己去猜宽高比而是以 Dart 传过来的最新值为准。这个机制类似一个远程遥控器Dart 是遥控器开关原生是接收指令的电视机谁也别越权决策。4.4 拉起失败权限与后台校验在鸿蒙上画中画窗口创建本身是允许的但在某些设备上仍然受“后台弹出界面”权限约束。如果你的应用在前台时创建 PiP 没问题一旦切到后台再发起创建系统可能直接拦截。避免的办法是尽量保证所有 PiP 创建动作都发生在应用前台阶段或者至少由用户在页面内的明确点击触发而不是某个后台定时任务自动触发。另外提醒一点画中画窗口数量一般被系统限制为一个。如果业务代码没有做好状态判断用户在两个视频页之间快速切换连续调用两次startPiP第二次创建很可能直接失败。正统做法是每次创建前先执行一次“吞掉旧窗口”的逻辑也就是先stopPiP等旧窗口销毁完成再创建新窗口中间加个防抖状态避免重复触发。4.5 常见问题速查表问题可能原因解决方向PiP 窗口黑屏纹理未绑定或渲染线程挂起创建前请求纹理同步必要时刷新渲染表面事件回调丢失EventChannel 在后台延迟原生侧缓存状态前台补发关键事件画面拉伸变形屏幕旋转或折叠状态变化监听尺寸变化调用updatePiP更新比例拉起小窗失败后台权限限制或多个 PiP 实例并存前台触发创建先关旧的再开新的点击小窗影响主页面PiP 窗口短暂获取焦点平台侧维护焦点状态Dart 侧屏蔽快捷键反复进入退出崩溃窗口销毁不彻底事件重复触发增加防抖统一窗口状态判断表格只是一个起点真实环境里的问题组合千奇百怪。我遇到过一个非常隐蔽的问题PiP 窗口销毁后Dart 侧还保留着旧的TextureId下一次创建窗口时用了这个失效纹理导致第二次进入画中画时画面闪烁。最后靠每次startPiP前都强制重新获取纹理 ID 才解决。最后分享一点个人体会。做鸿蒙化 Flutter 插件适配最艰难的往往不是写代码而是分清“系统本来就能做什么”和“必须由你连接什么”。系统窗口能力很强但它不认识 Flutter 的纹理也不认识 Dart 的状态你的插件本质上就是一个翻译器既要忠实传递指令也要做好异常保护。我建议所有接手类似任务的开发者先花半天时间把原生画中画的完整状态流转跑熟再回来对照 Flutter 插件架构顺序反了会反复走弯路。如果你也在做类似适配有什么我没遇到的坑欢迎私下交流多交流比对着文档猜要高效得多。