From ba1ff17595361900de30e8e096cc853babf547e6 Mon Sep 17 00:00:00 2001 From: SheetJS Date: Wed, 28 May 2014 14:31:33 -0400 Subject: [PATCH] README improvements [ci skip] --- README.md | 158 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 126 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 4516bed..7625477 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ ISO 29500 Office Open XML specifications, [MS-XLSB], and related documents. ## Installation -In [node](https://www.npmjs.org/package/xlsx): +In [nodejs](https://www.npmjs.org/package/xlsx): npm install xlsx @@ -29,7 +29,7 @@ Older versions of this README recommended a more explicit approach: ## Optional Modules -The node version automatically requires modules for additional features. Some +The nodejs version automatically requires modules for additional features. Some 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: @@ -41,50 +41,144 @@ 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` -## Usage +## Parsing Workbooks -Simple usage (walks through every cell of every sheet and dumps the values): +For parsing, the first step is to read the file. - if(typeof require !== 'undefined') XLSX = require('xlsx'); - var workbook = XLSX.readFile('test.xlsx'); - var sheet_name_list = workbook.SheetNames; - sheet_name_list.forEach(function(y) { - var worksheet = workbook.Sheets[y]; - for (z in worksheet) { - if(z[0] === '!') continue; - console.log(y + "!" + z + "=" + JSON.stringify(worksheet[z].v)); - } - }); +- nodejs: -An example of writing an array-of-arrays is available at +``` +if(typeof require !== 'undefined') XLSX = require('xlsx'); +var workbook = XLSX.readFile('test.xlsx'); +/* DO SOMETHING WITH workbook HERE */ +``` -The node version installs a binary `xlsx` which can read XLSX/XLSM/XLSB -files and output the contents in various formats. The source is available at -`xlsx.njs` in the bin directory. +- ajax: -See for a browser example. +``` +/* 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(); +``` + +- html5 drag-and-drop using readAsBinaryString: + +``` +/* set up drag-and-drop event */ +function handleDrop(e) { + e.stopPropagation(); + e.preventDefault(); + var files = e.dataTransfer.files; + var i,f; + for (i = 0, f = files[i]; i != files.length; ++i) { + var reader = new FileReader(); + var name = f.name; + reader.onload = function(e) { + var data = e.target.result; + + /* if binary string, read with type 'binary' */ + var wb = XLSX.read(data, {type: 'binary'}); + + /* DO SOMETHING WITH workbook HERE */ + }; + reader.readAsBinaryString(f); + } +} +drop_dom_element.addEventListener('drop', handleDrop, false); +``` + +This example walks through every cell of every sheet and dumps the values: + +``` +var sheet_name_list = workbook.SheetNames; +sheet_name_list.forEach(function(y) { + var worksheet = workbook.Sheets[y]; + for (z in worksheet) { + if(z[0] === '!') continue; + console.log(y + "!" + z + "=" + JSON.stringify(worksheet[z].v)); + } +}); +``` + +Complete examples: + +- HTML5 File API / Base64 Text / Web Workers Note that older versions of IE does not support HTML5 File API, so the base64 mode is provided for testing. On OSX you can get the base64 encoding with: - $ XMLHttpRequest + +- nodejs + +The nodejs version installs a binary `xlsx` which can read XLSX/XLSM/XLSB +files and output the contents in various formats. The source is available at +`xlsx.njs` in the bin directory. Some helper functions in `XLSX.utils` generate different views of the sheets: - `XLSX.utils.sheet_to_csv` generates CSV -- `XLSX.utils.sheet_to_row_object_array` interprets sheets as tables with a - header column and generates an array of objects +- `XLSX.utils.sheet_to_json` generates an array of objects - `XLSX.utils.get_formulae` generates a list of formulae -For more details: +## Writing Workbooks -- `bin/xlsx.njs` is a tool for node -- `index.html` is the live demo -- `bits/90_utils.js` contains the logic for generating CSV and JSON from sheets +Assuming `workbook` is a workbook object, just call write: + +- nodejs write to file: + +``` +/* output format determined by filename */ +XLSX.writeFile(workbook, 'out.xlsx'); +``` + +- write to binary string (using FileSaver.js) + +``` +/* bookType can be 'xlsx' or 'xlsm' or 'xlsb' */ +var wopts = { bookType:'xlsx', bookSST:true, type:'binary' }; + +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; +} + +saveAs(new Blob([s2ab(wbout)],{type:""}), "test.xlsx") +``` + +Complete examples: + +- generates a simple file +- writing an array of arrays in nodejs ## Interface -`XLSX` is the exposed variable in the browser and the exported variable in node +`XLSX` is the exposed variable in the browser and the exported nodejs variable `XLSX.read(data, read_opts)` attempts to parse `data`. @@ -161,18 +255,18 @@ The exported `write` and `writeFile` functions accept an options argument: with iOS Numbers - `bookType = 'xlsb'` is stubbed and far from complete - The raw data is the only thing guaranteed to be saved. Formulae, formatting, - and other niceties are not serialized (pending CSF standardization) + and other niceties may not be serialized (pending CSF standardization) ## Tested Environments - - Node 0.8, 0.10 (latest release) + - NodeJS 0.8, 0.10 (latest release) - IE 6/7/8/9/10 using Base64 mode (IE10/11 using HTML5 mode) - FF 18 using Base64 or HTML5 mode - Chrome 24 using Base64 or HTML5 mode Tests utilize the mocha testing framework. Travis-CI and Sauce Labs links: - - for XLSX module in node + - for XLSX module in nodejs - for XLS* modules - for XLS* modules using Sauce Labs @@ -184,7 +278,7 @@ Running `make init` will refresh the `test_files` submodule and get the files. ## Testing -`make test` will run the node-based tests. To run the in-browser tests, clone +`make test` will run the nodejs-based tests. To run the in-browser tests, clone [the oss.sheetjs.com repo](https://github.com/SheetJS/SheetJS.github.io) and replace the xlsx.js file (then fire up the browser and go to `stress.html`): @@ -204,7 +298,7 @@ important to ensure code is cleanroom. Consult CONTRIBUTING.md ## XLS Support -XLS is available in [js-xls](https://github.com/SheetJS/js-xls). +XLS is available in [js-xls](http://git.io/xls). ## License