企业官网建设流程全解析

• 前端
• UI组件

Jspreadsheet 是一个轻量级的原生 JavaScript（vanilla JS）插件，用于在 Web 应用中嵌入在线电子表格（spreadsheet）式的数据网格。本指南以 Jspreadsheet v3 官方入门文档为主线，完整覆盖安装、四种数据源初始化、表头定制、列宽行高控制、原生列类型以及自定义编辑器扩展等核心能力，并结合当前开源仓库的源码实现，帮助你快速掌握创建交互式数据表格的完整流程。读完本文，你将能够在自己的页面中独立初始化一个带类型约束、可交互的数据网格，并通过 JavaScript API 程序化地控制它的表头、尺寸与数据。

上图是一个典型的 Jspreadsheet 数据网格：包含行号列、下拉选择（Make 列）、日期（Available 列）、复选框（Stock 列）、货币数值（Price 列）以及自定义色块（G 列）等多种单元格类型，展示了该组件兼容 Excel 风格的典型表格场景。

安装与引入

Jspreadsheet 以 npm 包形式发布，在项目目录执行以下命令即可安装：

npm install jspreadsheet-ce

安装后需要在页面中引入组件的 JavaScript 与样式文件。由于 Jspreadsheet 与 jSuites 深度集成（列类型、下拉、日历等能力均由 jSuites 提供），使用时需要同时引入 jSuites 的脚本与样式，参考 导入数据示例 中的完整页面结构：

<script src="jexcel.js"></script> <link rel="stylesheet" href="jexcel.css" type="text/css" /> <script src="jsuites.js"></script> <link rel="stylesheet" href="jsuites.css" type="text/css" />

也可以直接从开源仓库下载源码包进行本地引用。仓库根目录下的 package.json 表明，当前开源仓库对应较新的版本线（version: 5.0.4），其全局入口为jspreadsheet()；而本指南所依据的 v3 文档使用jexcel()作为全局函数名。两者 API 形态相近，下文示例按 v3 语法展示，在使用时请与你的实际版本对应。

初始化

Jspreadsheet 的初始化方式非常灵活：你可以从一个 HTML 表格、一个 JavaScript 二维数组、一个 CSV 文件或一个 JSON 文件创建表格。所有示例都基于同一个固定容器元素，例如<div id='my-spreadsheet'></div>。

从 JavaScript 数组加载

最直接的用法是把二维数组通过data选项传入，并配合columns定义每一列的标题与宽度：

<div id='my-spreadsheet'></div> <script> data = [ ['Mazda', 2001, 2000], ['Peugeot', 2010, 5000], ['Honda Fit', 2009, 3000], ['Honda CRV', 2010, 6000], ]; jexcel(document.getElementById('my-spreadsheet'), { data:data, columns:[ { title:'Model', width:300 }, { title:'Price', width:80 }, { title:'Model', width:100 } ] }); </script>

从源码结构看，初始化时 factory.js 会创建spreadsheet对象并构建工作表；而 data.js 中的setData负责数据预处理：如果数据首行不是数组（即传入 JSON 对象数组），会依据columns中每个列的name字段将对象属性映射为数组单元格，从而支持“按字段名取列”。

从 JSON 文件加载

通过url选项指向一个远程 JSON 文件，组件会自动拉取并解析数据：

<div id='my-spreadsheet'></div> <script> jexcel(document.getElementById('my-spreadsheet'), { url:'data.json', columns:[ { title:'Model', width:300 }, { title:'Price', width:80 }, { title:'Model', width:100 } ] }); </script>

如果 JSON 内容是对象数组（而非二维数组），还可以利用name指令显式指定每个列对应数据对象的哪个字段，gender列配合type:'hidden'即可实现隐藏列：

jexcel(document.getElementById('spreadsheet3'), { data:[ { name:'Paulo', id:'3', age:'40', gender:'Male' }, { name:'Cosme Sergio', id:'4', age:'48', gender:'Male' }, ], columns: [ { type:'text', width:'300', name:'id' }, { type:'text', width:'200', name:'name' }, { type:'text', width:'100', name:'age' }, { type:'hidden', name:'gender' }, ] });

