Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Read + write style information to .xlsx #263

Open
wants to merge 104 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
104 commits
Select commit Hold shift + click to select a range
0227496
Add ability to save cell styles to .xlsx
pietersv Feb 28, 2015
845d2a8
Added support for alignment
pietersv Feb 28, 2015
a562150
Use jQuery parseXML to preserve case in XML
pietersv Mar 1, 2015
5f7a0f2
Removed dependence on cheerio, jquery; added xmlbuilder;
pietersv Mar 2, 2015
cd2b20f
Remove stray logs
pietersv Mar 2, 2015
576b59f
Fix issue with custom formats
pietersv Mar 2, 2015
05b58d8
Escape embedded quotes
pietersv Mar 3, 2015
1f02e5b
Handle embedded quotes in number formats
pietersv Mar 5, 2015
91ec052
Added support for borders
pietersv Mar 7, 2015
5e44331
Remove stray console.log() calls
pietersv Mar 7, 2015
c3af249
Add styles to README.md
pietersv Mar 9, 2015
97d4001
Update Style specifications in README.md
pietersv Mar 9, 2015
33dc7b8
Update README.md
pietersv Mar 9, 2015
aa8f3a7
Add support for textRotation
pietersv Mar 12, 2015
9b76f6b
Update README for textRotation
pietersv Mar 12, 2015
1a51c40
Remove broken link
Mar 12, 2015
0e2b8a4
Merge pull request #1 from knownasilya/patch-2
Mar 12, 2015
ad2a120
Update README.md
Mar 13, 2015
4f4f7fc
Fix issue exporting font color
pietersv Mar 20, 2015
33c32f0
Merge remote-tracking branch 'origin/master'
pietersv Mar 20, 2015
27a300b
Read styles - font, fill and numFmt
pietersv Mar 28, 2015
37a031c
Parse font bold-italic-strike-outline-shadow-superscript-subscript
pietersv Mar 28, 2015
995f5e8
Parse font bold-italic-strike-outline-shadow-superscript-subscript
pietersv Mar 28, 2015
8da3738
Update README.md
pietersv Mar 28, 2015
9102c82
Added round-trip test for styles
pietersv Mar 29, 2015
114f257
Merge remote-tracking branch 'origin/master'
pietersv Apr 15, 2015
5f9576a
Read borders and alignments
pietersv Apr 15, 2015
0b1a040
Merge changes from upsteam
pietersv Apr 15, 2015
08e648b
Update tests to reflect change in spec for fills
pietersv Apr 16, 2015
51b7cab
Parse raw_rgb
pietersv Apr 17, 2015
89066b4
Save fill color to .rgb but not tint
pietersv Apr 17, 2015
5dbf215
Correct hex2RGB coding, apply tints
pietersv Apr 17, 2015
c287383
Add syntax highlighting to readme examples
Apr 20, 2015
acf60c2
Merge pull request #2 from knownasilya/patch-2
Apr 20, 2015
40cfb0c
Document wrapText
pietersv May 8, 2015
21e1976
Merge branch 'master' of https://github.com/protobi/js-xlsx
pietersv May 8, 2015
858abf1
Remove requirement that require, module or jquery be defined before u…
pietersv May 12, 2015
ed0cd9b
Add alignment; update README
pietersv May 21, 2015
4099a24
Default gray125 style per pull request #3
pietersv Jun 4, 2015
0255a05
Remove temp example files from repo
pietersv Jun 12, 2015
8801e76
Make dist and update package name
pietersv Jun 13, 2015
0096c09
Update README, bower, package
pietersv Jun 13, 2015
9145958
Update README, bower, package
pietersv Jun 13, 2015
a602355
Update README, bower, package
pietersv Jun 13, 2015
d60a0a5
Update README, bower, package
pietersv Jun 13, 2015
3010d93
Update README, bower, package
pietersv Jun 13, 2015
c034eda
Update README, bower, package
pietersv Jun 13, 2015
1ca3c3e
Remove lab, .idea, test-csv, test-acid, etc. from repo
pietersv Jun 26, 2015
e7b06d7
Remove lab, .idea, test-csv, test-acid, etc. from repo
pietersv Jun 26, 2015
f52c80e
Remove lab, .idea, test-csv, test-acid, etc. from repo
pietersv Jun 26, 2015
dcf6f17
Retain styles for blank cells
pietersv Aug 11, 2015
0d1281c
Added test files
pietersv Aug 11, 2015
d76234a
Merge remote-tracking branch 'origin/master' into beta
pietersv Aug 11, 2015
3e3633a
Merge master to preserve blank style; increment version number
pietersv Aug 11, 2015
348c533
Update bower version to 0.8.5
pietersv Aug 11, 2015
57b6fd4
Pull changes to persist styles with blank cells; increment versions f…
pietersv Aug 11, 2015
7461389
Adds cheerio dependencie for tests/test-style.js
godu Aug 13, 2015
905c512
Adds tests
godu Aug 13, 2015
599f285
Breaks ref in style object
godu Aug 13, 2015
d00f36f
Merge pull request #10 from CoorpAcademy/fix-ref-styles
pietersv Aug 13, 2015
03b755b
Add showGridlines
pietersv Dec 4, 2015
fd83f20
Merge branch 'master' of https://github.com/protobi/js-xlsx into beta
pietersv Dec 4, 2015
8b1add6
Add showGridLines as option
pietersv Dec 4, 2015
2886195
Merge branch 'master' of https://github.com/protobi/js-xlsx
pietersv Dec 4, 2015
634699f
Merge branch 'master' of https://github.com/protobi/js-xlsx into beta
pietersv Dec 4, 2015
d4e0b8b
Bump bower version to 0.87
pietersv Dec 4, 2015
43f5698
Add row and column breaks
pietersv Dec 5, 2015
bbeec3e
Add row/col breaks
pietersv Dec 5, 2015
376096b
Add page setup
pietersv Dec 5, 2015
0bf1153
Add page scale and orientation
pietersv Dec 5, 2015
7de41c2
Add doc props
pietersv Dec 5, 2015
f984bd6
Add rowBreaks, colBreaks, scale, showGridLines
pietersv Dec 5, 2015
fe748ad
Copy README from beta
pietersv Mar 8, 2016
166d0e3
Update README.md
pietersv Mar 8, 2016
9407fe8
Update README.md
pietersv Mar 8, 2016
aceebf4
Update README.md
pietersv Mar 8, 2016
0e62411
Update README.md
pietersv Mar 8, 2016
050b74e
Update README.md
pietersv Mar 8, 2016
2ec18e9
Update README.md
pietersv Mar 8, 2016
bed6327
Set tabSelected to 0 per issue #26
pietersv Apr 6, 2016
876c4a0
Set tabSelected to 0 per issue #26
pietersv Apr 6, 2016
eef7da3
Merge branch 'master' of https://github.com/protobi/js-xlsx
pietersv Apr 6, 2016
0b8e538
Add repeating print headers
pietersv May 24, 2016
2424890
Merge remote-tracking branch 'origin/beta' into beta
pietersv May 24, 2016
8198744
merge from beta
pietersv May 25, 2016
245ffb8
Update tests; add feature to freeze headerrow
pietersv May 25, 2016
34d618c
Update tests; add feature to freeze headerrow
pietersv May 25, 2016
3c7f807
Revert package name
pietersv May 25, 2016
796fbb5
Fix file getter: letter case not match
chikh Jul 14, 2016
d3f6343
Apply letter case issue fix to the source code
chikh Sep 10, 2016
d5092b4
Merge pull request #46 from noodoo/fix/lower-case-files
pietersv Sep 29, 2016
6e66789
PR #40 - Skip cells with incorrect link to shared strings
pietersv Oct 11, 2016
1903cff
Merge remote-tracking branch 'origin/master'
pietersv Oct 11, 2016
9edf279
Add freeze pane option
pietersv Apr 3, 2017
f959b02
Add freeze panes
pietersv Apr 3, 2017
a03dc21
Add freeze panes
pietersv Apr 3, 2017
c224819
Fixed Style Table in README.md
zeg-io Apr 4, 2017
68ba4e8
Merge pull request #64 from zeg-io/patch-1
Apr 4, 2017
f2520b7
Freeze columns
pietersv May 31, 2017
c86472d
Merge branch 'master' of https://github.com/protobi/js-xlsx
pietersv May 31, 2017
9233322
Add examples
pietersv Apr 1, 2019
6226e1a
Undo last commit
pietersv Sep 18, 2019
6d0f51f
Fixed horizontal alignment values
oosswwaalldd Aug 27, 2020
8f7a294
Merge pull request #151 from oosswwaalldd/patch-1
pietersv Aug 28, 2020
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added .DS_Store
Binary file not shown.
6 changes: 6 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,9 @@ tmp
*.htm
*.html
*.sheetjs

