SEO 信息

• SEO 标题：动图魔方技术拆解 12：GIF 导出进度、取消按钮与异常恢复
• SEO 摘要：基于 HarmonyOS NEXT / ArkTS 项目“动图魔方”，本文继续拆解 GIF 导出体验层：ExportSignal.ets 如何用协作式取消把“取消导出”从按钮文案变成真实任务分支，Index.ets 怎样统一管理 exporting、exportProgress、exportStage 和 statusText，以及 ExportService.ets 如何在视频抽帧、GIF 重编辑、3D 合成和最终编码之间保证异常可恢复、像素资源可释放、作品列表可闭环。文章结合真实工程代码、页面截图和验收清单，适合正在做 HarmonyOS 媒体工具、ArkTS 长任务反馈或本地 GIF 编辑器的开发者参考。
• 关键词：HarmonyOS, ArkTS, GIF 导出, 导出进度, 取消导出, 异常恢复, ExportSignal, ExportService, TaskPool
• 文章封面：doc/csdn-series/covers/cover-12-export-progress-cancel-recovery.jpg
• 投稿方向：普通技术拆解 / 导出交互与异常恢复
• 项目环境：HarmonyOS SDK 6.1.0(23)、ArkTS、DevEco Studio、GIFRubiksCube

第 11 篇已经把 TaskPool 后台编码和 UI 线程保护拆开了，但对真实用户来说，“线程池已经接入”还不等于“导出体验合格”。如果进度条不可信、取消按钮点了没反应、失败后页面状态收不回来，最终感知仍然是这个工具不稳定。ExportSignal.ets、ExportService.ets 与 Index.ets 这一层，解决的正是“后台任务已存在”之后的导出体验问题。

一、真实工程问题背景

“动图魔方”的导出不是一个单步骤动作，而是多段串联：

1. 图片编辑时，要先把素材列表交给 FrameProcessor.buildImageGifFrames()。
2. 视频转 GIF 时，要先经 VideoFrameExtractor.extract() 抽帧，再统一处理 PixelMap[]。
3. GIF 再编辑时，要从 ImageSource.createPixelMapList() 读出多帧，并恢复真实逐帧延迟。
4. 3D 动图和浅 3D 动图还要经过能力探测、重建或合成，再进入编码。

这意味着“导出中”这几个字背后实际包含了准备、抽帧、逐帧处理、编码、写文件、作品入库多个阶段。用户只看到一个按钮，但工程上必须回答 4 个问题：

1. 任务开始后，页面怎样持续给出可信进度。
2. 用户点击取消后，怎样尽快停止后续处理而不是继续白跑。
3. 中途报错时，怎样区分“用户取消”和“真实失败”。
4. 不管成功、失败还是取消，怎样把页面、实况窗、服务卡片和资源释放都收回到一致状态。

二、本文目标与边界

本文重点回答 5 个问题：

1. ExportSignal 为什么要同时承载“进度回报”和“协作式取消”。
2. Index.ets 为什么要显式维护 exporting、exportProgress、exportStage 与 statusText。
3. ExportService 在多种导出入口之间如何统一接入取消与异常恢复。
4. 为什么 finally 和 releasePixelMaps() 这类收尾逻辑必须存在。
5. 作品页闭环为什么是导出体验的一部分，而不是额外功能。

本文不展开的部分：

1. TaskPool 后台编码边界，已在第 11 篇覆盖。
2. FrameProcessor 的裁剪、滤镜、字幕与调色板量化细节，已在第 08、09 篇覆盖。
3. GIF 多帧重编辑入口和 PixelMapList 读取细节，已在第 10 篇覆盖。

三、导出体验先要有一个可识别的状态机

Index.ets 里的 exportCurrent() 一开始就不是直接 await ExportService.exportGif()，而是先把页面切进导出态：

private async exportCurrent(): Promise<void> {
  if (this.exporting) {
    return;
  }
  if (this.sourceUris.length === 0) {
    this.statusText = '请先选择真实素材，再导出作品';
    return;
  }
  this.exporting = true;
  this.exportProgress = 0;
  this.exportStage = '准备中';
  this.statusText = this.editorType === 'video' ? '正在抽取视频帧并编码…' : '正在编码 GIF…';
  const signal = new ExportSignal();
  const ctx = this.ctx();
  this.lastCardPercent = -1;
  // ...
}

