小編精選 - 技術文章翻譯 · 04月13日

別讓壓圖拖垮首幀：系統 Picker + TaskPool + ImagePacker，將 HarmonyOS 圖片整理鏈路理順

別讓壓圖拖垮首幀：系統選取器 + TaskPool + ImagePacker，把 HarmonyOS 圖片整理鏈路做順

> 這篇不聊「會不會調 API」，聊的是一個更像線上專案的問題：

使用者選了十幾張圖，頁面不能卡；處理完了，結果要能穩定回存；頁面退到後台以後，上傳也別說沒就沒。

我最近在做圖片整理類功能時，重新把這條鏈路理了一遍。以前很多寫法放在 Demo 裡沒問題，一旦到了真機、真使用者、真批量場景，問題就全出來了：

一上來就申請大權限，使用者猶豫一下，轉換率先掉一截。
圖片解碼、縮放、編碼全放主執行緒，選 8～10 張圖時首幀明顯會卡頓。
「保存成功」只是前端狀態改了，檔案其實還沒穩定落盤。
上傳邏輯綁死在頁面生命週期上，頁面一退，任務也容易跟著斷。

後來我換了一個思路：入口盡量交給系統選取器（Picker），重活交給 TaskPool，編碼收口到 ImagePacker，回存盡量走 SaveButton / 授權式保存，後台上傳交給標準後台任務機制。

這個改完以後，最大的變化不是「程式碼更優雅」，而是整條使用者路徑沒那麼慌了。

一、先說結論：圖片類功能別再把所有活都塞給頁面

HarmonyOS 這幾年給圖片、檔案、後台任務這些場景配的系統能力，其實已經很完整了。真正容易踩坑的，不是能力不夠，而是鏈路設計還停留在「能跑就行」。

對圖片整理、票據掃描、相簿工具、內容發佈這類應用，我更推薦下面這套拆法：

入口層：優先系統選取器 / 相機選取器
先把「拿到資源」這件事做輕，不要一上來就用全量權限思路。
處理層：解碼、縮放、編碼、哈希都丟到 TaskPool（工作池）
UI 執行緒只管狀態切換、進度回寫、結果展示。
結果層：臨時檔案先落應用沙箱
不要一邊處理一邊直接改外部結果，失敗以後很難回滾。
回存層：保存回相簿時優先走 SaveButton / 授權保存
這一步是「使用者確認寫入系統資源」，語意更清楚，也更穩。
後續層：上傳 / 同步用標準後台任務機制托管
頁面銷毀不等於業務任務應該立刻消失。

這套方案的核心不是「炫 API」，而是四個字：責任拆分。

二、為什麼這套鏈路更適合線上專案

我把它總結成一句話：

系統能力負責邊界，業務程式碼負責規則。

1）資源入口盡量輕

很多圖片工具第一步就想着「我要讀圖庫，所以先申請圖庫權限」。
但從產品體驗看，這一步往往太重了。

如果你的場景只是「讓使用者選幾張圖來處理」，那更自然的做法是：

讓使用者用系統選取器（Picker）選圖；
用相機選取器拍照；
你的應用拿到 URI / 檔案句柄以後再繼續後面的業務。

這樣做有兩個好處：

第一，權限心智更輕。
第二，系統對資源邊界更清晰，後續排查問題也更容易。

2）圖片處理一定要和 UI 拆開

這是最關鍵的一點。

圖片整理裡最容易「偷懶」的地方，就是把下面這些步驟串著寫在一個按鈕回呼裡：

讀檔
解碼成 PixelMap（像素圖）
縮放
編碼
寫臨時檔
刷新列表

程式碼短期看挺順，長期看基本就是掉幀製造機。
尤其是一次選多張圖時，問題會非常明顯。

所以我的建議一直很明確：

UI 執行緒只維護「當前選了什麼、處理到哪一步、最終展示什麼」。
真正耗時的事全部下放到 TaskPool（工作池）。

這時候你的頁面就只剩三類狀態：

UI 狀態：按鈕是否可點、當前顯示哪個結果
任務狀態：壓縮中 / 完成 / 失敗 / 可重試
檔案狀態：是否真的寫出臨時檔案，是否可匯出