lab/
test_files
example.js
example2.js
.idea
197 changes: 167 additions & 30 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,18 @@
# xlsx
# xlsx-style

Parser and writer for various spreadsheet formats. Pure-JS cleanroom
implementation from official specifications and related documents.
Parser and writer for various spreadsheet formats. Pure-JS cleanroom implementation from official specifications and related documents.

# About this fork
**NOTE:** [This project](https://github.com/SheetJS/js-xlsx/tree/beta) is a fork of the original (and awesome) [SheetJS/xlsx](https://github.com/SheetJS/js-xlsx) project.
It is extended to enable cell formats to be read from and written to .xlsx workbooks.
The intent is to provide a temporary means of using these features in practice, and ultimately to merge this into the primary project.
Report any issues to https://github.com/protobi/js-xlsx/issues.

For those contributing to this fork:
* `master` is the main branch, which follows the original repo to enable a future pull request.
* `beta` branch is published to npm and bower to make this fork available for use.

# Supported formats

Supported read formats:

Expand All @@ -24,17 +35,23 @@ Source: <http://git.io/xlsx>

## Installation

With [npm](https://www.npmjs.org/package/xlsx):
With [npm](https://www.npmjs.org/package/xlsx-style):

npm install xlsx
```sh
npm install xlsx-style --save
```

In the browser:

<script lang="javascript" src="dist/xlsx.core.min.js"></script>
```html
<script lang="javascript" src="dist/xlsx.core.min.js"></script>
```

With [bower](http://bower.io/search/?q=js-xlsx):

bower install js-xlsx
```sh
bower install js-xlsx-style#beta
```

CDNjs automatically pulls the latest version and makes all versions available at
<http://cdnjs.com/libraries/xlsx>
Expand All @@ -46,10 +63,12 @@ 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:

<!-- international support from https://github.com/sheetjs/js-codepage -->
<script src="dist/cpexcel.js"></script>
<!-- ODS support -->
<script src="dist/ods.js"></script>
```html
<!-- international support from https://github.com/sheetjs/js-codepage -->
<script src="dist/cpexcel.js"></script>
<!-- ODS support -->
<script src="dist/ods.js"></script>
```

An appropriate version for each dependency is included in the dist/ directory.

Expand All @@ -63,7 +82,9 @@ Since xlsx.js uses ES5 functions like `Array#forEach`, older browsers require

To use the shim, add the shim before the script tag that loads xlsx.js:

<script type="text/javascript" src="/path/to/shim.js"></script>
```html
<script type="text/javascript" src="/path/to/shim.js"></script>
```

## Parsing Workbooks

Expand All @@ -72,7 +93,7 @@ data and feeding it into the library. Here are a few common scenarios:

- node readFile:

```
```js
if(typeof require !== 'undefined') XLSX = require('xlsx');
var workbook = XLSX.readFile('test.xlsx');
/* DO SOMETHING WITH workbook HERE */
Expand All @@ -81,10 +102,11 @@ var workbook = XLSX.readFile('test.xlsx');
- ajax (for a more complete example that works in older browsers, check the demo
at <http://oss.sheetjs.com/js-xlsx/ajax.html>):

```
```js
/* set up XMLHttpRequest */
var url = "test_files/formula_stress_test_ajax.xlsx";
var oReq = new XMLHttpRequest();

oReq.open("GET", url, true);
oReq.responseType = "arraybuffer";

Expand All @@ -108,13 +130,14 @@ oReq.send();

- HTML5 drag-and-drop using readAsBinaryString:

```
```js
/* set up drag-and-drop event */
function handleDrop(e) {
e.stopPropagation();
e.preventDefault();
var files = e.dataTransfer.files;
var i,f;
var i, f;

for (i = 0, f = files[i]; i != files.length; ++i) {
var reader = new FileReader();
var name = f.name;
Expand All @@ -134,10 +157,11 @@ drop_dom_element.addEventListener('drop', handleDrop, false);

- HTML5 input file element using readAsBinaryString:

```
```js
function handleFile(e) {
var files = e.target.files;
var i,f;
var i, f;

for (i = 0, f = files[i]; i != files.length; ++i) {
var reader = new FileReader();
var name = f.name;
Expand All @@ -160,7 +184,7 @@ The full object format is described later in this README.

This example extracts the value stored in cell A1 from the first worksheet:

```
```js
var first_sheet_name = workbook.SheetNames[0];
var address_of_cell = 'A1';

Expand All @@ -176,8 +200,9 @@ var desired_value = desired_cell.v;

This example iterates through every nonempty of every sheet and dumps values:

```
```js
var sheet_name_list = workbook.SheetNames;

sheet_name_list.forEach(function(y) { /* iterate through sheets */
var worksheet = workbook.Sheets[y];
for (z in worksheet) {
Expand All @@ -195,7 +220,9 @@ Complete examples:
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:

$ <target_file.xlsx base64 | pbcopy
```sh
$ <target_file.xlsx base64 | pbcopy
```

- <http://oss.sheetjs.com/js-xlsx/ajax.html> XMLHttpRequest

Expand All @@ -220,15 +247,15 @@ Assuming `workbook` is a workbook object:

- nodejs write to file:

```
```js
/* output format determined by filename */
XLSX.writeFile(workbook, 'out.xlsx');
/* at this point, out.xlsx is a file that you can distribute */
```

- write to binary string (using FileSaver.js):

```
```js
/* bookType can be 'xlsx' or 'xlsm' or 'xlsb' */
var wopts = { bookType:'xlsx', bookSST:false, type:'binary' };

Expand Down Expand Up @@ -303,7 +330,7 @@ Cell range objects are stored as `{s:S, e:E}` where `S` is the first cell and
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:

```
```js
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};
Expand Down Expand Up @@ -331,6 +358,9 @@ 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.

**Note**: The .z attribute is now deprecated. Use the `.s` attribute to specify cell styles including number formats.
To specify a number format, use `s.numFmt`, e.g. `{v: 42145.822, s: { numFmt: "m/dd/yy"}}` described below.

### Data Types

The raw value is stored in the `v` field, interpreted based on the `t` field.
Expand Down Expand Up @@ -400,14 +430,39 @@ Special worksheet keys (accessible as `worksheet[key]`, each starting with `!`):
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.

- `ws['!printHeader']`: array of row indices for repeating row headers on print, e.g. `[1:1]` to repeat just the first row.

The following properties are currently used when generating an XLSX file, but not yet parsed:

- `ws['!rowBreaks']`: array of row break points, e.g. `[16,32]`
- `ws['!colBreaks']`: array of col break points, e.g. `[8,16]`
- `ws['!pageSetup']`: `{scale: '100', orientation: 'portrait'||'landscape'}
- `ws['!printHeader']`: array of first and last row indexes for repeat header on printing, e.g. `[1,1]` to repeat just first row
- `ws['!freeze']`: string cell reference for breakpoint, e.g. the following will freeze the first row and first column:
{
xSplit: "1",
ySplit: "1",
topLeftCell: "B2",
activePane: "bottomRight",
state: "frozen"
}


### Workbook Object

`workbook.SheetNames` is an ordered list of the sheets in the workbook

`wb.Sheets[sheetname]` returns an object representing the worksheet.

`wb.Props` is an object storing the standard properties. `wb.Custprops` stores
custom properties. Since the XLS standard properties deviate from the XLSX
`wb.Props` is an object storing the standard properties. The following properties are currently used when
generating an XLSX file, but not yet parsed:
- `title`
- `subject`
- `description`
- `keywords`
- `creator`

`wb.Custprops` stores custom properties. Since the XLS standard properties deviate from the XLSX
standard, XLS parsing stores core properties in both places. .


Expand Down Expand Up @@ -459,6 +514,12 @@ The exported `write` and `writeFile` functions accept an options argument:
| cellDates | false | Store dates as type `d` (default is `n`) |
| bookSST | false | Generate Shared String Table ** |
| bookType | 'xlsx' | Type of Workbook ("xlsx" or "xlsm" or "xlsb") |
| showGridLines | true | Show gridlines on all pages |
| tabSelected | '1' | Initial tab selected |
| Props | null | Workbook properties |




- `bookSST` is slower and more memory intensive, but has better compatibility
with older versions of iOS Numbers
Expand All @@ -468,6 +529,84 @@ The exported `write` and `writeFile` functions accept an options argument:
- `cellDates` only applies to XLSX output and is not guaranteed to work with
third-party readers. Excel itself does not usually write cells with type `d`
so non-Excel tools may ignore the data or blow up in the presence of dates.
- showGridLines and tabSelected are currently used when generating an XLSX file but not yet parse.
- Props specifies workbook properties




## Cell Styles

Cell styles are specified by a style object that roughly parallels the OpenXML structure. The style object has five
top-level attributes: `fill`, `font`, `numFmt`, `alignment`, and `border`.


| Style Attribute | Sub Attributes | Values |
| :-------------- | :------------- | :------------- |
| fill | patternType | `"solid"` or `"none"`
| | fgColor | `COLOR_SPEC`
| | bgColor | `COLOR_SPEC`
| font | name | `"Calibri"` // default
| | sz | `"11"` // font size in points
| | color | `COLOR_SPEC`
| | bold | `true` or `false`
| | underline | `true` or `false`
| | italic | `true` or `false`
| | strike | `true` or `false`
| | outline | `true` or `false`
| | shadow | `true` or `false`
| | vertAlign | `true` or `false`
| numFmt | | `"0"` // integer index to built in formats, see StyleBuilder.SSF property
| | | `"0.00%"` // string matching a built-in format, see StyleBuilder.SSF
| | | `"0.0%"` // string specifying a custom format
| | | `"0.00%;\\(0.00%\\);\\-;@"` // string specifying a custom format, escaping special characters
| | | `"m/dd/yy"` // string a date format using Excel's format notation
| alignment | vertical | `"bottom"` or `"center"` or `"top"`
| | horizontal | `"left"` or `"center"` or `"right"`
| | wrapText | `true ` or ` false`
| | readingOrder | `2` // for right-to-left
| | textRotation | Number from `0` to `180` or `255` (default is `0`)
| | | `90` is rotated up 90 degrees
| | | `45` is rotated up 45 degrees
| | | `135` is rotated down 45 degrees
| | | `180` is rotated down 180 degrees
| | | `255` is special, aligned vertically
| border | top | `{ style: BORDER_STYLE, color: COLOR_SPEC }`
| | bottom | `{ style: BORDER_STYLE, color: COLOR_SPEC }`
| | left | `{ style: BORDER_STYLE, color: COLOR_SPEC }`
| | right | `{ style: BORDER_STYLE, color: COLOR_SPEC }`
| | diagonal | `{ style: BORDER_STYLE, color: COLOR_SPEC }`
| | diagonalUp | `true` or `false`
| | diagonalDown | `true` or `false`

**COLOR_SPEC**: Colors for `fill`, `font`, and `border` are specified as objects, either:
* `{ auto: 1}` specifying automatic values
* `{ rgb: "FFFFAA00" }` specifying a hex ARGB value
* `{ theme: "1", tint: "-0.25"}` specifying an integer index to a theme color and a tint value (default 0)
* `{ indexed: 64}` default value for `fill.bgColor`

**BORDER_STYLE**: Border style is a string value which may take on one of the following values:
* `thin`
* `medium`
* `thick`
* `dotted`
* `hair`
* `dashed`
* `mediumDashed`
* `dashDot`
* `mediumDashDot`
* `dashDotDot`
* `mediumDashDotDot`
* `slantDashDot`


Borders for merged areas are specified for each cell within the merged area. So to apply a box border to a merged area of 3x3 cells, border styles would need to be specified for eight different cells:
* left borders for the three cells on the left,
* right borders for the cells on the right
* top borders for the cells on the top
* bottom borders for the cells on the left



## Tested Environments

Expand All @@ -494,7 +633,7 @@ Running `make init` will refresh the `test_files` submodule and get the files.
[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`):

```
```sh
$ cp xlsx.js ../SheetJS.github.io
$ cd ../SheetJS.github.io
$ simplehttpserver # or "python -mSimpleHTTPServer" or "serve"
Expand All @@ -513,7 +652,7 @@ build script (run `make`) will concatenate the individual bits to produce the
script. Before submitting a contribution, ensure that running make will produce
the xlsx.js file exactly. The simplest way to test is to move the script:

```
```sh
$ mv xlsx.js xlsx.new.js
$ make
$ diff xlsx.js xlsx.new.js
Expand Down Expand Up @@ -564,5 +703,3 @@ Open Document Format for Office Applications Version 1.2 (29 September 2011)
[![Build Status](https://travis-ci.org/SheetJS/js-xlsx.svg?branch=master)](https://travis-ci.org/SheetJS/js-xlsx)

[![Coverage Status](http://img.shields.io/coveralls/SheetJS/js-xlsx/master.svg)](https://coveralls.io/r/SheetJS/js-xlsx?branch=master)

[![githalytics.com alpha](https://cruel-carlota.pagodabox.com/ed5bb2c4c4346a474fef270f847f3f78 "githalytics.com")](http://githalytics.com/SheetJS/js-xlsx)
2 changes: 1 addition & 1 deletion bits/01_version.js
Original file line number Diff line number Diff line change
@@ -1 +1 @@
XLSX.version = '0.8.0';
XLSX.version = '0.8.20';
10 changes: 8 additions & 2 deletions bits/21_ziputils.js
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,14 @@ function getdata(data) {

function safegetzipfile(zip, file) {
var f = file; if(zip.files[f]) return zip.files[f];
f = file.toLowerCase(); if(zip.files[f]) return zip.files[f];
f = f.replace(/\//g,'\\'); if(zip.files[f]) return zip.files[f];

var lowerCaseFiles = {};
for (var key in zip.files) {
lowerCaseFiles[key.toLowerCase()] = zip.files[key];
}

f = file.toLowerCase(); if(lowerCaseFiles[f]) return lowerCaseFiles[f];
f = f.replace(/\//g,'\\'); if(lowerCaseFiles[f]) return lowerCaseFiles[f];
return null;
}

Expand Down
Loading