n8n-nodes-excel-templater

v1.0.5

Published

23 days ago

Fill Excel templates with data using n8n - supports UI forms and JSON arrays

0High
0Medium
0Low

hueyanchen

n8n-community-node-package n8n excel xlsx template templater report form

n8n-nodes-excel-templater

一個增強版的 n8n 社群節點，用於根據 Excel 範本檔案填入資料並生成新的 Excel 檔案。非常適合自動化報表生成、發票製作和資料匯出工作流程。

English Documentation | 測試文件

✨ 主要功能

🎯 雙重資料輸入模式

UI 表單模式（推薦）
- 圖形化介面，類似 Set 節點
- 輕鬆新增多個資料項目
- 直觀易用
- 支援單一儲存格和表格資料
JSON 陣列模式（向下相容）
- 保留原始 JSON 格式
- 適合程式化操作
- 與舊工作流程向下相容

📊 支援的資料類型

單一儲存格輸入

指定儲存格位置（例如：B2、C10）
填入單一值
自動類型轉換：數字、布林值、日期和空值會自動偵測並轉換
- "12345.67" → 數值 (12345.67)
- "true"/"false" → 布林值
- "2026-01-16" → 日期物件
- "null"/"" → null
- 其他文字 → 字串

表格資料輸入

指定起始儲存格
自動展開 JSON 物件陣列
可選擇是否寫入標題列
自動處理多列多欄資料

🔧 進階選項

多工作表支援：寫入特定工作表
檔案存在處理：覆寫、重新命名或拋出錯誤
大型資料集支援：已測試 1000+ 列
特殊字元：完整支援 Unicode 和 emoji
錯誤處理：提供繼續執行模式

📦 安裝方式

方法 1：npm 安裝（推薦）

npm install n8n-nodes-excel-templater

方法 2：社群節點（n8n 介面）

在 n8n 中前往 Settings > Community Nodes
點擊 Install
輸入 n8n-nodes-excel-templater
點擊 Install

方法 3：手動安裝

cd ~/.n8n/nodes
git clone https://gitlab.com/hueyanchen-group/n8n-nodes-excel-templater.git
cd n8n-nodes-excel-templater
npm install
npm run build

🚀 快速開始

範例 1：填寫發票範本

UI 表單模式

基本設定
- Template Path: /data/invoice-template.xlsx
- Output Path: /data/invoice-2024.xlsx
- Data Input Mode: UI Form
新增單一儲存格資料
- 點擊 Add Entry
- Entry Type: Single Cell
- Cell: B2（發票編號）
- Value: INV-2024-001
新增更多儲存格
- Cell: B3, Value: 張三（客戶名稱）
- Cell: B4, Value: 台北市信義路100號（地址）
- Cell: E2, Value: 2024-01-16（日期）

新增表格資料

點擊 Add Entry
Entry Type: Table Data
Start Cell: A8
Write Headers: true

Table Data:

[
  {"品項": "筆記型電腦", "數量": 2, "單價": 35000, "總計": 70000},
  {"品項": "滑鼠", "數量": 5, "單價": 500, "總計": 2500},
  {"品項": "鍵盤", "數量": 3, "單價": 1500, "總計": 4500}
]

範例 2：員工報表

JSON 陣列模式

[
  {"cell": "B1", "value": "2024年員工報表"},
  {"cell": "B2", "value": "2024-01-16"},
  {"cell": "A5", "value": "部門：業務部"}
]

📖 使用指南

UI 表單模式 - 單一儲存格

適合填寫範本中的特定儲存格：

Cell：Excel 儲存格參照（例如：A1、B5、Z100）
Value：任何值（文字、數字、日期、布林值）

使用情境：

發票編號
客戶名稱
日期
報表標題

UI 表單模式 - 表格資料

適合填入資料表格：

Start Cell：表格左上角儲存格（例如：A1、B5）
Table Data：JSON 物件陣列
Write Headers：
- true：第一列將包含物件鍵名作為標題
- false：資料直接從起始儲存格開始

運作方式：

起始儲存格：B5，Write Headers：true

輸入資料：

[
  {"產品": "筆記本", "數量": 100, "單價": 50},
  {"產品": "原子筆", "數量": 500, "單價": 10}
]

Excel 結果：

    B         C      D
5   產品      數量    單價
6   筆記本    100     50
7   原子筆    500     10

JSON 陣列模式（舊版）

與舊工作流程向下相容：

[
  {"cell": "A1", "value": "你好"},
  {"cell": "B1", "value": 123},
  {"cell": "C1", "value": true}
]

⚙️ 配置選項

Template Path（範本路徑）

Excel 範本檔案的絕對路徑
範例：/data/templates/invoice.xlsx
支援 .xlsx 格式

Output Path（輸出路徑）

新檔案儲存的絕對路徑
範例：/data/output/invoice-2024.xlsx
目錄必須存在

Data Input Mode（資料輸入模式）

UI Form：使用圖形化介面（推薦）
JSON Array：使用舊版 JSON 格式

Options（選項）

If File Exists（檔案已存在時）

Overwrite（預設）：取代現有檔案
Rename：自動附加編號（例如：output-1.xlsx）
Error：拋出錯誤並停止執行

Worksheet Name（工作表名稱）

手動輸入要寫入的工作表名稱
留空則使用第一個工作表
範例：Sheet1、資料、摘要
注意：工作表名稱有區分大小寫

🎨 進階範例

範例 3：混合資料類型

// 在一個工作流程中使用單一儲存格 + 表格
{
  "entries": [
    {
      "entryType": "singleCell",
      "cell": "A1",
      "value": "2024年第一季銷售報表"
    },
    {
      "entryType": "singleCell", 
      "cell": "A2",
      "value": "生成日期：2024-01-16"
    },
    {
      "entryType": "tableData",
      "startCell": "A5",
      "writeHeaders": true,
      "tableData": [
        {"月份": "一月", "銷售額": 50000, "目標": 45000},
        {"月份": "二月", "銷售額": 55000, "目標": 50000},
        {"月份": "三月", "銷售額": 60000, "目標": 55000}
      ]
    }
  ]
}

範例 4：多工作表

在同一個活頁簿中處理多個工作表：

第一次執行：寫入 Sheet1

Options > Worksheet Name: Sheet1
新增您的資料項目

第二次執行：寫入摘要

Options > Worksheet Name: Summary
新增摘要資料

範例 5：大型資料集

有效處理 1000+ 列：

// 產生大型資料集
{
  "entryType": "tableData",
  "startCell": "A1",
  "writeHeaders": true,
  "tableData": [
    // 1000+ 個物件的陣列
    {"ID": 1, "姓名": "員工1", "部門": "業務部"},
    {"ID": 2, "姓名": "員工2", "部門": "資訊部"},
    // ... 更多列
  ]
}

效能：1000 列約 50-100ms ⚡

📊 支援的資料類型與自動轉換

自動類型轉換（v1.0.2 新功能）

在 UI 表單模式 的 Single Cell 輸入中，節點會自動偵測並轉換資料類型：

🔢 數值 (Number)

當輸入看起來像數字時，自動轉換為數值類型：

"12345.67" → 12345.67 (number)
"100" → 100 (number)
"0" → 0 (number)
"-99.99" → -99.99 (number)

✅ 布林值 (Boolean)

"true" → true (boolean)
"false" → false (boolean)

注意: 必須是小寫，大寫 "TRUE" 會被視為文字字串。

📅 日期 (Date)

支援 ISO 8601 格式的日期：

"2026-01-16" → Date 物件
"2026-01-16T10:30:00" → Date 物件
"2026-01-16T10:30:00.000Z" → Date 物件

⭕ 空值 (Null)

"null" → null
"undefined" → null
"" (空字串) → null

📝 文字 (String)

無法匹配以上規則的輸入保持為字串：

"Hello World" → "Hello World" (string)
"TRUE" → "TRUE" (string)
"2026/01/16" → "2026/01/16" (string)

轉換優先順序

空值檢測 (null, undefined, 空字串)
布林值檢測 (true, false)
日期檢測 (ISO 8601 格式)
數值檢測 (可轉換為數字)
保持為字串 (預設)

所有支援的資料類型

節點支援所有 ExcelJS 資料類型：

| 類型 | 範例 | 說明 | |------|------|------| | 字串 | "Hello World" | 任何文字，包括 Unicode 和 emoji | | 數字 | 123、99.99、-50 | 整數、小數、負數 | | 布林值 | true、false | 在 Excel 中顯示為 TRUE/FALSE | | 日期 | "2024-01-16" | 建議使用 ISO 格式 | | 空值 | null、undefined | 空儲存格 | | 特殊字元 | "@#$%^&*()" | 支援所有特殊字元 | | Unicode/Emoji | "😀🎉👍" | 完整 Unicode 支援 |

🔍 錯誤處理

常見錯誤

| 錯誤 | 原因 | 解決方案 | |------|------|----------| | 找不到範本檔案 | 範本路徑無效 | 檢查檔案路徑是否存在 | | 找不到工作表 | 工作表名稱無效 | 驗證工作表名稱 | | 無效的 JSON | 表格資料格式錯誤 | 驗證 JSON 語法 | | 無效的儲存格參照 | 儲存格格式錯誤 | 使用 A1、B2、Z100 等格式 | | 權限被拒 | 沒有寫入權限 | 檢查檔案/資料夾權限 |

繼續執行模式

在節點設定中啟用 Continue on Fail 可以：

發生錯誤時繼續處理剩餘項目
在輸出中回傳錯誤資訊
適用於批次處理

🧪 測試

節點包含完整的測試覆蓋：

28 個測試案例涵蓋所有功能
100% 程式碼覆蓋率（語句、函數、行）
所有資料類型和邊緣案例的測試
1000+ 列的效能測試

執行測試：

npm test                    # 執行所有測試
npm run test:coverage      # 產生覆蓋率報告
npm run test:watch         # 監視模式

詳見測試文件。

🎯 使用案例

商業報表

月度銷售報表
財務報表
庫存報表
KPI 儀表板

文件

發票和收據
採購訂單
送貨單
證書

資料匯出

資料庫到 Excel 匯出
API 資料到 Excel
CRM 資料匯出
問卷調查結果

表單填寫

政府表單
申請表
註冊表
範本文件

🔒 安全性與隱私

所有處理都在您的 n8n 實例本地進行
不會將資料發送到外部服務
檔案保留在您的伺服器上
開放原始碼且可審查

🤝 貢獻

歡迎貢獻！請隨時提交 Pull Request。

Fork 此儲存庫
建立您的功能分支（git checkout -b feature/AmazingFeature）
提交您的變更（git commit -m 'Add some AmazingFeature'）
推送到分支（git push origin feature/AmazingFeature）
開啟 Pull Request

開發

# 安裝依賴
npm install

# 建置
npm run build

# 監視模式
npm run dev

# 執行測試
npm test

# 檢查程式碼
npm run lint
npm run lintfix

📝 變更記錄

v1.0.5

修正: 日期字串的資料不會轉換成 Date 物件, 保持字串型態寫入儲存格.

v1.0.4

Repo從GitHub搬至GitLab - 更新相關的網址的Repo網址。

v1.0.3 (2026-03-01) 🔧

🔧 重大修正：節點現在可以透過拖拉或雙擊加入工作區
🛡️ 增強錯誤處理：範本檔案驗證、自動建立輸出目錄、工作表存在性檢查
🐛 錯誤修正：重新命名計數器邏輯、表格資料欄位對齊、缺失欄位處理
📊 測試：35/35 測試全數通過，新增邊界情境測試案例
🔄 重大變更：工作表名稱從下拉選單改為手動文字輸入

v1.0.2 (2026-01-16) 🎯

🎯 自動類型轉換 單一儲存格輸入（數字、布林值、日期、空值）
📚 增強文件說明與類型轉換範例
✅ 完整的類型轉換單元測試

v1.0.1 (2024-01-XX)

✨ 首次發布，支援雙輸入模式
✨ UI 表單模式與 JSON 陣列模式
✨ 多工作表支援
✅ 100% 測試覆蓋率
✨ 支援單一儲存格和表格資料
✨ 自訂工作表選擇
✨ 多種檔案處理選項（覆寫/重新命名/錯誤）
✨ 完整測試覆蓋（28 個測試案例，100% 覆蓋率）
✨ 支援所有資料類型，包括 Unicode/emoji
✨ 高效能（1000+ 列 <100ms）

📄 授權

MIT License

🔗 相關資源

🙏 致謝

使用 ExcelJS 建置
由 n8n 提供支援
使用 Jest 測試

💬 支援

用 ❤️ 為 n8n 社群打造

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

n8n-nodes-excel-templater

✨ 主要功能

🎯 雙重資料輸入模式

📊 支援的資料類型

單一儲存格輸入

表格資料輸入

🔧 進階選項

📦 安裝方式

方法 1：npm 安裝（推薦）

方法 2：社群節點（n8n 介面）

方法 3：手動安裝

🚀 快速開始

範例 1：填寫發票範本

範例 2：員工報表

📖 使用指南

UI 表單模式 - 單一儲存格

UI 表單模式 - 表格資料

JSON 陣列模式（舊版）

⚙️ 配置選項

Template Path（範本路徑）

Output Path（輸出路徑）

Data Input Mode（資料輸入模式）

Options（選項）

If File Exists（檔案已存在時）

Worksheet Name（工作表名稱）

🎨 進階範例

範例 3：混合資料類型

範例 4：多工作表

範例 5：大型資料集

📊 支援的資料類型與自動轉換

自動類型轉換（v1.0.2 新功能）

🔢 數值 (Number)

✅ 布林值 (Boolean)

📅 日期 (Date)

⭕ 空值 (Null)

📝 文字 (String)

轉換優先順序

所有支援的資料類型

🔍 錯誤處理

常見錯誤

繼續執行模式

🧪 測試

🎯 使用案例

商業報表

文件

資料匯出

表單填寫

🔒 安全性與隱私

🤝 貢獻

開發

📝 變更記錄

v1.0.5

v1.0.4

v1.0.3 (2026-03-01) 🔧

v1.0.2 (2026-01-16) 🎯

v1.0.1 (2024-01-XX)

📄 授權

🔗 相關資源

🙏 致謝

💬 支援