一旦狀態層次清楚了，很多「玄學 Bug」會立刻少一半。

3）結果先寫到沙箱，再決定是否匯出

很多人一開始會把「處理完成」直接等同於「保存完成」，這在工程上是兩件事。

我一般會分兩步：

第一步：處理結果落到應用沙箱臨時目錄；
第二步：使用者確認後，再匯出到系統相簿或指定目錄。

這麼拆的好處很實際：

失敗時不會把外部結果弄髒；
可以做失敗重試；
可以先預覽結果，再決定要不要落到系統資源裡；
上傳也可以直接基於沙箱內檔案做，不必和「是否回存相簿」強綁定。

三、給一個更像專案裡的寫法

下面這段不是「最短 Demo」，而是更接近業務專案裡的組織方式。
我故意沒有寫成一屏程式碼，而是按模組拆開。這樣後面你要加格式策略、清晰度分級、失敗重試，都比較好擴。

說明：下面是 ArkTS 專案化示例，媒體 Picker、SaveButton 以及後台任務相關 import 在不同 SDK 版本中命名可能有細微差異，落地時請以你當前使用的 HarmonyOS SDK 文件為準。

1）定義任務資料結構

<div><div><div></div><span>ts</span></div><div><div> <span>體驗AI程式碼助理</span></div><div> <span>程式碼解讀</span></div><div>複製程式碼</div></div></div>```
<span><span>export</span> <span>interface</span> <span>CompressJob</span> {</span>
<span>  <span>id</span>: <span>string</span></span>
<span>  <span>sourceUri</span>: <span>string</span></span>
<span>  <span>targetFormat</span>: <span>'image/jpeg'</span> | <span>'image/png'</span> | <span>'image/webp'</span> | <span>'image/heif'</span></span>
<span>  <span>quality</span>: <span>number</span></span>
<span>  <span>maxEdge</span>: <span>number</span></span>
<span>}</span>
<span></span>
<span><span>export</span> <span>interface</span> <span>CompressResult</span> {</span>
<span>  <span>id</span>: <span>string</span></span>
<span>  <span>success</span>: <span>boolean</span></span>
<span>  <span>tempFileUri</span>: <span>string</span></span>
<span>  <span>width</span>: <span>number</span></span>
<span>  <span>height</span>: <span>number</span></span>
<span>  message?: <span>string</span></span>
<span>}</span>


2）頁面只維護狀態，不直接做重活

<div><div><div></div>ts</div><div><div> 體驗AI程式碼助理</div><div> 程式碼解讀</div><div>複製程式碼</div></div></div>`` @Entry @Component struct BatchImagePage { @State jobs: CompressJob[] = [] @State results: CompressResult[] = [] @State running: boolean = false @State progressText: string = '等待選擇圖片' async pickImages() { // 這裡用系統媒體 Picker 選圖 // 實際 API 名稱請以當前 SDK 為準 const picker = new photoAccessHelper.PhotoViewPicker() const selected = await picker.select({ maxSelectNumber: 12 }) this.jobs = selected.photoUris.map((uri: string, index: number) => ({ id: job${Date.now()}${index}, sourceUri: uri, targetFormat: 'image/jpeg', quality: 78, maxEdge: 1600 })) this.progressText = 已選擇 ${this.jobs.length} 張圖片 } async startCompress() { if (this.jobs.length === 0 || this.running) { return } this.running = true this.results = [] for (let i = 0; i this.jobs.length; i++) { const job = this.jobs[i] this.progressText = 處理中 ${i + 1}/${this.jobs.length}`

 try {
 const result = await ImagePipelineService.compressInTaskPool(job)
 this.results = [...this.results, result]
 } catch (err) {
 this.results = [
 ...this.results,
 {
 id: job.id,
 success: false,
 tempFileUri: '',
 width: 0,
 height: 0,
 message: JSON.stringify(err)
 }
 ]
 }
 }

 this.progressText = '處理完成'
 this.running = false
 }

 build() {
 Column({ space: 16 }) {
 Text('批量圖片整理')
 .fontSize(26)
 .fontWeight(FontWeight.Bold)

 Text(this.progressText)
 .fontSize(14)
 .opacity(0.75)

 Row({ space: 12 }) {
 Button('選擇圖片').onClick(() => this.pickImages())
 Button(this.running ? '處理中...' : '開始整理')
 .enabled(!this.running && this.jobs.length > 0)
 .onClick(() => this.startCompress())
 }

 List() {
 ForEach(this.results, (item: CompressResult) => {
 ListItem() {
 Row({ space: 12 }) {
 Text(item.id).fontSize(14)
 Text(item.success ? '成功' : '失敗')
 .fontColor(item.success ? '#26c281' : '#ff5d73')
 Text(item.message ?? item.tempFileUri)
 .fontSize(12)
 .opacity(0.7)
 }
 }
 })
 }
 .layoutWeight(1)
 }
 .padding(20)
 .width('100%')
 .height('100%')
 }
}