这一段代码看起来普通，但它做了一个非常关键的工程决策：把“导出”明确建模为一个持续中的状态，而不是一次点击事件。

这样做有 4 个直接收益：

1. this.exporting 能立刻阻止重复点击，避免并发导出。
2. exportProgress 和 exportStage 给进度条与阶段文案提供统一数据源。
3. statusText 能及时区分“未选素材”“准备中”“正在取消”“导出失败”这些不同语义。
4. 后续无论是作品页跳转、取消恢复还是异常处理，都有明确的状态起点和终点。

对于工具类 App，这种状态机比“点按钮后 showToast”更重要，因为长任务一旦超过几秒，用户就会开始根据页面是否继续变化来判断应用是否可靠。

四、取消导出要做成协作式信号，不要做成假按钮

项目里承担这件事的是 ExportSignal.ets：

export const EXPORT_CANCELLED = 'EXPORT_CANCELLED';

export class ExportSignal {
  private canceled: boolean = false;
  onProgress: (done: number, total: number, stage: string) => void = () => {};

  cancel(): void {
    this.canceled = true;
  }

  report(done: number, total: number, stage: string): void {
    this.onProgress(done, total, stage);
  }

  checkCancelled(): void {
    if (this.canceled) {
      throw new Error(EXPORT_CANCELLED);
    }
  }
}

这里最值得注意的是两点：

1. cancel() 并不直接强杀任务，而是把取消状态交给处理链上的各个阶段协作检查。
2. checkCancelled() 抛出的不是匿名错误，而是统一的 EXPORT_CANCELLED 语义。

这套设计比“取消按钮只改个文案”更靠谱，原因很现实：

1. GIF 导出链路里既有抽帧，也有逐帧处理和编码，很多步骤无法安全强停。
2. 协作式取消可以在阶段边界尽快退出，避免留下半成品文件和未释放资源。
3. 明确错误语义后，页面层就能把“用户取消”与“系统失败”区别展示。

对应到 UI 层，取消入口很克制：

private cancelExport(): void {
  if (this.exportSignal !== null) {
    this.exportSignal.cancel();
    this.statusText = '正在取消…';
  }
}

这说明页面取消不是自己处理业务，而是只负责发送取消信号和更新当前提示，真正的中断时机仍由底层导出链控制。这样分层后，按钮逻辑才不会和导出实现纠缠在一起。

五、进度反馈必须跨页面、实况窗和服务卡片保持一致

exportCurrent() 里最关键的一段不是开始导出，而是怎么消费 signal.onProgress：

signal.onProgress = (done: number, total: number, stage: string) => {
  const ratio = total > 0 ? done / total : 0;
  this.exportProgress = ratio;
  this.exportStage = stage;
  const pct = Math.round(ratio * 100);
  if (pct !== this.lastCardPercent) {
    this.lastCardPercent = pct;
    LiveViewService.update(stage, pct);
    CardBridge.pushAll(ctx, true, pct, stage);
  }
};
this.exportSignal = signal;
await BackgroundRenderService.start(ctx);
await LiveViewService.start('准备中', 0);
await CardBridge.pushAll(ctx, true, 0, '准备中');

这段代码统一了 3 层反馈：

1. 页面内：exportProgress、exportStage、statusText 直接影响当前编辑页。
2. 实况窗：LiveViewService.start/update/stop() 让系统层看到同一任务状态。
3. 服务卡片：CardBridge.pushAll() 把导出态同步给桌面卡片。

如果这三层各自维护自己的导出状态，很快就会出现不一致：

1. 页面显示 60%，卡片还停在 20%。
2. 页面已失败，实况窗还显示导出中。
3. 页面已回到作品页，卡片仍保留上一次百分比。

当前实现把三者都收口到 ExportSignal 回调和 exportCurrent() 生命周期里，这样导出任务只有一个事实来源，体验才不会分裂。

另外，这里还做了一个很实际的性能保护：

