Merge pull request #3 from zurmokeeper/feature/add_encryption_func

Feature/add encryption func

Author: zurmokeeper

README.md

@@ -13,9 +13,44 @@ Reverse engineered from Excel spreadsheet files as a project.
 # Installation
 
 ```shell
-npm install exceljs
+npm install @zurmokeeper/exceljs
 ```
 
+# V4.4.1 New Features!
+
+Change Log:
+<ul>
+  <li>
+    Add nested columns feature. Thank you <a href="https://github.com/jeka1985">jeka1985</a>, Merged <a href="https://github.com/exceljs/exceljs/pull/1889"> PR1889</a>.
+    
+    Code snippets: 
+
+    // new api: worksheet.makeColumns(headers)
+  </li>
+  <li>
+    Add file encryption function.
+
+    Code snippets: 
+
+    await workbook.xlsx.writeFile(filename, {password: '123456'});
+  </li>
+</ul>
+
+# V4.4.0 New Features!
+
+Change Log:
+<ul>
+  <li>
+    Add decryption of excel files with password encryption (Support frontend and backend)
+
+    Code snippets:
+
+    // read from a stream, decrypt excel files encrypted with password
+    // const workbook = new Excel.Workbook();
+    // await workbook.xlsx.readFile(filename, {password:'123456'});
+  </li>
+</ul>
+
 # New Features!
 
 <ul>
@@ -742,6 +777,26 @@ const newCol3Values = [1,2,3,4,5];
 const newCol4Values = ['one', 'two', 'three', 'four', 'five'];
 worksheet.spliceColumns(3, 1, newCol3Values, newCol4Values);
 
+// Nested columns
+// Also you can build nested columns 
+worksheet.makeColumns([
+  {
+    id: 1, 
+    title: 'Some', 
+  },
+  {id: 2, title: 'Qwe'},
+  {id: 3, title: 'Foo'},
+  {
+    id: 4,
+    title: 'Zoo',
+    children: [
+      { id: 41, title: 'Zoo 1' },
+      { id: 42, title: 'Zoo 2' },
+      { id: 44, title: 'Zoo 3' },
+      { id: 45, title: 'Zoo 4' },
+    ]
+  }
+]);
 ```
 
 ## Rows[⬆](#contents)<!-- Link generated with jump2header -->
@@ -2193,11 +2248,21 @@ await workbook.xlsx.load(data, {password:'123456'});
 const workbook = createAndFillWorkbook();
 await workbook.xlsx.writeFile(filename);
 
+// write to a file, with password encryption
+const workbook = createAndFillWorkbook();
+await workbook.xlsx.writeFile(filename, {password: '123456'});
+
 // write to a stream
 await workbook.xlsx.write(stream);
 
+// write to a stream, with password encryption
+await workbook.xlsx.write(stream, {password: '123456'}));
+
 // write to a new buffer
 const buffer = await workbook.xlsx.writeBuffer();
+
+// write to a new buffer, with password encryption
+const buffer = await workbook.xlsx.writeBuffer({password: '123456'});
 ```
 
 ### CSV[⬆](#contents)<!-- Link generated with jump2header -->

README_zh.md

@@ -11,9 +11,44 @@
 # 安装
 
 ```shell
-npm install exceljs
+npm install @zurmokeeper/exceljs
 ```
 
+# V4.4.1 新的功能!
+
+变更日志:
+<ul>
+  <li>
+    新增嵌套列功能（多表头）. 感谢 <a href="https://github.com/jeka1985">jeka1985</a>, Merged <a href="https://github.com/exceljs/exceljs/pull/1889"> PR1889</a>.
+    
+    Code snippets: 
+
+    // new api: worksheet.makeColumns(headers)
+  </li>
+  <li>
+    新增导出加密Excel文件功能.
+
+    Code snippets: 
+
+    await workbook.xlsx.writeFile(filename, {password: '123456'});
+  </li>
+</ul>
+
+# V4.4.0 新的功能!
+
+变更日志:
+<ul>
+  <li>
+    新增读取加密Excel的功能 (支持前端和后端（Node.js）)
+
+    Code snippets:
+
+    // read from a stream, decrypt excel files encrypted with password
+    // const workbook = new Excel.Workbook();
+    // await workbook.xlsx.readFile(filename, {password:'123456'});
+  </li>
+</ul>
+
 # 新的功能!
 
 <ul>
@@ -689,6 +724,26 @@ const newCol3Values = [1,2,3,4,5];
 const newCol4Values = ['one', 'two', 'three', 'four', 'five'];
 worksheet.spliceColumns(3, 1, newCol3Values, newCol4Values);
 