3）把解碼、縮放、編碼收口到服務層

<div><div><div></div><span>ts</span></div><div><div> <span>體驗AI程式碼助理</span></div><div> <span>程式碼解讀</span></div><div>複製程式碼</div></div></div>```
<span><span>export</span> <span>class</span> <span>ImagePipelineService</span> {</span>
<span>  <span>static</span> <span>async</span> <span>compressInTaskPool</span>(<span>job</span>: <span>CompressJob</span>): <span>Promise</span>CompressResult</span>> {
<span>    <span>// 偽程式碼：把真正耗時的圖片處理丟進 TaskPool</span></span>
<span>    <span>return</span> <span>await</span> taskpool.<span>execute</span>(compressWorker, job)</span>
<span>  }</span>
<span>}</span>


4）Worker / TaskPool 裡只做「純處理」

<div><div><div></div>ts</div><div><div> 體驗AI程式碼助理</div><div> 程式碼解讀</div><div>複製程式碼</div></div></div>```
span>@Concurrent</span
async function compressWorker(job: CompressJob): PromiseCompressResult> {
 // 偽程式碼：不同專案裡你可能會把這部分繼續拆成
 // read -> decode -> resize -> encode -> writeTempFile

 const sourceImage = image.createImageSource(job.sourceUri)
 const pixelMap = await sourceImage.createPixelMap()

 const size = calcTargetSize(pixelMap.getImageInfoSync(), job.maxEdge)
 const resizedPixelMap = await resizePixelMap(pixelMap, size.width, size.height)

 const packer = image.createImagePacker()
 const packedArrayBuffer = await packer.packing(
 resizedPixelMap,
 {
 format: job.targetFormat,
 quality: job.quality
 }
 )

 const tempFileUri = await writeBufferToCache(job.id, packedArrayBuffer)

 return {
 id: job.id,
 success: true,
 tempFileUri,
 width: size.width,
 height: size.height
 }
}

5）保存不要和「處理完成」強綁死