const pct = Math.round(ratio * 100);
if (pct !== this.lastCardPercent) {
  this.lastCardPercent = pct;
  LiveViewService.update(stage, pct);
  CardBridge.pushAll(ctx, true, pct, stage);
}

也就是只在整数百分比变化时才更新跨层状态，避免逐帧高频刷新把原本为了解决卡顿而设计的反馈链路重新变成性能负担。

六、ExportService 的真正职责是把不同入口统一收束

第 12 篇如果只讲 ExportSignal 还不够，因为取消和异常恢复最终要落在每一条导出入口上。ExportService.buildGif() 正是统一入口：

private static async buildGif(preset: ExportPreset, signal: ExportSignal): Promise<GifBuildOutput> {
  if (preset.editorType === 'image') {
    const delayCs = Math.max(1, Math.round(preset.frameDuration * 100));
    const result = await FrameProcessor.buildImageGifFrames(preset.sourceUris, delayCs, ExportService.editOptions(preset), signal);
    return await ExportService.encodeResult(result, preset);
  }
  if (preset.editorType === 'video') {
    return await ExportService.buildFromVideo(preset, signal);
  }
  if (preset.editorType === 'gif') {
    return await ExportService.buildFromAnimatedGif(preset, signal);
  }
  if (preset.editorType === 'threeD') {
    return await ExportService.buildFromSynthetic(preset, 'rotate3d', signal);
  }
  if (preset.editorType === 'depth') {
    return await ExportService.buildFromSynthetic(preset, 'parallax', signal);
  }
  const tiny = ExportService.createTinyGif();
  return { bytes: tiny, width: 1, height: 1, frameCount: 1 };
}

这里的价值在于，不同类型素材虽然处理路径不同，但最终都共享同一个取消信号和统一输出模型 GifBuildOutput。这带来两个稳定性收益：

1. 上层页面不需要分别处理图片、视频、GIF、3D 的异常风格。
2. 后续只要某一条链路遗漏取消检查或资源释放，就能在服务层被发现并修正，而不是散落到 UI 代码。

真实项目里，统一入口比“每个按钮各写一套导出逻辑”更重要，因为只有入口统一，体验标准才有可能统一。

七、异常恢复不是 catch 一下就够，资源释放要跟上

视频和 GIF 再编辑这两条链路最容易踩坑的，是 PixelMap[] 生命周期。如果只关注成功路径，失败或取消时很容易忘记释放资源。

视频导出的处理方式：

private static async buildFromVideo(preset: ExportPreset, signal: ExportSignal): Promise<GifBuildOutput> {
  const pixelMaps = await VideoFrameExtractor.extract(preset.sourceUris[0], preset.duration, fps, signal);
  try {
    signal.checkCancelled();
    const result = await FrameProcessor.buildFramesFromPixelMaps(pixelMaps, [delayCs], ExportService.editOptions(preset), signal);
    return await ExportService.encodeResult(result, preset);
  } finally {
    await ExportService.releasePixelMaps(pixelMaps);
  }
}

GIF 再编辑也是同样模式：

private static async buildFromAnimatedGif(preset: ExportPreset, signal: ExportSignal): Promise<GifBuildOutput> {
  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);
  }
}

这里的设计说明了一个工程原则：异常恢复不能只看页面是不是报错，还要看底层临时资源有没有清理干净。

如果没有 finally 和 releasePixelMaps()，常见问题会是：

1. 导出取消后内存里还挂着一批 PixelMap。
2. 用户下一次再导出时，应用更容易卡顿或崩溃。
3. 问题表面上像是“第二次导出不稳定”，根因其实是上一次失败后的资源泄漏。

所以在媒体工具类 App 里，“异常恢复”至少包含三层：错误语义、状态回收、资源释放。缺一层都不算完整。

八、成功路径同样需要闭环，作品列表是导出结果的一部分

很多技术文章会把导出讲到“字节流写进文件”就结束，但真实工具不是这样。Index.ets 在成功后继续做了作品闭环：

const preset = this.createPreset(`${this.titleOf(this.editorType)}_${this.works.length + 1}`);
const work = await ExportService.exportGif(this.ctx(), preset, signal);
const next = this.works.slice();
next.unshift(work);
this.works = next;
await StorageService.saveWorks(this.ctx(), next);
this.page = 'works';
this.statusText = `已导出：${work.meta}`;

