在前面的文章中,我們實現了以 IndexedDB 做為本地儲存的 Local-First 架構。
但對於一個「不收集個人資料、資料存在使用者本地裝置」的工具來說,光是把資料存放在瀏覽器裡還不夠。萬一使用者更換電腦、清除瀏覽器快取,或是想把紀錄拿去做其他用途呢?
因此,我希望可以有資料匯出功能,讓使用者可以備份相關紀錄,所以接下來就要來加上 CSV 報表匯出 功能。
資料結構轉化的挑戰:陣列扁平化
TaskTimer 的原始資料結構是有層級關係的:
1 | 主任務(Task)→ 子任務(Subtask) → 計時紀錄(Records) |
但是,試算表軟體(如 Microsoft Excel、Google Sheets)讀取的 CSV 檔案是單層的橫列表格。
因此,我們需要進行 資料扁平化(Data Flattening) :將每一筆「計時紀錄」連同它所屬的主任務名稱與子任務名稱,拆解組合為獨立的一列資料。
匯出 CSV 的三個關鍵細節
在用原生 JavaScript 寫 CSV 匯出時,有三個地方需要特別注意:
1. UTF-8 BOM 標頭(\uFEFF):
如果直接輸出 UTF-8 編碼的中文文字,Microsoft Excel 開啟時常會出現整頁 中文亂碼。在字串開頭加上 \uFEFF(Byte Order Mark)可以強制引導 Excel 以 UTF-8 正確解析中文字元。
2. 特殊字元跳脫(CSV Escaping):
使用者的「備註」或「任務名稱」中可能包含逗號 ,、雙引號 " 或換行符號 \n。若沒有處理,會導致 CSV 欄位錯位拆分。
規則是:只要欄位內含有特殊字元,就必須將整段內容用雙引號包起來,並把內部的 " 替換為 ""。
3. 動態下載觸發(Blob & Object URL):
利用原生 Blob 物件將文字轉換為二進位檔案,並建立臨時的 <a download> 標籤觸發瀏覽器下載,下載完成後及時釋放記憶體(URL.revokeObjectURL)。
實作 CSV 匯出邏輯
實作 CSV 匯出的核心邏輯可拆解為三個步驟:格式防錯、資料扁平化 與 觸發下載。
1. 處理 CSV 欄位跳脫(Escape)
當欄位內容含有逗號 ,、雙引號 " 或換行符號 \n 時,必須用雙引號將內容包起來,並把內部的 " 替換為 "",避免試算表解析欄位錯亂:
1 | function escapeCSVField(str) { |
2. 將嵌套資料「扁平化」展開
走訪 tasks 陣列,把主任務、子任務與計時紀錄展開組合成單一維度的橫列字串陣列:
1 | // 1. 定義 CSV 標頭 |
3. 加入 UTF-8 BOM 並觸發瀏覽器下載
在字串最前方加上 \uFEFF 標頭防範 Excel 中文亂碼,最後利用原生 Blob 與動態 <a> 標籤觸發下載:
1 | // 3. 組合內容字串,加入 \uFEFF 防範 Excel 中文亂碼 |
成果驗證
點擊頁面上的 「下載 CSV 檔案」 按鈕後,瀏覽器會自動下載檔名如 TaskTimer_Backup_2026-09-27.csv 的檔案。
開啟後,可以獲得結構完整、中文呈現正常的統計報表:
