企业官网建设流程全解析

• 前端
• UI组件

jExcel（Jspreadsheet v2）是轻量级 JavaScript 数据表格插件，除了默认文本输入，它还内置了numeric、calendar、checkbox、dropdown、autocomplete等列类型，并允许通过实现openEditor/closeEditor/getValue/setValue四个方法接入任意第三方 jQuery 插件，构建完全自定义的录入控件。本文以 v2 文档 为核心骨架，结合仓库源码与配套示例，系统讲解列类型的配置方法、日历与下拉框的全部可选参数、自定义编辑器的实现协议，以及minDimensions最小表格尺寸的底层行为，读完即可在项目中直接落地使用。

说明：v2 是 jExcel 时代的 jQuery 插件形态（API 形如$('#my').jexcel({...})），其列类型分派、minDimensions补齐、dropdownfilter回调等核心机制，在当前仓库 src/ 源码中仍有清晰实现，本文会在对应小节给出源码级佐证。

一、jExcel v2 的列类型体系

Jspreadsheet 在默认文本输入框之外，内置了一批原生列类型，用来提供替代性的数据录入方式：从高级数字输入、下拉选择，到日历拾取，再到非常容易接入的自定义集成。它让表格插件成为非常灵活的工具，显著提升应用的使用体验。

v2 版本可用的原生列类型包括：text、numeric、hidden、dropdown、autocomplete、checkbox、calendar。通过初始化参数columns数组，可以逐列声明类型：

$('#my').jexcel({ data:data, colHeaders: ['Model', 'Date', 'Price', 'Date'], colWidths: [ 300, 80, 100, 100 ], columns: [ { type: 'text' }, { type: 'numeric' }, { type: 'numeric' }, { type: 'calendar', options: { format:'DD/MM/YYYY' } }, ] });

上面这个示例同时包含了文本列、两个数字列和一个日历列（日期格式为DD/MM/YYYY）。

源码佐证：列类型的分派入口

在 src/utils/editor.js 中可以看到列类型的分派逻辑：当columns[x].type是对象时，走自定义编辑器分支（直接调用type.openEditor(...)）；当它是字符串时，按类型名分别处理：

• hidden：不进入编辑；
• checkbox/radio：直接切换选中状态并写回值；
• dropdown：读取当前值（multiple时按;拆分），创建下拉编辑器，并支持filter函数动态生成选项；
• calendar/color：创建对应输入编辑器。

另外，src/utils/helpers.js 中的parseTableAutoCellType展示了自动推断逻辑：若一列所有值长度均为 10 且形如YYYY-MM-DD，则该列自动设为calendar；若某列去重后的取值较少（约占数据行数的 10% 且大于 1 种），则自动设为dropdown并以其取值集合作为source。这从侧面印证了这些原生类型在表格引擎中的一等公民地位。

二、初始化与数据加载（列类型的载体）

列类型总是作用在表格数据之上，因此先明确 jExcel 的三种数据装载方式（详见 getting-started）：

1. 从 JavaScript 数组加载

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

2. 从外部 JSON 文件加载（url参数指向返回 JSON 数据表的接口）：

<div id='my-spreadsheet'></div> <script> $('#my-spreadsheet').jexcel({ url:'/jspreadsheet/json', colHeaders: ['Model', 'Price', 'Price' ], colWidths: [ 300, 80, 100 ] }); </script>

3. 从外部 CSV 文件加载（csv参数指定 CSV 地址，csvHeaders:true表示把 CSV 首行作为表头）：

