SheetJS的通用电子表格对象简介和使用
简言
“通用电子表格格式”（CSF）是SheetJS使用的对象模型。
例如使用xlsx插件时，获得的excel文件数据对象就是依据这个模型设计的。
SheetJs通用电子表格对象
介绍
cdn导入：
<script lang="javascript" src="https://cdn.sheetjs.com/xlsx-0.19.2/package/dist/xlsx.full.min.js"></script>
对象模型
首先我们整体的看一下这个通用电子表格对象模型。
- workbook（工作簿对象）：工作簿对象就是转换读取到的文件对象。里面包含了文件对象的相关属性和存储的工作表数据信息。
- sheets(工作表对象)：工作表是普通的JavaScript对象。每个不以!开头的键是A1样式的地址，其对应值为单元格对象。（A1样式表示的是列是字母顺序、行是数字顺序的二维表格）
- cell(单元格对象)：在工作表中，以A1样式开头的属性为单元格对象，里面用一系列定义好的属性保存相关数据信息。
- 地址和范围： 地址表示单元格对象在工作表中的位置；范围表示工作表中的合并信息。
地址和范围（Addresses and Ranges）
地址
单元地址对象存储为{c:C, r:R}，其中C和R分别是0索引的列号(col)和行号(row),js索引默认从0开始。例如，单元地址B5由对象{c:1, r:4}表示，A1由{c:0,r:0}表示。
范围
单元格范围对象存储为{s:S, e:E}，其中S是范围中的第一个单元格，E是范围中的最后一个单元格。范围包括在内，闭区间。例如，范围A3:B7由对象{s:{c:0, r:2}, e:{c:1, r:6}}表示。
列范围（跨越每行）由起始行0和结束行1048575表示：
{ s: { c: 0, r: 0 }, e: { c: 0, r: 1048575 } } // A:A
{ s: { c: 1, r: 0 }, e: { c: 2, r: 1048575 } } // B:C
行范围（跨越每列）由起始列0和结束列16383表示：
{ s: { c: 0, r: 0 }, e: { c: 16383, r: 0 } } // 1:1
{ s: { c: 0, r: 1 }, e: { c: 16383, r: 2 } } // 2:3
相关接口
XLSX.utils对象提供了一些关于单元格地址和范围的函数：
- encode_row / decode_row在0索引行和1索引行之间转换。
- encode_col / decode_col在0索引列和列名之间转换。
- encode_cell / decode_cell转换单元格地址。
- encode_range / decode_range转换单元格范围。
示例：
// 在0索引行和1索引行之间转换
let row_index = XLSX.utils.decode_row("4");
let row_name = XLSX.utils.encode_row(3);
console.log(row_index, row_name);
// 列转换
let col_index = XLSX.utils.decode_col("D");
let col_name = XLSX.utils.encode_col(3);
console.log(col_index, col_name);
// 单元格地址转换
let b2_addr = XLSX.utils.encode_cell({ c: 1, r: 1 })
let b2_obj = XLSX.utils.decode_cell("B2")
console.log(b2_addr, b2_obj);
// 单元格范围转换
let a1_range = XLSX.utils.encode_range({ s: { c: 0, r: 0 }, e: { c: 3, r: 2 } });
let a1_obj = XLSX.utils.decode_range("A1:E5")
console.log(a1_range, a1_obj);
如果要自定义数据，在处理单元格合并信息时可能会用到。
单元格对象（Cell Object）
单元格对象是普通的js对象，以以下格式定义：
| 属性 | 描述 |
|---|---|
| v | 单元格的值（数字、字符串、日期对象、布尔值） |
| t | 值类型：（b:布尔值、s:字符串、n:数字、d:日期、e:错误、z:存根） |
| 数字相关 | |
| z | 与单元格关联的数字格式字符串 |
| w | 数字格式化文本 |
| 公式相关 | |
| f | 编码为A1样式字符串的单元格公式（如果适用） |
| F | 如果公式是数组公式，则封闭数组的范围（如果适用） |
| D | 如果为true，则数组公式是动态的（如果适用） |
| 其他单元格属性 | |
| l | 单元格超链接和工具提示 |
| c | 单元格注释 |
| r | 富文本编码（如适用） |
| h | 富文本的HTML呈现（如果适用） |
| s | 单元格的样式/主题（如果适用） |
工作表对象（Sheet Objects）
工作表是普通的JavaScript对象。每个不以!开头的键是A1样式的地址，其对应值为单元格对象。
工作表中的数据信息
一般情况下，sheet[address]返回指定地址的单元格对象。
在解析文件时，如果选项有dense: true，将会使用dense-mode模式显示数据，数据格式为sheet[“! data”][R][C] , 其中单元格存储在数组的数组中。表![R][C]返回第R行和第C列的单元格对象(零索引值)。
官网给了一个标准的打印工作表数据代码，我贴在下面：
const { decode_range, encode_cell } = XLSX.utils;
function log_all_cells(ws) {
let range = decode_range(ws["!ref"]);
let dense = ws["!data"] != null; // test if sheet is dense
for (let R = 0; R <= range.e.r; ++R) {
for (let C = 0; C <= range.e.c; ++C) {
let cell = dense ? ws["!data"]?.[R]?.[C] : ws[encode_cell({ r: R, c: C })];
console.log(R, C, cell);
}
}
}
log_all_cells（ws）的参数是工作表对象，获取对象时需要先从工作簿对象中获取工作表名，然后对象属性动态调用获取工作表对象。
工作表中的其他属性
每个键都以!开头。属性可作为sheet[key]访问。
-
sheet[‘!ref’]：基于A-1的范围，表示工作表范围。处理工作表的函数应使用此参数来确定范围。不处理分配在范围之外的单元格。特别是，当用手书写纸张时，不包括范围外的单元格
处理表单的函数应测试是否存在!ref字段。如果!ref被省略或不是有效范围，函数可以自由将工作表视为空或尝试猜测范围。此库附带的标准实用程序将工作表视为空（例如，CSV输出为空字符串）。
当读取设置了sheetRows属性的工作表时，ref参数将使用受限范围。原始范围设置为ws[‘!fullref’] -
sheet[‘!margins’]：表示页边距的对象。默认值遵循Excel的“常规”预设。Excel也有“宽”和“窄”预设，但它们存储为原始测量值。
-
ws[‘!cols’]：列属性对象的数组。列宽实际上以规范化的方式存储在文件中，根据“最大数字宽度”（渲染数字的最大宽度0-9，以像素为单位）进行测量。解析时，列对象在wpx字段中存储像素宽度，在wch字段中存储字符宽度，在MDW字段中存储最大数字宽度。
-
ws[‘!rows’]：行属性对象的数组，如文档稍后所述。每个行对象编码属性，包括行高和可见性。
-
ws[‘!merges’]：与工作表中的合并单元格相对应的范围对象数组。纯文本格式不支持合并单元格。CSV导出将写入合并区域中的所有单元格（如果存在），因此请确保仅设置该区域中的第一个单元格（左上角）。
-
ws[‘!outline’]：配置轮廓的行为方式。选项默认为Excel 2019中的默认设置。
-
ws[‘!protect’]：写入工作表保护属性的对象。password键指定支持密码保护工作表（XLSX/XLSB/XLS）的格式的密码。
-
ws[‘!autofilter’]：模式后的自动筛选对象。
-
ws[‘!type’]:表示工作表类型，“chart”为图表工作表，“macro”为宏工作表，“dialog”对话框工作表。
相关接口
在XLSX.utils对象下面：
- aoa_to_sheet将JS数据数组转换为工作表。
- json_to_sheet将JS对象数组转换为工作表。
- table_to_sheet将DOM表元素转换为工作表。
- sheet_add_aoa将JS数据数组添加到现有工作表中。
- sheet_add_json将JS对象数组添加到现有工作表中。
- sheet_add_dom将DOM表元素中的数据添加到现有工作表中
- sheet_to_json将工作表对象转换为JSON对象数组。
- sheet_to_csv生成分隔符分隔的值输出。
- sheet_to_txt生成UTF16格式的文本。
- sheet_to_html生成HTML输出。
- sheet_to_formulae生成公式列表（具有值回退）。
工作表的方法比较多，那是因为工作表是文件的主体。如果想自定义工作表或处理工作表信息请到官网浏览详情。
工作簿对象（Workbook Object）
工作簿是对excel文件的对象描述。其中一些属性描述如下：
- workbook.SheetNames ： 工作簿中工作表的有序列表，存储了工作表名。
- wb.Sheets[sheetname] ： 返回工作表对象。
- wb.Props：是存储标准特性的对象。
- wb.Custprops：存储自定义特性。
- wb.Workbook： 存储工作簿级属性。
相关接口
- book_new创建空工作簿
- book_append_sheet将工作表添加到工作簿
除此之外，解析文件函数中，读取文件函数返回的是工作簿对象，导出文件函数的第一个参数是工作簿对象。例如：
XLSX.read(data, read_opts)尝试解析data，返回workbook、
XLSX.writeXLSX(wb, write_opts)尝试以XLSX格式编写工作簿。
示例：
// 创建工作簿
const wb = new XLSX.utils.book_new()
// json数据转成工作表对象
let ws = XLSX.utils.json_to_sheet([
{ A: "S1", B: "h1", C: "e1", D: "e1", E: "t1", F: "J1", G: "S1" },
{ A: "S2", B: "h2", C: "e2", D: "e2", E: "t2", F: "J2", G: "S2" }
], { header: ["A", "B", "C", "D", "E", "F", "G"], skipHeader: true });
// 更新对应地址的值，不存在添加，存在替换
XLSX.utils.sheet_add_json(ws, [
{ A: 1, B: 2 }, { A: 2, B: 3 }, { A: 3, B: 4 }
], { skipHeader: true, origin: "A2" });
// 将工作表对象追加到工作簿中
XLSX.utils.book_append_sheet(wb, ws, '数据表1')
XLSX.utils.book_append_sheet(wb, ws, '数据表2')
console.log(wb);
// 导出
XLSX.writeFile(wb, '新的excel.xlsx')
结语
结束了。