动图魔方技术拆解 10：GIF 多帧重编辑的 ImageSource 与 PixelMapList 实践

SEO 信息

• SEO 标题：动图魔方技术拆解 10：GIF 多帧重编辑的 ImageSource 与 PixelMapList 实践
• SEO 摘要：基于 HarmonyOS NEXT / ArkTS 项目“动图魔方”，本文拆解 GIF 多帧重编辑入口的真实工程实现：如何通过image.createImageSource()和createPixelMapList()读取 GIF 多帧，如何保留原始帧延迟，为什么需要把毫秒延迟转换成 GIF 编码使用的厘秒，以及在端侧批量处理PixelMap时怎样控制释放时机、防止内存占用失控。文章结合ExportService.ets真实代码、工程截图和验收清单，适合正在做 HarmonyOS GIF 编辑器、动画帧处理或本地媒体工具的开发者参考。
• 关键词：HarmonyOS, ArkTS, ImageSource, PixelMapList, GIF 重编辑, 帧延迟, PixelMap 释放, ExportService
• 文章封面：doc/csdn-series/covers/cover-10-gif-imagesource-pixelmaplist.jpg
• 投稿方向：普通技术拆解 / GIF 重编辑
• 项目环境：HarmonyOS SDK6.1.0(23)、ArkTS、DevEco Studio、GIFRubiksCube

第 09 篇把FrameProcessor这一层的统一处理流水线拆开了，但 GIF 再编辑还有一个更前面的现实问题：已有动图不是一张图，而是一组按时序播放的多帧。要把它重新裁剪、加字幕、调滤镜，第一步不是编码，而是先把原 GIF 按帧稳定读出来。ExportService.buildFromAnimatedGif()处理的正是这个入口。

一、真实工程问题背景

图片拼 GIF 和视频转 GIF 的输入都比较直观：

1. 图片入口本来就是多张静态图。
2. 视频入口可以按目标帧率主动抽帧。

但 GIF 重编辑不是这样。对于用户来说，“编辑 GIF”意味着两件事必须同时成立：

1. 要把原 GIF 的每一帧真正读出来，而不是只读首帧做静态图编辑。
2. 要尽量保留原来的播放节奏，否则重导出后会出现“动作变快了”或“停顿点没了”的问题。

这会马上引出几个端侧工程问题：

1. HarmonyOS 上如何读取 GIF 的全部帧，而不是只拿一张PixelMap。
2. 原 GIF 的帧延迟如果缺失、异常或读取失败，导出链路怎样回退才不会直接崩。
3. PixelMap[]一旦按帧展开，端侧内存压力会明显上升，释放时机必须明确。
4. 读帧阶段不能自己再发明一套编辑逻辑，最终还要汇回第 09 篇讲过的统一处理流水线。

二、本文目标与边界

本文重点回答 4 个问题：

1. ExportService如何通过ImageSource进入 GIF 多帧重编辑模式。
2. createPixelMapList()和getDelayTimeList()在这条链路里分别承担什么职责。
3. 为什么要把原始毫秒延迟转换成 GIF 编码阶段可直接使用的厘秒。
4. 在端侧批量处理 GIF 帧时，如何安排source和pixelMaps的释放顺序。

本文不展开的部分：

1. 统一裁剪、滤镜、字幕叠加与量化，已经在第 09 篇覆盖。
2. GIF89a 文件落盘与 LZW 压缩，已经在第 06、07 篇覆盖。
3. 后台编码与 UI 线程隔离，留到第 11 篇继续拆GifEncodeTask。

三、GIF 重编辑入口在导出链路中的位置

整个导出入口先按editorType分流：

