excel-csv-handler 1.0.8 → 1.0.11

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "excel-csv-handler",
-  "version": "1.0.8",
+  "version": "1.0.11",
   "description": "A Node.js utility to read/write Excel and CSV files with GBK encoding support",
   "main": "src/index.js",
   "types": "src/excel-csv-handler.d.ts",
   "type": "module",
+  "files": [
+    "src/",
+    "README.md"
+  ],
   "keywords": [
     "excel",
     "csv",
@@ -16,6 +20,7 @@
   "author": "Chao_bei",
   "license": "MIT",
   "dependencies": {
+    "chardet": "^2.1.1",
     "fast-csv": "^5.0.5",
     "iconv-lite": "^0.7.0",
     "xlsx": "^0.18.5"

package/src/excel-csv-handler.d.ts

@@ -1,12 +1,47 @@
 // src/excel-csv-handler.d.ts
 export default class ExcelCsvHandler {
+	/**
+	 * 检测文件编码（用于 CSV 文件）
+	 * @param filePath - 文件路径
+	 * @returns 检测到的编码格式 (utf8 或 gbk)
+	 */
+	detectEncoding(filePath: string): string;
+	/**
+	 * 读取 Excel 或 CSV 文件（支持 GBK 编码）
+	 * @param filePath - 文件路径
+	 * @param headerRow - 标题行索引（从 0 开始）
+	 * @returns Promise<Array<Object>>
+	 */
 	read(
 		filePath: string,
 		headerRow?: number
 	): Promise<Array<Record<string, string>>>;
+
+	/**
+	 * 写入 Excel 或 CSV 文件（以 GBK 编码保存 CSV，Excel 保持默认）
+	 * @param filePath - 文件路径
+	 * @param data - 要写入的数据
+	 * @param headers - 可选列顺序
+	 * @param sheetName - Excel sheet 名称（默认为 'Sheet1'）
+	 */
 	write(
 		filePath: string,
 		data: Array<Record<string, any>>,
-		headers?: string[] | null
+		headers?: string[] | null,
+		sheetName?: string
+	): Promise<void>;
+
+	/**
+	 * 追加数据到 CSV 文件末尾（以 GBK 编码）
+	 * @param filePath - 文件路径
+	 * @param data - 要追加的数据
+	 * @param headers - 可选列顺序（如果文件不存在会自动创建并写入标题行）
+	 * @param encoding - 编码格式，默认 'gbk'，可选 'utf8'
+	 */
+	appendCsv(
+		filePath: string,
+		data: Array<Record<string, any>>,
+		headers?: string[] | null,
+		encoding?: string
 	): Promise<void>;
 }

package/src/index.js

@@ -6,9 +6,48 @@ import * as path from 'path';
 import iconv from 'iconv-lite';
 import * as csv from 'fast-csv';
 import { writeToString } from 'fast-csv';
+import chardet from 'chardet';
 const require = createRequire(import.meta.url);
 const XLSX = require('xlsx');
 class ExcelCsvHandler {
+    /**
+     * 检测文件编码（用于 CSV 文件）
+     * @param {string} filePath - 文件路径
+     * @returns {string} 检测到的编码格式 (utf8 或 gbk)
+     */
+    detectEncoding(filePath) {
+        // 读取文件的前几个字节来检测编码
+        const buffer = fs.readFileSync(filePath);
+        
+        // 检查 UTF-8 BOM
+        if (buffer.length >= 3 && 
+            buffer[0] === 0xEF && 
+            buffer[1] === 0xBB && 
+            buffer[2] === 0xBF) {
+            return 'utf8';
+        }
+        
+        // 使用 chardet 库检测编码
+        const detected = chardet.detect(buffer);
+        
+        // 将检测结果映射到 iconv-lite 支持的编码名称
+        if (detected) {
+            const encoding = detected.toLowerCase();
+            
+            // GB2312, GBK, GB18030 都映射为 gbk
+            if (encoding.includes('gb') || encoding.includes('gbk')) {
+                return 'gbk';
+            }
+            
+            // UTF-8 相关
+            if (encoding.includes('utf-8') || encoding.includes('utf8')) {
+                return 'utf8';
+            }
+        }
+        
+        // 默认返回 gbk（考虑到中国用户常用 GBK）
+        return 'gbk';
+    }
     /**
      * 读取 Excel 或 CSV 文件（支持 GBK 编码）
      * @param {string} filePath - 文件路径
@@ -19,9 +58,9 @@ class ExcelCsvHandler {
         const ext = path.extname(filePath).toLowerCase();
 
         if (ext === '.xlsx' || ext === '.xls') {
-            return this.readExcelFile(filePath, headerRow);
+            return this.#readExcelFile(filePath, headerRow);
         } else if (ext === '.csv') {
-            return this.readCsvFile(filePath, headerRow);
+            return this.#readCsvFile(filePath, headerRow);
         } else {
             throw new Error(`不支持的文件格式: ${ext}`);
         }
@@ -38,9 +77,9 @@ class ExcelCsvHandler {
         const ext = path.extname(filePath).toLowerCase();
 
         if (ext === '.xlsx' || ext === '.xls') {
-            this.writeExcelFile(filePath, data, headers, sheetName);
+            this.#writeExcelFile(filePath, data, headers, sheetName);
         } else if (ext === '.csv') {
-            await this.writeCsvFile(filePath, data, headers);
+            await this.#writeCsvFile(filePath, data, headers);
         } else {
             throw new Error(`不支持的文件格式: ${ext}`);
         }
@@ -48,7 +87,7 @@ class ExcelCsvHandler {
 
     // ========= Excel 读写 =========
 
-    readExcelFile(filePath, headerRow) {
+    #readExcelFile(filePath, headerRow) {
         const workbook = XLSX.readFile(filePath);
         const sheetName = workbook.SheetNames[0];
         const worksheet = workbook.Sheets[sheetName];
@@ -80,7 +119,7 @@ class ExcelCsvHandler {
         });
     }
 
-    writeExcelFile(filePath, data, headers = null, sheetName = 'Sheet1') {
+    #writeExcelFile(filePath, data, headers = null, sheetName = 'Sheet1') {
         if (!headers && data.length > 0) {
             headers = Object.keys(data[0]);
         } else if (!headers) {
@@ -96,11 +135,14 @@ class ExcelCsvHandler {
 
     // ========= CSV 读写 =========
 
-    async readCsvFile(filePath, headerRow) {
+    async #readCsvFile(filePath, headerRow) {
+        // 自动检测编码
+        const encoding = this.detectEncoding(filePath);
+        
         return new Promise((resolve, reject) => {
             const allRows = [];
             const stream = fs.createReadStream(filePath)
-                .pipe(iconv.decodeStream('gbk'))
+                .pipe(iconv.decodeStream(encoding))
                 .pipe(csv.parse({ headers: false, skipLines: headerRow }));
 
             stream.on('data', row => {
@@ -132,7 +174,14 @@ class ExcelCsvHandler {
         });
     }
 
-    async writeCsvFile(filePath, data, headers = null) {
+    /**
+     * 写入 CSV 文件（以 GBK 编码保存）
+     * @param {string} filePath - 文件路径
+     * @param {Array<Object>} data - 要写入的数据
+     * @param {Array<string>} headers - 可选列顺序
+     * @param {string} encoding - 编码格式，默认 'gbk'，可选 'utf8'
+     */
+    async #writeCsvFile(filePath, data, headers = null, encoding = 'gbk') {
         if (!headers && data.length > 0) {
             headers = Object.keys(data[0]);
         } else if (!headers) {
@@ -145,8 +194,65 @@ class ExcelCsvHandler {
             rowDelimiter: '\r\n',
         });
 
-        const gbkBuffer = iconv.encode(csvString, 'gbk');
-        fs.writeFileSync(filePath, gbkBuffer);
+        const buffer = iconv.encode(csvString, encoding);
+        
+        // 如果是 UTF-8，添加 BOM 标记以确保 Excel 正确识别
+        if (encoding === 'utf8') {
+            const bom = Buffer.from([0xEF, 0xBB, 0xBF]);
+            fs.writeFileSync(filePath, Buffer.concat([bom, buffer]));
+        } else {
+            fs.writeFileSync(filePath, buffer);
+        }
+    }
+
+    /**
+     * 追加数据到 CSV 文件末尾（以 GBK 编码）
+     * @param {string} filePath - 文件路径
+     * @param {Array<Object>} data - 要追加的数据
+     * @param {Array<string>} headers - 可选列顺序（如果文件不存在会自动创建并写入标题行）
+     * @param {string} encoding - 编码格式，默认 'gbk'，可选 'utf8'
+     */
+    async appendCsv(filePath, data, headers = null, encoding = 'gbk') {
+        if (!headers && data.length > 0) {
+            headers = Object.keys(data[0]);
+        } else if (!headers) {
+            headers = [];
+        }
+
+        // 检查文件是否存在
+        const fileExists = fs.existsSync(filePath);
+
+        if (!fileExists) {
+            // 文件不存在，自动创建并写入标题行和数据
+            await this.#writeCsvFile(filePath, data, headers, encoding);
+            return;
+        }
+        
+        // 文件存在时，检测现有文件的编码
+        const detectedEncoding = this.detectEncoding(filePath);
+
+        // 文件存在，追加数据（不包含标题行）
+        const csvString = await writeToString(data, {
+            headers: false,
+            includeEndRowDelimiter: true,
+            rowDelimiter: '\r\n',
+            writeHeaders: false,
+        });
+
+        // 将数据按照指定的列顺序格式化
+        const rows = data.map(row =>
+            headers.map(h => {
+                const value = row[h] ?? '';
+                // 如果值包含逗号、引号或换行符，需要用引号包裹并转义
+                if (value.toString().includes(',') || value.toString().includes('"') || value.toString().includes('\n')) {
+                    return '"' + value.toString().replace(/"/g, '""') + '"';
+                }
+                return value;
+            }).join(',')
+        ).join('\r\n') + '\r\n';
+
+        const buffer = iconv.encode(rows, detectedEncoding);
+        fs.appendFileSync(filePath, buffer);
     }
 }