xsheetjs/docbits/63_numfmt.md
SheetJS a8736580a5 version bump 0.10.0: cleanup
- updated SSF to 0.9.2
- XLSB style records and number format writing
- CSV avoid parseFloat (fixes #646 h/t @jabbermarky)
- CSV recognize mac line ending (fixes #648 h/t @charlesread)
- BIFF2 format table refactored to align with SSF
- BIFF5 image data exposure
- SSF custom format auto table update (fixes #267 h/t @Fangmingdu)
- eslint more checks
- browser test timeout extended to 10 seconds
2017-05-09 14:07:57 -04:00

3.0 KiB

Number Formats

The cell.w formatted text for each cell is produced from cell.v and cell.z format. If the format is not specified, the Excel General format is used. The format can either be specified as a string or as an index into the format table. Parsers are expected to populate workbook.SSF with the number format table. Writers are expected to serialize the table.

Custom tools should ensure that the local table has each used format string somewhere in the table. Excel convention mandates that the custom formats start at index 164. The following example creates a custom format from scratch:

New worksheet with custom format (click to show)
var tbl = {};
var wb = {
	SheetNames: ["Sheet1"],
	Sheets: {
		Sheet1: {
			"!ref":"A1:C1",
			A1: { t:"n", v:10000 },                    // <-- General format
			B1: { t:"n", v:10000, z: "0%" },           // <-- Builtin format
			C1: { t:"n", v:10000, z: "\"T\"\ #0.00" }  // <-- Custom format
		}
	}
}

The rules are slightly different from how Excel displays custom number formats. In particular, literal characters must be wrapped in double quotes or preceded by a backslash. For more info, see the Excel documentation article Create or delete a custom number format or ECMA-376 18.8.31 (Number Formats)

Default Number Formats (click to show)

The default formats are listed in ECMA-376 18.8.30:

ID Format
0 General
1 0
2 0.00
3 #,##0
4 #,##0.00
9 0%
10 0.00%
11 0.00E+00
12 # ?/?
13 # ??/??
14 m/d/yy (see below)
15 d-mmm-yy
16 d-mmm
17 mmm-yy
18 h:mm AM/PM
19 h:mm:ss AM/PM
20 h:mm
21 h:mm:ss
22 m/d/yy h:mm
37 #,##0 ;(#,##0)
38 #,##0 ;[Red](#,##0)
39 #,##0.00;(#,##0.00)
40 #,##0.00;[Red](#,##0.00)
45 mm:ss
46 [h]:mm:ss
47 mmss.0
48 ##0.0E+0
49 @

Format 14 (m/d/yy) is localized by Excel: even though the file specifies that number format, it will be drawn differently based on system settings. It makes sense when the producer and consumer of files are in the same locale, but that is not always the case over the Internet. To get around this ambiguity, parse functions accept the dateNF option to override the interpretation of that specific format string.