private static async buildGif(preset: ExportPreset, signal: ExportSignal): Promise<GifBuildOutput> { if (preset.editorType === 'image') { // ... } if (preset.editorType === 'video') { return await ExportService.buildFromVideo(preset, signal); } if (preset.editorType === 'gif') { return await ExportService.buildFromAnimatedGif(preset, signal); } // ... }

也就是说，GIF 再编辑并没有走图片入口“伪装成多张图”，而是单独保留了一个明确分支。这样做很重要，因为 GIF 输入和图片输入的核心差异不在“像素内容”，而在“时间信息”：

1. 图片序列的帧时长可以由当前导出参数决定。
2. GIF 多帧重编辑必须优先尊重原始动图的帧延迟。

如果这两类输入混进同一入口，时间维度的信息就会丢。

四、buildFromAnimatedGif 的最小闭环

这条链路的核心代码其实很短：

private static async buildFromAnimatedGif(preset: ExportPreset, signal: ExportSignal): Promise<GifBuildOutput> { if (preset.sourceUris.length === 0) { throw new Error('No GIF source'); } const source = image.createImageSource(preset.sourceUris[0]); const pixelMaps = await source.createPixelMapList({ desiredPixelFormat: image.PixelMapFormat.RGBA_8888 }); const delaysCs = await ExportService.readGifDelaysCs(source, preset); await source.release(); try { signal.checkCancelled(); const result = await FrameProcessor.buildFramesFromPixelMaps( pixelMaps, delaysCs, ExportService.editOptions(preset), signal ); return await ExportService.encodeResult(result, preset); } finally { await ExportService.releasePixelMaps(pixelMaps); } }

这段实现有 5 个顺序点不能乱：

1. 先createImageSource()建立 GIF 输入源。
2. 再createPixelMapList()一次性拿到多帧。
3. 然后读取原 GIF 帧延迟。
4. source用完先释放，但pixelMaps还要继续传给后续处理链。
5. 最后不管成功失败，都在finally里释放每一帧PixelMap。

这个顺序背后体现的其实就是资源所有权转移。

五、为什么必须使用 createPixelMapList，而不是只读单帧

如果只把 GIF 当普通图片读，最常见的错误就是只拿首帧。那样后面所有裁剪、滤镜和字幕逻辑虽然也能跑，但输出结果会直接退化成“静态图转 GIF”，跟用户预期完全不一致。

项目里选择的是：

const pixelMaps = await source.createPixelMapList({ desiredPixelFormat: image.PixelMapFormat.RGBA_8888 });

这里有两个关键点：

1. 直接获取PixelMap[]，明确告诉后续处理链“这是一个多帧输入”。
2. 目标像素格式固定成RGBA_8888，方便和视频抽帧、图片序列一样汇入统一帧处理流程。

也就是说，GIF 多帧入口在这里被主动标准化成了“逐帧 RGBA 数据”，而不是继续把它当封装格式对象往后传。

六、原始帧延迟为什么不能丢

GIF 再编辑最容易被忽视的一点，是“原图为什么看着有节奏”，很多时候并不只靠帧内容本身，而是靠帧时长。

项目里专门保留了读延迟的逻辑：

private static async readGifDelaysCs(source: image.ImageSource, preset: ExportPreset): Promise<number[]> { try { const delaysMs: number[] = await source.getDelayTimeList(); if (delaysMs && delaysMs.length > 0) { const delaysCs: number[] = []; for (let index = 0; index < delaysMs.length; index++) { delaysCs.push(Math.max(1, Math.round(delaysMs[index] / 10))); } return delaysCs; } } catch (err) { } const fps = ExportService.parseFps(preset.fps); return [Math.max(1, Math.round(100 / fps))]; }

这里最核心的不是 API 调用本身，而是设计态度：

1. 优先保留原 GIF 的逐帧 delay。
2. 读取失败时不直接中断，而是回退到按当前导出帧率推导出的均匀延迟。

这意味着 GIF 重编辑入口不会因为个别来源动图 metadata 不规范就完全失效。

七、为什么要把毫秒转换成厘秒

getDelayTimeList()返回的是毫秒语义，但后面FrameProcessor和 GIF 编码器使用的是delayCs，也就是厘秒。

转换逻辑很直接：

delaysCs.push(Math.max(1, Math.round(delaysMs[index] / 10)));

这一步的工程意义是：

1. 跟 GIF 编码输出阶段统一时间单位，避免后面重复换算。
2. 通过Math.max(1, ...)避免 0 延迟帧进入编码阶段导致播放异常。
3. 读取阶段就把时间值标准化，后面FrameProcessor.buildFramesFromPixelMaps()只需要消费统一单位。

这类单位转换如果留到后面再做，很容易出错，尤其是在“原始 delay + speed 倍速 + reversed 倒放”叠加之后。

八、读取失败时为什么要回退到 fps 推导值

项目并没有假设所有 GIF 都规范到可以完整读出 delay list。它明确做了 fallback：

const fps = ExportService.parseFps(preset.fps); return [Math.max(1, Math.round(100 / fps))];

这意味着：

1. 如果 GIF 自带的延迟读不到，依然能继续编辑和导出。
2. 回退值直接绑定当前导出帧率，用户对节奏还有可预期的控制。
3. 后续buildFramesFromPixelMaps()即使拿到的 delay 数组长度不足，也有补位逻辑兜底。

而FrameProcessor里对 delay 的消费也是按这个思路设计的：

const delayCs = index < delaysCs.length ? delaysCs[index] : delaysCs[delaysCs.length - 1];

这类“长度不足时复用最后一个值”的处理，看起来普通，但很适合端侧容错。

九、为什么 source 和 pixelMaps 的释放顺序不能反

这一段是本文最关键的资源管理问题。

在buildFromAnimatedGif()里，source和pixelMaps的生命周期不是一回事：

1. source只负责“把 GIF 解出来”。
2. pixelMaps是解码后的逐帧数据，还要继续走裁剪、滤镜、字幕、量化和编码。

所以顺序必须是：

const delaysCs = await ExportService.readGifDelaysCs(source, preset); await source.release(); try { // 使用 pixelMaps } finally { await ExportService.releasePixelMaps(pixelMaps); }

如果反过来太早释放pixelMaps，后面的统一处理链就没有输入了；如果一直不释放，GIF 多帧编辑在端侧就会非常容易堆内存。

项目里专门抽了一个释放函数：

private static async releasePixelMaps(pixelMaps: image.PixelMap[]): Promise<void> { for (let index = 0; index < pixelMaps.length; index++) { try { await pixelMaps[index].release(); } catch (err) { } } }

这段代码的务实点在于：

1. 逐帧释放，不假设每一帧都一定能正常释放。
2. 用try/catch包裹单帧释放，避免某一帧异常把清理流程整个打断。
3. 资源清理被集中在一个函数里，后续如果需要补日志或监控点，也有固定入口。

十、GIF 重编辑为什么仍然要汇回 FrameProcessor

拿到pixelMaps和delaysCs以后，项目并没有另写一套 GIF 专属后处理，而是继续调用：

const result = await FrameProcessor.buildFramesFromPixelMaps( pixelMaps, delaysCs, ExportService.editOptions(preset), signal );

这意味着 GIF 再编辑和视频抽帧最终共用同一套帧处理协议。好处很直接：

1. 比例裁剪、滤镜、字幕、亮度/对比度在不同入口上行为一致。
2. 统一处理后再进入量化与编码，不会出现“GIF 再编辑入口视觉规则特殊化”。
3. 后续优化某个编辑参数时，只需要修一处主链路。

所以buildFromAnimatedGif()的真正职责不是“做完所有事情”，而是把 GIF 封装格式稳定拆成统一的逐帧输入。

十一、页面与工程证据

11.1 编辑页里 GIF 再编辑并不是假入口

编辑页把 GIF 重编辑和图片、视频入口并列暴露出来，说明这个能力在当前工程里是正式链路，不是留空按钮或静态演示。

11.2 测试素材入口说明项目已支持真实文件验证

项目当前已经把真实测试素材导入接入到编辑流程，GIF 重编辑入口不是只靠伪数据模拟，因此多帧读取和释放策略必须按真实文件处理。

11.3 导出后作品页闭环说明读帧结果能走完整链路

测试素材导出结果能回到作品页，说明“GIF 读帧 -> 统一编辑 -> 重新编码 -> 落盘”这一整条闭环已经打通。对于本文讨论的多帧重编辑入口来说，这个闭环比单独展示 API 调用更有说服力。

十二、工程复盘

把 GIF 多帧重编辑入口拆开后，可以更明确地看到 4 个结论：

1. buildFromAnimatedGif()的第一职责不是编辑，而是把 GIF 封装稳定拆成逐帧PixelMap[]。
2. 原始帧延迟必须作为正式输入保留下来，否则 GIF 重编辑会退化成“只保留帧内容、不保留节奏”。
3. source和pixelMaps的资源释放顺序是这条链路稳定性的关键点，不能随手写。
4. GIF 入口之所以能维护住复杂度，是因为它只负责“解码和时间信息保留”，后续编辑仍然回到统一的FrameProcessor主链。

十三、验收清单

十四、小结

第 10 篇真正想说明的，不是ImageSource这个 API 本身，而是 GIF 多帧重编辑入口为什么要被当成一条完整工程链路来处理。对于“动图魔方”这种本地优先的 HarmonyOS GIF 工具来说，能把原 GIF 稳定拆帧、尽量保留原节奏、在处理完成后及时释放资源，才是让再编辑能力真正可用的关键。

十五、下一篇衔接

下一篇进入第 11 篇：动图魔方技术拆解 11：TaskPool 长任务导出与 UI 线程保护。到那一篇我会继续拆GifEncodeTask.run()和ExportService.encodeResult()，把为什么要把 GIF 编码搬进TaskPool、失败时为什么要回退主线程同步编码，以及这套兜底策略如何保护编辑页交互讲清楚。