对应地，data.js 会读取obj.options.columns[i].name完成对象数据到数组行数据的转换。

从 CSV 文件加载

通过csv选项加载外部 CSV 文件，csvHeaders:true表示将文件首行作为列名（此时columns中无需再写title，只定义宽度即可）：

<div id='my-spreadsheet'></div> <script> jexcel(document.getElementById('my-spreadsheet'), { csv:'/tests/demo.csv', csvHeaders:true, columns:[ { width:300 }, { width:80 }, { width:100 } ] }); </script>

可参考 导入数据示例 查看 CSV 加载配合tableOverflow、下拉列以及download()导出 CSV 的完整页面。

从 HTML 表格加载

除了上述三种数据源，Jspreadsheet 还支持直接传入一个已有的<table>元素完成初始化。从 factory.js 的实现可以看到：当传入元素是TABLE标签时，会调用createFromTable读取原表格的表头与数据，生成一个临时div替换原表格后再构建工作表，原表格的数据与结构被完整迁移到网格中。

销毁表格

通过jexcel.destroy()可以销毁已有表格及其相关数据与事件：

<script> let table = jexcel(document.getElementById('my-spreadsheet'), { csv:'/tests/demo.csv', csvHeaders:true, columns:[ { width:300 }, { width:80 }, { width:100 } ] }); // 如果第二个参数为 true，将销毁所有事件处理器，且无法再创建其他实例 jexcel.destroy(document.getElementById('my-spreadsheet'), true); </script>

在 src/index.js 中，destroy(element, destroyEventHandlers)会从全局实例列表中移除该表格、清空容器内容，并在destroyEventHandlers为真时调用destroyEvents清理绑定在根节点上的全部事件。

表头标题

默认情况下，如果不为列定义title，表头会像 Excel 一样以 A、B、C…… 依次命名。如需自定义列名，使用title指令即可：

<script> jexcel(document.getElementById('spreadsheet'), { data:data, columns:[ { title:'Model' }, { title:'Price' }, { title:'Model' } ] }); </script>

从 columns.js 的createCellHeader实现可以看到，表头文本的取值优先级是：columns[col].title优先，缺失时回退到getColumnName(col)（即 A、B、C 序列），这与文档描述一致。

从 CSV 文件读取表头

加载 CSV 时设置csvHeaders:true，文件的第一行将被用作列名，无需再逐列声明title。完整示例见 导入数据示例。

程序化更新表头

setHeader()、getHeader()与getHeaders()三个方法用于通过 JavaScript 程序化读写表头：

• getHeader(column)：获取指定列（从 0 开始计数）的标题；
• getHeaders(asArray)：返回所有标题；asArray为true时返回数组，否则返回以csvDelimiter拼接的字符串；
• setHeader(column, newValue)：设置指定列的新标题。

在 headers.js 中，setHeader不仅更新 DOM 中的textContent与title属性，还会同步回写options.columns[column].title，将其纳入历史记录（可撤销），并派发onchangeheader事件，方便外部监听标题变更。实操示例见 表头示例。

嵌套表头

通过nestedHeaders:[]指令可以在初始化时创建多级表头，实现分组列的效果。每个嵌套表头对象用title定义分组名称、用colspan定义横跨的列数：

<script> jexcel(document.getElementById('spreadsheet'), { data:data, columns: [ { type: 'autocomplete', title:'Country', width:'300', url:'/jexcel/countries' }, { type: 'dropdown', title:'Food', width:'150', source:['Apples','Bananas','Carrots','Oranges','Cheese'] }, { type: 'checkbox', title:'Stock', width:'100' }, ], nestedHeaders:[ [ { title:'Supermarket information', colspan:'3' }, ], [ { title:'Location', colspan:'1' }, { title:' Other Information', colspan:'2' } ], ], }); </script>

上面的例子建立了两层嵌套表头：第一层将三列统一归入“Supermarket information”，第二层再细分“Location”（1 列）与“Other Information”（2 列）。在线效果可参考 表头示例。

列宽

列的初始宽度通过columns中的width属性定义：

<script> jexcel(document.getElementById('spreadsheet'), { data:data, columns:[ { title:'Model', width:300 }, { title:'Price', width:80 }, { title:'Model', width:100 } ] }); </script>

源码层面，columns.js 中createCellHeader计算列宽的逻辑是：columns[col].width优先，缺失时回退到defaultColWidth（默认 100）；同时列的对齐方式默认center，可通过columns[col].align或defaultColAlign调整。

程序化更新列宽

setWidth(column, width)与getWidth(column)用于通过 JavaScript 动态读写列宽，适合在数据变化或响应式布局时调整表格。与表头一样，setWidth也会同步options.columns并派发onresizecolumn事件。实操示例见 程序化更新示例 中的setWidth部分。

行高

行的初始高度通过rows指令按行号指定，同时可以用rowResize: true开启用户手动拖拽调整行高的能力：

<script> jexcel(document.getElementById('spreadsheet'), { data:data, rows:{ 3: { height:'500px' }}, rowResize: true, }); </script>

在 rows.js 的createRow中可以看到行高的处理细节：若配置了全局defaultRowHeight，所有行先应用该默认高度；随后检查options.rows[j].height，命中则覆盖为该行的专属高度。因此rows指令适合对个别行做特殊高度处理。

程序化更新行高

setHeight(row, height)与getHeight(row)用于程序化读写行高。setHeight会把新高度写回options.rows[row].height、记录历史并派发onresizerow事件；getHeight不传参数时返回所有已设置高度的行。示例见 程序化更新示例 中的setHeight部分。

列类型

除了默认的文本输入，Jspreadsheet 还内置了一批原生列类型，为数据录入提供更丰富的交互方式。由于组件与 jSuites 深度集成（见 package.json 中声明的jsuites依赖），原生支持的类型包括：text、numeric、hidden、dropdown、autocomplete、checkbox、radio、calendar、image 和 color。此外还提供集成接口，允许把任何第三方 JavaScript 插件扩展为自定义列。

<script> jexcel(document.getElementById('spreadsheet'), { data:data, columns: [ { title:'Model', width:300, type:'text' }, { title:'Price', width:80, type:'numeric' }, { title:'Date', width:100, type:'calendar', options: { format:'DD/MM/YYYY' } }, { title:'Photo', width:150, type:'image' }, { title:'Condition', width:150, type:'dropdown', source:['New','Used'] }, { title:'Color', width:80, type:'color' }, { title:'Available', width:80, type:'checkbox' }, ] }); </script>

上面这份配置同时展示了多种类型：纯文本、数值、日期日历、图片上传、下拉、颜色选择与布尔复选框，能覆盖大多数业务表单场景。

Calendar（日历）类型

日历列通过options传递额外配置来改变行为，可用选项如下：

{ options: { // 日期格式 format:'DD/MM/YYYY', // 允许键盘输入日期 readonly:0, // 默认选中今天 today:0, // 显示时间选择器 time:0, // 显示重置按钮 resetButton:true, // 占位符 placeholder:'', // 在此处进行翻译 months:['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'], weekdays:['Sunday','Monday','Tuesday','Wednesday','Thursday', 'Friday','Saturday'], weekdays_short:['S', 'M', 'T', 'W', 'T', 'F', 'S'], // 值 value:null, // 事件 onclose:null, onchange:null, // 全屏（屏幕宽度小于 800 时自动开启） fullscreen:false, } }

format控制日期的显示格式，months/weekdays/weekdays_short用于本地化日历文案，time开启时间选择，fullscreen则保证小屏幕下的可用性。在线效果可参考 日期与日期时间选择器示例。

Dropdown 与 Autocomplete 类型

下拉与自动完成列提供了多种数据来源与交互模式：

• source：可以是简单字符串数组，也可以是{id, name}形式的键值对象数组；
• url：从外部 JSON 接口动态填充下拉选项；
• autocomplete:true：开启输入联想过滤；
• multiple:true：开启多选（多选时数据以分号分隔存储，如'4;5'）；
• 条件联动：一个下拉的值可以影响表格中其他下拉的可选范围。

<script> let data = [ ['Honda', 1, 'Civic', '4'], ['Peugeot', 3,'1007', '2'], ['Smart', 3,'Cabrio', '4;5'], ]; jexcel(document.getElementById('spreadsheet'), { data:data, columns: [ { type:'dropdown', title:'Region', source:['South East','South West','North','London'], width:'200', }, { type:'dropdown', title:'Available in', multiple:true, source:[{id:1, name:'Red'},{id:2, name:'Yellow'},{id:3,name:'Blue'}], width:'200', }, { type:'autocomplete', title:'Region', url:'values.json', width:'200', }, ] }); </script>

上述示例中，Region列为普通单选下拉，Available in列为多选下拉（选项来自键值对象数组），第三列则通过url从远程 JSON 获取选项并支持输入联想。完整示例见 下拉与自动完成示例。

自定义类型

Jspreadsheet 允许把第三方 JavaScript 插件封装为自定义列类型。核心是实现四个约定方法：

• openEditor(cell)：进入编辑态时调用，负责在单元格内创建并聚焦编辑控件；
• closeEditor(cell, save)：退出编辑态时调用，负责读取编辑器值、写回单元格并返回该值；
• getValue(cell)：读取单元格当前显示值；
• setValue(cell, value)：把值写入单元格。

下面的例子将 jQuery 的 clockpicker 时间选择器封装为一个自定义编辑器：

<script> let data2 = [ ['PHP', '14:00'], ['Javascript', '16:30'], ]; var customColumn = { // Methods closeEditor : function(cell, save) { var value = cell.children[0].value; cell.innerHTML = value; return value; }, openEditor : function(cell) { // Create input var element = document.createElement('input'); element.value = cell.innerHTML; // Update cell cell.classList.add('editor'); cell.innerHTML = ''; cell.appendChild(element); $(element).clockpicker({ afterHide:function() { setTimeout(function() { // To avoid double call if (cell.children[0]) { spreadsheet.closeEditor(cell, true); } }); } }); // Focus on the element element.focus(); }, getValue : function(cell) { return cell.innerHTML; }, setValue : function(cell, value) { cell.innerHTML = value; } } spreadsheet = jexcel(document.getElementById('custom'), { data:data2, columns: [ { type: 'text', title:'Course Title', width:300 }, { type: 'text', title:'Time', width:100, editor:customColumn }, ] }); </script>

在列定义中通过editor: customColumn把自定义对象挂到某列上，该列在编辑时便会调用openEditor渲染时钟选择器。这种“实现四个方法即可接入任意编辑器”的契约，让 Jspreadsheet 在对接日期、颜色、富文本等第三方控件时非常灵活。相关示例见 列类型示例。

定义最小表格尺寸

minDimensions指令用于保证表格至少具备指定的行列数，即使传入数据不足以填满：

<script> let data3 = [ ['Mazda', 2001, 2000], ['Peugeot', 2010, 5000], ['Honda Fit', 2009, 3000], ['Honda CRV', 2010, 6000], ]; jexcel(document.getElementById('minExample'), { data:data3, minDimensions:[10,5], }); </script>

上面minDimensions:[10,5]表示表格最少包含 10 列、5 行。从源码看，这一约束有两处生效：其一，data.js 中的setData会用minDimensions与现有数据行列数取较大值，把缺失的单元格补成空字符串，从而保证网格尺寸达标；其二，columns.js 的getNumberOfColumns在数据列数小于minDimensions[0]时也会以最小列数为准创建列头。因此该指令同时作用于表头渲染与数据填充两个环节。

继续深入

本指南覆盖了 Jspreadsheet 入门所需的基础能力。若要进一步掌握表格的完整能力，可继续阅读同一文档体系下的其他章节：

• 程序化修改文档：通过 JavaScript 全面操控表格数据与结构；
• 事件处理文档：了解onchange、onchangeheader、onresizecolumn等事件的使用；
• 快速参考：全部方法、配置项、事件与语言的速查表；
• 源码层面，可在 src/utils/headers.js、src/utils/columns.js、src/utils/rows.js、src/utils/data.js 中深入阅读表头、列宽、行高与数据装载的底层实现。

• 前端
• UI组件