Fixed-Width Inspector

VS Code 套件：依你定義的欄位規格，將固定長度文字檔（台灣稱「媒體檔」）的每個欄位上色，並自動檢核資料是否異常。

Highlight and validate fixed-width (fixed-length) text files — ACH, payroll, NACHA, Zengin, tax and health-insurance filings — using a JSON record layout. Supports Big5 / MS950 files whose field lengths are counted in bytes.

官網與設定說明：https://fixed-width-inspector.pylabs.app（設定說明 / Schema guide）

欄位上色與記錄別標籤滑鼠停在欄位上顯示說明表格檢視

功能

欄位看得見：相鄰欄位以 2–4 色交替上色，亮色、暗色主題都適用
異常自動標出：錯誤以紅色波浪底線標示，並列入「問題」面板
游標所在欄位即時說明：Hover 顯示欄位名稱、起訖位置、長度、原值、解析值與錯誤原因；狀態列顯示「帳號｜第 2–15 碼」
中文以位元組計：Big5 / MS950 媒體檔中文佔 2 碼，欄位邊界切到中文字時會提示
記錄別標籤：每行最前面顯示「首筆／明細／尾筆」，認不出的行顯示紅色「未知」；可用 schema 的 label 自訂文字
表格檢視：每種記錄一個分頁、每個欄位一欄，有錯的格子標紅；點格子跳到原檔位置，修改檔案時表格即時更新
匯出 CSV：把表格匯出成 Excel 可直接開啟的 CSV（中文不亂碼、帳號前面的 0 不會消失）
編碼開錯偵測：Big5 檔被當成 UTF-8 開啟時，提示並可一鍵以正確編碼重新開啟

檢核項目

層級	檢核
欄位	`text`（靠左、`pattern`）、`numeric`（只能 0–9、左補 0）、`amount`（隱含小數、正負號）、`date`（`YYYYMMDD` / `YYMMDD` / 民國 `ROC_YYYMMDD`）、`enum`、`twid`（身分證字號檢查碼）、`twbiz`（統一編號檢查碼）、`filler`（保留欄位）
行	整行長度、無法對應任何記錄格式、換行符號、首筆 / 尾筆位置、無法解碼的字元（U+FFFD）
跨行	尾筆總筆數 = 明細筆數、尾筆總金額 = 明細金額加總

開始使用

在媒體檔的同一層建立 .fixedwidth/ 資料夾，放入 schema（*.json）。也可以執行 Fixed-Width Inspector: Create Schema from Template，會在目前檔案旁邊建立範例並立即套用。
開啟檔名符合 schema filePattern 的檔案，就會自動套用。
或點編輯器右上角的尺規圖示、狀態列的「未套用 schema」，選 從檔案選擇 schema… 指定任何位置的 schema 檔；這個選擇會被記住。
撰寫 schema 時有自動完成與格式驗證。

schema 的尋找順序

手動指定給這個檔案的 schema
檔案同一層的 .fixedwidth/，找不到再往上一層，直到工作區根目錄（最近的優先）
設定 fixedWidthInspector.schemaPaths 列出的目錄

filePattern 若含有資料夾（如 data/*.txt），是相對於 .fixedwidth/ 所在的資料夾；**/ACH*.txt 或 ACH*.txt 則不受位置影響。

Schema 範例

{
  "name": "ACH 扣款媒體檔",
  "filePattern": "**/ACH*.txt",
  "encoding": "big5",
  "lengthUnit": "byte",
  "lineLength": 250,
  "lineEnding": "CRLF",
  "records": [
    {
      "type": "detail",
      "when": { "start": 1, "length": 1, "equals": "2" },
      "fields": [
        { "name": "帳號", "start": 2, "length": 14, "type": "numeric" },
        { "name": "戶名", "start": 16, "length": 40, "type": "text" },
        { "name": "金額", "start": 56, "length": 13, "type": "amount", "decimals": 2 },
        { "name": "身分證號", "start": 69, "length": 10, "type": "twid" }
      ]
    }
  ],
  "crossChecks": [
    { "rule": "sum", "field": "detail.金額", "equals": "trailer.總金額" }
  ]
}

start 為 1-based，單位依 lengthUnit（byte 或 char）。省略時，big5 / ms950 預設 byte，utf-8 預設 char。
只有單一記錄格式時，records 放一筆且可省略 when。
所有欄位都可加 required（不可全空白）、description（顯示在 Hover）、severity（error / warning / info）。

首筆、明細、尾筆的組合

首筆、明細、尾筆可以任意組合（共 7 種），schema 的 records 只要列出這種檔案有的記錄即可，例如只有明細的檔案就只放一筆 detail。執行 Create Schema from Template 時可以直接勾選要哪幾種記錄。

每種記錄可用 required 設定是否每個檔案都必須出現：

記錄	`required` 預設	設為 `false` 時
有 `position` 的記錄（首筆 / 尾筆）	`true`：缺少時報錯	可有可無；出現時仍須在第一行 / 最後一行，參照它的跨行檢核在缺少時略過
其他記錄（明細）	`false`：可以沒有	設為 `true` 時，檔案中至少要有一筆

更多範例與每個參數的說明見設定說明。

表格檢視與匯出 CSV

首筆、明細、尾筆各一個分頁；只出現一次的記錄（通常是首筆、尾筆）也會濃縮顯示在表格上方
金額、日期顯示解析後的值（1,500.00、2026-10-19），勾「顯示原始值」可切換；帳號等數字欄位一律照原樣顯示
有錯的格子標紅、警告標黃，滑鼠移上去看原因；整行的問題（例如長度錯誤）標在行號上
可勾「只看有問題的列」或搜尋任何內容；在編輯器移動游標，表格會標出對應的列
匯出 CSV 為 UTF-8（含 BOM）：
- 前面有 0 或 12 碼以上的數字（例如帳號）以 ="000123" 寫入，Excel 開啟後不會被吃掉或變成科學記號
- 以 =、+、-、@ 開頭的文字前面加 '，避免被 Excel 當成公式執行

指令

指令	說明
Fixed-Width Inspector: Select Schema	為目前檔案選擇 schema，或從檔案指定（編輯器右上角也有按鈕）
Fixed-Width Inspector: Validate File	對全檔執行完整檢核並開啟「問題」面板
Fixed-Width Inspector: Toggle Highlighting	開關欄位上色
Fixed-Width Inspector: Create Schema from Template	在目前檔案旁的 `.fixedwidth/` 建立範例 schema
Fixed-Width Inspector: Show as Table	以表格檢視目前檔案（有套用 schema 時，編輯器右上角也有按鈕）
Fixed-Width Inspector: Export as CSV	把某一種記錄匯出成 CSV，可選「解析值」或「原始值」
Fixed-Width Inspector: Reopen with Schema Encoding	以 schema 指定的編碼重新開啟（VS Code 1.100 以上可直接切換，舊版會開啟編碼選單）

設定

設定	預設	說明
`fixedWidthInspector.enabled`	`true`	啟用套件
`fixedWidthInspector.schemaPaths`	`[".fixedwidth"]`	額外的 schema 目錄（相對於工作區或絕對路徑）；檔案旁邊的 `.fixedwidth/` 一律會自動尋找
`fixedWidthInspector.fieldColors`	4 個半透明色	欄位交替上色的顏色
`fixedWidthInspector.showRecordLabels`	`true`	在每行最前面顯示記錄別標籤
`fixedWidthInspector.maxDiagnostics`	`1000`	「問題」面板最多列出的筆數，超過時狀態列會提示
`fixedWidthInspector.debounceMs`	`300`	編輯後延遲多久重新檢核（毫秒）
`fixedWidthInspector.language`	`auto`	介面語言：`auto` 跟隨 VS Code、`en` 英文、`zh-tw` 繁體中文

開發

本套件不含任何第三方執行期套件；開發只需 TypeScript 與型別定義。

npm install
npm run compile          # 編譯到 out/
npm run lint             # TypeScript 嚴格型別檢查
npm test                 # 單元測試（node:test）+ 覆蓋率門檻 80%
npm run test:integration # 在本機 VS Code 中執行整合測試（使用獨立暫存設定檔）
npm run samples          # 重新產生 examples/ 的範例媒體檔
npm run package          # 打包 .vsix

src/core/ 與 src/schema/ 為純邏輯，不 import vscode，可直接單元測試。

授權

MIT

Fixed-Width Inspector

PyLabs

Fixed-Width Inspector

功能

檢核項目

開始使用

schema 的尋找順序

Schema 範例

首筆、明細、尾筆的組合

表格檢視與匯出 CSV

指令

設定

開發

授權