ExcelJS
读取,操作并写入电子表格数据和样式到 XLSX 和 JSON 文件。
一个 Excel 电子表格文件逆向工程项目。
安装
|
导入⬆
|
ES5 导入⬆
要使用 ES5 编译代码,请使用 dist/es5 路径。
|
注意:ES5 版本对许多 polyfill 都具有隐式依赖,而 exceljs 不再明确添加。
您需要在依赖项中添加 core-js
和 regenerator-runtime
,并在导入 exceljs
之前在代码中包含以下引用:
|
对于 IE 11,您还需要一个 polyfill 以支持 unicode regex 模式。 例如,
|
浏览器端⬆
ExcelJS 在 dist/ 文件夹内发布了两个支持浏览器的包:
一个是隐式依赖 core-js
polyfills 的…
|
另一个则没有…
|
接口⬆
创建工作簿⬆
|
设置工作簿属性⬆
|
|
设置计算属性⬆
|
工作簿视图⬆
工作簿视图控制在查看工作簿时 Excel 将打开多少个单独的窗口。
|
添加工作表⬆
|
使用 addWorksheet
函数的第二个参数来指定工作表的选项。
示例:
|
删除工作表⬆
使用工作表的 id
从工作簿中删除工作表。
示例:
|
访问工作表⬆
|
工作表状态⬆
|
工作表属性⬆
工作表支持属性存储,以允许控制工作表的某些功能。
|
支持的属性
属性名 | 默认值 | 描述 |
---|---|---|
tabColor | undefined |
标签的颜色 |
outlineLevelCol | 0 | 工作表列大纲级别 |
outlineLevelRow | 0 | 工作表行大纲级别 |
defaultRowHeight | 15 | 默认行高 |
defaultColWidth | (optional) | 默认列宽 |
dyDescent | 55 | TBD |
工作表尺寸⬆
一些新的尺寸属性已添加到工作表中…
属性名 | 描述 |
---|---|
rowCount | 文档的总行数。 等于具有值的最后一行的行号。 |
actualRowCount | 具有值的行数的计数。 如果中间文档行为空,则该行将不包括在计数中。 |
columnCount | 文档的总列数。 等于所有行的最大单元数。 |
actualColumnCount | 具有值的列数的计数。 |
页面设置⬆
所有可能影响工作表打印的属性都保存在工作表上的 pageSetup
对象中。
|
支持的页面设置配置项
属性名 | 默认值 | 描述 |
---|---|---|
margins | 页面上的空白边距。 单位为英寸。 | |
orientation | 'portrait' |
页面方向 - 即较高 ('portrait' ) 或者较宽 ('landscape' ) |
horizontalDpi | 4294967295 | 水平方向上的 DPI。默认值为 -1 |
verticalDpi | 4294967295 | 垂直方向上的 DPI。默认值为 -1 |
fitToPage | 是否使用 fitToWidth 和 fitToHeight 或 scale 设置。默认基于存在于 pageSetup 对象中的设置-如果两者都存在,则 scale 优先级高(默认值为 false )。 |
|
pageOrder | 'downThenOver' |
打印页面的顺序-['downThenOver', 'overThenDown'] 之一 |
blackAndWhite | false |
无色打印 |
draft | false |
打印质量较低(墨水) |
cellComments | 'None' |
在何处放置批注-['atEnd','asDisplayed','None'] 中的一个 |
errors | 'displayed' |
哪里显示错误 -['dash', 'blank', 'NA', 'displayed'] 之一 |
scale | 100 | 增加或减小打印尺寸的百分比值。 当 fitToPage 为 false 时激活 |
fitToWidth | 1 | 纸张应打印多少页宽。 当 fitToPage 为 true 时激活 |
fitToHeight | 1 | 纸张应打印多少页高。 当 fitToPage 为 true 时激活 |
paperSize | 使用哪种纸张尺寸(见下文) | |
showRowColHeaders | false | 是否显示行号和列字母 |
showGridLines | false | 是否显示网格线 |
firstPageNumber | 第一页使用哪个页码 | |
horizontalCentered | false | 是否将工作表数据水平居中 |
verticalCentered | false | 是否将工作表数据垂直居中 |
示例纸张尺寸
属性名 | 值 |
---|---|
Letter | undefined |
Legal | 5 |
Executive | 7 |
A3 | 8 |
A4 | 9 |
A5 | 11 |
B5 (JIS) | 13 |
Envelope #10 | 20 |
Envelope DL | 27 |
Envelope C5 | 28 |
Envelope B5 | 34 |
Envelope Monarch | 37 |
Double Japan Postcard Rotated | 82 |
16K 197x273 mm | 119 |
页眉和页脚⬆
这是添加页眉和页脚的方法。
添加的内容主要是文本,例如时间,简介,文件信息等,您可以设置文本的样式。
此外,您可以为首页和偶数页设置不同的文本。
注意:目前不支持图片。
|
支持的 headerFooter 设置
属性名 | 默认值 | 描述 |
---|---|---|
differentFirst | false |
将 differentFirst 的值设置为 true ,这表示第一页的页眉/页脚与其他页不同 |
differentOddEven | false |
将 differentOddEven 的值设置为 true ,表示奇数页和偶数页的页眉/页脚不同 |
oddHeader | null |
设置奇数(默认)页面的标题字符串,可以设置格式化字符串 |
oddFooter | null |
设置奇数(默认)页面的页脚字符串,可以设置格式化字符串 |
evenHeader | null |
设置偶数页的标题字符串,可以设置格式化字符串 |
evenFooter | null |
为偶数页设置页脚字符串,可以设置格式化字符串 |
firstHeader | null |
设置首页的标题字符串,可以设置格式化字符串 |
firstFooter | null |
设置首页的页脚字符串,可以设置格式化字符串 |
脚本命令
命令 | 描述 |
---|---|
&L | 将位置设定在左侧 |
&C | 将位置设置在中心 |
&R | 将位置设定在右边 |
&P | 当前页码 |
&N | 总页数 |
&D | 当前日期 |
&T | 当前时间 |
&G | 照片 |
&A | 工作表名称 |
&F | 文件名称 |
&B | 加粗文本 |
&I | 斜体文本 |
&U | 文本下划线 |
&”font name” | 字体名称,例如&“ Aril” |
&font size | 字体大小,例如 12 |
&KHEXCode | 字体颜色,例如 &KCCCCCC |
工作表视图⬆
现在,工作表支持视图列表,这些视图控制 Excel 如何显示工作表:
frozen
- 顶部和左侧的许多行和列被冻结在适当的位置。 仅右下部分会滚动split
- 该视图分为 4 个部分,每个部分可半独立滚动。
每个视图还支持各种属性:
属性名 | 默认值 | 描述 |
---|---|---|
state | 'normal' |
控制视图状态 - 'normal' , 'frozen' 或者 'split' 之一 |
rightToLeft | false |
将工作表视图的方向设置为从右到左 |
activeCell | undefined |
当前选择的单元格 |
showRuler | true |
在页面布局中显示或隐藏标尺 |
showRowColHeaders | true |
显示或隐藏行标题和列标题(例如,顶部的 A1,B1 和左侧的 1,2,3) |
showGridLines | true |
显示或隐藏网格线(针对未定义边框的单元格显示) |
zoomScale | 100 | 用于视图的缩放比例 |
zoomScaleNormal | 100 | 正常缩放视图 |
style | undefined |
演示样式- pageBreakPreview 或 pageLayout 之一。 注意:页面布局与 frozen 视图不兼容 |
冻结视图⬆
冻结视图支持以下额外属性:
属性名 | 默认值 | 描述 |
---|---|---|
xSplit | 0 | 冻结多少列。要仅冻结行,请将其设置为 0 或 undefined |
ySplit | 0 | 冻结多少行。要仅冻结列,请将其设置为 0 或 undefined |
topLeftCell | special | 哪个单元格将在右下窗格中的左上角。注意:不能是冻结单元格。默认为第一个未冻结的单元格 |
|
拆分视图⬆
拆分视图支持以下额外属性:
属性名 | 默认值 | 描述 |
---|---|---|
xSplit | 0 | 从左侧多少个点起,以放置拆分器。要垂直拆分,请将其设置为 0 或 undefined |
ySplit | 0 | 从顶部多少个点起,放置拆分器。要水平拆分,请将其设置为 0 或 undefined |
topLeftCell | undefined |
哪个单元格将在右下窗格中的左上角。 |
activePane | undefined |
哪个窗格将处于活动状态-topLeft ,topRight ,bottomLeft 和 bottomRight 中的一个 |
|
自动筛选器⬆
可以对工作表应用自动筛选器。
|
尽管范围字符串是 autoFilter
的标准形式,但工作表还将支持以下值:
|
列⬆
|
行⬆
|
Add Rows⬆
|
Parameter | Description | Default Value |
---|---|---|
value/s | The new row/s values | |
style | ‘i’ for inherit from row above, ‘i+’ to include empty cells, ‘n’ for none | ‘n’ |
处理单个单元格⬆
|
合并单元格⬆
|
Insert Rows⬆
|
Parameter | Description | Default Value |
---|---|---|
pos | Row number where you want to insert, pushing down all rows from there | |
value/s | The new row/s values | |
style | ‘i’ for inherit from row above, , ‘i+’ to include empty cells, ‘o’ for original style, ‘o+’ to include empty cells, ‘n’ for none | ‘n’ |
Splice⬆
|
Parameter | Description | Default Value |
---|---|---|
start | Starting point to splice from | |
count | Number of rows/cells to remove | |
…inserts | New row/cell values to insert |
重复行⬆
|
参数 | 描述 | 默认值 |
---|---|---|
start | 要复制的行号(Excel 中的第一个是 1) | |
amount | 您要复制行的次数 | 1 |
insert | 如果要为重复项插入新行,则为 true ,否则为 false 将替换已有行 |
true |
定义名称⬆
单个单元格(或多个单元格组)可以为它们分配名称。名称可用于公式和数据验证(可能还有更多)。
|
数据验证⬆
单元格可以定义哪些值有效或无效,并提示用户以帮助指导它们。
验证类型可以是以下之一:
类型 | 描述 |
---|---|
list | 定义一组离散的有效值。Excel 将在下拉菜单中提供这些内容,以便于输入 |
whole | 该值必须是整数 |
decimal | 该值必须是十进制数 |
textLength | 该值可以是文本,但长度是受控的 |
custom | 自定义公式控制有效值 |
对于 list
或 custom
以外的其他类型,以下运算符会影响验证:
运算符 | 描述 |
---|---|
between | 值必须介于公式结果之间 |
notBetween | 值不能介于公式结果之间 |
equal | 值必须等于公式结果 |
notEqual | 值不能等于公式结果 |
greaterThan | 值必须大于公式结果 |
lessThan | 值必须小于公式结果 |
greaterThanOrEqual | 值必须大于或等于公式结果 |
lessThanOrEqual | 值必须小于或等于公式结果 |
|
单元格注释⬆
将旧样式的注释添加到单元格
|
单元格批注属性⬆
下表定义了单元格注释已支持的属性。
Field | Required | Default Value | Description |
---|---|---|---|
texts | Y | 评论文字 | |
margins | N | {} | 确定自动或自定义设置单元格注释的边距值 |
protection | N | {} | 可以使用保护属性来指定对象和对象文本的锁定状态 |
editAs | N | ‘absolute’ | 可以使用’editAs’属性来指定注释如何锚定到单元格 |
单元格批注页边距⬆
确定单元格批注的页面距设置模式,自动或者自定义模式。
|
已支持的页边距属性⬆
Property | Required | Default Value | Description |
---|---|---|---|
insetmode | N | ‘auto’ | 确定是否自动设置注释边距,并且值是’auto’ 或者 ‘custom’ |
inset | N | [0.13, 0.13, 0.25, 0.25] | 批注页边距的值,单位是厘米, 方向是左-上-右-下 |
注意:只有当 insetmode
的值设置为’custom’时,inset
的设置才生效。
单元格批注保护⬆
可以使用保护属性来修改单元级别保护。
|
已支持的保护属性⬆
Property | Required | Default Value | Description |
---|---|---|---|
locked | N | ‘True’ | 此元素指定在保护工作表时对象已锁定 |
lockText | N | ‘True’ | 该元素指定对象的文本已锁定 |
单元格批注对象位置属性⬆
单元格注释还可以具有属性 ‘editAs’,该属性将控制注释如何锚定到单元格。
它可以具有以下值之一:
|
Value | Description |
---|---|
twoCells | 它指定注释的大小、位置随单元格而变 |
oneCells | 它指定注释的大小固定,位置随单元格而变 |
absolute | 这是默认值,它指定注释的大小、位置均固定 |
表格⬆
表允许表格内数据的表内操作。
要将表添加到工作表,请定义表模型并调用 addTable
:
|
注意:将表格添加到工作表将通过放置表格的标题和行数据来修改工作表。
结果就是表格覆盖的工作表上的所有数据(包括标题和所有的)都将被覆盖。
表格属性⬆
下表定义了表格支持的属性。
表属性 | 描述 | 是否需要 | 默认值 |
---|---|---|---|
name | 表格名称 | Y | |
displayName | 表格的显示名称 | N | name |
ref | 表格的左上方单元格 | Y | |
headerRow | 在表格顶部显示标题 | N | true |
totalsRow | 在表格底部显示总计 | N | false |
style | 额外的样式属性 | N | {} |
columns | 列定义 | Y | |
rows | 数据行 | Y |
表格样式属性⬆
下表定义了表格中支持的属性样式属性。
样式属性 | 描述 | 是否需要 | 默认值 |
---|---|---|---|
theme | 桌子的颜色主题 | N | 'TableStyleMedium2' |
showFirstColumn | 突出显示第一列(粗体) | N | false |
showLastColumn | 突出显示最后一列(粗体) | N | false |
showRowStripes | 用交替的背景色显示行 | N | false |
showColumnStripes | 用交替的背景色显示列 | N | false |
表格列属性⬆
下表定义了每个表格列中支持的属性。
列属性 | 描述 | 是否需要 | 默认值 |
---|---|---|---|
name | 列名,也用在标题中 | Y | |
filterButton | 切换标题中的过滤器控件 | N | false |
totalsRowLabel | 用于描述统计行的标签(第一列) | N | 'Total' |
totalsRowFunction | 统计函数名称 | N | 'none' |
totalsRowFormula | 自定义函数的可选公式 | N |
统计函数⬆
下表列出了由列定义的 totalsRowFunction
属性的有效值。如果使用 'custom'
以外的任何值,则无需包括关联的公式,因为该公式将被表格插入。
统计函数 | 描述 |
---|---|
none | 此列没有统计函数 |
average | 计算列的平均值 |
countNums | 统计数字条目数 |
count | 条目数 |
max | 此列中的最大值 |
min | 此列中的最小值 |
stdDev | 该列的标准偏差 |
var | 此列的方差 |
sum | 此列的条目总数 |
custom | 自定义公式。 需要关联的 totalsRowFormula 值。 |
表格样式主题⬆
有效的主题名称遵循以下模式:
- “TableStyle[Shade][Number]”
Shades(阴影),Number(数字)可以是以下之一:
- Light, 1-21
- Medium, 1-28
- Dark, 1-11
对于无主题,请使用值 null
。
注意:exceljs 尚不支持自定义表格主题。
修改表格⬆
表格支持一组操作函数,这些操作函数允许添加或删除数据以及更改某些属性。由于这些操作中的许多操作可能会对工作表产生副作用,因此更改必须在完成后立即提交。
表中的所有索引值均基于零,因此第一行号和第一列号为 0
。
添加或删除标题和统计
|
重定位表
|
添加和删除行
|
添加和删除列
|
更改列属性
|
样式⬆
单元格,行和列均支持一组丰富的样式和格式,这些样式和格式会影响单元格的显示方式。
通过分配以下属性来设置样式:
|
将样式应用于行或列时,它将应用于该行或列中所有当前存在的单元格。另外,创建的任何新单元格都将从其所属的行和列继承其初始样式。
如果单元格的行和列都定义了特定的样式(例如,字体),则该单元格所在行样式比列样式具有更高优先级。但是,如果行和列定义了不同的样式(例如 column.numFmt
和 row.font
),则单元格将继承行的字体和列的 numFmt
。
注意:以上所有属性(numFmt
(字符串)除外)都是 JS 对象结构。如果将同一样式对象分配给多个电子表格实体,则每个实体将共享同一样式对象。如果样式对象后来在电子表格序列化之前被修改,则所有引用该样式对象的实体也将被修改。此行为旨在通过减少创建的 JS 对象的数量来优先考虑性能。如果希望样式对象是独立的,则需要先对其进行克隆,然后再分配它们。同样,默认情况下,如果电子表格实体共享相似的样式,则从文件(或流)中读取文档时,它们也将引用相同的样式对象。
数字格式⬆
|
字体
|
字体属性 | 描述 | 示例值 |
---|---|---|
name | 字体名称。 | ‘Arial’, ‘Calibri’, etc. |
family | 备用字体家族。整数值。 | 1 - Serif, 2 - Sans Serif, 3 - Mono, Others - unknown |
scheme | 字体方案。 | ‘minor’, ‘major’, ‘none’ |
charset | 字体字符集。整数值。 | 1, 2, etc. |
size | 字体大小。整数值。 | 9, 10, 12, 16, etc. |
color | 颜色描述,一个包含 ARGB 值的对象。 | { argb: ‘FFFF0000’} |
bold | 字体 粗细 | true, false |
italic | 字体 倾斜 | true, false |
underline | 字体 下划线 样式 | true, false, ‘none’, ‘single’, ‘double’, ‘singleAccounting’, ‘doubleAccounting’ |
strike | 字体 |
true, false |
outline | 字体轮廓 | true, false |
vertAlign | 垂直对齐 | ‘superscript’, ‘subscript’ |
对齐⬆
|
有效的对齐属性值
水平的 | 垂直 | 文本换行 | 自适应 | 缩进 | 阅读顺序 | 文本旋转 |
---|---|---|---|---|---|---|
left | top | true | true | integer | rtl | 0 to 90 |
center | middle | false | false | ltr | -1 to -90 | |
right | bottom | vertical | ||||
fill | distributed | |||||
justify | justify | |||||
centerContinuous | ||||||
distributed |
边框⬆
|
有效边框样式
- thin
- dotted
- dashDot
- hair
- dashDotDot
- slantDashDot
- mediumDashed
- mediumDashDotDot
- mediumDashDot
- medium
- double
- thick
填充⬆
|
填充模式⬆
属性 | 是否需要 | 描述 |
---|---|---|
type | Y | 值: 'pattern' 指定此填充使用模式 |
pattern | Y | 指定模式类型 (查看下面 有效模式类型 ) |
fgColor | N | 指定图案前景色。默认为黑色。 |
bgColor | N | 指定图案背景色。默认为白色。 |
有效模式类型
- none
- solid
- darkGray
- mediumGray
- lightGray
- gray125
- gray0625
- darkHorizontal
- darkVertical
- darkDown
- darkUp
- darkGrid
- darkTrellis
- lightHorizontal
- lightVertical
- lightDown
- lightUp
- lightGrid
- lightTrellis
渐变填充⬆
属性 | 是否需要 | 描述 |
---|---|---|
type | Y | 值: 'gradient' 指定此填充使用渐变 |
gradient | Y | 指定渐变类型。['angle','path'] 之一 |
degree | angle | 对于“角度”渐变,指定渐变的方向。0 是从左到右。值从 1-359 顺时针旋转方向 |
center | path | 对于“路径”渐变。指定路径起点的相对坐标。“左”和“顶”值的范围是 0 到 1 |
stops | Y | 指定渐变颜色序列。是包含位置和颜色(从位置 0 开始到位置 1 结束)的对象的数组。中间位置可用于指定路径上的其他颜色。 |
注意事项
使用上面的接口,可能会创建使用 XLSX 编辑器程序无法实现的渐变填充效果。例如,Excel 仅支持 0、45、90 和 135 的角度梯度。类似地,stops 的顺序也可能受到 UI 的限制,其中位置 [0,1] 或[0,0.5,1] 是唯一的选择。请谨慎处理此填充,以确保目标 XLSX 查看器支持该填充。
富文本⬆
现在,单个单元格支持 RTF 文本或单元格格式化。富文本值可以控制文本值内任意数量的子字符串的字体属性。有关支持哪些字体属性的详细信息,请参见字体。
|
单元格保护⬆
可以使用保护属性来修改单元级别保护。
|
支持的保护属性
属性 | 默认值 | 描述 |
---|---|---|
locked | true |
指定在工作表受保护的情况下是否将单元格锁定。 |
hidden | false |
指定如果工作表受保护,则单元格的公式是否可见。 |
条件格式化⬆
条件格式化允许工作表根据单元格值或任意公式显示特定的样式,图标等。
条件格式设置规则是在工作表级别添加的,通常会覆盖一系列单元格。
可以将多个规则应用于给定的单元格范围,并且每个规则都将应用自己的样式。
如果多个规则影响给定的单元格,则规则优先级值将确定如果竞争样式冲突,则哪个规则胜出。优先级值较低的规则获胜。如果没有为给定规则指定优先级值,ExcelJS 将按升序分配它们。
注意:目前,仅支持条件格式设置规则的子集。具体来说,只有格式规则不需要 <extLst> 元素内的 XML 呈现。这意味着不支持数据集和三个特定的图标集(3Triangles,3Stars,5Boxes)。
|
支持的条件格式设置规则类型
类型 | 描述 |
---|---|
expression | 任何自定义功能均可用于激活规则。 |
cellIs | 使用指定的运算符将单元格值与提供的公式进行比较 |
top10 | 将格式化应用于值在顶部(或底部)范围内的单元格 |
aboveAverage | 将格式化应用于值高于(或低于)平均值的单元格 |
colorScale | 根据其值在范围内的位置将彩色背景应用于单元格 |
iconSet | 根据值将一系列图标之一添加到单元格 |
containsText | 根据单元格是否为特定文本来应用格式 |
timePeriod | 根据单元格日期时间值是否在指定范围内应用格式 |
表达式⬆
属性 | 可选 | 默认值 | 描述 |
---|---|---|---|
type | 'expression' |
||
priority | Y | <auto> | 确定样式的优先顺序 |
formulae | 1 个包含真/假值的公式字符串数组。要引用单元格值,请使用左上角的单元格地址 | ||
style | 公式返回 true 时要应用的样式结构 |
Cell Is⬆
属性 | 可选 | 默认值 | 描述 |
---|---|---|---|
type | 'cellIs' |
||
priority | Y | <auto> | 确定样式的优先顺序 |
operator | 如何将单元格值与公式结果进行比较 | ||
formulae | 1 个公式字符串数组,返回要与每个单元格进行比较的值 | ||
style | 如果比较返回 true ,则应用样式结构 |
Cell Is 运算符
运算 | 描述 |
---|---|
equal | 如果单元格值等于公式值,则应用格式 |
greaterThan | 如果单元格值大于公式值,则应用格式 |
lessThan | 如果单元格值小于公式值,则应用格式 |
between | 如果单元格值在两个公式值之间(包括两个值),则应用格式 |
Top 10⬆
属性 | 可选 | 默认值 | 描述 |
---|---|---|---|
type | 'top10' |
||
priority | Y | <auto> | 确定样式的优先顺序 |
rank | Y | 10 | 指定格式中包含多少个顶部(或底部)值 |
percent | Y | false |
如果为 true,则等级字段为百分比,而不是绝对值 |
bottom | Y | false |
如果为 true,则包含最低值而不是最高值 |
style | 如果比较返回 true,则应用样式结构 |
高于平均值⬆
属性 | 可选 | 默认值 | 描述 |
---|---|---|---|
type | 'aboveAverage' |
||
priority | Y | <auto> | 确定样式的优先顺序 |
aboveAverage | Y | false |
如果为 true,则等级字段为百分比,而不是绝对值 |
style | 如果比较返回 true,则应用样式结构 |
色阶⬆
属性 | 可选 | 默认值 | 描述 |
---|---|---|---|
type | 'colorScale' |
||
priority | Y | <auto> | 确定样式的优先顺序 |
cfvo | 2 到 5 个条件格式化值对象的数组,指定值范围内的航路点 | ||
color | 在给定的航路点使用的相应颜色数组 | ||
style | 如果比较返回 true,则应用样式结构 |
图标集⬆
属性 | 可选 | 默认值 | 描述 |
---|---|---|---|
type | 'iconSet' |
||
priority | Y | <auto> | 确定样式的优先顺序 |
iconSet | Y | 3TrafficLights | 设置使用的图标名称 |
showValue | true | 指定应用范围内的单元格是显示图标和单元格值,还是仅显示图标 | |
reverse | false | 指定是否以保留顺序显示 iconSet 中指定的图标集中的图标。 如果 custom 等于 true ,则必须忽略此值 |
|
custom | false | 指定是否使用自定义图标集 | |
cfvo | 2 到 5 个条件格式化值对象的数组,指定值范围内的航路点 | ||
style | 如果比较返回 true,则应用样式结构 |
数据条⬆
字段 | 可选 | 默认值 | 描述 |
---|---|---|---|
type | 'dataBar' |
||
priority | Y | <auto> | 确定样式的优先顺序 |
minLength | 0 | 指定此条件格式范围内最短数据条的长度 | |
maxLength | 100 | 指定此条件格式范围内最长数据条的长度 | |
showValue | true | 指定条件格式范围内的单元格是否同时显示数据条和数值或数据条 | |
gradient | true | 指定数据条是否具有渐变填充 | |
border | true | 指定数据条是否有边框 | |
negativeBarColorSameAsPositive | true | 指定数据条是否具有与正条颜色不同的负条颜色 | |
negativeBarBorderColorSameAsPositive | true | 指定数据条的负边框颜色是否不同于正边框颜色 | |
axisPosition | ‘auto’ | 指定数据条的轴位置 | |
direction | ‘leftToRight’ | 指定数据条的方向 | |
cfvo | 2 到 5 个条件格式化值对象的数组,指定值范围内的航路点 | ||
style | 如果比较返回 true,则应用样式结构 |
包含文字⬆
属性 | 可选 | 默认值 | 描述 |
---|---|---|---|
type | 'containsText' |
||
priority | Y | <auto> | 确定样式的优先顺序 |
operator | 文本比较类型 | ||
text | 要搜索的文本 | ||
style | 如果比较返回 true,则应用样式结构 |
包含文本运算符
运算符 | 描述 |
---|---|
containsText | 如果单元格值包含在 text 字段中指定的值,则应用格式 |
containsBlanks | 如果单元格值包含空格,则应用格式 |
notContainsBlanks | 如果单元格值不包含空格,则应用格式 |
containsErrors | 如果单元格值包含错误,则应用格式 |
notContainsErrors | 如果单元格值不包含错误,则应用格式 |
时间段⬆
属性 | 可选 | 默认值 | 描述 |
---|---|---|---|
type | 'timePeriod' |
||
priority | Y | <auto> | 确定样式的优先顺序 |
timePeriod | 比较单元格值的时间段 | ||
style | 如果比较返回 true,则应用样式结构 |
时间段
时间段 | 描述 |
---|---|
lastWeek | 如果单元格值落在最后一周内,则应用格式 |
thisWeek | 如果单元格值在本周下降,则应用格式 |
nextWeek | 如果单元格值在下一周下降,则应用格式 |
yesterday | 如果单元格值等于昨天,则应用格式 |
today | 如果单元格值等于今天,则应用格式 |
tomorrow | 如果单元格值等于明天,则应用格式 |
last7Days | 如果单元格值在过去 7 天之内,则应用格式 |
lastMonth | 如果单元格值属于上个月,则应用格式 |
thisMonth | 如果单元格值在本月下降,则应用格式 |
nextMonth | 如果单元格值在下个月下降,则应用格式 |
大纲级别⬆
Excel 支持大纲;行或列可以根据用户希望查看的详细程度展开或折叠。
大纲级别可以在列设置中定义:
|
或直接在行或列上
|
工作表大纲级别可以在工作表上设置
|
注意:调整行或列上的大纲级别或工作表上的大纲级别将产生副作用,即还修改受属性更改影响的所有行或列的折叠属性。 例如。:
|
大纲属性可以在工作表上设置
|
图片⬆
将图像添加到工作表是一个分为两个步骤的过程。首先,通过 addImage()
函数将图像添加到工作簿中,该函数还将返回 imageId
值。然后,使用 imageId
,可以将图像作为平铺背景或覆盖单元格区域添加到工作表中。
注意:从此版本开始,不支持调整或变换图像。
将图片添加到工作簿⬆
Workbook.addImage
函数支持按文件名或按 Buffer
添加图像。请注意,在两种情况下,都必须指定扩展名。有效的扩展名包括 “jpeg”,“png”,“gif”。
|
将图片添加到工作表背景⬆
使用 Workbook.addImage
中的图像 ID
,可以使用 addBackgroundImage
函数设置工作表的背景
|
在一定范围内添加图片⬆
使用 Workbook.addImage
中的图像 ID
,可以将图像嵌入工作表中以覆盖一定范围。从该范围计算出的坐标将覆盖从第一个单元格的左上角到第二个单元格的右下角。
|
使用结构而不是范围字符串,可以部分覆盖单元格。
请注意,为此使用的坐标系基于零,因此 A1 的左上角将为 {col:0,row:0}
。单元格的分数可以通过使用浮点数来指定,例如 A1 的中点是 {col:0.5,row:0.5}
。
|
单元格区域还可以具有属性 "editAs"
,该属性将控制将图像锚定到单元格的方式。它可以具有以下值之一:
值 | 描述 |
---|---|
undefined |
它指定使图像将根据单元格移动和调整其大小 |
oneCell |
这是默认值。图像将与单元格一起移动,但大小不变动 |
absolute |
图像将不会随着单元格移动或调整大小 |
|
将图片添加到单元格⬆
您可以将图像添加到单元格,然后以 96dpi 定义其宽度和高度(以像素为单位)。
|
添加带有超链接的图片⬆
您可以将带有超链接的图像添加到单元格,并在图像范围内定义超链接。
|
工作表保护⬆
可以通过添加密码来保护工作表免受修改。
|
工作表保护也可以删除:
|
有关如何修改单个单元格保护的详细信息请查看 单元格保护。
注意: 当 protect()
函数返回一个 Promise 代表它是异步的,当前的实现在主线程上运行,并且在 CPU 上将使用平均大约 600 毫秒。可以通过设置 spinCount
进行调整,该值可用于使过程更快或更有弹性。
工作表保护选项⬆
属性 | 默认值 | 描述 |
---|---|---|
selectLockedCells | true |
允许用户选择锁定的单元格 |
selectUnlockedCells | true |
允许用户选择未锁定的单元格 |
formatCells | false |
允许用户格式化单元格 |
formatColumns | false |
允许用户格式化列 |
formatRows | false |
允许用户格式化行 |
insertRows | false |
允许用户插入行 |
insertColumns | false |
允许用户插入列 |
insertHyperlinks | false |
允许用户插入超链接 |
deleteRows | false |
允许用户删除行 |
deleteColumns | false |
允许用户删除列 |
sort | false |
允许用户对数据进行排序 |
autoFilter | false |
允许用户过滤表中的数据 |
pivotTables | false |
允许用户使用数据透视表 |
spinCount | 100000 | 保护或取消保护时执行的哈希迭代次数 |
文件 I/O⬆
XLSX⬆
读 XLSX⬆
|
写 XLSX
|
CSV⬆
读 CSV⬆
读取 CSV 文件时支持的选项。
属性 | 是否需要 | 类型 | 描述 |
---|---|---|---|
dateFormats | N | Array | 指定 dayjs 的日期编码格式。 |
map | N | Function | 自定义Array.prototype.map() 回调函数,用于处理数据。 |
sheetName | N | String | 指定工作表名称。 |
parserOptions | N | Object | parseOptions 选项 @fast-csv/format 模块以写入 csv 数据。 |
|
CSV 解析器使用 fast-csv 读取 CSV 文件。传递给上述写入函数的选项中的 formatterOptions
将传递给 @fast-csv/format 模块以写入 csv 数据。 有关详细信息,请参阅 fast-csv README.md。
使用 npm 模块 dayjs 解析日期。如果未提供 dateFormats
数组,则使用以下 dateFormats:
- ‘YYYY-MM-DD[T]HH:mm:ss’
- ‘MM-DD-YYYY’
- ‘YYYY-MM-DD’
请参阅 dayjs CustomParseFormat 插件,以获取有关如何构造 dateFormat
的详细信息。
写 CSV⬆
写入 CSV 文件时支持的选项。
属性 | 是否需要 | 类型 | 描述 |
---|---|---|---|
dateFormat | N | String | 指定 dayjs 的日期编码格式。 |
dateUTC | N | Boolean | 指定 ExcelJS 是否使用dayjs.utc() 转换时区以解析日期。 |
encoding | N | String | 指定文件编码格式。 |
includeEmptyRows | N | Boolean | 指定是否可以写入空行。 |
map | N | Function | 自定义Array.prototype.map() 回调函数,用于处理行值。 |
sheetName | N | String | 指定工作表名称。 |
sheetId | N | Number | 指定工作表 ID。 |
formatterOptions | N | Object | formatterOptions 选项 @fast-csv/format 模块写入 csv 数据。 |
|
CSV 解析器使用 fast-csv 编写 CSV 文件。传递给上述写入函数的选项中的 formatterOptions
将传递给 @fast-csv/format 模块以写入 csv 数据。有关详细信息,请参阅 fast-csv README.md。
日期使用 npm 模块 dayjs 格式化。如果未提供 dateFormat
,则使用 dayjs.ISO_8601
。编写 CSV 时,您可以提供布尔值 dateUTC
为 true
,以使 ExcelJS 解析日期,而无需使用 dayjs.utc()
自动转换时区。
流式 I/O⬆
上面记录的文件 I/O 需要在内存中建立整个工作簿,然后才能写入文件。虽然方便,但是由于所需的内存量,它可能会限制文档的大小。
流写入器(或读取器)在生成工作簿或工作表数据时对其进行处理,然后将其转换为文件形式。通常,这在内存上效率要高得多,因为最终的内存占用量,甚至中间的内存占用量都比文档版本要紧凑得多,尤其是当您考虑到行和单元格对象一旦提交就被销毁时,尤其如此。
流式工作簿和工作表的接口几乎与文档版本相同,但实际存在一些细微差别:
- 将工作表添加到工作簿后,将无法将其删除。
- 提交行后,将无法再访问该行,因为该行将从工作表中删除。
- 不支持
unMergeCells()
。
请注意,可以在不提交任何行的情况下构建整个工作簿。提交工作簿后,所有添加的工作表(包括所有未提交的行)将自动提交。但是,在这种情况下,与文档版本相比收效甚微。
流式 XLSX⬆
流式 XLSX 写入器⬆
流式 XLSX 写入器在 ExcelJS.stream.xlsx
命名空间中可用。
构造函数采用带有以下字段的可选 options
对象:
字段 | 描述 |
---|---|
stream | 指定要写入 XLSX 工作簿的可写流。 |
filename | 如果未指定流,则此字段指定要写入 XLSX 工作簿的文件的路径。 |
useSharedStrings | 指定是否在工作簿中使用共享字符串。默认为 false |
useStyles | 指定是否将样式信息添加到工作簿。样式会增加一些性能开销。默认为 false |
zip | ExcelJS 内部传递给 Archiver 的 Zip 选项。默认值为 undefined |
如果在选项中未指定 stream
或 filename
,则工作簿编写器将创建一个 StreamBuf 对象,该对象将 XLSX 工作簿的内容存储在内存中。可以通过属性 workbook.stream
访问此 StreamBuf 对象,该对象可用于通过 stream.read()
直接访问字节,或将内容通过管道传输到另一个流。
|
通常,流式 XLSX 写入器的接口与上述文档工作簿(和工作表)相同,实际上行,单元格和样式对象是相同的。
但是有一些区别…
构造
如上所示,WorkbookWriter 通常将要求在构造函数中指定输出流或文件。
提交数据
当工作表行准备就绪时,应将其提交,以便可以释放行对象和内容。通常,这将在添加每一行时完成…
|
WorksheetWriter 在添加行时不提交行的原因是允许单元格跨行合并:
|
每个工作表完成后,还必须提交:
|
要完成 XLSX 文档,必须提交工作簿。 如果未提交工作簿中的任何工作表,则将在工作簿提交中自动提交它们。
|
流式 XLSX 阅读器⬆
流式 XLSX 工作簿阅读器可以在 ExcelJS.stream.xlsx 命名空间中找到。
构造函数包含必需的输入参数和可选的 options 参数:
Argument | Description |
---|---|
input (必需的) | 指定从中读取 XLSX 工作簿的文件或可读流的名称 |
options (可选的) | 指定如何处理读取解析期间发生的事件类型 |
options.entries | 指定是否去触发事件('emit' )或者不发出事件('ignore' ),默认值是'emit' |
options.sharedStrings | 指定是否去缓存('cache' )共享字符串,将其插入到相应的单元格值中,或者是否去触发('emit' )或忽略('ignore' )它们,在这两种情况下,单元格值都将是对共享字符串索引的引用。默认值是'cache' |
options.hyperlinks | 指定是否去缓存超链接('cache' ),将其插入到相应的单元格值中,是否去触发('emit' )或忽略('ignore' )它们。默认值是'cache' |
options.styles | 指定是否去缓存样式('cache' ),将其插入到相应的行或单元格值中,或是否忽略('忽略' )它们。默认值是'cache' |
options.worksheets | 指定是否去触发('emit' )或忽略('ignore' )工作表。默认值是'emit' |
|
请注意,由于性能原因,worksheetReader
返回一个行数组,而不是单独返回每一行: https://github.com/nodejs/node/issues/31979
迭代遍历所有事件⬆
工作簿上的事件是 ‘worksheet’、’shared-strings’ 和 ‘hyperlinks’。 工作表上的事件是 ‘row’ 和 ‘hyperlinks’.
|
可读流⬆
我们强烈建议使用异步迭代,但我们也公开了流接口以实现向后兼容性。
|
浏览器⬆
该库的一部分已被隔离,并经过测试可在浏览器环境中使用。
由于工作簿读写器的流式传输性质,因此未包括这些内容。只能使用基于文档的工作簿(有关详细信息,请参见 创建工作簿)。
例如,在浏览器中使用 ExcelJS 的代码可查看 github 中的 spec / browser 文件夹。
预捆绑⬆
以下文件已预先捆绑在一起,并包含在 dist 文件夹中。
- exceljs.js
- exceljs.min.js
值类型⬆
支持以下值类型。
Null 值⬆
Enum: Excel.ValueType.Null
空值表示没有值,通常在写入文件时将不存储(合并的单元格除外)。可用于从单元格中删除该值。例如:
|
合并单元格⬆
Enum: Excel.ValueType.Merge
合并单元格是其值绑定到另一个“主”单元格的单元格。分配给合并单元将导致修改单元格。
数字值⬆
Enum: Excel.ValueType.Number
一个数字值。
例如:
|
字符串值⬆
Enum: Excel.ValueType.String
一个简单的文本字符串。
例如:
|
日期值⬆
Enum: Excel.ValueType.Date
日期值,由 JavaScript Date 类型表示。
例如:
|
超链接值⬆
Enum: Excel.ValueType.Hyperlink
具有文本和链接值的 URL。
例如:
|
公式值⬆
Enum: Excel.ValueType.Formula
一个 Excel 公式,用于即时计算值。请注意,虽然单元格类型将为“公式”,但该单元格可能具有一个有效类型值,该值将从结果值中得出。
请注意,ExcelJS 无法处理公式以生成结果,必须提供该公式。
例如:
|
单元格还支持便捷的获取器,以访问公式和结果:
|
共享公式⬆
共享的公式通过减少工作表 xml 中文本的重复来增强 xlsx 文档的压缩。范围中左上角的单元格是指定的母版,它将保留该范围内的所有其他单元格都将引用的公式。然后,其他“从属”单元格可以引用此主单元格,而不必再次重新定义整个公式。请注意,主公式将以常用的 Excel 方式转换为从属单元格,以便对其他单元格的引用将根据从属单元相对于主单元的偏移量向右下移。例如:如果主单元格 A2 具有引用 A1 的公式,则如果单元格 B2 共享 A2 的公式,则它将引用 B1。
可以将主公式与该范围内的从属单元格一起分配给该单元格
|
可以使用新的值形式将共享公式分配给单元格:
|
这指定单元格 B2 是将从 A2 中的公式派生的公式,其结果为 10。
公式便捷获取器会将 A2 中的公式转换为 B2 中应具有的公式:
|
可以使用 fillFormula
方法将共享的公式分配到工作表中:
|
fillFormula
也可以使用回调函数来计算每个单元格的值
|
公式类型⬆
要区分真正的和转换后的公式单元格,请使用 FormulaType getter:
|
公式类型具有以下值:
名称 | 值 |
---|---|
Enums.FormulaType.None | 0 |
Enums.FormulaType.Master | 1 |
Enums.FormulaType.Shared | 2 |
数组公式⬆
在 Excel 中表示共享公式的一种新方法是数组公式。以这种形式,主单元格是唯一包含与公式有关的任何信息的单元格。它包含 shareType ‘array’ 以及适用于其的单元格范围以及将要复制的公式。其余单元格是具有常规值的常规单元格。
注意:数组公式不会以共享公式的方式转换。因此,如果主单元 A2 引用 A1,则从单元 B2 也将引用 A1。
例如:
|
fillFormula
方法也可以用于填充数组公式
|
富文本值⬆
Enum: Excel.ValueType.RichText
样式丰富的文本。
例如:
|
布尔值⬆
Enum: Excel.ValueType.Boolean
例如:
|
错误值⬆
Enum: Excel.ValueType.Error
例如:
|
当前有效的错误文本值为:
名称 | 值 |
---|---|
Excel.ErrorValue.NotApplicable | #N/A |
Excel.ErrorValue.Ref | #REF! |
Excel.ErrorValue.Name | #NAME? |
Excel.ErrorValue.DivZero | #DIV/0! |
Excel.ErrorValue.Null | #NULL! |
Excel.ErrorValue.Value | #VALUE! |
Excel.ErrorValue.Num | #NUM! |
接口变化⬆
我们会尽一切努力创建一个良好的,一致的接口,该接口不会在版本之间不兼容,但令人遗憾的是,为了实现更大的利益,有时需要进行一些更改。
0.1.0⬆
Worksheet.eachRow⬆
在 Worksheet.eachRow
的回调函数中的参数已被交换和更改;它是 function(rowNumber,rowValues)
,现在是 function(row,rowNumber)
,使它的外观更像 underscore(_.each
)方法,并且行对象优先于行号。
Worksheet.getRow⬆
此函数已从返回稀疏的单元格数组更改为返回 Row
对象。这样可以访问行属性,并有助于管理行样式等。
仍可通过 Worksheet.getRow(rowNumber).values;
获得稀疏的单元格值的数组。
0.1.1⬆
cell.model⬆
cell.styles
重命名为 cell.style
0.2.44⬆
从 Bluebird 切换到 Node 原生 Promise 的函数返回的 Promise 如果依赖 Bluebird 的额外功能,则可能会破坏调用代码。
为了减少这种情况的出现,在 0.3.0 中添加了以下两个更改:
- 默认情况下使用功能更全且仍与浏览器兼容的 promise lib。 该库支持 Bluebird 的许多功能,但占用空间少得多。
- 注入其他 Promise 实现的选项。有关更多详细信息,请参见配置部分。
配置⬆
ExcelJS 现在支持对 Promise 库的依赖项注入。您可以通过在模块中包含以下代码来还原 Bluebird Promise。
|
请注意:我已经使用 bluebird 专门测试了 ExcelJS(直到最近,这是它使用的库)。根据我所做的测试,它不适用于 Q。
注意事项⬆
Dist 文件夹⬆
在发布此模块之前,先对源代码进行编译和其他处理,然后再将它们放置在 dist/ 文件夹中。该自述文件标识两个文件-浏览器捆绑和压缩版本。除了在 package.json 中指定为 "main"
的文件外,不能保证 dist/ 文件夹的其他内容。
已知的问题⬆
使用 Puppeteer 进行测试⬆
该 lib 中包含的测试套件包括一个在无头浏览器中执行的小脚本,以验证捆绑的软件包。 在撰写本文时,其表现出该测试在 Windows Linux 子系统中不能很好地进行。
因此,可以通过存在名为 .disable-test-browser 的文件来禁用浏览器测试。
|
拼接与合并⬆
如果任何 splice
操作影响合并的单元格,则合并组将无法正确移动
- 本文作者: luckyship
- 本文链接: https://luckyship.github.io/2023/07/02/2023-07-02-node-excel/
- 版权声明: 本博客所有文章除特别声明外,均采用 MIT 许可协议。转载请注明出处!