鸿蒙 HarmonyOS 6 | Media Kit 屏幕捕获填充模式迁移详解

文章目录前言一、填充模式真正影响的是什么二、代码里最关键的是策略对象和调用时序三、适配时别只看设备类型先看内容和输出比例四、排查方式总结前言做屏幕录制时最容易被忽略的一层是捕获源尺寸和目标输出尺寸并不总是一致。手机长屏录到 16:9 视频平板横屏录到固定比例画布或者应用自己指定了一组输出宽高这几种情况都会让画面进入缩放、裁切、留边三选一的处理过程。鸿蒙 6 这一轮在 Media Kit 里把这件事收进了录屏策略新增了屏幕捕获填充模式的 C API同时引入了配套的填充模式枚举和策略对象。相关能力已经进入 6.0 的新增特性列表OH_AVScreenCapture_CaptureStrategy也从 API version 20 开始可用。这类能力一旦开放录屏页面的控制粒度会高很多。项目可以继续沿用原来的输出宽高也可以针对直播、教学录屏、UI 演示、游戏录制分别做策略切换。文档里的录屏最佳实践还专门提到屏幕宽高设置不当会导致录制视频出现黑边这个提醒本身已经说明输出尺寸和填充方式是联动关系。一、填充模式真正影响的是什么这次新增能力的抓手很明确录屏策略对象OH_AVScreenCapture_CaptureStrategy用来承接策略设置填充模式通过OH_AVScreenCapture_StrategyForFillMode配进去再交给OH_AVScreenCapture_SetCaptureStrategy挂到录屏实例上。6.0 的新增能力里已经点名提到屏幕录制新增支持通过 C API 设置目标区域内捕获画面的填充模式。放到实际效果上填充模式主要在解决一个问题录制出来的画面到底优先铺满目标区域还是优先保住完整内容。工程上可以把它理解成两种思路。第一种追求铺满目标区域里尽量不留空代价通常是边缘会被裁掉。第二种追求完整原始内容尽量全保留代价通常是上下或左右会出现黑边。这个判断和视频、图片里常见的 cover 与 contain 很接近录屏场景只是在系统底层把它做成了策略开关。相关 API 的命名和文档里对黑边风险的提示已经能支撑这种工程化理解。这件事在比例差异明显的场景里最容易看出来。举个实际的例子捕获源如果是 2340×1080目标输出是 1920×1080源画面更宽。铺满思路下系统会优先保住目标区域被完整覆盖横向超出的部分会被裁掉左右边缘各损失一部分画面。完整保留思路下系统会先把宽度缩进目标区域最终得到大约 1920×886 的有效画面上下各留出接近 97 像素的黑边。这部分是按常见填充逻辑做出来的计算推导用来帮助开发时预估效果比直接到真机上盲试更省时间。支持填充模式和录屏宽高自定义这两个前提都已经在当前文档里列出来了。二、代码里最关键的是策略对象和调用时序这组能力的接入路径已经很清楚。先创建录屏实例再创建OH_AVScreenCapture_CaptureStrategy然后把填充模式写进策略对象再把策略对象挂到录屏实例上。相关指南和录屏写文件示例都已经出现了OH_AVScreenCapture_CreateCaptureStrategy()和OH_AVScreenCapture_SetCaptureStrategy(capture, strategy)这套写法说明策略对象已经进入正式使用路径。代码里最需要控制的是时序。SetCaptureStrategy应该放在真正开始录屏之前尽量和其他录屏前置配置放在一起处理。录屏写文件的文档片段里策略设置和屏幕 ID 回调这类动作都处在开始录屏前的准备阶段。把策略设置拖到启动之后再做后面排查效果异常时会很麻烦。下面这段代码把核心配置流程收了一遍重点放在填充模式和策略绑定不再塞过多无关逻辑#includemultimedia/player_framework/native_avscreen_capture.hint32_tConfigureFillMode(structOH_AVScreenCapture*capture,OH_AVScreenCapture_FillMode mode){if(captureNULL){return-1;}OH_AVScreenCapture_CaptureStrategy*strategyOH_AVScreenCapture_CreateCaptureStrategy();if(strategyNULL){return-1;}OH_AVSCREEN_CAPTURE_ErrCode retOH_AVScreenCapture_StrategyForFillMode(strategy,mode);if(ret!AV_SCREEN_CAPTURE_ERR_OK){// 这里按项目约定补资源清理returnret;}retOH_AVScreenCapture_SetCaptureStrategy(capture,strategy);if(ret!AV_SCREEN_CAPTURE_ERR_OK){// 这里按项目约定补资源清理returnret;}// 后续再进入 Init、StartScreenCapture 等流程returnAV_SCREEN_CAPTURE_ERR_OK;}这段代码里最重要的点有三个。第一填充模式的配置对象和录屏实例分开管理。第二填充模式先写入策略对象再整体挂到录屏实例。第三策略配置完成后再进入真正的初始化和启动流程。录屏示例文档已经明确给出了策略对象创建和绑定的写法Release()用来销毁录屏实例、释放资源这一点也已经在写文件示例里点出来了。三、适配时别只看设备类型先看内容和输出比例填充模式这件事表面上像设备适配真正落地时先看内容。游戏录屏、短视频录屏、横屏直播这几类场景更容易接受边缘裁切画面铺满通常更重要。教程演示、表单录屏、后台管理系统录屏、UI 走查视频这些场景对边缘内容更敏感留边通常更稳。鸿蒙当前文档已经把录屏能力往文件输出、码流输出、自定义场景、矩形区域录制这些方向展开了说明录屏早就不只是单一的系统全屏录像能力应用自己要做的取舍会越来越多。设备尺寸当然也要看但不需要把规则写得太复杂。手机长屏转标准横屏视频时比例差异最明显裁切或黑边至少会出现一种。平板和大屏设备录到固定比例视频时留边的概率更高。应用如果本身支持自定义输出宽高最先该做的事不是切模式而是先把目标宽高设置得合理一些。录屏最佳实践里已经直接提醒过屏幕宽高设置不当会让视频出现黑边这比一上来就堆设备分支更有用。项目里如果准备把这件事做成用户可选项界面层只需要把选择解释清楚就够了。给用户一个完整保留内容和画面优先铺满的切换入口比一口气讲清楚所有比例细节更有效。技术上只要把填充模式切换收回到同一个策略构建流程里后面维护成本不会高。API 6.0 已经把这套能力做成标准策略配置项目没必要自己再做一套裁剪和补边算法。四、排查方式这类功能最怕的情况是接口已经接了画面也录出来了但不同设备效果不一致。处理这类问题时优先排查三件事。第一目标输出宽高是不是设置得过于激进。第二填充模式是不是和当前内容类型不匹配。第三策略是不是在录屏开始前就已经挂上去了。当前文档已经明确指出宽高设置不当会带来黑边录屏示例也把策略设置放在开始录屏前的配置阶段这两点先看能省掉很多无效调试。性能上也别把事情想得太重。填充模式多了一层策略配置开发成本几乎不会成为瓶颈真正影响录制流畅度的还是分辨率、帧率、编码参数和设备本身的吞吐能力。高分辨率录屏时如果设备边跑边发热、帧率开始掉优先先降输出分辨率再看是否要调整填充策略。录屏 API 这条线本身已经同时覆盖文件写入、码流输出和自定义场景说明系统把录屏能力铺得很完整了应用侧更值得花时间的地方还是录制参数组合。如果项目里有比较重的录屏功能建议把填充模式、输出宽高、录屏场景一起提成一份集中配置。这样做有两个好处。第一排查黑边和裁切问题时更容易看出是哪一组参数组合导致的。第二后面如果新设备形态再变化或者项目要补更多录屏入口配置层能直接复用。OH_AVScreenCapture_CaptureStrategy本身就是给这类策略收口用的继续把逻辑分散到多个业务模块里后面会越来越乱。总结鸿蒙 6 API 20 这一轮把屏幕捕获填充模式正式收进了 Media Kit 的录屏策略体系相关 C API、策略对象和填充模式枚举都已经进了当前能力范围。项目里真正要处理的核心问题很明确录制画面在目标区域里到底追求铺满还是追求完整。只要输出宽高和捕获源比例不一致这个问题就绕不过去。工程上更稳的做法也很清楚。策略对象统一创建填充模式统一配置开始录屏前把策略挂好。业务层按内容类型去选模式参数层把输出宽高和录制场景一起收口。这样做下来黑边、裁切和设备差异都会更容易控住后面的录屏体验也会稳很多。