Flutter 3.47 鸿蒙三方库适配实战：从 0 到 1 处理 flutter_screen

Flutter 3.47 鸿蒙三方库适配实战：从 0 到 1 处理 flutter_screen_recording

录制屏幕视频到本地文件。

本文以flutter_screen_recording 2.0.24为例，记录我如何保留原有 Dart API、补齐 Flutter OH 插件入口、在鸿蒙端接入真实系统能力，并在 HarmonyOS API 26 真机上完成构建、安装、启动与调用验证。

适配仓库：flutter_screen_recording

适配分支：feat/ohos_flutter_screen_recording_2.0.24

适配 TAG：2.0.24-ohos.1

一、先看最终效果

本库的原生行为无法用截图直接呈现（音频输出、系统授权弹窗等），本文只记录构建产物与调用链路，不声称已通过截图验收。

验证点	实测结果
Flutter OH 3.47 工程构建	通过，产出`entry-default-signed.hap`
安装、启动（真机）	通过
插件注册	`startRecordScreen`/`stopRecordScreen`就绪

二、这个库原来是怎么工作的

上游flutter_screen_recording通过平台通道与原生侧通信，通道定义在 Dart 源码里，原生侧只需要注册同名通道并实现方法分发，Dart 代码一行都不用改。

MethodChannel('flutter_screen_recording')

上游是 monorepo：真正的包在flutter_screen_recording/，而 example 工程在仓库根目录的example/。我第一次搭骨架时把 example 放进了子包，导致示例跑不起来，后来删掉重做。

三、实际环境

Flutter 鸿蒙环境搭建不在本文重复展开，直接参考 Flutter OH 环境搭建指南。

组件	版本
Flutter OH	`3.47.4-ohos-1.0.4`
Dart	`3.13.3`
DevEco Studio	`26.0.0 Release`
HarmonyOS SDK	API 26
测试设备	华为畅享 90 Pro Max（CHZ-AL00），HarmonyOS`7.0.0.109`（API 26）
目标库	`flutter_screen_recording 2.0.24`

flutter--versionhdc list targets

这里要特别注意 Flutter 版本：本机同时装了3.41和3.47.4-ohos，3.41会因为 SDK 约束解析失败，构建时必须显式把3.47.4-ohos放到 PATH 前面。

四、确认上游版本并同步到 AtomGit

上游包地址是 “https://github.com/Isvisoft/flutter_screen_recording”，版本2.0.24使用 MIT License。适配前我用 AtomGit API（GET /api/v5/repos/<org>/<lib>）在oh-flutter、hxa-flutter、CPF-Flutter三个组织做了排重，未发现同名 OHOS 实现。

gitclone https://atomgit.com/oh-flutter/flutter_screen_recording.gitcdflutter_screen_recordinggitswitch feat/ohos_flutter_screen_recording_2.0.24gitlog--oneline-5

五、创建适配分支并检查工程结构

gitswitch-cfeat/ohos_flutter_screen_recording_2.0.24

关键目录如下：

flutter_screen_recording/ ├── flutter_screen_recording/ # 实际 Flutter 包 │ ├── lib/ │ └── ohos/ # 本适配新增 │ ├── index.ets │ └── src/main/ets/components/plugin/ │ └── FlutterScreenRecordingPlugin.ets ├── example/ # 注意：在仓库根，不在子包下 ├── flutter_screen_recording_platform_interface/ └── flutter_screen_recording_web/

flutter:plugin:platforms:ohos:pluginClass:FlutterScreenRecordingPlugin

pluginClass必须和ohos/index.ets导出的类名一致。这一步是本批次最容易踩的坑：pubspec.yaml里漏掉ohos声明时，Flutter 生成的GeneratedPluginRegistrant.ets是个空try块，Dart 侧调用直接返回null，构建期没有任何报错，运行时也不抛MissingPluginException，只是所有返回值都是空的。我第一次跑is_lock_screen2就卡在这里，查了半天日志才发现注册表是空的。

六、适配过程：注册通道并对齐语义

通道名必须与上游 Dart 源码逐字一致。本库的映射如下：