<div><div><div></div><span>ts</span></div><div><div> <span>體驗AI程式碼助理</span></div><div> <span>程式碼解讀</span></div><div>複製程式碼</div></div></div>```
<span><span>@Component</span></span>
<span>struct <span>ExportPanel</span> {</span>
<span>  <span>@Prop</span> <span>fileUri</span>: <span>string</span></span>
<span></span>
<span>  <span>build</span>(<span></span>) {</span>
<span>    <span>Column</span>({ <span>space</span>: <span>12</span> }) {</span>
<span>      <span>Text</span>(<span>'處理完成後，可以先預覽，再決定是否匯出到系統相簿。'</span>)</span>
<span></span>
<span>      <span>// 實際專案裡優先考慮安全元件 / SaveButton 的方案</span></span>
<span>      <span>SaveButton</span>({</span>
<span>        <span>text</span>: <span>'儲存到相簿'</span></span>
<span>      })</span>
<span>      .<span>onClick</span>(<span>async</span> () => {</span>
<span>        <span>await</span> <span>exportResultToGallery</span>(<span>this</span>.<span>fileUri</span>)</span>
<span>      })</span>
<span>    }</span>
<span>  }</span>
<span>}</span>



---

四、這套寫法最容易忽略的 4 個細節
------------------

![image.png](https://i.imgur.com/Js7AzuV.jpeg)

細節 1：不要只存「任務成功」，要存「檔案可用」

很多程式碼會寫成這樣：

- TaskPool 回傳成功
- 列表顯示「已完成」
- 使用者點擊匯出
- 結果發現檔案並不可讀

這類問題本質上是：
你把「任務回傳成功」和「結果檔案可用」混成了一件事。

更穩的做法是分開記：

- taskStatus
- fileStatus
- exportStatus

狀態一旦拆開，排查就快很多。

細節 2：格式策略不要寫死

圖片場景裡，格式不是越統一越好，而是要看業務目標。

我自己一般會這樣分：

- 追求通用分享：優先 JPEG
- 需要透明背景：保留 PNG
- 更關注體積：視相容性考慮 WebP / HEIF
- 要保細節或特殊能力：另走高品質策略

所以我不太建議在專案初期就寫死成「所有圖都壓成 JPEG 80」。
後面你只要收到一次「為什麼透明背景沒了」的反饋，就會明白這坑有多真實。

細節 3：頁面狀態不要和上傳狀態綁在一起

很多專案會在圖片處理頁裡順手把上傳也一起做掉。
從流程上看沒毛病，但從生命週期看問題很大。

更推薦的方式是：

- 頁面內只負責發起上傳任務；
- 上傳狀態由任務系統維護；
- 頁面返回後，再次進入時讀取任務狀態。

這樣你才能真正做到：

- 頁面退了，任務還在；
- 網路恢復了，任務還能繼續；
- 失敗了，可以單獨重試，不必重新壓圖。

細節 4：別把「系統資源存取」當普通本地檔案讀寫

很多 Bug 到最後都不是圖像演算法問題，而是 URI、授權、資源歸屬、目錄可見性這些邊界沒想清楚。

尤其是下面幾件事，最好一開始就想明白：

- 你拿到的是暫時 URI 還是長期可讀資源？
- 壓縮結果先落哪裡？
- 誰來觸發最終匯出？
- 匯出失敗後是否還能重試？
- 使用者沒按保存，但按了上傳，這是不是允許？

這些問題想通以後，程式碼層面的複雜度反而會下降。

---

五、給一個我自己現在更認可的工程拆法
------------------

![image.png](https://i.imgur.com/gPVqNYl.jpeg)

如果讓我現在從 0 到 1 再搭一次圖片整理功能，我會直接按下面分層：

1）UI 層

只負責：

- 選取入口
- 任務列表展示
- 進度與錯誤提示
- 預覽結果
- 使用者點擊匯出 / 上傳

2）任務編排層

只負責：

- 隊列管理
- 串行 / 並行策略
- 失敗重試
- 結果狀態彙總

3）影像處理層

只負責：

- 解碼
- 縮放
- 編碼
- 哈希 / 校驗
- 臨時檔案輸出

4）資源與系統能力層

只負責：

- Picker 取得資源
- SaveButton / 授權保存
- 後台任務托管
- 檔案系統 / URI 管理

這樣一來，後面你要加這些功能都很自然：

- 批量浮水印
- 多規格匯出
- 上傳前秒傳校驗
- 壓縮失敗自動降級
- 低電量 / 弱網場景策略切換

---

六、最後說一句真話：圖片功能拼的不是「壓縮演算法」，是鏈路穩定性
-------------------------------

很多時候大家討論圖片處理，第一反應都是：

- 品質參數設多少？
- 壓縮率能不能更高？
- WebP 和 JPEG 哪個更小？

這些當然重要，但在實際專案裡，使用者第一時間感知到的並不是「你比別人小了 8%」，而是：

- 點了以後會不會卡
- 處理過程中會不會慌
- 保存會不會莫名失敗
- 退到後台以後會不會白跑

所以我現在更在意的排序是：

1. 不卡
2. 穩定
3. 邊界清楚
4. 最後才是壓得漂亮

這也是我為什麼越來越傾向於把系統選取器、TaskPool、ImagePacker、SaveButton、後台任務這些能力串成一條完整鏈路，而不是各自零散使用。

真正上線以後你會發現，工程上的「順」，比演算法上的「狠」更值錢。

---

原文出處：https://juejin.cn/post/7627665051667283983