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
|
2017-05-09 18:07:57 +00:00
|
|
|
enhancements, additional features by request, and dedicated support.
|
|
|
|
|
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-07-27 20:07:51 +00:00
|
|
|
[**Rendered Documentation**](http://docs.sheetjs.com/)
|
2017-04-26 02:27:12 +00:00
|
|
|
|
2017-04-20 03:24:48 +00:00
|
|
|
[**In-Browser Demos**](http://sheetjs.com/demos)
|
|
|
|
|
|
|
|
[**Source Code**](http://git.io/xlsx)
|
|
|
|
|
2017-05-09 18:07:57 +00:00
|
|
|
[**Issues and Bug Reports**](https://github.com/sheetjs/js-xlsx/issues)
|
2017-03-13 06:46:37 +00:00
|
|
|
|
2017-05-09 18:07:57 +00:00
|
|
|
[**Other General Support Issues**](https://discourse.sheetjs.com)
|
|
|
|
|
|
|
|
[**File format support for known spreadsheet data formats:**](#file-formats)
|
2014-10-26 05:26:18 +00:00
|
|
|
|
2017-04-30 20:37:53 +00:00
|
|
|
<details>
|
2017-09-24 23:40:09 +00:00
|
|
|
<summary><b>Graph of supported formats</b> (click to show)</summary>
|
2017-05-09 18:07:57 +00:00
|
|
|
|
|
|
|
![circo graph of format support](formats.png)
|
2017-04-30 20:37:53 +00:00
|
|
|
|
2017-04-03 00:16:03 +00:00
|
|
|
![graph legend](legend.png)
|
2012-12-04 19:27:20 +00:00
|
|
|
|
2017-04-30 20:37:53 +00:00
|
|
|
</details>
|
2017-02-03 20:50:45 +00:00
|
|
|
|
2017-05-09 18:07:57 +00:00
|
|
|
[**Browser Test**](http://oss.sheetjs.com/js-xlsx/tests/)
|
|
|
|
|
|
|
|
[![Build Status](https://saucelabs.com/browser-matrix/sheetjs.svg)](https://saucelabs.com/u/sheetjs)
|
|
|
|
|
|
|
|
[![Build Status](https://travis-ci.org/SheetJS/js-xlsx.svg?branch=master)](https://travis-ci.org/SheetJS/js-xlsx)
|
|
|
|
[![Build Status](https://semaphoreci.com/api/v1/sheetjs/js-xlsx/branches/master/shields_badge.svg)](https://semaphoreci.com/sheetjs/js-xlsx)
|
|
|
|
[![Coverage Status](http://img.shields.io/coveralls/SheetJS/js-xlsx/master.svg)](https://coveralls.io/r/SheetJS/js-xlsx?branch=master)
|
|
|
|
[![Dependencies Status](https://david-dm.org/sheetjs/js-xlsx/status.svg)](https://david-dm.org/sheetjs/js-xlsx)
|
2017-09-24 23:40:09 +00:00
|
|
|
[![npm Downloads](https://img.shields.io/npm/dt/xlsx.svg)](https://npmjs.org/package/xlsx)
|
2017-05-09 18:07:57 +00:00
|
|
|
[![ghit.me](https://ghit.me/badge.svg?repo=sheetjs/js-xlsx)](https://ghit.me/repo/sheetjs/js-xlsx)
|
|
|
|
[![Analytics](https://ga-beacon.appspot.com/UA-36810333-1/SheetJS/js-xlsx?pixel)](https://github.com/SheetJS/js-xlsx)
|
|
|
|
|
2017-03-13 06:46:37 +00:00
|
|
|
## Table of Contents
|
|
|
|
|
2017-04-30 20:37:53 +00:00
|
|
|
<details>
|
2017-09-24 23:40:09 +00:00
|
|
|
<summary><b>Expand to show Table of Contents</b></summary>
|
2017-04-30 20:37:53 +00:00
|
|
|
|
2017-03-13 06:46:37 +00:00
|
|
|
<!-- toc -->
|
|
|
|
|
|
|
|
- [Installation](#installation)
|
|
|
|
* [JS Ecosystem Demos](#js-ecosystem-demos)
|
|
|
|
* [Optional Modules](#optional-modules)
|
|
|
|
* [ECMAScript 5 Compatibility](#ecmascript-5-compatibility)
|
2017-05-09 18:07:57 +00:00
|
|
|
- [Philosophy](#philosophy)
|
2017-03-13 06:46:37 +00:00
|
|
|
- [Parsing Workbooks](#parsing-workbooks)
|
2017-07-05 22:27:54 +00:00
|
|
|
* [Parsing Examples](#parsing-examples)
|
2017-06-10 01:47:42 +00:00
|
|
|
* [Streaming Read](#streaming-read)
|
2017-03-13 06:46:37 +00:00
|
|
|
- [Working with the Workbook](#working-with-the-workbook)
|
2017-07-05 22:27:54 +00:00
|
|
|
* [Parsing and Writing Examples](#parsing-and-writing-examples)
|
2017-03-13 06:46:37 +00:00
|
|
|
- [Writing Workbooks](#writing-workbooks)
|
2017-07-05 22:27:54 +00:00
|
|
|
* [Writing Examples](#writing-examples)
|
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-10-02 08:15:36 +00:00
|
|
|
+ [Macrosheet Object](#macrosheet-object)
|
|
|
|
+ [Dialogsheet Object](#dialogsheet-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-12-30 05:40:35 +00:00
|
|
|
+ [Workbook Views](#workbook-views)
|
2017-06-01 21:22:11 +00:00
|
|
|
+ [Miscellaneous Workbook Properties](#miscellaneous-workbook-properties)
|
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-10-02 08:15:36 +00:00
|
|
|
+ [VBA and Macros](#vba-and-macros)
|
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-05-11 18:23:21 +00:00
|
|
|
* [Array of Objects Input](#array-of-objects-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-05-16 17:45:35 +00:00
|
|
|
* [HTML Output](#html-output)
|
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-10-02 08:15:36 +00:00
|
|
|
+ [Rich Text Format (RTF)](#rich-text-format-rtf)
|
2017-12-04 04:41:41 +00:00
|
|
|
+ [Ethercalc Record Format (ETH)](#ethercalc-record-format-eth)
|
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-09 07:11:08 +00:00
|
|
|
* [OSX/Linux](#osxlinux)
|
|
|
|
* [Windows](#windows)
|
2017-05-16 17:45:35 +00:00
|
|
|
* [Tests](#tests)
|
2017-03-13 06:46:37 +00:00
|
|
|
- [License](#license)
|
|
|
|
- [References](#references)
|
|
|
|
|
|
|
|
<!-- tocstop -->
|
2017-02-10 19:23:01 +00:00
|
|
|
|
2017-04-30 20:37:53 +00:00
|
|
|
</details>
|
|
|
|
|
2012-12-04 19:27:20 +00:00
|
|
|
## Installation
|
|
|
|
|
2017-05-09 18:07:57 +00:00
|
|
|
In the browser, just add a script tag:
|
2012-12-04 19:27:20 +00:00
|
|
|
|
2017-05-09 18:07:57 +00:00
|
|
|
```html
|
|
|
|
<script lang="javascript" src="dist/xlsx.full.min.js"></script>
|
2016-12-31 08:20:45 +00:00
|
|
|
```
|
2012-12-04 19:27:20 +00:00
|
|
|
|
2017-09-24 23:40:09 +00:00
|
|
|
<details>
|
|
|
|
<summary><b>CDN Availability</b> (click to show)</summary>
|
|
|
|
|
|
|
|
| CDN | URL |
|
|
|
|
|-----------:|:-----------------------------------------|
|
|
|
|
| `unpkg` | <https://unpkg.com/xlsx/> |
|
|
|
|
| `jsDelivr` | <https://jsdelivr.com/package/npm/xlsx> |
|
|
|
|
| `CDNjs` | <http://cdnjs.com/libraries/xlsx> |
|
|
|
|
|
|
|
|
`unpkg` makes the latest version available at:
|
|
|
|
|
|
|
|
```html
|
|
|
|
<script src="https://unpkg.com/xlsx/dist/xlsx.full.min.js"></script>
|
|
|
|
```
|
|
|
|
|
|
|
|
</details>
|
|
|
|
|
|
|
|
|
2017-05-09 18:07:57 +00:00
|
|
|
With [npm](https://www.npmjs.org/package/xlsx):
|
2012-12-04 19:27:20 +00:00
|
|
|
|
2017-05-09 18:07:57 +00:00
|
|
|
```bash
|
|
|
|
$ npm install xlsx
|
2016-12-31 08:20:45 +00:00
|
|
|
```
|
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
|
|
|
|
2017-03-10 17:33:08 +00:00
|
|
|
### JS Ecosystem Demos
|
|
|
|
|
2017-09-24 23:40:09 +00:00
|
|
|
The [`demos` directory](demos/) includes sample projects for:
|
2017-03-10 17:33:08 +00:00
|
|
|
|
2017-09-12 20:02:06 +00:00
|
|
|
**Frameworks and APIs**
|
2017-06-21 23:10:36 +00:00
|
|
|
- [`angular 1.x`](demos/angular/)
|
2018-01-09 07:36:02 +00:00
|
|
|
- [`angular 2 / 4 / 5 and ionic`](demos/angular2/)
|
2017-05-24 22:52:35 +00:00
|
|
|
- [`meteor`](demos/meteor/)
|
2017-09-12 20:02:06 +00:00
|
|
|
- [`react and react-native`](demos/react/)
|
|
|
|
- [`vue 2.x and weex`](demos/vue/)
|
2017-09-05 05:26:50 +00:00
|
|
|
- [`XMLHttpRequest and fetch`](demos/xhr/)
|
2017-09-12 20:02:06 +00:00
|
|
|
- [`nodejs server`](demos/server/)
|
2018-01-27 00:52:46 +00:00
|
|
|
- [`databases and key/value stores`](demos/database/)
|
2017-08-10 23:46:34 +00:00
|
|
|
|
2017-09-12 20:02:06 +00:00
|
|
|
**Bundlers and Tooling**
|
2017-08-10 23:46:34 +00:00
|
|
|
- [`browserify`](demos/browserify/)
|
2018-01-27 00:52:46 +00:00
|
|
|
- [`fusebox`](demos/fusebox/)
|
|
|
|
- [`parcel`](demos/parcel/)
|
2017-03-23 17:11:31 +00:00
|
|
|
- [`requirejs`](demos/requirejs/)
|
2017-06-08 06:19:11 +00:00
|
|
|
- [`rollup`](demos/rollup/)
|
2017-03-23 17:11:31 +00:00
|
|
|
- [`systemjs`](demos/systemjs/)
|
2017-12-01 05:48:10 +00:00
|
|
|
- [`typescript`](demos/typescript/)
|
2017-09-05 05:26:50 +00:00
|
|
|
- [`webpack 2.x`](demos/webpack/)
|
2017-03-10 17:33:08 +00:00
|
|
|
|
2017-09-12 20:02:06 +00:00
|
|
|
**Platforms and Integrations**
|
|
|
|
- [`electron application`](demos/electron/)
|
|
|
|
- [`nw.js application`](demos/nwjs/)
|
2017-08-10 23:46:34 +00:00
|
|
|
- [`Adobe ExtendScript`](demos/extendscript/)
|
2017-08-19 23:06:34 +00:00
|
|
|
- [`Headless Browsers`](demos/headless/)
|
2017-08-10 23:46:34 +00:00
|
|
|
- [`canvas-datagrid`](demos/datagrid/)
|
2017-09-05 05:26:50 +00:00
|
|
|
- [`Swift JSC and other engines`](demos/altjs/)
|
2018-02-03 20:46:32 +00:00
|
|
|
- [`internet explorer`](demos/oldie/)
|
2017-08-10 23:46:34 +00:00
|
|
|
|
2017-02-22 06:57:59 +00:00
|
|
|
### Optional Modules
|
2014-04-23 01:37:08 +00:00
|
|
|
|
2017-05-24 22:52:35 +00:00
|
|
|
<details>
|
2017-09-24 23:40:09 +00:00
|
|
|
<summary><b>Optional features</b> (click to show)</summary>
|
2017-05-24 22:52:35 +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-09-24 23:40:09 +00:00
|
|
|
Webpack and Browserify builds include optional modules by default. Webpack can
|
2017-03-13 06:46:37 +00:00
|
|
|
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-05-24 22:52:35 +00:00
|
|
|
</details>
|
2017-03-13 06:46:37 +00:00
|
|
|
|
2017-02-22 06:57:59 +00:00
|
|
|
### ECMAScript 5 Compatibility
|
2014-06-03 18:39:46 +00:00
|
|
|
|
2017-09-24 23:40:09 +00:00
|
|
|
Since the library uses functions like `Array#forEach`, older browsers require
|
|
|
|
[shims to provide missing functions](http://oss.sheetjs.com/js-xlsx/shim.js).
|
2014-06-03 18:39:46 +00:00
|
|
|
|
2017-09-24 23:40:09 +00:00
|
|
|
To use the shim, add the shim before the script tag that loads `xlsx.js`:
|
2014-06-03 18:39:46 +00:00
|
|
|
|
2016-12-31 08:20:45 +00:00
|
|
|
```html
|
2017-09-24 23:40:09 +00:00
|
|
|
<!-- add the shim first -->
|
|
|
|
<script type="text/javascript" src="shim.js"></script>
|
|
|
|
<!-- after the shim is referenced, add the library -->
|
|
|
|
<script type="text/javascript" src="xlsx.full.min.js"></script>
|
2016-12-31 08:20:45 +00:00
|
|
|
```
|
2014-06-03 18:39:46 +00:00
|
|
|
|
2017-05-09 18:07:57 +00:00
|
|
|
## Philosophy
|
|
|
|
|
|
|
|
<details>
|
2017-09-24 23:40:09 +00:00
|
|
|
<summary><b>Philosophy</b> (click to show)</summary>
|
2017-05-09 18:07:57 +00:00
|
|
|
|
|
|
|
Prior to SheetJS, APIs for processing spreadsheet files were format-specific.
|
|
|
|
Third-party libraries either supported one format, or they involved a separate
|
|
|
|
set of classes for each supported file type. Even though XLSB was introduced in
|
|
|
|
Excel 2007, nothing outside of SheetJS or Excel supported the format.
|
|
|
|
|
|
|
|
To promote a format-agnostic view, js-xlsx starts from a pure-JS representation
|
|
|
|
that we call the ["Common Spreadsheet Format"](#common-spreadsheet-format).
|
2017-08-01 05:50:53 +00:00
|
|
|
Emphasizing a uniform object representation enables new features like format
|
2017-09-24 23:40:09 +00:00
|
|
|
conversion (reading an XLSX template and saving as XLS) and circumvents the
|
2017-05-09 18:07:57 +00:00
|
|
|
"class trap". By abstracting the complexities of the various formats, tools
|
|
|
|
need not worry about the specific file type!
|
|
|
|
|
|
|
|
A simple object representation combined with careful coding practices enables
|
|
|
|
use cases in older browsers and in alternative environments like ExtendScript
|
|
|
|
and Web Workers. It is always tempting to use the latest and greatest features,
|
|
|
|
but they tend to require the latest versions of browsers, limiting usability.
|
|
|
|
|
|
|
|
Utility functions capture common use cases like generating JS objects or HTML.
|
|
|
|
Most simple operations should only require a few lines of code. More complex
|
|
|
|
operations generally should be straightforward to implement.
|
|
|
|
|
|
|
|
Excel pushes the XLSX format as default starting in Excel 2007. However, there
|
|
|
|
are other formats with more appealing properties. For example, the XLSB format
|
|
|
|
is spiritually similar to XLSX but files often tend up taking less than half the
|
|
|
|
space and open much faster! Even though an XLSX writer is available, other
|
|
|
|
format writers are available so users can take advantage of the unique
|
|
|
|
characteristics of each format.
|
|
|
|
|
|
|
|
</details>
|
|
|
|
|
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
|
|
|
|
2017-04-30 20:37:53 +00:00
|
|
|
<details>
|
2017-09-24 23:40:09 +00:00
|
|
|
<summary><b>nodejs read a file</b> (click to show)</summary>
|
2012-12-04 19:27:20 +00:00
|
|
|
|
2017-09-30 06:18:11 +00:00
|
|
|
`readFile` is only available in server environments. Browsers have no API for
|
|
|
|
reading arbitrary files given a path, so another strategy must be used.
|
|
|
|
|
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-04-30 20:37:53 +00:00
|
|
|
</details>
|
|
|
|
|
|
|
|
<details>
|
2017-09-24 23:40:09 +00:00
|
|
|
<summary><b>Browser read TABLE element from page</b> (click to show)</summary>
|
2017-03-29 19:14:15 +00:00
|
|
|
|
2017-09-30 06:18:11 +00:00
|
|
|
The `table_to_book` and `table_to_sheet` utility functions take a DOM TABLE
|
|
|
|
element and iterate through the child nodes.
|
|
|
|
|
2017-03-29 19:14:15 +00:00
|
|
|
```js
|
|
|
|
var worksheet = XLSX.utils.table_to_book(document.getElementById('tableau'));
|
|
|
|
/* DO SOMETHING WITH workbook HERE */
|
|
|
|
```
|
|
|
|
|
2017-09-30 06:18:11 +00:00
|
|
|
Alternatively, the HTML code can be extracted and parsed:
|
|
|
|
|
|
|
|
```js
|
|
|
|
var htmlstr = document.getElementById('tableau').outerHTML;
|
|
|
|
var worksheet = XLSX.read(htmlstr, {type:'string'});
|
|
|
|
```
|
|
|
|
|
2017-04-30 20:37:53 +00:00
|
|
|
</details>
|
|
|
|
|
|
|
|
<details>
|
2017-09-24 23:40:09 +00:00
|
|
|
<summary><b>Browser download file (ajax)</b> (click to show)</summary>
|
2017-04-30 20:37:53 +00:00
|
|
|
|
|
|
|
Note: for a more complete example that works in older browsers, check the demo
|
2018-02-03 20:46:32 +00:00
|
|
|
at <http://oss.sheetjs.com/js-xlsx/ajax.html>). The [`xhr` demo](demos/xhr/)
|
2017-09-24 23:40:09 +00:00
|
|
|
includes more examples with `XMLHttpRequest` and `fetch`.
|
2014-05-28 18:31:33 +00:00
|
|
|
|
2016-12-31 08:20:45 +00:00
|
|
|
```js
|
2017-09-24 23:40:09 +00:00
|
|
|
var url = "http://oss.sheetjs.com/test_files/formula_stress_test.xlsx";
|
2014-05-28 18:31:33 +00:00
|
|
|
|
2017-09-24 23:40:09 +00:00
|
|
|
/* set up async GET request */
|
|
|
|
var req = new XMLHttpRequest();
|
|
|
|
req.open("GET", url, true);
|
|
|
|
req.responseType = "arraybuffer";
|
2014-05-28 18:31:33 +00:00
|
|
|
|
2017-09-24 23:40:09 +00:00
|
|
|
req.onload = function(e) {
|
|
|
|
var data = new Uint8Array(req.response);
|
|
|
|
var workbook = XLSX.read(data, {type:"array"});
|
2014-05-28 18:31:33 +00:00
|
|
|
|
|
|
|
/* DO SOMETHING WITH workbook HERE */
|
|
|
|
}
|
|
|
|
|
2017-09-24 23:40:09 +00:00
|
|
|
req.send();
|
2014-05-28 18:31:33 +00:00
|
|
|
```
|
|
|
|
|
2017-04-30 20:37:53 +00:00
|
|
|
</details>
|
|
|
|
|
|
|
|
<details>
|
2017-09-24 23:40:09 +00:00
|
|
|
<summary><b>Browser drag-and-drop</b> (click to show)</summary>
|
2017-04-30 20:37:53 +00:00
|
|
|
|
2017-09-24 23:40:09 +00:00
|
|
|
Drag-and-drop uses the HTML5 `FileReader` API, loading the data with
|
|
|
|
`readAsBinaryString` or `readAsArrayBuffer`. Since not all browsers support the
|
|
|
|
full `FileReader` API, dynamic feature tests are highly recommended.
|
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
|
|
|
var rABS = true; // true: readAsBinaryString ; false: readAsArrayBuffer
|
2014-05-28 18:31:33 +00:00
|
|
|
function handleDrop(e) {
|
2017-09-24 23:40:09 +00:00
|
|
|
e.stopPropagation(); e.preventDefault();
|
|
|
|
var files = e.dataTransfer.files, f = files[0];
|
|
|
|
var reader = new FileReader();
|
|
|
|
reader.onload = function(e) {
|
|
|
|
var data = e.target.result;
|
|
|
|
if(!rABS) data = new Uint8Array(data);
|
|
|
|
var workbook = XLSX.read(data, {type: rABS ? 'binary' : 'array'});
|
|
|
|
|
|
|
|
/* DO SOMETHING WITH workbook HERE */
|
|
|
|
};
|
|
|
|
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-04-30 20:37:53 +00:00
|
|
|
</details>
|
|
|
|
|
|
|
|
<details>
|
2017-09-24 23:40:09 +00:00
|
|
|
<summary><b>Browser file upload form element</b> (click to show)</summary>
|
|
|
|
|
|
|
|
Data from file input elements can be processed using the same `FileReader` API
|
|
|
|
as in the drag-and-drop example:
|
2014-07-28 13:22:32 +00:00
|
|
|
|
2016-12-31 08:20:45 +00:00
|
|
|
```js
|
2017-09-24 23:40:09 +00:00
|
|
|
var rABS = true; // true: readAsBinaryString ; false: readAsArrayBuffer
|
2014-07-28 13:22:32 +00:00
|
|
|
function handleFile(e) {
|
2017-09-24 23:40:09 +00:00
|
|
|
var files = e.target.files, f = files[0];
|
|
|
|
var reader = new FileReader();
|
|
|
|
reader.onload = function(e) {
|
|
|
|
var data = e.target.result;
|
|
|
|
if(!rABS) data = new Uint8Array(data);
|
|
|
|
var workbook = XLSX.read(data, {type: rABS ? 'binary' : 'array'});
|
|
|
|
|
|
|
|
/* DO SOMETHING WITH workbook HERE */
|
|
|
|
};
|
|
|
|
if(rABS) reader.readAsBinaryString(f); else reader.readAsArrayBuffer(f);
|
2014-07-28 13:22:32 +00:00
|
|
|
}
|
|
|
|
input_dom_element.addEventListener('change', handleFile, false);
|
|
|
|
```
|
|
|
|
|
2017-04-30 20:37:53 +00:00
|
|
|
</details>
|
|
|
|
|
2018-02-03 20:46:32 +00:00
|
|
|
More specialized cases, including mobile app file processing, are covered in the
|
|
|
|
[included demos](demos/)
|
2017-04-30 20:37:53 +00:00
|
|
|
|
2017-07-05 22:27:54 +00:00
|
|
|
### Parsing Examples
|
2017-04-16 04:32:13 +00:00
|
|
|
|
|
|
|
- <http://oss.sheetjs.com/js-xlsx/> HTML5 File API / Base64 Text / Web Workers
|
|
|
|
|
2017-09-24 23:40:09 +00:00
|
|
|
Note that older versions of IE do not support HTML5 File API, so the Base64 mode
|
2017-06-03 07:19:09 +00:00
|
|
|
is used for testing.
|
|
|
|
|
|
|
|
<details>
|
2017-09-24 23:40:09 +00:00
|
|
|
<summary><b>Get Base64 encoding on OSX / Windows</b> (click to show)</summary>
|
2017-06-03 07:19:09 +00:00
|
|
|
|
2017-09-24 23:40:09 +00:00
|
|
|
On OSX you can get the Base64 encoding with:
|
2017-04-16 04:32:13 +00:00
|
|
|
|
|
|
|
```bash
|
|
|
|
$ <target_file base64 | pbcopy
|
|
|
|
```
|
|
|
|
|
2017-09-24 23:40:09 +00:00
|
|
|
On Windows XP and up you can get the Base64 encoding using `certutil`:
|
2017-04-16 04:32:13 +00:00
|
|
|
|
|
|
|
```cmd
|
|
|
|
> certutil -encode target_file target_file.b64
|
|
|
|
```
|
|
|
|
|
|
|
|
(note: You have to open the file and remove the header and footer lines)
|
|
|
|
|
2017-06-03 07:19:09 +00:00
|
|
|
</details>
|
|
|
|
|
2017-04-16 04:32:13 +00:00
|
|
|
- <http://oss.sheetjs.com/js-xlsx/ajax.html> XMLHttpRequest
|
|
|
|
|
2017-06-10 01:47:42 +00:00
|
|
|
### Streaming Read
|
|
|
|
|
|
|
|
<details>
|
2017-09-24 23:40:09 +00:00
|
|
|
<summary><b>Why is there no Streaming Read API?</b> (click to show)</summary>
|
2017-04-16 04:32:13 +00:00
|
|
|
|
|
|
|
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
|
2017-08-01 05:50:53 +00:00
|
|
|
end of the logical file, while CFB files can place the storage info anywhere in
|
2017-04-16 04:32:13 +00:00
|
|
|
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
|
2017-06-10 01:47:42 +00:00
|
|
|
expectations of streaming, so we do not provide any streaming read API.
|
|
|
|
|
|
|
|
</details>
|
|
|
|
|
|
|
|
When dealing with Readable Streams, the easiest approach is to buffer the stream
|
|
|
|
and process the whole thing at the end. This can be done with a temporary file
|
|
|
|
or by explicitly concatenating the stream:
|
|
|
|
|
|
|
|
<details>
|
2017-09-24 23:40:09 +00:00
|
|
|
<summary><b>Explicitly concatenating streams</b> (click to show)</summary>
|
2017-06-10 01:47:42 +00:00
|
|
|
|
|
|
|
```js
|
|
|
|
var fs = require('fs');
|
|
|
|
var XLSX = require('xlsx');
|
|
|
|
function process_RS(stream/*:ReadStream*/, cb/*:(wb:Workbook)=>void*/)/*:void*/{
|
2017-09-24 23:40:09 +00:00
|
|
|
var buffers = [];
|
|
|
|
stream.on('data', function(data) { buffers.push(data); });
|
|
|
|
stream.on('end', function() {
|
|
|
|
var buffer = Buffer.concat(buffers);
|
|
|
|
var workbook = XLSX.read(buffer, {type:"buffer"});
|
|
|
|
|
|
|
|
/* DO SOMETHING WITH workbook IN THE CALLBACK */
|
|
|
|
cb(workbook);
|
|
|
|
});
|
2017-06-10 01:47:42 +00:00
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
More robust solutions are available using modules like `concat-stream`.
|
|
|
|
|
|
|
|
</details>
|
|
|
|
|
|
|
|
<details>
|
2017-09-24 23:40:09 +00:00
|
|
|
<summary><b>Writing to filesystem first</b> (click to show)</summary>
|
2017-06-10 01:47:42 +00:00
|
|
|
|
2017-09-24 23:40:09 +00:00
|
|
|
This example uses [`tempfile`](https://npm.im/tempfile) to generate file names:
|
2017-06-10 01:47:42 +00:00
|
|
|
|
|
|
|
```js
|
|
|
|
var fs = require('fs'), tempfile = require('tempfile');
|
|
|
|
var XLSX = require('xlsx');
|
|
|
|
function process_RS(stream/*:ReadStream*/, cb/*:(wb:Workbook)=>void*/)/*:void*/{
|
2017-09-24 23:40:09 +00:00
|
|
|
var fname = tempfile('.sheetjs');
|
|
|
|
console.log(fname);
|
|
|
|
var ostream = fs.createWriteStream(fname);
|
|
|
|
stream.pipe(ostream);
|
|
|
|
ostream.on('finish', function() {
|
|
|
|
var workbook = XLSX.readFile(fname);
|
|
|
|
fs.unlinkSync(fname);
|
|
|
|
|
|
|
|
/* DO SOMETHING WITH workbook IN THE CALLBACK */
|
|
|
|
cb(workbook);
|
|
|
|
});
|
2017-06-10 01:47:42 +00:00
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
</details>
|
2017-04-16 04:32:13 +00:00
|
|
|
|
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.
|
|
|
|
|
2017-05-24 22:52:35 +00:00
|
|
|
<details>
|
2017-09-24 23:40:09 +00:00
|
|
|
<summary><b>Reading a specific cell </b> (click to show)</summary>
|
2017-05-24 22:52:35 +00:00
|
|
|
|
2015-04-02 20:32:22 +00:00
|
|
|
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-05-24 22:52:35 +00:00
|
|
|
</details>
|
|
|
|
|
|
|
|
<details>
|
2017-09-24 23:40:09 +00:00
|
|
|
<summary><b>Adding a new worksheet to a workbook</b> (click to show)</summary>
|
2017-05-24 22:52:35 +00:00
|
|
|
|
|
|
|
This example uses [`XLSX.utils.aoa_to_sheet`](#array-of-arrays-input) to make a
|
|
|
|
worksheet and appends the new worksheet to the workbook:
|
|
|
|
|
|
|
|
```js
|
|
|
|
var new_ws_name = "SheetJS";
|
|
|
|
|
|
|
|
/* make worksheet */
|
|
|
|
var ws_data = [
|
2017-09-24 23:40:09 +00:00
|
|
|
[ "S", "h", "e", "e", "t", "J", "S" ],
|
|
|
|
[ 1 , 2 , 3 , 4 , 5 ]
|
2017-05-24 22:52:35 +00:00
|
|
|
];
|
|
|
|
var ws = XLSX.utils.aoa_to_sheet(ws_data);
|
|
|
|
|
|
|
|
/* Add the sheet name to the list */
|
|
|
|
wb.SheetNames.push(ws_name);
|
|
|
|
|
|
|
|
/* Load the worksheet object */
|
|
|
|
wb.Sheets[ws_name] = ws;
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
</details>
|
|
|
|
|
|
|
|
|
2017-07-05 22:27:54 +00:00
|
|
|
### Parsing and Writing Examples
|
|
|
|
|
|
|
|
- <http://sheetjs.com/demos/modify.html> read + modify + write files
|
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
|
2017-12-01 05:48:10 +00:00
|
|
|
- `XLSX.utils.sheet_to_txt` generates UTF16 Formatted Text
|
2017-05-16 17:45:35 +00:00
|
|
|
- `XLSX.utils.sheet_to_html` generates HTML
|
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
|
|
|
|
2017-04-30 20:37:53 +00:00
|
|
|
<details>
|
2017-09-24 23:40:09 +00:00
|
|
|
<summary><b>nodejs write a file</b> (click to show)</summary>
|
2014-05-28 18:31:33 +00:00
|
|
|
|
2018-02-03 20:46:32 +00:00
|
|
|
`XLSX.writeFile` uses `fs.writeFileSync` in server environments:
|
2017-09-30 06:18:11 +00:00
|
|
|
|
2016-12-31 08:20:45 +00:00
|
|
|
```js
|
2017-09-30 06:18:11 +00:00
|
|
|
if(typeof require !== 'undefined') XLSX = require('xlsx');
|
2014-05-28 18:31:33 +00:00
|
|
|
/* output format determined by filename */
|
2017-09-30 06:18:11 +00:00
|
|
|
XLSX.writeFile(workbook, 'out.xlsb');
|
|
|
|
/* at this point, out.xlsb is a file that you can distribute */
|
2014-05-28 18:31:33 +00:00
|
|
|
```
|
|
|
|
|
2017-04-30 20:37:53 +00:00
|
|
|
</details>
|
|
|
|
|
|
|
|
<details>
|
2018-02-03 20:46:32 +00:00
|
|
|
<summary><b>Browser add TABLE element to page</b> (click to show)</summary>
|
2017-09-30 06:18:11 +00:00
|
|
|
|
|
|
|
The `sheet_to_html` utility function generates HTML code that can be added to
|
|
|
|
any DOM element.
|
|
|
|
|
|
|
|
```js
|
|
|
|
var worksheet = workbook.Sheets[workbook.SheetNames[0]];
|
|
|
|
var container = document.getElementById('tableau');
|
|
|
|
container.innerHTML = XLSX.utils.sheet_to_html(worksheet);
|
|
|
|
```
|
|
|
|
|
2017-04-30 20:37:53 +00:00
|
|
|
</details>
|
2014-05-28 18:31:33 +00:00
|
|
|
|
2017-09-05 05:26:50 +00:00
|
|
|
<details>
|
2018-02-03 20:46:32 +00:00
|
|
|
<summary><b>Browser upload file (ajax)</b> (click to show)</summary>
|
2017-09-05 05:26:50 +00:00
|
|
|
|
2017-09-24 23:40:09 +00:00
|
|
|
A complete example using XHR is [included in the XHR demo](demos/xhr/), along
|
2017-09-05 05:26:50 +00:00
|
|
|
with examples for fetch and wrapper libraries. This example assumes the server
|
|
|
|
can handle Base64-encoded files (see the demo for a basic nodejs server):
|
|
|
|
|
|
|
|
```js
|
|
|
|
/* in this example, send a base64 string to the server */
|
|
|
|
var wopts = { bookType:'xlsx', bookSST:false, type:'base64' };
|
|
|
|
|
|
|
|
var wbout = XLSX.write(workbook,wopts);
|
|
|
|
|
2017-09-24 23:40:09 +00:00
|
|
|
var req = new XMLHttpRequest();
|
|
|
|
req.open("POST", "/upload", true);
|
2017-09-05 05:26:50 +00:00
|
|
|
var formdata = new FormData();
|
|
|
|
formdata.append('file', 'test.xlsx'); // <-- server expects `file` to hold < |