+// 嵌套列
+// 使用这个API来构建嵌套列（实现多级表头）
+worksheet.makeColumns([
+  {
+    id: 1, 
+    title: 'Some', 
+  },
+  {id: 2, title: 'Qwe'},
+  {id: 3, title: 'Foo'},
+  {
+    id: 4,
+    title: 'Zoo',
+    children: [
+      { id: 41, title: 'Zoo 1' },
+      { id: 42, title: 'Zoo 2' },
+      { id: 44, title: 'Zoo 3' },
+      { id: 45, title: 'Zoo 4' },
+    ]
+  }
+]);
 ```
 
 ## 行[⬆](#目录)<!-- Link generated with jump2header -->
@@ -2083,11 +2138,21 @@ await workbook.xlsx.load(data, {password:'123456'});
 const workbook = createAndFillWorkbook();
 await workbook.xlsx.writeFile(filename);
 
+// 写入文件, 带密码保护的
+const workbook = createAndFillWorkbook();
+await workbook.xlsx.writeFile(filename, {password: '123456'});
+
 // 写入流
 await workbook.xlsx.write(stream);
 
+// 写入流, 带密码保护的
+await workbook.xlsx.write(stream, {password: '123456'}));
+
 // 写入 buffer
 const buffer = await workbook.xlsx.writeBuffer();
+
+// 写入 buffer, 带密码保护的
+const buffer = await workbook.xlsx.writeBuffer({password: '123456'});
 ```
 
 ### CSV[⬆](#目录)<!-- Link generated with jump2header -->

index.d.ts

@@ -1163,15 +1163,43 @@ export interface Worksheet {
 	 * Cut one or more columns (columns to the right are shifted left)
 	 * and optionally insert more
 	 *
-	 * If column properties have been definde, they will be cut or moved accordingly
+	 * If column properties have been define, they will be cut or moved accordingly
 	 *
 	 * Known Issue: If a splice causes any merged cells to move, the results may be unpredictable
 	 *
-	 * Also: If the worksheet has more rows than values in the colulmn inserts,
+	 * Also: If the worksheet has more rows than values in the column inserts,
 	 * the rows will still be shifted as if the values existed
 	 */
 	spliceColumns(start: number, count: number, ...insert: any[][]): void;
 
+	/**
+	 * Generate nested columns
+	 * Example:
+	 * 
+	 *  const headers = [
+	 *  {id: 1,title: 'name'},
+        {id: 2, title: 'Qwe'},
+        {id: 3, title: 'Foo'},
+        {
+          id: 4,
+          title: 'ABC',
+          children: [
+            {id: 41, title: 'Zoo 1'},
+            {id: 42, title: 'Zoo 2'},
+            {id: 44, title: 'Zoo 3'},
+          ],
+        }]
+	 *
+	 *	const workbook = new ExcelJS.Workbook();
+	 *	const worksheet = workbook.addWorksheet('Sheet1');
+	 *	worksheet.makeColumns(headers);
+	 *
+	 * 
+	 * Note: This API allows you to quickly build an excel with multiple table headers.
+	 * TODO: Can you set the background color together?
+	 */
+	makeColumns(input: any[][]): any[][];
+
 	/**
 	 * Add column headers and define column keys and widths.
 	 *
@@ -1451,6 +1479,12 @@ export interface XlsxWriteOptions extends stream.xlsx.WorkbookWriterOptions {
 	 * The option passed to JsZip#generateAsync(options)
 	 */
 	zip: Partial<JSZipGeneratorOptions>;
+
+	/**
+	 * @desc Password for decryption
+	 * optional
+	 */
+	password: string;
 }
 
 export interface XlsxReadOptions {

lib/doc/worksheet.js

@@ -10,6 +10,7 @@ const Table = require('./table');
 const DataValidations = require('./data-validations');
 const Encryptor = require('../utils/encryptor');
 const {copyStyle} = require('../utils/copy-style');
+const ColumnFlatter = require('../utils/column-flatter');
 
 // Worksheet requirements
 //  Operate as sheet inside workbook or standalone
@@ -922,6 +923,37 @@ class Worksheet {
     }, {});
     this.conditionalFormattings = value.conditionalFormattings;
   }
+
+  /**
+   * @desc Generates a nested column
+   */
+  makeColumns(input) {
+    const flatter = new ColumnFlatter(input);
+    const merges = flatter.getMerges();
+    const rows = flatter.getRows();
+
+    this.columns = flatter.getColumns();
+
+    // For the time being, do not write dead freeze, can be set by the developers themselves
+    // this.views.push({state: 'frozen', ySplit: rows.length});
+
+    this.addRows(
+      rows.map(row => {
+        return row.map(item => {
+          if (!item) return null;
+          if (item.title) return item.title;
+          if (item.id) return item.id;
+          return null;
+        });
+      })
+    );
+
+    merges.forEach(item => {
+      this.mergeCells(item);
+    });
+
+    return {rows};
+  }
 }
 
 module.exports = Worksheet;