动图魔方技术拆解 11：TaskPool 长任务导出与 UI 线程保护

SEO 信息

• SEO 标题：动图魔方技术拆解 11：TaskPool 长任务导出与 UI 线程保护
• SEO 摘要 ：基于 HarmonyOS NEXT / ArkTS 项目"动图魔方"，本文拆解 GIF 导出链路里最容易被忽略却最影响体验的一层：为什么要把 LZW 编码这类计算密集任务移入 TaskPool，GifEncodeTask.ets 如何用最小并发边界封装 worker 线程，ExportService.ets 为什么必须保留主线程同步编码兜底，以及 Index.ets 如何把进度回调、取消导出、实况窗和服务卡片串成一条可感知的长任务链路。文章结合真实工程代码、页面截图和验收清单，适合正在做 HarmonyOS 媒体工具、ArkTS 长任务处理或本地 GIF 编辑器的开发者参考。
• 关键词：HarmonyOS, ArkTS, TaskPool, GIF 编码, 长任务, UI 线程, 导出进度, 取消导出, ExportService
• 文章封面 ：doc/csdn-series/covers/cover-11-taskpool-export-ui.jpg
• 投稿方向：普通技术拆解 / 长任务与导出体验
• 项目环境 ：HarmonyOS SDK 6.1.0(23)、ArkTS、DevEco Studio、GIFRubiksCube

第 06、07、08、09、10 篇已经把 GIF 文件结构、LZW、调色板量化、统一帧处理和 GIF 重编辑入口拆开了。但真实项目到了"能导出"这一步，体验问题才刚开始暴露：编码一旦压在 UI 线程里，页面按钮会卡、进度会假、取消会失效。GifEncodeTask.ets、ExportService.encodeResult() 和 Index.ets 这三处代码，解决的正是"功能能跑"和"用户敢用"之间的差距。

一、真实工程问题背景

"动图魔方"当前的导出并不是简单地把一张图写成 GIF，而是要先走完一整条本地链路：

1. 图片、视频、GIF 或合成帧先进入 FrameProcessor。
2. 统一做裁剪、滤镜、字幕、亮度/对比度和量化。
3. 再把 IndexedGifFrame[] 和全局调色板交给编码器。
4. 最终把字节流落盘、更新作品页、同步实况窗和服务卡片状态。

这里最耗时、最容易卡住交互的阶段，不是 UI 参数选择，而是最后的 GIF 编码。原因很直接：

1. LZW 编码是纯 CPU 密集任务。
2. 多帧 GIF 往往要处理成百上千个索引像素。
3. 用户导出时仍然会盯着页面，期待看到实时进度和"取消导出"立即生效。
4. 如果主线程被长时间占住，按钮、进度条、实况窗刷新和状态文案都会一起失真。

所以这一篇要回答的不是"GIF 怎么编码"，而是"在 HarmonyOS / ArkTS 项目里，怎么把导出做成一条可持续交互的长任务"。

二、本文目标与边界

本文重点回答 4 个问题：

1. 为什么 GifEncodeTask 只负责一件事：把 GIF 编码移进 TaskPool。
2. ExportService 为什么不能只做后台编码，还必须保留主线程兜底。
3. Index.ets 如何把进度、卡片、实况窗和取消导出串起来。
4. 这套设计为什么比"直接 await 一个 encode()"更适合真实工具类 App。

本文不展开的部分：

1. GIF89a 文件结构和 LZW 字典细节，已在第 06、07 篇覆盖。
2. 调色板量化与 FrameProcessor 帧处理，已在第 08、09 篇覆盖。
3. GIF 多帧重编辑入口与 ImageSource.createPixelMapList()，已在第 10 篇覆盖。

三、并发边界为什么要尽量小

GifEncodeTask.ets 的实现非常短：

import { taskpool } from '@kit.ArkTS';
import { GifEncoderService, IndexedGifFrame } from './GifEncoderService';

@Concurrent
function encodeGifConcurrently(frames: IndexedGifFrame[], palette: number[], loopCount: number): ArrayBuffer {
  return GifEncoderService.encodeIndexedFrames(frames, palette, loopCount);
}

export class GifEncodeTask {
  static async run(frames: IndexedGifFrame[], palette: number[], loopCount: number): Promise<ArrayBuffer> {
    const task: taskpool.Task = new taskpool.Task(encodeGifConcurrently, frames, palette, loopCount);
    const result = await taskpool.execute(task, taskpool.Priority.HIGH);
    return result as ArrayBuffer;
  }
}

这段代码最值得学的地方，不是 API 本身，而是它克制地只封装了"编码"这一件事。

原因有 3 个：