这一段说明导出成功至少还包括 4 件事：

1. 返回统一的 WorkEntry，而不是裸文件路径。
2. 把新作品插入当前列表顶部。
3. 立即持久化到本地存储，保证重启后仍可见。
4. 页面切到作品页，让用户马上看到结果。

这就是为什么“作品列表”不是边角功能。对用户来说，导出任务只有在结果能立刻被看见、被再次打开、被分享时，才算真正完成。

九、页面与工程证据

9.1 编辑页已经具备长任务所需的真实操作入口

当前编辑页集中了比例、帧率、清晰度、滤镜、字幕、亮度/对比度和导出动作。这种单页编辑器一旦没有进度和取消反馈，用户体感就会直接变成“点了导出以后不知道应用是不是死了”。

9.2 导出区是长任务交互的主要承载面

页面底部明确承载了导出按钮和输出参数区，说明这个项目的导出不是隐藏在系统菜单里的轻量动作，而是工具页主流程的一部分。因此导出进度、取消按钮和异常提示必须做成主流程级交互。

9.3 作品页闭环证明导出后的状态收尾是必要的

作品页能立即承接导出结果，说明这条链路最终影响的不只是文件写出，还包括列表刷新、页面跳转和状态文案更新。这也是为什么 finally 收尾和 StorageService.saveWorks() 必须被纳入导出体验讨论。

十、工程复盘

结合第 11、12 篇，可以把“长任务体验”进一步拆成 5 条更稳定的工程结论：

1. 后台编码解决的是“不阻塞”，但不能自动解决“可感知”。
2. ExportSignal 最核心的作用不是一个布尔值，而是把进度与取消统一成一套任务协议。
3. 页面层必须显式维护导出状态机，否则成功、取消、失败三条路径迟早会串线。
4. ExportService 的价值不只是编码，而是把不同素材入口的取消、异常和资源释放拉回统一标准。
5. 导出成功后的作品闭环、失败后的状态恢复、取消后的资源清理，本质上属于同一个体验问题。

十一、验收清单

验收项	结果	说明
页面导出前会检查素材是否为空	通过	sourceUris.length === 0 时直接提示
页面进入导出态后会统一维护进度与阶段文案	通过	exporting/exportProgress/exportStage/statusText 同步设置
取消导出具备独立错误语义	通过	ExportSignal.checkCancelled() 抛出 EXPORT_CANCELLED
页面支持“正在取消…”到“已取消导出”的状态演进	通过	cancelExport() + catch 分支明确区分
实况窗与服务卡片接入同一任务生命周期	通过	LiveViewService 与 CardBridge 在导出开始、更新、结束时同步
跨层进度更新已做百分比节流	通过	pct !== this.lastCardPercent 时才桥接更新
图片 / 视频 / GIF / 3D 导出共用统一服务入口	通过	ExportService.buildGif() 按 editorType 路由
视频与 GIF 导出失败后会释放 PixelMap[]	通过	finally 中调用 releasePixelMaps()
导出成功后作品会写入本地持久层并跳转作品页	通过	StorageService.saveWorks() + this.page = 'works'
成功、失败、取消后页面与卡片状态都能收回	通过	exportCurrent() 的 finally 统一清理

十二、小结

第 12 篇真正拆开的，不是某个单独 API，而是媒体工具里“用户能不能相信导出过程”这件事。在“动图魔方”里，ExportSignal 负责让取消与进度变成一套可传递协议，ExportService 负责把不同素材入口统一成同一种异常恢复标准，Index.ets 负责把状态变化准确地投射到页面、实况窗、卡片和作品页。这样导出功能才不是“后台偷偷跑完”，而是一个可以被用户感知、打断和验证的长任务流程。

十三、下一篇衔接

下一篇进入第 13 篇：动图魔方技术拆解 13：Preferences 实现作品列表、草稿和主题偏好持久化。会继续沿着导出后的作品闭环往下拆，重点讲 StorageService 如何把作品记录、草稿数据和主题偏好收束到本地持久化模型里。