CSV 大量批次轉 JSON 是一種受控的轉換作業,可將一個以逗號分隔、內含最多 5,000,000 個 UTF-16 字碼單元與 10,000 筆資料列的 CSV 表格,轉成經過美化排版的 JSON 陣列,同時將每個儲存格保留為 JSON 字串。 CSV 轉 JSON 工具會在目前瀏覽器分頁中執行這項工作:貼上一個以逗號分隔的表格、進行轉換、檢視回報的計數、檢查 JSON,然後複製或下載結果。其第一筆 CSV 記錄會成為精確的 JSON 標頭,而每筆資料記錄會成為一個物件。標頭順序決定屬性的順序,每個儲存格則會成為一個字串。因此,轉換器並不會猜測 001 是數字、true 是布林值,或 null 代表 JSON 的 null 值。引號內的逗號、雙引號、以及嵌入引號欄位內的換行字元,都會依據支援的 CSV 語法保留。成功轉換後,資料列、欄、儲存格與 UTF-8 輸出大小的摘要資訊,可提供快速的整體性檢查。在此,「大量批次」指的是在單一有界限表格中可處理的記錄數,而不是多個 CSV 檔案的佇列。若要轉換不同的檔案,請為每個表格分別執行轉換。完整的解析、驗證、序列化、測量與匯出流程都在本機進行,不會上傳任何 CSV 或 JSON。
大量批次轉換指的是單一有界限的表格
重點在於區分「大量資料」與「批次檔案」。本工具設計用於在單一貼上的文字表格內處理大規模資料。它最多可處理 10,000 筆資料記錄、200 個欄位與 200,000 個資料儲存格,但這些上限是相互搭配的,並非各自獨立的建議值。
欄位多但列數少的寬表格,可能會在達到 10,000 列之前就先觸及 200,000 儲存格的上限;反之,欄位少但記錄多的窄表格,則會受到列數與輸出大小預算的限制。若 JSON 含有大量跳脫字元,可能會比原始輸入大小更快耗盡 UTF-8 輸出上限。
這些都是強制執行的限制,而不是靜默的上限。剛好等於上限的值會被接受;但只要超出任何一項邊界——無論是字碼單元、列、欄、儲存格或 UTF-8 位元組——一個單位,轉換作業就會明確失敗。成功的轉換會產生完整的 JSON 陣列;失敗則不會回傳部分陣列,因此下游程式碼無須猜測是否有部分記錄被省略。
準備表格以進行嚴謹解析
請在轉換前先準備輸入內容,讓第一筆記錄能作為精確的標頭。在處理完選擇性的 UTF-8 BOM 之後,每個標頭名稱都必須保持非空。標頭名稱必須唯一,比較時採完全相符且區分大小寫。空白字元也算標頭的一部分,因此 id、Id,以及含前置空白的名稱,都是不同的鍵值。轉換器不會自動修剪這些空白。
- 僅使用逗號作為欄位分隔字元。Tab、分號與直立線符號都會被視為一般的欄位字元。
- 每筆資料記錄的欄位數必須相同。對於列數過短、過長,或最後一筆記錄結尾看似會產生多餘記錄的情況,將依解析器規則處理,但每筆實際的資料記錄都必須符合標頭的欄位數。
- 可使用未加引號的欄位,或以雙引號將欄位包住。以引號包住的欄位內可以包含逗號、CRLF、LF、CR,以及兩個連續的雙引號。引號欄位內的兩個連續引號會解碼為一個字面上的引號。
- 請精確使用引號語法。未加引號的引號、未閉合的引號,或收尾引號之後仍帶有內容的情況,將會被拒絕,而不會自動修復或捨棄。
在引號欄位之外,CRLF 是標準的記錄結束符號。獨立的 LF 與獨立的 CR 可作為互通性的延伸形式而被接受。最後一筆記錄的結束符號可有可無,不會產生額外的空記錄;但兩個連續的記錄結束符號則代表一筆空白記錄。引號內的換行字元會以原本的 CRLF、LF 或 CR 形式保留為欄位資料。
解析器不會自動偵測其他分隔字元、略過註解、修剪欄位、捨棄空白記錄、合併寬度不一致的列,或推斷結構描述。輸入最開頭的一個 U+FEFF 會作為常見的 UTF-8 BOM 被消耗掉(即使第一個欄位已加引號也是如此),而原始輸入的預算會在移除 BOM 之前檢查。位於其他位置的 U+FEFF 則會保留為資料。若檔案內容僅有 BOM,則在標準化後會變成空內容,並回報「需要輸入內容」的錯誤。
轉換並驗證單一 CSV 表格
- 貼上 CSV。將一個以逗號分隔的文字表格貼到工具中。確認其第一筆記錄含有非空、唯一且區分大小寫的標頭名稱,且每筆資料記錄的欄位數完全相同。
- 進行轉換並檢查摘要。執行轉換,然後驗證回報的資料列數、欄數、資料儲存格數與 UTF-8 輸出大小。這些數字有助於確認表格為矩形結構,且符合所有強制限制。
- 檢查 JSON 字串。檢查具代表性的值,並掃描整個輸出結果中是否有型別變動。值 001 應保留為「001」,true 應保留為「true」,null 應保留為「null」,而空儲存格則應保留為空 JSON 字串。
- 複製或下載檔案。確認物件對應、值與大小摘要皆正確後,即可複製完整的 JSON,或將其下載為 converted.json。編輯來源輸入會清除先前的輸出、計數、錯誤與複製狀態,以免重複使用到舊的 JSON。
檢查物件對應與字串值
此轉換作業會將表格結構直接對應至 JSON 結構。在匯出前檢視這個對應關係相當重要,因為工具會保留儲存格文字,而不會像資料庫或試算表那樣加以解讀。
| CSV 輸入 | JSON 結果 |
|---|---|
| 完整的表格 | 一個經美化排版的 JSON 陣列 |
| 第一筆記錄 | 精確的物件鍵 |
| 標頭順序 | 屬性的順序 |
| 每筆資料記錄 | 一個物件 |
| 每個儲存格 | 一個 JSON 字串 |
| 空儲存格 | 空字串 |
| 以引號包住的逗號 | 同一字串內的逗號 |
| 雙引號 | 一個字面上的引號 |
| 嵌入的換行字元 | 字串內的換行文字 |
在內部,每筆記錄會在序列化之前建構成一個無原型的物件。因此,名稱如 __proto__、constructor、prototype 與 toString 等都是一般的自有字串鍵,而非繼承而來的物件屬性。接著 JSON.stringify 會對屬性名稱、引號、反斜線、控制字元與嵌入的換行字元進行跳脫處理,並使用兩個空格的縮排。最終結果是有效的 JSON 資料,而非可執行的程式碼。接收端的應用程式仍須根據自身需求來解析與驗證 JSON。
遵守強制執行的轉換限制
在嘗試進行大型轉換之前,請先檢查每一項相關限制。表格必須符合以下由產品定義的邊界:
| 測量項目 | 上限 | 測量細節 |
|---|---|---|
| 原始輸入 | 5,000,000 個 UTF-16 字碼單元 | 在消耗開頭的 U+FEFF 之前進行檢查 |
| 資料列 | 10,000 | 標頭不計入資料列 |
| 欄位 | 200 | 每筆資料記錄的欄位數都必須符合標頭寬度 |
| 資料儲存格 | 200,000 | 欄位較多的表格可能會在達到列數上限之前先觸及此上限 |
| 產生的 JSON | 10,000,000 個 UTF-8 位元組 | 以 TextEncoder 進行測量,而非以 JavaScript 字串長度計算 |
多位元組的 Unicode 會以其 UTF-8 位元組數,而非 JavaScript 字串長度,來影響所產生 JSON 的大小。這就是為什麼一個表格雖然符合原始字碼單元預算,仍可能在輸出測量階段失敗。剛好等於列數、欄數、儲存格數與位元組上限的值都會被接受;只要超過上限一個單位,就會明確失敗,並適用相同的「完整轉換」規則。若列寬無效或超出輸出大小上限,將不會留下部分 JSON 或可下載的舊檔。
在檢視輸出時保留來源脈絡
保留字串的轉換方式不應與逐位元組還原原始檔案混為一談。第一個開頭的 BOM 會在標頭解析之前被消耗,而位於其他位置的 BOM 則會保留為資料。在引號之外,記錄結束符號屬於結構性的分隔字元,不會被序列化為儲存格內容。在引號之內,所支援的結束符號會以其原始形式保留為字串的一部分。工具也不會對 Unicode 進行標準化。
轉換器不會執行試算表公式、抓取連結的值、驗證商業意義、推斷結構描述、壓平結構、去除重複記錄,或重新命名鍵值。在匯入 JSON 之前,請檢查標頭名稱、計數、引號使用情形,以及具代表性的字串值。若原始 CSV 的引號或換行呈現方式在檢視或除錯時可能很重要,請一併保留。
在瀏覽器中本機執行大量批次轉換
所有解析、物件建構、UTF-8 測量、複製與 Blob 建立作業,都會在目前瀏覽器分頁中本機執行。工具不會抓取連結的值,在轉換過程中也不會上傳所貼上的 CSV 或所產生的 JSON。
狀態清理機制已內建於工作流程中。編輯 CSV 時會撤銷舊的 JSON ObjectURL,並清除先前的輸出、錯誤、摘要、複製狀態與計時器。轉換失敗時同樣會撤銷下載狀態,且不會留下舊檔。這些機制可避免將先前的成功結果誤認為是較新的編輯輸入。
若要獲得可靠的批次轉換結果,請確認第一筆記錄符合標頭規則、檢查每筆記錄的寬度是否一致、檢視回報的限制、驗證所有儲存格皆保留為字串,然後再複製或下載 converted.json。如此可讓結果保持可預期,並將最終的商業驗證交由接收端的應用程式負責。