1. @Concurrent 约束下，入参和返回值必须可序列化，IndexedGifFrame[]、palette、ArrayBuffer 刚好符合这个边界。
2. 图像读取、PixelMap 生命周期、文件写入、UI 状态更新都不适合一起塞进 worker 线程。
3. 并发边界越小，失败时越容易回退，排查问题时也更容易定位到底是"数据准备失败"还是"后台编码失败"。

很多项目做长任务时容易一上来就把整条导出链打包进线程池，结果会遇到两个新问题：

1. 线程边界太大，调试困难。
2. 某个不支持并发序列化的对象混进来，整条链路直接不可用。

"动图魔方"这里反而做得很稳：上游先把所有数据整理成纯数组和标量，真正进入 TaskPool 的只有计算最重、边界最明确的编码步骤。

四、为什么后台编码之外还必须保留主线程兜底

ExportService.encodeResult() 里真正的关键不是 try，而是"TaskPool 优先 + 同步编码兜底"这一层设计：

private static async encodeResult(result: GifFrameBuildResult, preset: ExportPreset): Promise<GifBuildOutput> {
  let frames = result.frames;
  const speed = preset.speed > 0 ? preset.speed : 1;
  if (speed !== 1) {
    for (let index = 0; index < frames.length; index++) {
      frames[index].delayCs = Math.max(1, Math.round(frames[index].delayCs / speed));
    }
  }
  if (preset.reversed) {
    frames = frames.slice().reverse();
  }
  let bytes: ArrayBuffer;
  try {
    bytes = await GifEncodeTask.run(frames, result.palette, 0);
  } catch (err) {
    bytes = GifEncoderService.encodeIndexedFrames(frames, result.palette, 0);
  }
  return {
    bytes: bytes,
    width: frames[0].width,
    height: frames[0].height,
    frameCount: frames.length
  };
}

这里有 4 个现实考虑：

1. 导出体验的首选路径必须是后台编码，否则 UI 线程保护没有意义。
2. 但项目不能把"后台线程失败"直接等同于"导出功能失效"。
3. speed 和 reversed 这种时间维度处理应该发生在编码前，而不是分散到 UI 层。
4. 最终对外仍然只返回一个统一的 GifBuildOutput，调用方不需要感知底层到底走了哪条编码路径。

这类兜底很重要，因为真实设备环境不会永远理想：

1. TaskPool 可能因为并发限制、运行时差异或序列化边界问题失败。
2. 某些极端素材可能只在后台线程路径暴露问题。
3. 工具类 App 最怕"按钮点了没结果"，而不是"慢一点但至少能导出"。

所以这里的思路不是把并发当成唯一正确答案，而是把并发当成体验增强层，把同步编码当成可靠性兜底层。

五、导出页面为什么必须先进入"长任务模式"

真正把这套后台编码变成用户可感知体验的，是 Index.ets 的 exportCurrent()：

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;
  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, '准备中');
  // ...
}

这段实现的重点是，它没有把"导出"理解成一个单点按钮事件，而是显式切换到长任务状态机：

1. this.exporting = true：页面进入导出态，按钮可禁用，避免重复触发。
2. exportProgress / exportStage：页面内进度条和文本有了统一数据源。
3. LiveViewService.start()：实况窗同步进入"准备中"。
4. CardBridge.pushAll()：服务卡片也被拉进同一条状态链路。

这意味着即使真正的编码在后台线程里跑，用户依旧能从多个表面看到"任务已经开始且仍在推进"，而不是看着一个静止页面猜应用是不是卡死了。

六、进度回调为什么要做节流

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);
  }
};

代码注释已经点明了设计意图：避免逐帧高频刷新。

这一步为什么必要：

1. GIF 导出天然是多帧任务，进度回调频率可能非常高。
2. 页面本地状态更新还好，但实况窗、卡片桥接这类跨层通知如果每帧都发，会形成新的性能噪声。
3. 如果为了显示进度反而把 UI 刷新压垮，就等于"为了避免主线程卡顿，又重新制造了主线程卡顿"。

按百分比节流的好处是：

1. 页面内仍然保留连续进度感。
2. 卡片和实况窗只在关键节点更新，成本更可控。
3. 用户视角几乎感受不到损失，但系统层刷新压力明显降低。

这就是典型的工具类 App 经验：不是所有回调都值得原样冒泡到每个展示层。

七、取消导出为什么不能只是改一个按钮文案

页面上的"取消导出"背后，其实接的是一条协作式取消链路。

UI 入口很简单：

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

但真正让取消生效的是 ExportSignal：

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. 取消不是强杀线程，而是协作式中断。
2. 处理链上的关键阶段要主动 checkCancelled()。
3. 一旦抛出 EXPORT_CANCELLED，调用方就能明确区分"用户取消"与"真实失败"。