<div id='my-spreadsheet'></div> <script> $('#my-spreadsheet').jexcel({ // URL from the CSV file csv:'/jspreadsheet/csv', // Get the first of the CSV file and consider the headers csvHeaders: true, // Default column widths colWidths: [ 300, 80, 100 ] }); </script>

配套示例见 创建基于外部 CSV 的表格，其中还展示了用tableOverflow:true+tableHeight:'300px'控制表格溢出与高度，以及通过$('#my').jexcel('download')一键导出 CSV。

销毁表格：$('#my').jexcel('destroy')会移除表格及其关联的所有数据与事件。

表头与列宽：不声明表头时默认使用 Excel 风格字母；用colHeaders数组自定义列名（CSV 场景则用csvHeaders:true取首行）；用colWidths数组按像素定义各列宽度：

$('#my').jexcel({ data:data, colHeaders: ['Model', 'Price', 'Price', 'Date'], colWidths: [ 300, 80, 100, 100 ], });

三、Calendar 日历列类型详解

当使用calendar列类型时，可以通过options参数改变日历的行为。初始化选项的完整清单如下（完整出处见 calendar 示例文档）：

let defaults = { format:'DD/MM/YYYY', // 日期格式 readonly:0, // 输入框只读（1 为只读） today:0, // 默认值为今天（1 开启） time:0, // 显示时间选择器（1 开启） clear:1, // 显示清空按钮 mask:1, // 输入遮罩 };

各参数含义与取值：

此外，日历还支持本地化配置：months（月份名数组）、weekdays（星期名数组）、weekdays_short（星期缩写数组），可直接在此做多语言翻译：

{ options: { format:'DD/MM/YYYY', readonly:0, today:0, time:0, clear:1, mask:1, 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'] } }

基础日期列示例：

<div id="my"></div> <script> data = [ ['Mazda', 2001, 2000, '2006-01-01'], ['Peugeot', 2010, 5000, '2005-01-01'], ['Honda Fit', 2009, 3000, '2004-01-01'], ['Honda CRV', 2010, 6000, '2003-01-01'], ]; $('#my').jexcel({ data:data, colHeaders: ['Model', 'Date', 'Price', 'Date'], colWidths: [ 300, 80, 100, 100 ], columns: [ { type: 'text' }, { type: 'numeric' }, { type: 'numeric' }, { type: 'calendar', options: { format:'DD/MM/YYYY' } }, ] }); </script>

日期时间选择器（datetime picker）：只需同时传入time:1，并让format带上时间部分：

<div id="my2"></div> <script> $('#my2').jexcel({ data:data, colHeaders: ['Model', 'Year', 'Price', 'Date'], colWidths: [ 300, 80, 100, 120 ], columns: [ { type: 'text' }, { type: 'text' }, { type: 'text' }, { type: 'calendar', options: { format:'DD/MM/YYYY HH24:MI', time:1 } }, ] }); </script>

源码佐证：在 src/utils/editor.js 中，calendar与color类型共用“创建 input 编辑器”的分支，之后由底层日历控件接管交互；src/utils/copyPaste.js 在粘贴时对calendar类型做专门处理，说明日历列的值在复制/粘贴链路中有独立逻辑。

四、Dropdown 与 Autocomplete 列类型

jExcel 的下拉列非常灵活：source可以是一个简单字符串数组，也可以是{id, name}键值对象数组；还可以用url参数从外部 JSON 接口动态填充选项。autocomplete 下拉使用相同的配置项，两者可同时启用autocomplete:true与multiple:true：

let data = [ ['Honda', 1, 'Civic', '4'], ['Peugeot', 3,'1007', '2'], ['Smart', 3,'Cabrio', '4;5'], ]; $('#my').jexcel({ data:data, colHeaders: ['Model','Color', 'Description'], colWidths: [ 300, 80, 100 ], columns: [ { type: 'dropdown', source:['Seat', 'Renault', 'Peugeot'] }, { type: 'dropdown', source:[{'id':1,'name':'Yellow'}, {'id':2,'name':'Black'}, {'id':3,'name':'Green'}] }, { type: 'dropdown', url:'/jspreadsheet/test' }, { type: 'dropdown', url:'/jspreadsheet/countries', autocomplete:true, multiple:true }, ] });

（注意：原文档示例中第四列缺少逗号，上文已修正为合法语法。）

4.1 多选与自动补全（multiple + autocomplete）

multiple:true允许一列存多个值，单元格内以分号;分隔存储；autocomplete:true开启输入即过滤的自动补全。完整示例见 working-with-dropdowns 示例：

<div id="my1"></div> <script> $('#my1').jexcel({ data: [ ['US', 'Cheese', 'Yes', '2019-02-12'], ['CA;US;UK', 'Apples', 'Yes', '2019-03-01'], ['CA;BR', 'Carrots', 'No', '2018-11-10'], ['BR', 'Oranges', 'Yes', '2019-01-12'], ], colHeaders: [ 'Product Origin','Description', 'Stock', 'Best before' ], colWidths: [ 300, 200, 100, 100 ], columns: [ { type: 'dropdown', source: ['BR', 'US', 'UK', 'CA'], autocomplete:true, multiple:true }, { type: 'text' }, { type: 'dropdown', source:['No','Yes'] }, { type: 'calendar' }, ] }); </script>

注意第一行第一列的数据'CA;US;UK'——这正是多选值以分号拼接存储的体现。

4.2 条件下拉（conditional dropdown）

通过filter参数传入一个函数，可以让下拉选项根据其他列的值动态变化。该函数签名为filter(instance, cell, c, r, source)，其中c为当前列号、r为当前行号，可通过$(instance).jexcel('getValue', ...)读取同行其他单元格的值，返回值作为新的选项数组：

<div id="spreadsheet2"></div> <script> let dropdown = function(instance, cell, c, r, source) { // Get a value from the same row but previous column var value = $(instance).jexcel('getValue', c-1 + '-' + r); // Return the values will be part in your current column if (value == 1) { return ['Apples','Bananas','Oranges']; } else if (value == 2) { return ['Carrots']; } else { return source; } } $('#spreadsheet2').jexcel({ data: [ [3, 'Cheese', 0], [1, 'Apples', 1], [2, 'Carrots', 0], [1, 'Oranges', 0], ], colHeaders: ['Category','Product', 'Buy later'], colWidths: [ 300, 200, 100 ], columns: [ { type: 'dropdown', source: [ {'id':'1', 'name':'Fruits'}, {'id':'2', 'name':'Legumes'}, {'id':'3', 'name':'General Food'} ] }, { type: 'dropdown', source: [ 'Apples', 'Bananas', 'Carrots', 'Oranges', 'Cheese' ], filter:dropdown }, { type: 'checkbox' }, ] }); </script>

上面示例中，“Product”列的选项完全取决于上一列“Category”选中的值（1 返回水果、2 返回蔬菜、否则回退到默认source）。

源码佐证：在 src/utils/editor.js 的 dropdown 分支中可以看到完整实现细节——multiple时把单元格值value.split(';')拆成数组；当filter是函数时以filter(obj.element, cell, x, y, obj.options.columns[x].source)动态计算source；autocomplete、multiple、opened等配置被透传给jSuites.dropdown(editor, options)创建编辑器。这说明 v2 文档描述的行为与当前源码一致。

五、自定义列类型（Custom columns）：接入第三方插件

为了让工具足够灵活，jExcel 允许扩展插件、创建自己的录入列。基本做法是实现四个方法：openEditor、closeEditor、getValue、setValue，把它们打包成一个对象，通过列的editor属性注入。

下面以 Spectrum 颜色选择器插件），实现一个“自定义颜色列”：

var spectrumEditor = { // Methods closeEditor : function(cell, save) { // Get value var value = $(cell).find('.editor').spectrum('get').toHexString(); // Set visual value $(cell).html(value); $(cell).css('color', value); // Close edition $(cell).removeClass('edition'); // Save history return value; }, openEditor : function(cell) { // Get current content var html = $(cell).html(); // Create the editor var editor = document.createElement('div'); $(cell).html(editor); $(editor).prop('class', 'editor'); // Create the instance of the plugin $(editor).spectrum({ color:html, preferredFormat:'hex', hide: function(color) { // Close editor $('#' + $.fn.jexcel.current).jexcel('closeEditor', $(cell), true); }}); // Run $(editor).spectrum('show'); }, getValue : function(cell) { return $(cell).html(); }, setValue : function(cell, value) { $(cell).html(value); $(cell).css('color', value); return true; } } let data = [ ['Google', '#542727'], ['Yahoo', '#724f4f'], ['Bing', '#b43131'], ]; $('#my').jexcel({ data:data, colHeaders: [ 'Name', 'Custom color' ], colWidths: [ 300, 200 ], columns: [ { type: 'text' }, { type: 'text', editor:spectrumEditor }, ] });

四个方法的职责与调用时机：

源码佐证：自定义编辑器在引擎中的接入点在 src/utils/editor.js——当columns[x].type是对象而非字符串时，引擎直接调用type.openEditor(cell, ...)，随后触发oncreateeditor事件。换言之，type与editor对象是同一套“编辑器协议”，v2 文档演示的editor:spectrumEditor写法与源码实现完全吻合。可以推断，任何遵循这四个方法的 jQuery 插件（日期、颜色、评分、文件选择器等）都能以同样方式接入。

六、minDimensions：定义最小表格尺寸

minDimensions参数用于定义表格的最小维度[列数, 行数]。即使传入的数据不足，表格也会被补齐到该尺寸。下面的示例创建了一个至少 10 列 × 5 行的表格：

data3 = [ ['Mazda', 2001, 2000], ['Peugeot', 2010, 5000], ['Honda Fit', 2009, 3000], ['Honda CRV', 2010, 6000], ]; $('#minExample').jexcel({ data:data3, minDimensions:[10,5], colHeaders: ['Model', 'Year', 'Price' ], colWidths: [ 300, 80, 100 ] });

源码佐证（底层补齐机制）：

• 在 src/utils/data.js 的setData流程中，min_i = minDimensions[0]、min_j = minDimensions[1]，随后对max_i × max_j的网格做双重循环：行不存在时补空数组data[j] = []，单元格缺失时补空字符串data[j][i] = ''。这就是“最小尺寸”被物理填充到数据层的过程。
• 在 src/utils/columns.js 中，计算列数时若minDimensions[0]大于数据本身的列数，会以minDimensions[0]为准生成列头。
• src/utils/internal.js 与 src/utils/worksheets.js 进一步保证列数不小于minDimensions[0]，并在未配置时默认补[0, 0]。

可见minDimensions不是简单的“视觉占位”，而是真正参与了数据网格的初始化与列数计算，保证表格在数据不足时依然结构完整、可继续编辑。

七、配套 API 速查：方法与事件

v2 还提供了一整套程序化操作 API 与事件回调，常用于配合列类型做动态增删改（完整表格见 quick-reference）。

常用方法（jQuery 调用方式）：

事件回调：

常用初始化参数（columns、colHeaders、colWidths之外）：colAlignments（对齐）、colHeaderClasses（自定义 CSS 类）、defaultColWidth、minSpareRows/minSpareCols（最小备用行列）、minDimensions、contextMenu（自定义右键菜单）、columnSorting/columnResize/rowDrag（排序/调宽/拖行开关）、editable、allowInsertRow/allowInsertColumn/allowDeleteRow/allowDeleteColumn及对应的allowManualInsertRow/allowManualInsertColumn（是否允许用户手动增删）、wordWrap、csvFileName、selectionCopy、tableOverflow/tableHeight/tableWidth、allowComments、toolbar等。

八、延伸阅读与仓库路径

• 列类型主题文档：docs/jspreadsheet/v2/docs.md、docs/jspreadsheet/v2/getting-started.md
• 日历列完整示例：docs/jspreadsheet/v2/examples/using-a-calendar-column-type.md
• 下拉与条件下拉示例：docs/jspreadsheet/v2/examples/working-with-dropdowns.md
• 第三方插件自定义列示例：docs/jspreadsheet/v2/examples/integrating-a-third-party-plugin-into-your-spreadsheet.md
• CSV/JSON 加载示例：docs/jspreadsheet/v2/examples/creating-a-table-from-an-external-csv-file.md
• 方法、事件与参数速查：docs/jspreadsheet/v2/docs/quick-reference.md
• 核心源码：列类型分派与编辑器创建 src/utils/editor.js、最小尺寸补齐 src/utils/data.js、列数计算 src/utils/columns.js、类型自动推断 src/utils/helpers.js

掌握内置列类型与自定义编辑器协议之后，你可以把 jExcel 从“纯数据表格”升级为贴合业务录入场景的表单级组件——无论是日期时间选择、多选下拉、条件联动，还是基于任意 jQuery 插件的专属输入控件，都能在统一的数据网格框架下开箱即用。

• 前端
• UI组件