方法	OpenHarmony 实现	说明
`startRecordScreen`	`media.createAVScreenCaptureRecorder()`→`init({fd,...})`→ `startRec	yes
`stopRecordScreen`	`stopRecording()`并关闭文件	yes
`getPlatformVersion`	返回平台标识	yes

核心代码：

switch(call.method){case'startRecordScreen':this.start(result);break;case'stopRecordScreen':this.stop(result);break;case'getPlatformVersion':result.success('OpenHarmony');break;default:result.notImplemented();}

七、构建配置与签名

示例工程的目标 SDK 对齐到 26，与@ohos/flutter_ohos的要求一致：

{ "name": "default", "compatibleSdkVersion": "26.0.0", "targetSdkVersion": "26.0.0", "runtimeOS": "HarmonyOS" }

Demo 的AppScope/app.json5统一成com.example.flutter_oh_demo。签名 profile 里绑定的 bundleName 必须与它一致，否则SignHap直接报00303074 Configuration Error。证书、p12、p7b 和密码不提交到仓库。

另外两个和签名、SDK 相关的坑：

build-profile.json5里签名材料写${HOME}不会展开，必须是绝对路径，否则报00303107 Invalid storeFile value。
DEVECO_SDK_HOME要指向Contents/sdk（含版本目录的上一级）。指到sdk/default报00303312 Cannot find the corresponding SDK version，完全不设则报00303217。

八、通过 AtomGit 引入适配版

在业务工程中使用时锁定 TAG：

dependencies:flutter_screen_recording:git:url:https://atomgit.com/oh-flutter/flutter_screen_recording.gitref:2.0.24-ohos.1

flutter pub get

然后在pubspec.lock里确认source: git、AtomGit 地址和resolved-ref，避免解析到 pub.dev 的同名版本。

九、构建、安装和真机验证

cdexample flutter pub get flutter build hap--debughdcinstall-rbuild/ohos/hap/entry-default-signed.hap hdc shell aa start-aEntryAbility-bcom.example.flutter_oh_demo

构建输出为✓ Built build/ohos/hap/entry-default-signed.hap.，随后hdc报告安装成功。所有示例共用同一个 bundleName，重装后要先aa force-stop再aa start，否则系统只是把旧任务拉到前台，看到的是上一次安装的界面——这个现象在批量验证时骗过我一次。

取实测值时用uitest定位控件并点击，而不是靠肉眼判断：

hdc shell"uitest dumpLayout -p /data/local/tmp/l.json"hdcfilerecv /data/local/tmp/l.json /tmp/l.json hdc shell"uitest uiInput click <x> <y>"hdc shell"uitest screenCap -p /data/local/tmp/s.png"

十、适配结果和当前边界

鸿蒙录屏要求应用在前台且由系统弹出授权确认框，未授权或后台调用会失败，此时返回RECORD_START_FAILED，不返回「录制中」的假状态。
录制参数在实现中固定为 1080×2340 / 8Mbps 视频 / 48kHz 双声道音频，不接受 Dart 侧自定义分辨率。
输出文件固定落在应用沙箱cacheDir，不直接写相册，需要外部可访问时由 Dart 侧另行导出。

十一、FAQ

Q1：为什么开始录屏会弹窗？

原因：鸿蒙录屏要求应用在前台并由系统弹出授权确认，这是系统行为，不是插件加的。自动化脚本无法替代人工确认。

Q2：录制参数能改吗？

原因：当前实现固定 1080×2340 / 8Mbps 视频 / 48kHz 双声道，不接受 Dart 侧自定义分辨率，这一点在遗留问题里标注了。

Q3：init 为什么需要文件描述符？

原因：AVScreenCaptureRecorder.init()的配置里fd是必填项，不是路径。所以先fileIo.openSync(path, READ_WRITE | CREATE)拿fd，stopRecording后再关闭句柄，避免文件句柄泄漏。

十二、总结

flutter_screen_recording 2.0.24在鸿蒙上已经接入真实系统能力，Dart 侧 API 与上游保持一致。本文的验证结果全部来自 HarmonyOS API 26 真机，没有占位返回值；平台本身不具备的能力在正文和 README 中都标注为边界。

十三、参考资料和仓库地址

适配仓库主页
适配分支
适配 TAG
ArkTS 通道实现
鸿蒙适配说明
pub.dev 包页面
pub.dev 2.0.24 版本页
上游仓库
Flutter 官方平台通道文档
Flutter OH 鸿蒙 SDK 仓库
HarmonyOS 开发者官方文档

欢迎加入CPF-Flutter 鸿蒙社区：https://atomgit.com/CPF-Flutter

企业官网建设流程全解析