List.js 版本演进全解析：从 2011 年 Alpha 到 2.3.1 的搜索、排序与分页能力变迁

UI组件前端【免费下载链接】list.jsThe perfect library for adding search, sort, filters and flexibility to tables, lists and various HTML elements. Built to be invisible and work on existing HTML.项目地址https://gitcode.com/gh_mirrors/li/list.js点击查看免费下载List.js 是一款隐形作用于现有 HTML 的轻量级前端库可为表格、列表及各类 DOM 元素注入搜索search、排序sort、过滤filter与分页能力。本文以仓库根目录下的 CHANGELOG.md 为骨架完整梳理该库自 2011 年 Alpha 0.1 至 2.3.12021-01-17的版本演进史并结合src/目录下的核心源码逐一印证每个里程碑背后的实现变化。读完本文你将掌握 List.js 各主要 API 的来龙去脉、2.x 时代的工程化升级内容以及多词搜索、防抖输入、异步添加等关键特性的源码级原理能够据此更精准地选择版本、排查升级兼容性问题。一、CHANGELOG 概览一条完整的迭代时间线CHANGELOG.md 记录了从2011-07-25 Alpha 0.1到2021-01-17 v2.3.1近十年的演进。整理其版本节奏如下版本日期定位Alpha 0.1 / 0.2 / 0.32011-07 ~ 2011-10异步添加/索引、分页雏形固定 200 项0.1.x ~ 0.2.x2011-10 ~ 2012-04clear()、data-sort、模糊搜索插件雏形1.0.02013-11-12核心重构、模块化、事件系统定型1.1.x2014-02-03排序 API 更名、data-order1.2.02016-02-27data 属性支持、toJSON、reIndex、searchColumns1.3.0 ~ 1.5.02016-10 ~ 2017-01tr模板、插件并入核心、Webpack/Jest2.0.02020-11-21Winter cleanup工具链全面现代化、放弃 IE6-82.1.02020-11-21模板函数、自定义分页项、多项 bugfix2.3.02020-11-25多词搜索、搜索防抖、性能提升2.3.12021-01-17恢复 Node 6/8/10/12 支持值得说明的是changelog 中记录的提交均以指向 GitHub 的 commit 链接形式存在本文不再重复这些外部链接而将重点放在每个版本到底改变了什么、对应源码如何实现上。二、Alpha 与 0.x 时代核心能力的播种期2.1 Alpha 阶段异步能力与性能起点Alpha 0.12011-07-25首个可运行的 Alpha 版本官方示例已在 IE7/8/9 下工作IE6 未测。Alpha 0.22011-08-08新增异步 item 添加与异步列表索引。异步添加的实现在今天依然保留于 src/add-async.js每次从数组头部splice(0, 50)取出 50 条调用同步list.add(valuesToAdd)后通过setTimeout(..., 1)递归处理剩余数据避免一次性渲染海量 DOM 导致主线程阻塞。Alpha 0.32011-10-15Only show 200 items at same time, huge speed increase——同一时间只渲染 200 条这是分页机制的性能前身。如今这一单页渲染思想已固化为 src/index.js 中的self.page 100001.2.0 起默认值从 200 调大为 10000。2.2 0.1.x排序机制的确立0.1.x 系列奠定了今天排序 API 的基础形态0.1.12011-10-18支持反向排序reverse sort。0.1.22011-11-16排序按钮通过asc/descCSS 类标识当前状态新增hasClass(element, class)、addClass、removeClass三个辅助函数——它们如今集中在 src/utils/classes.js。0.1.32011-11-29新增list.clear()移除全部 item排序属性由rel改为data-sort排序某一列时清除其他排序按钮上的类sort(valueName, sortFunction)升级为sort(valueName, options)。注意0.1.3 release条目中addClass前的反引号属于原文档笔误不影响语义。0.1.42011-12-15.filters()、.sort()、.search()三者开始互相依赖——列表被过滤后再搜索被过滤隐藏的项保持隐藏.filter()成为重置过滤的唯一方式.filter(false)不再有效。2.3 0.2.x插件体系萌芽0.2.02012-01-23带来plugins paging两大主题。0.2.12012-04-24引入Fuzzy Search 插件并调整.filter()行为。模糊搜索插件后来在 1.5.0 被并入核心即今天的 src/fuzzy-search.js其默认参数location: 0, distance: 100, threshold: 0.4, multiSearch: true仍可在初始化时通过fuzzySearch选项覆盖。三、1.0.0一次几乎完全重写的里程碑2013-11-12 的 1.0.0 是 changelog 中浓墨重彩的一笔核心变化如下模块化与分发渠道改用 Component 管理依赖支持 Component.js、Bower、RequireJS 与 CommonJS 四种加载方式网站拆分为独立仓库list-website。事件系统完善支持在初始化时挂载事件处理器并新增.off(event, handler)移除处理器。今日的事件机制可在 src/index.js 看到handlers以事件名为 key 存放回调数组on/off/trigger三方法构成完整的发布订阅模型。API 语义收敛listObj.get(valueName, value)始终返回数组此前单条命中返回对象、无命中返回null默认排序顺序从desc改为asc指定列搜索语法改为.search(val, [columnName, columnName2])此前是对象形式{ columnName: true }。对应实现见 src/search.js 的prepare.setOptions——第二个参数为数组时即按列搜索。内部结构优化新增item._values便于调试时直接访问 item 数据文档同时提醒交互时应使用item.values()修复templater.set()在templater.get()中被重复调用的问题修复对undefined/null值排序、搜索时的报错修复 issue #51filters/search 与分页组合时的 bug。分页默认样式对齐 Bootstrap分页插件的默认类与结构对齐 Twitter Bootstrap 的 pagination 组件——这一点在 src/pagination.js 的默认模板lia classpage href#/a/li中仍可见。四、1.1.x 与 1.2.0排序定型与属性增强4.1 1.1.x排序 API 与事件绑定修复1.1.02014-02-03排序 API 正式定型为listObj.sort(name, { order: asc })/{ order: desc }取代旧的{ desc: true/false }支持通过new List(id, { sortFunction: function(itemA, itemB) {...} })注入默认排序函数给排序按钮添加data-orderasc/desc可让该按钮只升序或只降序。这些在 src/sort.js 的getOrder中都有直接对应按钮优先读取data-order否则依据现有asc/desc类切换方向。同时修复了搜索/过滤时排序未重置、分页插件下排序与搜索冲突的 bug。1.1.1更新javve/events依赖修复 PC Safari 与 PhantomJS 下的关键事件 bug命令行测试因此恢复点击 HTML5 原生 clear 按钮时清空搜索——对应 src/search.js 中额外绑定的input事件监听。4.2 1.2.0间隔两年后的功能爆发1.2.02016-02-27是 changelog 中篇幅最大的一个版本其中还包含维护者的致歉说明主要新增能力与源码对应如下特性源码佐证支持 data 属性与自定义属性链接、图片等src/templater.js 的createCleanTemplateItem处理valueName.data如{ data: [src, href] }与valueName.attr组合toJSON()方法src/index.js遍历items收集各 item 的values()reIndex()方法src/index.js当 HTML 被非 List.js 代码改动后重新解析列表searchColumns选项src/search.js未显式传列时回退到list.searchColumns或首个 item 的全部字段支持options.item为tr字符串src/templater.jsgetItemSource用tbody包裹tr模板初始化事件处理器new List(id, { searchComplete: fn })src/index.js 的init.handlers自动将同名方法注册为事件回调空列表搜索不抛错src/search.jsif (list.items.length 0) returnitem.visible()可用于尚未模板化的 itemsrc/item.js异步add/index修复、空数组初始化不添加空 itemsrc/add-async.js 与 src/index.js自动排序按钮默认大小写不敏感src/sort.jsdata-insensitivefalse可显式关闭此外该版本还有几处破坏性变更默认分页大小由 200 调整为10000避免新用户困惑list.helpers更名为list.utils排序顺序由 List.js 统一管理而非自定义排序函数决定。工程上则弃用 Component改用Browserify并回移全部 utils 到核心库同时新增测试确保与 require.js 兼容__test__/usage/amd.html至今保留该用例。五、1.3.0 ~ 1.5.0工程基建与插件归核1.3.02016-10-23构建脚本mkdir改为 OS 无关实现支持重置搜索列对应 src/search.js 中customSearch undefined的复位逻辑允许无模板的空列表支持tr字符串模板NaturalSort升级到 0.8.1改用本地 Browserify压缩文件头部附带版本号官网迁移至 GitHub Pages。1.4.02017-01-15将 natural-sort 库替换为支持自定义字母表的实现修复 JavaScript 原生排序对瑞典语ÅÄÖ等 Unicode 字符排序错误的问题。如今该能力体现为 src/sort.js 中sort.alphabet list.alphabet || options.alphabet的设置——自定义字母表可同时来自列表级alphabet选项或单次sort()的options.alphabet。1.4.12017-01-19string-natural-compare从 devDependencies 移入 dependencies生产依赖保证安装后开箱可用——参见 package.json。1.5.02017-01-29fuzzySearch 与 pagination 两个插件正式并入核心库开发者无需再单独引入list.fuzzysearch.js/list.pagination.js构建系统从 Grunt 切换到Webpack测试框架从 Mocha 切换到Jest。分页相关实现集中在 src/pagination.js模糊搜索在 src/fuzzy-search.js。六、2.0.0 Winter cleanup工程现代化的分水岭2020-11-21 发布的 2.0.0 是一次以工具链现代化为主题的清理版changelog 中标注了 也是理解 2.x 兼容性边界的关键版本6.1 浏览器与运行时支持边界[Breaking] 放弃 IE6-81.0.2 时代还专门为 IE8 修过错2.0.0 则彻底告别三巨头改用babel-loaderbabel/preset-env转译以继续支持IE9-11。Node 开发环境升级从 6.15 升至 14.15.1dev 用。6.2 构建链路全面换代Webpack3.12.0 → 5.6.0jest23.3 → 26.6.3、jquery3.3.1 → 3.5.1压缩工具由 uglify-js 换成terser移除 jshint / jshint-loader全项目启用Prettier发布脚本简化、History.md更名为CHANGELOG.md、新增 WISHLIST.md 收纳功能诉求、CircleCI 由 1.0 升级到 2.0。/dist产物新增source-maps。当前构建产物dist/list.min.js及list.min.js.map已被同步到 docs/assets/javascripts 供官网使用。以上依赖版本均可从 package.json 的 devDependencies 与engines字段node ^6.0 || ^8.0 || ^10.0 || ^12.0 || 14得到印证。6.3 分页模块的两处关键重构2.0.0 中分页有两处值得注意的 bugfix均在 src/pagination.js 中有明确实现每个分页组件只挂一个事件监听器通过data-*属性定位页码刷新分页列表时src/pagination.js为每个页码链接写入data-i页内起始索引与data-page每页条数容器上仅绑定一次click委托src/pagination.js点击后调用list.show((i - 1) * page 1, page)跳页。这相比每个按钮各绑一个监听器大幅减少了 DOM 监听数量。page0不再破坏分页refresh开头判断list.page 1时直接隐藏列表容器src/pagination.js避免除零或产生非法页码序列。6.4 官网与文档同步维护2.0.0 同步修复了官网全部示例、将 Jekyll 升级以消除安全告警、全站改用 https并更新了贡献指南。仓库docs/目录下的_examples/如add-get-remove.html、existing-list.html、pagination.html、fuzzy-search.html等与docs/docs/plugins/均是该次维护的产物。七、2.1.0模板函数与自定义分页项2.1.02020-11-21延续功能增强路线[Feature] #634 添加 item 模板函数options.item现在可以是一个函数而非字符串/元素。见 src/templater.js当typeof list.item function时每个新 item 通过list.item(values)生成模板节点这为根据数据动态生成行提供了极大灵活性例如根据状态值输出不同结构。[Feature] #591 支持自定义分页 item分页初始化选项item可覆盖默认的lia classpage href#/a/li模板见 src/pagination.js。Bugfix 系列#667 修复getAttributefallback 方法对应 src/utils/get-attribute.js#636 规避诡异的 IE11 bug#570异步添加不再清空原始值数组——对比 src/add-async.js 与 src/index.js 可知异步入口list.add(values, callback)内部先values.slice(0)拷贝一份再交给addAsync从而保护调用方传入的数组不被splice破坏。#637 复用迭代索引缓存il、倒序循环等减少重复求值。八、2.3.0多词搜索与防抖——搜索体验的质变2.3.02020-11-25带来三项直接面向使用体验的改进也是 2.x 时代最重要的搜索能力升级。8.1 多词搜索#682changelog 中的 Multiple word search 意味着搜索框输入多个关键词时item 必须同时命中所有词才算匹配。查看 src/search.js 的search.list()实现逻辑清晰先用正则/([^])/从搜索串中提取带引号的短语如web developer视为一个整体词剩余部分按空白拆分为若干单词对每个 item 遍历所有搜索词任一单词在指定列中找不到即判定不匹配内层循环if (!word_found) break全部命中才item.found true。这解释了为什么 2.3.0 之前无法可靠地用空格分隔多个条件——旧版把整串当作单一子串匹配。8.2 搜索防抖#683Debounced keyup handler in search 在 src/search.js 中体现搜索框的keyup事件绑定了list.utils.events.debounce(fn, list.searchDelay)。防抖实现位于 src/utils/events.js在wait毫秒内连续触发只执行最后一次从而避免每次击键都触发全列表扫描与 DOM 重建。默认searchDelay为 0src/index.js开发者可通过new List(id, { searchDelay: 200 })自行设置防抖同样应用于模糊搜索输入src/fuzzy-search.js。8.3 更快的搜索#679配合多词搜索search.list()被重写为逐词短路策略一旦某个词在所有列中均未命中立即结束该 item 的判断src/search.js同时每个词的列内命中即break显著减少无谓比较。从源码结构看旧的search.item()与search.values()辅助方法也在本次重构中被移除文件中有明确注释。8.4 文档补充#684本版还为自动化搜索与排序元素补充了更多文档覆盖searchClass、sortClass对应的自动绑定行为。九、2.3.1Node 兼容性收尾2.3.12021-01-17是当前 package.json 中标注的版本version: 2.3.1。该版恢复对Node 6、8、10、12的支持对应 issue #708这也解释了为什么engines字段写的是^6.0 || ^8.0 || ^10.0 || ^12.0 || 14这样一个跨度极大的兼容区间——对需要在这些旧 Node 版本下跑构建/测试的 CI 场景至关重要。十、从 changelog 到源码给升级者的实用清单综合全文如果你正计划把项目从 1.x 升级到 2.x或想充分利用 2.3.x 的新能力以下几点需要重点核对浏览器基线2.0.0 起不再支持 IE6-8IE9-11 依赖 Babel 转译产物生产环境应使用dist/下的构建版本。默认分页大小page默认值为 100001.2.0 起如果需要强制分页展示务必显式调用list.show(i, page)或配置 pagination 插件。排序 API使用sort(valueName, { order: asc | desc, insensitive, alphabet, sortFunction })形式get()始终返回数组。搜索语义2.3.0 起空格分隔为多词 AND 匹配短语可用双引号包裹敏感度与列范围由searchColumns与search()第二参数控制。模板能力options.item既支持字符串、tr字符串、DOM 引用也支持函数2.1.0 起动态生成行时优先考虑函数形式。事件钩子searchStart、searchComplete、sortStart、sortComplete、filterStart、updated等事件可通过初始化选项或.on()注册分页刷新依赖updated事件驱动。上述每一项都能在仓库中找到可验证的源码与测试支撑测试用例集中在test目录如search.test.js、sort.test.js、pagination.test.js、add-get-remove.test.js分别覆盖对应模块。可以说CHANGELOG.md 不只是版本记录更是一部浓缩的 List.js 设计演进史——理解它就是理解这个库的现在与边界。赞分享UI组件前端【免费下载链接】list.jsThe perfect library for adding search, sort, filters and flexibility to tables, lists and various HTML elements. Built to be invisible and work on existing HTML.项目地址https://gitcode.com/gh_mirrors/li/list.js点击查看免费下载相关推荐RePKG解锁Wallpaper Engine壁纸资源的终极钥匙RePKG解锁Wallpaper Engine壁纸资源的终极钥匙 你是否曾经在Wallpaper Engine中看到惊艳的动态壁纸想要提取其中的素材进行二次前端音视频SkyWalking 5.x 版本演进全解析从 5.0.0-alpha 到 5.1.0 的关键能力与架构变迁SkyWalking 5.x 版本演进全解析从 5.0.0 alpha 到 5.1.0 的关键能力与架构变迁 SkyWalking 5.x 是 Apache可观测性后端微服务云原生WasmEdge 版本演进全解析从 0.1.0 到 0.18.0-alpha 的架构、AOT、WASI-NN 与运行时能力变迁WasmEdge 版本演进全解析从 0.1.0 到 0.18.0 alpha 的架构、AOT、WASI NN 与运行时能力变迁 WasmEdge 是一个面向云语言运行时云原生本地部署边缘计算上一篇揭秘whoops性能为什么无依赖库也能实现高效错误处理下一篇终极指南如何用Fluentd搭建Docker和Containerd容器日志驱动方案 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考