这比单纯 return 或吞错更好，因为导出链上还牵涉作品落盘、状态恢复、实况窗关闭等收尾动作。只有把取消显式当成一种可识别结果，页面才能做对：

} catch (err) {
  const message = err instanceof Error ? err.message : '请检查素材或重试';
  this.statusText = message === EXPORT_CANCELLED ? '已取消导出' : `导出失败：${message}`;
}

也就是说，取消导出在这个项目里不是"UI 小功能"，而是一种完整的任务结果分支。

八、收尾逻辑为什么必须放在 finally

长任务最怕的不是失败，而是失败后状态没收干净。exportCurrent() 的 finally 正是在兜这个底：

} finally {
  this.exporting = false;
  this.exportProgress = 0;
  this.exportStage = '';
  this.exportSignal = null;
  await LiveViewService.stop();
  await BackgroundRenderService.stop(ctx);
  await CardBridge.pushAll(ctx, false, 0, '待命中');
}

这里统一回收了 5 类状态：

1. 页面导出态恢复，按钮重新可点。
2. 进度条和阶段文本清零。
3. 当前取消信号置空，避免误复用。
4. 实况窗关闭。
5. 后台任务态与服务卡片回到待命状态。

如果这些清理动作散落在 success / catch 分支里，真实项目里非常容易漏掉一条路径，最后表现成：

1. 页面明明导出结束了，按钮还禁用。
2. 实况窗一直停在上一次百分比。
3. 卡片仍显示"进行中"。
4. 下一次导出复用了过期 signal。

所以 finally 在这里不是语法习惯，而是长任务状态一致性的必要条件。

九、页面与工程证据

9.1 编辑页已经暴露导出参数与导出按钮

当前编辑页已经把比例、帧率、清晰度、滤镜、字幕、亮度/对比度和导出入口集中到一页里。只要编码阶段阻塞了主线程，用户立刻就会感知为"点了导出以后整页假死"。

9.2 导出页底部区域明确承载长任务交互

页面底部已经预留了导出按钮、预计文件大小和导出设置区。这说明项目不是一次性脚本，而是面向真实交互场景的工具页，长任务体验必须纳入设计。

9.3 导出完成后作品页能形成闭环

作品页能承接导出结果，说明这条链路不是"只把字节算出来就结束"，而是要把导出结果、状态回收和后续操作一起闭环。这也是为什么长任务控制不能只停留在编码函数内部。

十、工程复盘

把第 11 篇拆开之后，可以得到 4 个更稳定的工程结论：

1. TaskPool 最适合承接纯计算密集、可序列化、边界清晰的编码步骤，而不是整条导出链。
2. GifEncodeTask 保持最小封装后，ExportService 才能自然实现"后台优先、主线程兜底"。
3. 进度、实况窗、卡片、取消导出和页面按钮必须共享同一个长任务状态源，否则交互一定会失真。
4. 长任务体验的关键不是"有没有线程池"，而是失败、取消和收尾时状态能不能保持一致。

十一、验收清单

验收项	结果	说明
GIF 编码已从主导出流程中抽成独立 TaskPool 任务	通过	GifEncodeTask.run() 只承接编码步骤
并发函数入参与返回值满足 @Concurrent 边界	通过	传入 IndexedGifFrame[]、palette，返回 ArrayBuffer
导出默认优先走后台编码	通过	ExportService.encodeResult() 先调用 GifEncodeTask.run()
后台编码失败存在主线程兜底	通过	catch 中回退到 GifEncoderService.encodeIndexedFrames()
页面导出态、进度和阶段文案统一维护	通过	exportCurrent() 设置 exporting/exportProgress/exportStage
实况窗与服务卡片接入同一导出状态	通过	LiveViewService.start/update/stop() 与 CardBridge.pushAll()
高进度回调已做百分比节流	通过	pct !== this.lastCardPercent 时才桥接更新
取消导出具备明确错误语义	通过	ExportSignal.checkCancelled() 抛出 EXPORT_CANCELLED
成功、失败、取消后都有统一收尾	通过	finally 中关闭导出态、实况窗和卡片状态

十二、小结

第 11 篇真正想说明的，是"长任务不是加个线程池就结束"。在"动图魔方"里，GifEncodeTask 负责把最重的 CPU 编码移出 UI 线程，ExportService 负责保证后台失败后仍能导出，Index.ets 负责把用户真正看得到的进度、取消和状态收尾做完整。三层配合起来，导出功能才从"能跑"变成"可用"。

十三、下一篇衔接

下一篇进入第 12 篇：动图魔方技术拆解 12：GIF 导出进度、取消按钮与异常恢复。到那一篇我会继续沿着 ExportSignal、statusText、作品落盘和错误提示这条线，把"用户能感知的长任务体验"单独拆成一篇，更完整地讲清楚进度反馈和异常恢复。