SheetJS的通用电子表格对象简介和使用

简言

“通用电子表格格式”(CSF)是SheetJS使用的对象模型。
例如使用xlsx插件时,获得的excel文件数据对象就是依据这个模型设计的。
SheetJs通用电子表格对象

SheetJS的通用电子表格对象简介和使用_第1张图片

介绍

cdn导入:

  <script lang="javascript" src="https://cdn.sheetjs.com/xlsx-0.19.2/package/dist/xlsx.full.min.js"></script>

对象模型

首先我们整体的看一下这个通用电子表格对象模型。
SheetJS的通用电子表格对象简介和使用_第2张图片

  • 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')

结语

结束了。

你可能感兴趣的:(工具集,javascript,html,前端)