2017-04-21 22:02:02 +00:00
|
|
|
# [SheetJS js-xlsx](http://sheetjs.com)
|
2012-12-04 19:27:20 +00:00
|
|
|
|
2015-04-02 20:32:22 +00:00
|
|
|
Parser and writer for various spreadsheet formats. Pure-JS cleanroom
|
2017-02-22 06:57:59 +00:00
|
|
|
implementation from official specifications, related documents, and test files.
|
|
|
|
Emphasis on parsing and writing robustness, cross-format feature compatibility
|
|
|
|
with a unified JS representation, and ES3/ES5 browser compatibility back to IE6.
|
|
|
|
|
2017-04-20 03:24:48 +00:00
|
|
|
This is the community version. We also offer a pro version with performance
|
|
|
|
enhancements and additional features by request.
|
2017-02-22 06:57:59 +00:00
|
|
|
|
2017-04-20 03:24:48 +00:00
|
|
|
[**Pro Version**](http://sheetjs.com/pro)
|
2014-10-26 05:26:18 +00:00
|
|
|
|
2017-04-20 03:24:48 +00:00
|
|
|
[**Commercial Support**](http://sheetjs.com/support)
|
2017-03-10 17:33:08 +00:00
|
|
|
|
2017-04-26 02:27:12 +00:00
|
|
|
[**Rendered Documentation**](https://sheetjs.gitbooks.io/docs/)
|
|
|
|
|
2017-04-20 03:24:48 +00:00
|
|
|
[**In-Browser Demos**](http://sheetjs.com/demos)
|
|
|
|
|
|
|
|
[**Source Code**](http://git.io/xlsx)
|
|
|
|
|
2017-03-13 06:46:37 +00:00
|
|
|
[**File format support for known spreadsheet data formats:**](#file-formats)
|
|
|
|
|
|
|
|
![circo graph of format support](formats.png)
|
2014-10-26 05:26:18 +00:00
|
|
|
|
2017-04-03 00:16:03 +00:00
|
|
|
![graph legend](legend.png)
|
2012-12-04 19:27:20 +00:00
|
|
|
|
2017-02-03 20:50:45 +00:00
|
|
|
|
2017-03-13 06:46:37 +00:00
|
|
|
## Table of Contents
|
|
|
|
|
|
|
|
<!-- toc -->
|
|
|
|
|
|
|
|
- [Installation](#installation)
|
|
|
|
* [JS Ecosystem Demos](#js-ecosystem-demos)
|
|
|
|
* [Optional Modules](#optional-modules)
|
|
|
|
* [ECMAScript 5 Compatibility](#ecmascript-5-compatibility)
|
|
|
|
- [Parsing Workbooks](#parsing-workbooks)
|
2017-04-16 04:32:13 +00:00
|
|
|
* [Note on Streaming Read](#note-on-streaming-read)
|
2017-03-13 06:46:37 +00:00
|
|
|
- [Working with the Workbook](#working-with-the-workbook)
|
|
|
|
- [Writing Workbooks](#writing-workbooks)
|
2017-04-16 04:32:13 +00:00
|
|
|
* [Streaming Write](#streaming-write)
|
2017-03-13 06:46:37 +00:00
|
|
|
- [Interface](#interface)
|
|
|
|
* [Parsing functions](#parsing-functions)
|
|
|
|
* [Writing functions](#writing-functions)
|
|
|
|
* [Utilities](#utilities)
|
2017-04-03 00:16:03 +00:00
|
|
|
- [Common Spreadsheet Format](#common-spreadsheet-format)
|
2017-03-13 06:46:37 +00:00
|
|
|
* [General Structures](#general-structures)
|
|
|
|
* [Cell Object](#cell-object)
|
2017-03-20 09:02:25 +00:00
|
|
|
+ [Data Types](#data-types)
|
2017-03-21 20:44:35 +00:00
|
|
|
+ [Dates](#dates)
|
2017-03-31 21:46:02 +00:00
|
|
|
* [Sheet Objects](#sheet-objects)
|
2017-04-01 07:32:12 +00:00
|
|
|
+ [Worksheet Object](#worksheet-object)
|
|
|
|
+ [Chartsheet Object](#chartsheet-object)
|
2017-03-13 06:46:37 +00:00
|
|
|
* [Workbook Object](#workbook-object)
|
2017-04-01 07:32:12 +00:00
|
|
|
+ [Workbook File Properties](#workbook-file-properties)
|
2017-04-11 22:15:36 +00:00
|
|
|
* [Workbook-Level Attributes](#workbook-level-attributes)
|
|
|
|
+ [Defined Names](#defined-names)
|
2017-03-20 09:02:25 +00:00
|
|
|
* [Document Features](#document-features)
|
|
|
|
+ [Formulae](#formulae)
|
|
|
|
+ [Column Properties](#column-properties)
|
2017-04-28 07:28:03 +00:00
|
|
|
+ [Row Properties](#row-properties)
|
2017-04-30 16:27:03 +00:00
|
|
|
+ [Number Formats](#number-formats)
|
2017-03-29 19:14:15 +00:00
|
|
|
+ [Hyperlinks](#hyperlinks)
|
2017-04-02 06:47:25 +00:00
|
|
|
+ [Cell Comments](#cell-comments)
|
2017-03-31 18:46:42 +00:00
|
|
|
+ [Sheet Visibility](#sheet-visibility)
|
2017-03-13 06:46:37 +00:00
|
|
|
- [Parsing Options](#parsing-options)
|
|
|
|
* [Input Type](#input-type)
|
|
|
|
* [Guessing File Type](#guessing-file-type)
|
|
|
|
- [Writing Options](#writing-options)
|
|
|
|
* [Supported Output Formats](#supported-output-formats)
|
|
|
|
* [Output Type](#output-type)
|
|
|
|
- [Utility Functions](#utility-functions)
|
2017-03-25 01:36:40 +00:00
|
|
|
* [Array of Arrays Input](#array-of-arrays-input)
|
2017-03-29 19:14:15 +00:00
|
|
|
* [HTML Table Input](#html-table-input)
|
2017-03-13 06:46:37 +00:00
|
|
|
* [Formulae Output](#formulae-output)
|
2017-04-03 00:16:03 +00:00
|
|
|
* [Delimiter-Separated Output](#delimiter-separated-output)
|
|
|
|
+ [UTF-16 Unicode Text](#utf-16-unicode-text)
|
2017-03-13 06:46:37 +00:00
|
|
|
* [JSON](#json)
|
|
|
|
- [File Formats](#file-formats)
|
|
|
|
* [Excel 2007+ XML (XLSX/XLSM)](#excel-2007-xml-xlsxxlsm)
|
|
|
|
* [Excel 2.0-95 (BIFF2/BIFF3/BIFF4/BIFF5)](#excel-20-95-biff2biff3biff4biff5)
|
|
|
|
* [Excel 97-2004 Binary (BIFF8)](#excel-97-2004-binary-biff8)
|
|
|
|
* [Excel 2003-2004 (SpreadsheetML)](#excel-2003-2004-spreadsheetml)
|
|
|
|
* [Excel 2007+ Binary (XLSB, BIFF12)](#excel-2007-binary-xlsb-biff12)
|
2017-04-03 00:16:03 +00:00
|
|
|
* [Delimiter-Separated Values (CSV/TXT)](#delimiter-separated-values-csvtxt)
|
2017-04-04 16:09:41 +00:00
|
|
|
* [Other Workbook Formats](#other-workbook-formats)
|
|
|
|
+ [Lotus 1-2-3 (WKS/WK1/WK2/WK3/WK4/123)](#lotus-1-2-3-wkswk1wk2wk3wk4123)
|
|
|
|
+ [Quattro Pro (WQ1/WQ2/WB1/WB2/WB3/QPW)](#quattro-pro-wq1wq2wb1wb2wb3qpw)
|
|
|
|
+ [OpenDocument Spreadsheet (ODS/FODS)](#opendocument-spreadsheet-odsfods)
|
|
|
|
+ [Uniform Office Spreadsheet (UOS1/2)](#uniform-office-spreadsheet-uos12)
|
2017-04-01 07:32:12 +00:00
|
|
|
* [Other Single-Worksheet Formats](#other-single-worksheet-formats)
|
|
|
|
+ [dBASE and Visual FoxPro (DBF)](#dbase-and-visual-foxpro-dbf)
|
|
|
|
+ [Symbolic Link (SYLK)](#symbolic-link-sylk)
|
2017-04-03 00:16:03 +00:00
|
|
|
+ [Lotus Formatted Text (PRN)](#lotus-formatted-text-prn)
|
2017-04-01 07:32:12 +00:00
|
|
|
+ [Data Interchange Format (DIF)](#data-interchange-format-dif)
|
|
|
|
+ [HTML](#html)
|
2017-03-13 06:46:37 +00:00
|
|
|
- [Testing](#testing)
|
2017-04-13 17:05:42 +00:00
|
|
|
* [Node](#node)
|
|
|
|
* [Browser](#browser)
|
2017-03-13 06:46:37 +00:00
|
|
|
* [Tested Environments](#tested-environments)
|
|
|
|
* [Test Files](#test-files)
|
|
|
|
- [Contributing](#contributing)
|
2017-04-28 07:28:03 +00:00
|
|
|
* [Tests](#tests)
|
2017-04-09 07:11:08 +00:00
|
|
|
* [OSX/Linux](#osxlinux)
|
|
|
|
* [Windows](#windows)
|
2017-03-13 06:46:37 +00:00
|
|
|
- [License](#license)
|
|
|
|
- [References](#references)
|
|
|
|
- [Badges](#badges)
|
|
|
|
|
|
|
|
<!-- tocstop -->
|
2017-02-10 19:23:01 +00:00
|
|
|
|
2012-12-04 19:27:20 +00:00
|
|
|
## Installation
|
|
|
|
|
2015-04-02 20:32:22 +00:00
|
|
|
With [npm](https://www.npmjs.org/package/xlsx):
|
2012-12-04 19:27:20 +00:00
|
|
|
|
2016-12-31 08:20:45 +00:00
|
|
|
```bash
|
|
|
|
$ npm install xlsx
|
|
|
|
```
|
2012-12-04 19:27:20 +00:00
|
|
|
|
|
|
|
In the browser:
|
|
|
|
|
2016-12-31 08:20:45 +00:00
|
|
|
```html
|
|
|
|
<script lang="javascript" src="dist/xlsx.core.min.js"></script>
|
|
|
|
```
|
2014-04-23 01:37:08 +00:00
|
|
|
|
2015-04-02 20:32:22 +00:00
|
|
|
With [bower](http://bower.io/search/?q=js-xlsx):
|
2014-04-23 01:37:08 +00:00
|
|
|
|
2016-12-31 08:20:45 +00:00
|
|
|
```bash
|
|
|
|
$ bower install js-xlsx
|
|
|
|
```
|
2014-04-23 01:37:08 +00:00
|
|
|
|
|
|
|
CDNjs automatically pulls the latest version and makes all versions available at
|
|
|
|
<http://cdnjs.com/libraries/xlsx>
|
|
|
|
|
2017-03-10 17:33:08 +00:00
|
|
|
### JS Ecosystem Demos
|
|
|
|
|
|
|
|
The `demos` directory includes sample projects for:
|
|
|
|
|
2017-03-25 01:36:40 +00:00
|
|
|
- [`angular`](demos/angular/)
|
2017-03-23 17:11:31 +00:00
|
|
|
- [`browserify`](demos/browserify/)
|
2017-03-25 22:18:50 +00:00
|
|
|
- [`Adobe ExtendScript`](demos/extendscript/)
|
2017-03-28 04:41:01 +00:00
|
|
|
- [`phantomjs`](demos/phantomjs/)
|
2017-03-23 17:11:31 +00:00
|
|
|
- [`requirejs`](demos/requirejs/)
|
|
|
|
- [`systemjs`](demos/systemjs/)
|
|
|
|
- [`webpack`](demos/webpack/)
|
2017-03-10 17:33:08 +00:00
|
|
|
|
2017-02-22 06:57:59 +00:00
|
|
|
### Optional Modules
|
2014-04-23 01:37:08 +00:00
|
|
|
|
2015-04-02 20:32:22 +00:00
|
|
|
The node version automatically requires modules for additional features. Some
|
2014-05-01 00:24:27 +00:00
|
|
|
of these modules are rather large in size and are only needed in special
|
|
|
|
circumstances, so they do not ship with the core. For browser use, they must
|
|
|
|
be included directly:
|
2014-04-23 01:37:08 +00:00
|
|
|
|
2016-12-31 08:20:45 +00:00
|
|
|
```html
|
2017-02-03 20:50:45 +00:00
|
|
|
<!-- international support from js-codepage -->
|
2016-12-31 08:20:45 +00:00
|
|
|
<script src="dist/cpexcel.js"></script>
|
|
|
|
```
|
2014-04-23 01:37:08 +00:00
|
|
|
|
|
|
|
An appropriate version for each dependency is included in the dist/ directory.
|
|
|
|
|
|
|
|
The complete single-file version is generated at `dist/xlsx.full.min.js`
|
|
|
|
|
2017-03-13 06:46:37 +00:00
|
|
|
Webpack and browserify builds include optional modules by default. Webpack can
|
|
|
|
be configured to remove support with `resolve.alias`:
|
|
|
|
|
|
|
|
```js
|
|
|
|
/* uncomment the lines below to remove support */
|
|
|
|
resolve: {
|
|
|
|
alias: { "./dist/cpexcel.js": "" } // <-- omit international support
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
|
2017-02-22 06:57:59 +00:00
|
|
|
### ECMAScript 5 Compatibility
|
2014-06-03 18:39:46 +00:00
|
|
|
|
|
|
|
Since xlsx.js uses ES5 functions like `Array#forEach`, older browsers require
|
|
|
|
[Polyfills](http://git.io/QVh77g). This repo and the gh-pages branch include
|
|
|
|
[a shim](https://github.com/SheetJS/js-xlsx/blob/master/shim.js)
|
|
|
|
|
|
|
|
To use the shim, add the shim before the script tag that loads xlsx.js:
|
|
|
|
|
2016-12-31 08:20:45 +00:00
|
|
|
```html
|
|
|
|
<script type="text/javascript" src="/path/to/shim.js"></script>
|
|
|
|
```
|
2014-06-03 18:39:46 +00:00
|
|
|
|
2014-05-28 18:31:33 +00:00
|
|
|
## Parsing Workbooks
|
2012-12-04 19:27:20 +00:00
|
|
|
|
2014-10-26 05:26:18 +00:00
|
|
|
For parsing, the first step is to read the file. This involves acquiring the
|
|
|
|
data and feeding it into the library. Here are a few common scenarios:
|
2012-12-04 19:27:20 +00:00
|
|
|
|
2015-04-02 20:32:22 +00:00
|
|
|
- node readFile:
|
2012-12-04 19:27:20 +00:00
|
|
|
|
2016-12-31 08:20:45 +00:00
|
|
|
```js
|
2014-05-28 18:31:33 +00:00
|
|
|
if(typeof require !== 'undefined') XLSX = require('xlsx');
|
|
|
|
var workbook = XLSX.readFile('test.xlsx');
|
|
|
|
/* DO SOMETHING WITH workbook HERE */
|
|
|
|
```
|
2014-05-22 12:16:51 +00:00
|
|
|
|
2017-03-29 19:14:15 +00:00
|
|
|
- Browser DOM Table element:
|
|
|
|
|
|
|
|
```js
|
|
|
|
var worksheet = XLSX.utils.table_to_book(document.getElementById('tableau'));
|
|
|
|
/* DO SOMETHING WITH workbook HERE */
|
|
|
|
```
|
|
|
|
|
2014-10-26 05:26:18 +00:00
|
|
|
- ajax (for a more complete example that works in older browsers, check the demo
|
|
|
|
at <http://oss.sheetjs.com/js-xlsx/ajax.html>):
|
2014-05-28 18:31:33 +00:00
|
|
|
|
2016-12-31 08:20:45 +00:00
|
|
|
```js
|
2014-05-28 18:31:33 +00:00
|
|
|
/* set up XMLHttpRequest */
|
|
|
|
var url = "test_files/formula_stress_test_ajax.xlsx";
|
|
|
|
var oReq = new XMLHttpRequest();
|
|
|
|
oReq.open("GET", url, true);
|
|
|
|
oReq.responseType = "arraybuffer";
|
|
|
|
|
|
|
|
oReq.onload = function(e) {
|
|
|
|
var arraybuffer = oReq.response;
|
|
|
|
|
|
|
|
/* convert data to binary string */
|
|
|
|
var data = new Uint8Array(arraybuffer);
|
|
|
|
var arr = new Array();
|
|
|
|
for(var i = 0; i != data.length; ++i) arr[i] = String.fromCharCode(data[i]);
|
|
|
|
var bstr = arr.join("");
|
|
|
|
|
|
|
|
/* Call XLSX */
|
|
|
|
var workbook = XLSX.read(bstr, {type:"binary"});
|
|
|
|
|
|
|
|
/* DO SOMETHING WITH workbook HERE */
|
|
|
|
}
|
|
|
|
|
|
|
|
oReq.send();
|
|
|
|
```
|
|
|
|
|
2017-02-03 20:50:45 +00:00
|
|
|
- HTML5 drag-and-drop using readAsBinaryString or readAsArrayBuffer:
|
|
|
|
note: readAsBinaryString and readAsArrayBuffer may not be available in every
|
|
|
|
browser. Use dynamic feature tests to determine which method to use.
|
2014-05-28 18:31:33 +00:00
|
|
|
|
2016-12-31 08:20:45 +00:00
|
|
|
```js
|
2017-02-03 20:50:45 +00:00
|
|
|
/* processing array buffers, only required for readAsArrayBuffer */
|
|
|
|
function fixdata(data) {
|
2017-03-13 06:46:37 +00:00
|
|
|
var o = "", l = 0, w = 10240;
|
|
|
|
for(; l<data.byteLength/w; ++l) o+=String.fromCharCode.apply(null,new Uint8Array(data.slice(l*w,l*w+w)));
|
|
|
|
o+=String.fromCharCode.apply(null, new Uint8Array(data.slice(l*w)));
|
|
|
|
return o;
|
2017-02-03 20:50:45 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
var rABS = true; // true: readAsBinaryString ; false: readAsArrayBuffer
|
2014-05-28 18:31:33 +00:00
|
|
|
/* set up drag-and-drop event */
|
|
|
|
function handleDrop(e) {
|
|
|
|
e.stopPropagation();
|
|
|
|
e.preventDefault();
|
|
|
|
var files = e.dataTransfer.files;
|
|
|
|
var i,f;
|
2017-02-03 20:50:45 +00:00
|
|
|
for (i = 0; i != files.length; ++i) {
|
|
|
|
f = files[i];
|
2014-05-28 18:31:33 +00:00
|
|
|
var reader = new FileReader();
|
|
|
|
var name = f.name;
|
|
|
|
reader.onload = function(e) {
|
|
|
|
var data = e.target.result;
|
|
|
|
|
2017-02-03 20:50:45 +00:00
|
|
|
var workbook;
|
|
|
|
if(rABS) {
|
|
|
|
/* if binary string, read with type 'binary' */
|
|
|
|
workbook = XLSX.read(data, {type: 'binary'});
|
|
|
|
} else {
|
|
|
|
/* if array buffer, convert to base64 */
|
|
|
|
var arr = fixdata(data);
|
|
|
|
workbook = XLSX.read(btoa(arr), {type: 'base64'});
|
|
|
|
}
|
2014-05-28 18:31:33 +00:00
|
|
|
|
|
|
|
/* DO SOMETHING WITH workbook HERE */
|
|
|
|
};
|
2017-02-03 20:50:45 +00:00
|
|
|
if(rABS) reader.readAsBinaryString(f);
|
|
|
|
else reader.readAsArrayBuffer(f);
|
2014-05-28 18:31:33 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
drop_dom_element.addEventListener('drop', handleDrop, false);
|
|
|
|
```
|
|
|
|
|
2017-02-03 20:50:45 +00:00
|
|
|
- HTML5 input file element using readAsBinaryString or readAsArrayBuffer:
|
2014-07-28 13:22:32 +00:00
|
|
|
|
2016-12-31 08:20:45 +00:00
|
|
|
```js
|
2017-02-03 20:50:45 +00:00
|
|
|
/* fixdata and rABS are defined in the drag and drop example */
|
2014-07-28 13:22:32 +00:00
|
|
|
function handleFile(e) {
|
|
|
|
var files = e.target.files;
|
|
|
|
var i,f;
|
2017-02-03 20:50:45 +00:00
|
|
|
for (i = 0; i != files.length; ++i) {
|
|
|
|
f = files[i];
|
2014-07-28 13:22:32 +00:00
|
|
|
var reader = new FileReader();
|
|
|
|
var name = f.name;
|
|
|
|
reader.onload = function(e) {
|
|
|
|
var data = e.target.result;
|
|
|
|
|
2017-02-03 20:50:45 +00:00
|
|
|
var workbook;
|
|
|
|
if(rABS) {
|
|
|
|
/* if binary string, read with type 'binary' */
|
|
|
|
workbook = XLSX.read(data, {type: 'binary'});
|
|
|
|
} else {
|
|
|
|
/* if array buffer, convert to base64 */
|
|
|
|
var arr = fixdata(data);
|
|
|
|
workbook = XLSX.read(btoa(arr), {type: 'base64'});
|
|
|
|
}
|
2014-07-28 13:22:32 +00:00
|
|
|
|
|
|
|
/* DO SOMETHING WITH workbook HERE */
|
|
|
|
};
|
|
|
|
reader.readAsBinaryString(f);
|
|
|
|
}
|
|
|
|
}
|
|
|
|
input_dom_element.addEventListener('change', handleFile, false);
|
|
|
|
```
|
|
|
|
|
2017-04-16 04:32:13 +00:00
|
|
|
**Complete examples:**
|
|
|
|
|
|
|
|
- <http://oss.sheetjs.com/js-xlsx/> HTML5 File API / Base64 Text / Web Workers
|
|
|
|
|
|
|
|
Note that older versions of IE do not support HTML5 File API, so the base64 mode
|
|
|
|
is used for testing. On OSX you can get the base64 encoding with:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
$ <target_file base64 | pbcopy
|
|
|
|
```
|
|
|
|
|
|
|
|
On Windows XP and up you can get the base64 encoding using `certutil`:
|
|
|
|
|
|
|
|
```cmd
|
|
|
|
> certutil -encode target_file target_file.b64
|
|
|
|
```
|
|
|
|
|
|
|
|
(note: You have to open the file and remove the header and footer lines)
|
|
|
|
|
|
|
|
- <http://oss.sheetjs.com/js-xlsx/ajax.html> XMLHttpRequest
|
|
|
|
|
|
|
|
### Note on Streaming Read
|
|
|
|
|
|
|
|
The most common and interesting formats (XLS, XLSX/M, XLSB, ODS) are ultimately
|
|
|
|
ZIP or CFB containers of files. Neither format puts the directory structure at
|
|
|
|
the beginning of the file: ZIP files place the Central Directory records at the
|
|
|
|
end of the logical file, while CFB files can place the FAT structure anywhere in
|
|
|
|
the file! As a result, to properly handle these formats, a streaming function
|
|
|
|
would have to buffer the entire file before commencing. That belies the
|
|
|
|
expectations of streaming, so we do not provide any streaming read API. If you
|
|
|
|
really want to stream, there are node modules like `concat-stream` that will do
|
|
|
|
the buffering for you.
|
|
|
|
|
2014-10-26 05:26:18 +00:00
|
|
|
## Working with the Workbook
|
|
|
|
|
2015-04-02 20:32:22 +00:00
|
|
|
The full object format is described later in this README.
|
|
|
|
|
|
|
|
This example extracts the value stored in cell A1 from the first worksheet:
|
|
|
|
|
2016-12-31 08:20:45 +00:00
|
|
|
```js
|
2015-04-02 20:32:22 +00:00
|
|
|
var first_sheet_name = workbook.SheetNames[0];
|
|
|
|
var address_of_cell = 'A1';
|
|
|
|
|
|
|
|
/* Get worksheet */
|
|
|
|
var worksheet = workbook.Sheets[first_sheet_name];
|
|
|
|
|
|
|
|
/* Find desired cell */
|
|
|
|
var desired_cell = worksheet[address_of_cell];
|
|
|
|
|
|
|
|
/* Get the value */
|
2017-03-14 08:19:51 +00:00
|
|
|
var desired_value = (desired_cell ? desired_cell.v : undefined);
|
2015-04-02 20:32:22 +00:00
|
|
|
```
|
|
|
|
|
2017-03-14 08:19:51 +00:00
|
|
|
**Complete examples:**
|
2014-05-28 18:31:33 +00:00
|
|
|
|
2015-04-02 20:32:22 +00:00
|
|
|
- <https://github.com/SheetJS/js-xlsx/blob/master/bin/xlsx.njs> node
|
2014-05-28 18:31:33 +00:00
|
|
|
|
2015-04-02 20:32:22 +00:00
|
|
|
The node version installs a command line tool `xlsx` which can read spreadsheet
|
2014-05-28 18:31:33 +00:00
|
|
|
files and output the contents in various formats. The source is available at
|
|
|
|
`xlsx.njs` in the bin directory.
|
2014-02-12 06:09:42 +00:00
|
|
|
|
2014-01-27 09:38:50 +00:00
|
|
|
Some helper functions in `XLSX.utils` generate different views of the sheets:
|
|
|
|
|
2014-02-04 00:00:44 +00:00
|
|
|
- `XLSX.utils.sheet_to_csv` generates CSV
|
2014-05-28 18:31:33 +00:00
|
|
|
- `XLSX.utils.sheet_to_json` generates an array of objects
|
2014-07-28 13:22:32 +00:00
|
|
|
- `XLSX.utils.sheet_to_formulae` generates a list of formulae
|
2014-01-27 09:38:50 +00:00
|
|
|
|
2014-05-28 18:31:33 +00:00
|
|
|
## Writing Workbooks
|
|
|
|
|
2014-10-26 05:26:18 +00:00
|
|
|
For writing, the first step is to generate output data. The helper functions
|
|
|
|
`write` and `writeFile` will produce the data in various formats suitable for
|
|
|
|
dissemination. The second step is to actual share the data with the end point.
|
|
|
|
Assuming `workbook` is a workbook object:
|
2014-05-28 18:31:33 +00:00
|
|
|
|
|
|
|
- nodejs write to file:
|
|
|
|
|
2016-12-31 08:20:45 +00:00
|
|
|
```js
|
2014-05-28 18:31:33 +00:00
|
|
|
/* output format determined by filename */
|
|
|
|
XLSX.writeFile(workbook, 'out.xlsx');
|
2014-10-26 05:26:18 +00:00
|
|
|
/* at this point, out.xlsx is a file that you can distribute */
|
2014-05-28 18:31:33 +00:00
|
|
|
```
|
|
|
|
|
2017-02-10 19:23:01 +00:00
|
|
|
- browser generate binary blob and "download" to client
|
|
|
|
(using [FileSaver.js](https://github.com/eligrey/FileSaver.js/) for download):
|
2014-05-28 18:31:33 +00:00
|
|
|
|
2016-12-31 08:20:45 +00:00
|
|
|
```js
|
2017-02-10 19:23:01 +00:00
|
|
|
/* bookType can be 'xlsx' or 'xlsm' or 'xlsb' or 'ods' */
|
2014-07-28 13:22:32 +00:00
|
|
|
var wopts = { bookType:'xlsx', bookSST:false, type:'binary' };
|
2014-05-28 18:31:33 +00:00
|
|
|
|
|
|
|
var wbout = XLSX.write(workbook,wopts);
|
|
|
|
|
|
|
|
function s2ab(s) {
|
|
|
|
var buf = new ArrayBuffer(s.length);
|
|
|
|
var view = new Uint8Array(buf);
|
|
|
|
for (var i=0; i!=s.length; ++i) view[i] = s.charCodeAt(i) & 0xFF;
|
|
|
|
return buf;
|
|
|
|
}
|
|
|
|
|
2014-10-26 05:26:18 +00:00
|
|
|
/* the saveAs call downloads a file on the local machine */
|
2017-02-03 20:50:45 +00:00
|
|
|
saveAs(new Blob([s2ab(wbout)],{type:"application/octet-stream"}), "test.xlsx");
|
2014-05-28 18:31:33 +00:00
|
|
|
```
|
|
|
|
|
2017-03-14 08:19:51 +00:00
|
|
|
**Complete examples:**
|
2014-02-07 10:53:40 +00:00
|
|
|
|
2014-05-28 18:31:33 +00:00
|
|
|
- <http://sheetjs.com/demos/writexlsx.html> generates a simple file
|
|
|
|
- <http://git.io/WEK88Q> writing an array of arrays in nodejs
|
2014-07-28 13:22:32 +00:00
|
|
|
- <http://sheetjs.com/demos/table.html> exporting an HTML table
|
2014-02-07 10:53:40 +00:00
|
|
|
|
2017-04-16 04:32:13 +00:00
|
|
|
### Streaming Write
|
|
|
|
|
2017-04-16 07:31:21 +00:00
|
|
|
The streaming write functions are available in the `XLSX.stream` object. They
|
|
|
|
take the same arguments as the normal write functions but return a readable
|
|
|
|
stream. They are only exposed in node.
|
2017-04-16 04:32:13 +00:00
|
|
|
|
2017-04-16 07:31:21 +00:00
|
|
|
- `XLSX.stream.to_csv` is the streaming version of `XLSX.utils.sheet_to_csv`.
|
|
|
|
- `XLSX.stream.to_html` is the streaming version of the HTML output type.
|
|
|
|
|
|
|
|
<https://github.com/sheetjs/sheetaki> pipes write streams to nodejs response.
|
2014-05-16 00:33:34 +00:00
|
|
|
## Interface
|
|
|
|
|
2015-04-02 20:32:22 +00:00
|
|
|
`XLSX` is the exposed variable in the browser and the exported node variable
|
2014-05-16 00:33:34 +00:00
|
|
|
|
2014-07-28 13:22:32 +00:00
|
|
|
`XLSX.version` is the version of the library (added by the build script).
|
|
|
|
|
|
|
|
`XLSX.SSF` is an embedded version of the [format library](http://git.io/ssf).
|
|
|
|
|
|
|
|
### Parsing functions
|
2014-05-16 00:33:34 +00:00
|
|
|
|
|
|
|
`XLSX.read(data, read_opts)` attempts to parse `data`.
|
|
|
|
|
|
|
|
`XLSX.readFile(filename, read_opts)` attempts to read `filename` and parse.
|
|
|
|
|
2017-03-10 23:39:17 +00:00
|
|
|
Parse options are described in the [Parsing Options](#parsing-options) section.
|
|
|
|
|
2014-07-28 13:22:32 +00:00
|
|
|
### Writing functions
|
|
|
|
|
2014-05-16 00:33:34 +00:00
|
|
|
`XLSX.write(wb, write_opts)` attempts to write the workbook `wb`
|
|
|
|
|
|
|
|
`XLSX.writeFile(wb, filename, write_opts)` attempts to write `wb` to `filename`
|
|
|
|
|
2017-03-25 01:36:40 +00:00
|
|
|
`XLSX.writeFileAsync(filename, wb, o, cb)` attempts to write `wb` to `filename`.
|
|
|
|
If `o` is omitted, the writer will use the third argument as the callback.
|
|
|
|
|
2017-04-16 07:31:21 +00:00
|
|
|
`XLSX.stream` contains a set of streaming write functions.
|
|
|
|
|
2017-03-10 23:39:17 +00:00
|
|
|
Write options are described in the [Writing Options](#writing-options) section.
|
|
|
|
|
2014-07-28 13:22:32 +00:00
|
|
|
### Utilities
|
|
|
|
|
|
|
|
Utilities are available in the `XLSX.utils` object:
|
|
|
|
|
2017-03-25 01:36:40 +00:00
|
|
|
**Importing:**
|
|
|
|
|
|
|
|
- `aoa_to_sheet` converts an array of arrays of JS data to a worksheet.
|
|
|
|
|
2017-03-14 08:19:51 +00:00
|
|
|
**Exporting:**
|
2014-07-28 13:22:32 +00:00
|
|
|
|
2017-03-05 00:56:31 +00:00
|
|
|
- `sheet_to_json` converts a worksheet object to an array of JSON objects.
|
2017-02-03 20:50:45 +00:00
|
|
|
`sheet_to_row_object_array` is an alias that will be removed in the future.
|
|
|
|
- `sheet_to_csv` generates delimiter-separated-values output.
|
|
|
|
- `sheet_to_formulae` generates a list of the formulae (with value fallbacks).
|
|
|
|
|
2017-03-10 23:39:17 +00:00
|
|
|
Exporters are described in the [Utility Functions](#utility-functions) section.
|
|
|
|
|
2014-07-28 13:22:32 +00:00
|
|
|
|
2017-03-14 08:19:51 +00:00
|
|
|
**Cell and cell address manipulation:**
|
2014-07-28 13:22:32 +00:00
|
|
|
|
|
|
|
- `format_cell` generates the text value for a cell (using number formats)
|
|
|
|
- `{en,de}code_{row,col}` convert between 0-indexed rows/cols and A1 forms.
|
|
|
|
- `{en,de}code_cell` converts cell addresses
|
|
|
|
- `{en,de}code_range` converts cell ranges
|
|
|
|
|
2017-04-03 00:16:03 +00:00
|
|
|
## Common Spreadsheet Format
|
2014-01-27 09:38:50 +00:00
|
|
|
|
2014-05-16 00:33:34 +00:00
|
|
|
js-xlsx conforms to the Common Spreadsheet Format (CSF):
|
|
|
|
|
2014-07-28 13:22:32 +00:00
|
|
|
### General Structures
|
|
|
|
|
|
|
|
Cell address objects are stored as `{c:C, r:R}` where `C` and `R` are 0-indexed
|
|
|
|
column and row numbers, respectively. For example, the cell address `B5` is
|
|
|
|
represented by the object `{c:1, r:4}`.
|
|
|
|
|
|
|
|
Cell range objects are stored as `{s:S, e:E}` where `S` is the first cell and
|
|
|
|
`E` is the last cell in the range. The ranges are inclusive. For example, the
|
|
|
|
range `A3:B7` is represented by the object `{s:{c:0, r:2}, e:{c:1, r:6}}`. Utils
|
|
|
|
use the following pattern to walk each of the cells in a range:
|
|
|
|
|
2016-12-31 08:20:45 +00:00
|
|
|
```js
|
2014-07-28 13:22:32 +00:00
|
|
|
for(var R = range.s.r; R <= range.e.r; ++R) {
|
|
|
|
for(var C = range.s.c; C <= range.e.c; ++C) {
|
|
|
|
var cell_address = {c:C, r:R};
|
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
### Cell Object
|
|
|
|
|
2017-02-19 20:36:32 +00:00
|
|
|
| Key | Description |
|
|
|
|
| --- | ---------------------------------------------------------------------- |
|
|
|
|
| `v` | raw value (see Data Types section for more info) |
|
|
|
|
| `w` | formatted text (if applicable) |
|
|
|
|
| `t` | cell type: `b` Boolean, `n` Number, `e` error, `s` String, `d` Date |
|
|
|
|
| `f` | cell formula encoded as an A1-style string (if applicable) |
|
|
|
|
| `F` | range of enclosing array if formula is array formula (if applicable) |
|
|
|
|
| `r` | rich text encoding (if applicable) |
|
|
|
|
| `h` | HTML rendering of the rich text (if applicable) |
|
|
|
|
| `c` | comments associated with the cell |
|
|
|
|
| `z` | number format string associated with the cell (if requested) |
|
2017-03-29 19:14:15 +00:00
|
|
|
| `l` | cell hyperlink object (.Target holds link, .Tooltip is tooltip) |
|
2017-02-19 20:36:32 +00:00
|
|
|
| `s` | the style/theme of the cell (if applicable) |
|
2014-07-28 13:22:32 +00:00
|
|
|
|
|
|
|
Built-in export utilities (such as the CSV exporter) will use the `w` text if it
|
|
|
|
is available. To change a value, be sure to delete `cell.w` (or set it to
|
|
|
|
`undefined`) before attempting to export. The utilities will regenerate the `w`
|
|
|
|
text from the number format (`cell.z`) and the raw value if possible.
|
|
|
|
|
2017-02-19 20:36:32 +00:00
|
|
|
The actual array formula is stored in the `f` field of the first cell in the
|
|
|
|
array range. Other cells in the range will omit the `f` field.
|
|
|
|
|
2017-03-20 09:02:25 +00:00
|
|
|
#### Data Types
|
2014-10-26 05:26:18 +00:00
|
|
|
|
|
|
|
The raw value is stored in the `v` field, interpreted based on the `t` field.
|
|
|
|
|
2017-03-10 17:33:08 +00:00
|
|
|
Type `b` is the Boolean type. `v` is interpreted according to JS truth tables.
|
2014-10-26 05:26:18 +00:00
|
|
|
|
|
|
|
Type `e` is the Error type. `v` holds the number and `w` holds the common name:
|
|
|
|
|
2017-03-10 17:33:08 +00:00
|
|
|
| Value | Error Meaning |
|
|
|
|
| -----: | :-------------- |
|
|
|
|
| `0x00` | `#NULL!` |
|
|
|
|
| `0x07` | `#DIV/0!` |
|
|
|
|
| `0x0F` | `#VALUE!` |
|
|
|
|
| `0x17` | `#REF!` |
|
|
|
|
| `0x1D` | `#NAME?` |
|
|
|
|
| `0x24` | `#NUM!` |
|
|
|
|
| `0x2A` | `#N/A` |
|
|
|
|
| `0x2B` | `#GETTING_DATA` |
|
2014-10-26 05:26:18 +00:00
|
|
|
|
|
|
|
Type `n` is the Number type. This includes all forms of data that Excel stores
|
|
|
|
as numbers, such as dates/times and Boolean fields. Excel exclusively uses data
|
|
|
|
that can be fit in an IEEE754 floating point number, just like JS Number, so the
|
2017-03-19 23:04:31 +00:00
|
|
|
`v` field holds the raw number. The `w` field holds formatted text. Dates are
|
|
|
|
stored as numbers by default and converted with `XLSX.SSF.parse_date_code`.
|
2014-10-26 05:26:18 +00:00
|
|
|
|
|
|
|
Type `d` is the Date type, generated only when the option `cellDates` is passed.
|
|
|
|
Since JSON does not have a natural Date type, parsers are generally expected to
|
|
|
|
store ISO 8601 Date strings like you would get from `date.toISOString()`. On
|
|
|
|
the other hand, writers and exporters should be able to handle date strings and
|
2017-02-03 20:50:45 +00:00
|
|
|
JS Date objects. Note that Excel disregards timezone modifiers and treats all
|
2014-10-26 05:26:18 +00:00
|
|
|
dates in the local timezone. js-xlsx does not correct for this error.
|
|
|
|
|
|
|
|
Type `s` is the String type. `v` should be explicitly stored as a string to
|
|
|
|
avoid possible confusion.
|
|
|
|
|
2017-03-15 08:19:02 +00:00
|
|
|
Type `z` represents blank stub cells. These do not have any data or type, and
|
|
|
|
are not processed by any of the core library functions. By default these cells
|
2017-03-16 01:17:24 +00:00
|
|
|
will not be generated; the parser `sheetStubs` option must be set to `true`.
|
2017-03-15 08:19:02 +00:00
|
|
|
|
2017-03-21 20:44:35 +00:00
|
|
|
#### Dates
|
|
|
|
|
|
|
|
By default, Excel stores dates as numbers with a format code that specifies date
|
|
|
|
processing. For example, the date `19-Feb-17` is stored as the number `42785`
|
|
|
|
with a number format of `d-mmm-yy`. The `SSF` module understands number formats
|
|
|
|
and performs the appropriate conversion.
|
|
|
|
|
|
|
|
XLSX also supports a special date type `d` where the data is an ISO 8601 date
|
|
|
|
string. The formatter converts the date back to a number.
|
|
|
|
|
|
|
|
The default behavior for all parsers is to generate number cells. Setting
|
|
|
|
`cellDates` to true will force the generators to store dates.
|
|
|
|
|
2017-03-31 21:46:02 +00:00
|
|
|
### Sheet Objects
|
2014-01-27 09:38:50 +00:00
|
|
|
|
2014-07-28 13:22:32 +00:00
|
|
|
Each key that does not start with `!` maps to a cell (using `A-1` notation)
|
2014-01-27 09:38:50 +00:00
|
|
|
|
2017-03-31 21:46:02 +00:00
|
|
|
`sheet[address]` returns the cell object for the specified address.
|
2014-02-04 00:00:44 +00:00
|
|
|
|
2017-03-31 21:46:02 +00:00
|
|
|
Special sheet keys (accessible as `sheet[key]`, each starting with `!`):
|
2014-07-28 13:22:32 +00:00
|
|
|
|
2017-03-31 21:46:02 +00:00
|
|
|
- `sheet['!ref']`: A-1 based range representing the sheet range. Functions that
|
2014-07-28 13:22:32 +00:00
|
|
|
work with sheets should use this parameter to determine the range. Cells that
|
|
|
|
are assigned outside of the range are not processed. In particular, when
|
2017-03-31 21:46:02 +00:00
|
|
|
writing a sheet by hand, cells outside of the range are not included
|
2014-07-28 13:22:32 +00:00
|
|
|
|
2017-03-31 21:46:02 +00:00
|
|
|
Functions that handle sheets should test for the presence of `!ref` field.
|
2014-08-26 17:40:04 +00:00
|
|
|
If the `!ref` is omitted or is not a valid range, functions are free to treat
|
|
|
|
the sheet as empty or attempt to guess the range. The standard utilities that
|
2017-02-03 20:50:45 +00:00
|
|
|
ship with this library treat sheets as empty (for example, the CSV output is
|
2014-08-26 17:40:04 +00:00
|
|
|
empty string).
|
|
|
|
|
2014-07-28 13:22:32 +00:00
|
|
|
When reading a worksheet with the `sheetRows` property set, the ref parameter
|
|
|
|
will use the restricted range. The original range is set at `ws['!fullref']`
|
|
|
|
|
2017-04-13 01:29:38 +00:00
|
|
|
- `sheet['!margins']`: Object representing the page margins. The default values
|
|
|
|
follow Excel's "normal" preset. Excel also has a "wide" and a "narrow" preset
|
|
|
|
but they are stored as raw measurements. The main properties are listed below:
|
|
|
|
|
|
|
|
| key | description | "normal" | "wide" | "narrow" |
|
|
|
|
|----------|------------------------|:---------|:-------|:-------- |
|
|
|
|
| `left` | left margin (inches) | `0.7` | `1.0` | `0.25` |
|
|
|
|
| `right` | right margin (inches) | `0.7` | `1.0` | `0.25` |
|
|
|
|
| `top` | top margin (inches) | `0.75` | `1.0` | `0.75` |
|
|
|
|
| `bottom` | bottom margin (inches) | `0.75` | `1.0` | `0.75` |
|
|
|
|
| `header` | header margin (inches) | `0.3` | `0.5` | `0.3` |
|
|
|
|
| `footer` | footer margin (inches) | `0.3` | `0.5` | `0.3` |
|
|
|
|
|
|
|
|
```js
|
|
|
|
/* Set worksheet sheet to "normal" */
|
|
|
|
sheet["!margins"] = { left:0.7, right:0.7, top:0.75, bottom:0.75, header:0.3, footer:0.3 }
|
|
|
|
/* Set worksheet sheet to "wide" */
|
|
|
|
sheet["!margins"] = { left:1.0, right:1.0, top:1.0, bottom:1.0, header:0.5, footer:0.5 }
|
|
|
|
/* Set worksheet sheet to "narrow" */
|
|
|
|
sheet["!margins"] = { left:0.25, right:0.25, top:0.75, bottom:0.75, header:0.3, footer:0.3 }
|
|
|
|
```
|
|
|
|
|
2017-04-01 07:32:12 +00:00
|
|
|
#### Worksheet Object
|
2017-03-31 21:46:02 +00:00
|
|
|
|
|
|
|
In addition to the base sheet keys, worksheets also add:
|
|
|
|
|
2014-07-28 13:22:32 +00:00
|
|
|
- `ws['!cols']`: array of column properties objects. Column widths are actually
|
|
|
|
stored in files in a normalized manner, measured in terms of the "Maximum
|
|
|
|
Digit Width" (the largest width of the rendered digits 0-9, in pixels). When
|
|
|
|
parsed, the column objects store the pixel width in the `wpx` field, character
|
|
|
|
width in the `wch` field, and the maximum digit width in the `MDW` field.
|
|
|
|
|
2017-04-28 07:28:03 +00:00
|
|
|
- `ws['!rows']`: array of row properties objects as explained later in the docs.
|
|
|
|
Each row object encodes properties including row height and visibility.
|
|
|
|
|
2014-07-28 13:22:32 +00:00
|
|
|
- `ws['!merges']`: array of range objects corresponding to the merged cells in
|
|
|
|
the worksheet. Plaintext utilities are unaware of merge cells. CSV export
|
|
|
|
will write all cells in the merge range if they exist, so be sure that only
|
|
|
|
the first cell (upper-left) in the range is set.
|
|
|
|
|
2017-04-28 07:28:03 +00:00
|
|
|
- `ws['!protect']`: object of write sheet protection properties. The `password`
|
2017-04-26 02:27:12 +00:00
|
|
|
key specifies the password for formats that support password-protected sheets
|
|
|
|
(XLSX/XLSB/XLS). The writer uses the XOR obfuscation method. The following
|
2017-04-28 07:28:03 +00:00
|
|
|
keys control the sheet protection -- set to `false` to enable a feature when
|
|
|
|
sheet is locked or set to `true` to disable a feature:
|
|
|
|
|
|
|
|
| key | feature (true=disabled / false=enabled) | default |
|
|
|
|
|:----------------------|:----------------------------------------|:-----------|
|
|
|
|
| `selectLockedCells` | Select locked cells | enabled |
|
|
|
|
| `selectUnlockedCells` | Select unlocked cells | enabled |
|
|
|
|
| `formatCells` | Format cells | disabled |
|
|
|
|
| `formatColumns` | Format columns | disabled |
|
|
|
|
| `formatRows` | Format rows | disabled |
|
|
|
|
| `insertColumns` | Insert columns | disabled |
|
|
|
|
| `insertRows` | Insert rows | disabled |
|
|
|
|
| `insertHyperlinks` | Insert hyperlinks | disabled |
|
|
|
|
| `deleteColumns` | Delete columns | disabled |
|
|
|
|
| `deleteRows` | Delete rows | disabled |
|
|
|
|
| `sort` | Sort | disabled |
|
|
|
|
| `autoFilter` | Filter | disabled |
|
|
|
|
| `pivotTables` | Use PivotTable reports | disabled |
|
|
|
|
| `objects` | Edit objects | enabled |
|
|
|
|
| `scenarios` | Edit scenarios | enabled |
|
2017-04-04 18:41:11 +00:00
|
|
|
|
2017-04-10 05:10:54 +00:00
|
|
|
- `ws['!autofilter']`: AutoFilter object following the schema:
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
type AutoFilter = {
|
2017-04-26 02:27:12 +00:00
|
|
|
ref:string; // A-1 based range representing the AutoFilter table range
|
2017-04-10 05:10:54 +00:00
|
|
|
}
|
|
|
|
```
|
|
|
|
|