Dolibarr 内置 Select2 4.x 全版本变更解读：从 4.0.0 重构到 4.0.13 的选项、事件与无障碍演进-育师

企业应用
后端

【免费下载链接】dolibarr

Dolibarr ERP CRM is a modern software package to manage your company or foundation's activity (contacts, suppliers, invoices, orders, stocks, agenda, accounting, ...). it's an open source Web application (written in PHP) designed for businesses of any sizes, foundations and freelancers.

项目地址：https://gitcode.com/gh_mirrors/do/dolibarr

点击查看免费下载

Dolibarr ERP/CRM 的 Web 界面大量依赖 jQuery 生态组件来增强表单交互，其中 Select2 是替换原生<select>下拉框的核心插件，为联系人、用户、产品等选择器提供了搜索、远程数据分页、标签与多选能力。本文以仓库内 CHANGELOG.md 为骨架，完整梳理 Select2 从 4.0.0 跨代重构到 4.0.13 的每一次功能演进、选项/事件/方法重命名与无障碍改进，并结合 Dolibarr 源码说明其实际集成方式，帮助开发者理解当前仓库内置的 4.0.13 版本从何而来、升级时需要注意哪些破坏性变更。

一、关联文档与仓库定位

仓库以第三方组件目录方式内置了 Select2 的完整发布物，位于 htdocs/includes/jquery/plugins/select2，共包含 8 个文件：

CHANGELOG.md：本文主体，记录 4.0.0 至 4.0.13 的全部版本变更；
README.md：项目用途、浏览器兼容性、使用方式与第三方集成列表；
package.json：确认内置版本为4.0.13，main指向dist/js/select2.js，style指向dist/css/select2.css，许可证为 MIT；
composer.json：以 component 类型声明脚本、样式与 i18n 文件清单（dist/js/i18n/*.js）；
Gruntfile.js、bower.json、component.json、LICENSE.md：构建与包管理元数据。

该目录是"发布快照"形态（不含src/dist源码树），说明 Dolibarr 直接引入预构建产物，并在此基础上通过自有 JS 全局脚本扩展翻译与行为（详见后文"仓库中的实际集成"）。

二、4.0.0：跨代重构与破坏性变更

4.0.0 是 Select2 的第三代重写，CHANGELOG 明确要求升级前完整审阅此前所有发布说明（尤其是 rc.1、rc.2）。

支持环境

jQuery 1.7.2+；
现代浏览器（Chrome、Firefox、Safari）；
Internet Explorer 8+。

新特性

完全兼容 AMD 与 UMD 模块加载器，并可配合jQuery.noConflict使用；
基于自定义适配器（adapters）的插件系统，选择、搜索、下拉等行为均可替换与装饰；
<select>成为推荐承载元素，可用于所有选项（含远程数据场景），旧式<input type="hidden" />方案仅在完整构建中保留有限向后兼容；
支持通过data-*属性进行声明式配置；
可配置的主题系统与全新默认主题；
支持更细粒度语言区域（如en-US），Select2 可据此自动确定应加载的翻译文件。

破坏性变更清单

许可证改为 MIT；
完整构建（full build）不再内置 jQuery，页面必须自行引入 jQuery；
Select2 打开时会阻止模态框等可滚动容器的内部滚动，防止 UI 错乱；
bower.json/component.json不再将 jQuery 列为依赖；
<select>取代<input type="hidden" />，覆盖全部选项（包括远程数据）；
matcher匹配器重构为携带完整上下文，并新增兼容模块select2/compat/matcher；
显示顺序始终反映数据发送给服务端的真实顺序；
点击遮罩（click mask）不再默认启用，如需旧行为可给selectionAdapter包上ClickMask装饰器；
Select2 不再阻止下拉与选中区域内部事件冒泡，完整构建提供StopPropagation模块；
回车键（Enter）不再切换多选结果项的选中状态，而只执行选中；切换状态改用 Ctrl + Space；
检测到不支持的配置时，开发者控制台会输出警告。

选项重命名对照表

旧名称	新名称
`formatSelection`	`templateSelection`
`formatResult`	`templateResult`
`sortResults`	`sorter`
`createSearchChoice`	`createTag`
`selectOnBlur`	`selectOnClose`
`ajax.jsonpCallback`	`ajax.jsonp`
`ajax.results`	`ajax.processResults`
`tags: [array]`	`data: [array], tags: true`
`placeholderOption`	`placeholder.id`（`placeholder`->`placeholder.text`）

此外，width选项默认值由style改为resolve，copy取值更名为style。

国际化（i18n）键重命名

formatNoMatches->language.noMatches、formatSearching->language.searching、formatInputTooShort->language.inputTooShort、formatInputTooLong->language.inputTooLong、formatAjaxError->language.errorLoading、formatLoading->language.loadingMore、formatSelectionTooBig->language.maximumSelected。

废弃/移除的选项

initSelection：基于<select>后不再需要，完整构建中保留有限兼容；
id：数据对象应始终提供字符串类型的id与text，迁移时可借助$.map；
query：改用自定义数据适配器，完整构建保留有限兼容；
ajax.params：传给ajax的所有参数都会传给 AJAX 数据传输函数。

方法重命名与移除

重命名：.select2("val", value)->.val(value)；.select2("enable", !disabled)->.prop("disabled", disabled)；
移除：.select2("onSortStart"/"onSortEnd")（应自定义选择适配器）、.select2("data", data)（应先创建<option>再设.val）、.select2("readonly")（<select>本身无法只读，请用disabled）。

事件重命名

新增：select2:closing（下拉关闭前触发）、select2:select（选项被选中时触发）；
重命名：select2-close->select2:close、select2-open->select2:open、select2-opening->select2:opening、select2-selecting->select2:selecting、select2-removed->select2:unselect、select2-removing->select2:unselecting；
移除：select2-clearing（改用select2:unselecting）、select2-highlight、select2-loaded、select2-focus（用原生focus）、select2-blur（用原生blur）；change事件上附加的所有额外属性被移除——val改用$element.val()获取，added监听select2:select，removed监听select2:unselect。

三、4.0.1 至 4.0.5：稳定化与国际化扩张

4.0.1（首个 4.0.0 修正版）

模板回调增强：templateResult与templateSelection现在将选项容器作为第二个参数传入；
多选框中 Tab 进入即可立即开始输入搜索；
传给 AJAX 请求的所有参数默认都作为查询字符串参数发送；
修复：删除选中项后搜索框尺寸、屏幕阅读器朗读下拉结果、多实例同时初始化的选项克隆、selectOnClose与closeOnSelect并用时的栈溢出、非静态父元素定位、IE 多选占位符、AJAX 下拉以数组数据初始化、:all:在containerCss/dropdownCss中的处理、RTL 模式多选搜索框位置、ALT+UP 改为关闭下拉、多选搜索框在change触发时的焦点、ArrayAdapter误用既有<option>数据、AttachBody装饰器的随机宽度调用与内存泄漏、禁用状态下不可删除选中项、冗余的open事件、ajax.data/ajax.url回调中的this引用、select2('option')作用于所有元素；
设计：原生<select>隐藏逻辑、IE 下 Bootstrap 渐变兼容、Zurb Foundation 兼容、移动 Safari 多选搜索框内边距、清除按钮与长文本重叠、加载更多消息 CSS 迁移到 BEM、Safari 内联搜索显示；
翻译：新增塞尔维亚语（西里尔）、日语、马来语、印尼语（含errorLoading）、丹麦语（含errorLoading）、阿拉伯语；修正泰语、加利西亚语（inputTooLong/inputTooShort互换）、荷兰语、波兰语、希伯来语。

4.0.2

新特性：新增insertTag选项以控制tags标签插入位置；新增 AJAX 错误处理；
修复：静态下拉父元素定位、数组数据时既有选中项不被尊重、自动生成 ID 进行消毒以便作为 CSS 标识符、递归应用默认值使 AJAX 默认值可设置、避免两次计算下拉顶部位置；
翻译：修正罗马尼亚语。

4.0.3

新特性/改进：dropdownAutoWidth选项恢复可用；处理原生<select>上的focus事件；增删选项时自动刷新选中项；
修复：select2('option')操作多元素时不再修改参数、更可靠地检测被中止的请求、tokenization 期间正确创建新选项、非静态父元素下拉定位、无限滚动不再重置键盘焦点、selectOnClose与closeOnSelect协同、ajax.delay同样作用于空搜索词；
翻译：新增高棉语、希腊语，补充挪威语、法语、立陶宛语（复数规则）的errorLoading。

4.0.4

新特性：标签匹配改为大小写不敏感；支持选中值为空或为0的选项；
修复：Tab 移出 Select2 控件时整张表单不再失焦；CommonJS 下的 UMD 支持；
翻译：新增斯洛文尼亚语，为匈牙利语、德语、加利西亚语、泰语、芬兰语、土耳其语、亚美尼亚语补齐errorLoading/searching。

4.0.5

修复：autocapitalize=off替换为autocapitalize=none；
翻译：新增普什图语（ps）、上索布语（hsb）、下索布语（dsb）、南非荷兰语（af）、波斯尼亚语（bs）；修正越南语、捷克语、西班牙语（errorLoading）、罗马尼亚语、法语、斯洛伐克语、挪威语（inputTooShort）。

四、4.0.6 至 4.0.9：事件、无障碍与细节打磨

4.0.6

新特性：package.json增加style属性；新增clear与clearing事件；新增scrollAfterSelect选项；补齐缺失的变音符号字符；
修复：无选项时按上方向键报错、工厂包装器前补;、IE11 选中后失去焦点、清空选中时清除select2-selection__rendered的 tooltip、iOS 10 键盘关闭、用户自定义数据类型未归一化、Defaults.set()深度合并、AJAX 请求期间误显示"results could not be loaded"、改用Utils.__cache缓存对象替代$.data、移除selection:update的双重事件绑定；
无障碍：改进.select2-hidden-accessible；为单选下拉值添加role与aria-readonly属性；
翻译：新增土库曼语（tk）、阿尔巴尼亚语（sq）、格鲁吉亚语（ka）、尼泊尔语（ne）、孟加拉语（bn），新增removeAllItems翻译，修正法语、越南语、俄语；
杂项：移除经典主题中重复的 CSS 选择器。

4.0.7

改进：按住 Ctrl 或 Meta（Cmd）键时选中项不再关闭下拉；
修复：单选下拉关闭后不再自动重新打开；
杂项：almost与jquery-mousewheel移入 devDependencies。

4.0.8

新特性：针对 jQuery 3.4.1 做兼容性测试与修复；结果尊重<option>的 disabled 状态；新增computedstyle选项用于宽度计算；
修复：4.0.7 引入的标签创建问题、滚动条不可见时的无限滚动、回退 4.0.6 的焦点行为变更；
翻译：修正法语措辞；
杂项：升级 grunt-contrib-qunit；移除多选下未使用的.select2-selection__placeholderCSS；移除废弃的 jQuery 简写。

4.0.9

新特性/改进：通过选中项上的aria-disabled镜像禁用状态；销毁实例时清除内部 ID；设置 combobox 的 ARIA 1.1 角色与属性；language选项具备明确定义的回退链；
修复：搜索框非空时不传播点击、maximumSelectionLength被closeOnSelect忽略、生成的选项未获得结果 ID、文本为空时移除选中项 title 属性、选中项时重新定位下拉、向上展开且带消息时的下拉定位、搜索框撑宽容器、allowClear不再把选中项换行；
翻译：修正德语翻译错误；
杂项：升级开发用 grunt 版本消除漏洞告警，清理未使用变量。

五、4.0.10 至 4.0.13：定位、兼容性与维护收尾

4.0.10

改进：dropdownParent选项支持传入选择器；
修复：向上展开的下拉定位错误。

4.0.11

修复：dropdownParent不在文档中时获取 offset 触发的 jQuery migrate 错误；
杂项：CI 迁移到 GitHub Actions；文档迁入代码仓库并从仓库发布；移除 Travis CI 集成。

4.0.12

修复：使用 Shadow DOM 且对<html>元素设置样式时的偏移计算错误；
杂项：文档 CDN 引用从 cdnjs 更换为 jsDelivr；修正自动化 NPM 部署的 provider 配置。

4.0.13（仓库内置版本）

新特性/改进：change事件之前触发input事件；close事件反馈导致关闭的按键码；DOM 变更时selection:update只触发一次；
修复：防止禁用元素被打开；
文档：修正文档中的 "edit this page" 链接；
杂项：Select2 在 Open Collective 平台注册以接收资助。

六、Dolibarr 中的实际集成与二次开发

全局翻译注入（htdocs/core/js/lib_head.js.php）

Dolibarr 在全局头部脚本中定义了select2arrayoflanguage对象，将 Select2 的language选项回调（matches、noResults、inputTooShort、loadMore、searching）映射到 Dolibarr 的翻译键（Select2ResultFoundUseArrows、Select2NotFound、Select2Enter、Select2MoreCharacter(s)、Select2LoadingMoreResults、Select2SearchInProgress），从而让下拉提示语跟随 ERP 当前语言包。表单组件初始化时会优先使用该对象，未定义时才回退为"en"。

表单组件中的 Select2（htdocs/core/class/html.form.class.php）

Form类在大量场景调用 Select2 API：

联系人"搜索并选择"组合（第 1979-2058 行）：以<option selected>预填当前选中项，其余结果通过contact/ajax/contact.php按需远程加载；单选框模式下需要一个空的第一个<option>作为占位符；下拉获得焦点即展开并携带空搜索词请求端点；分页大小由CONTACT_LIMIT_SIZE配置控制，Select2 滚动到底部持续拉取下一页；并强制.select2-container { z-index: 1010; }以高于弹窗遮罩；
用户"搜索并选择"组合（第 2832-3070 行）：通过user/ajax/users.php分页，select2的ajax.data将minimumInputLength等参数传给端点，同样在单选框空占位、自动展开、z-index 上保持一致；
常规下拉美化（第 3363、3507、10558 行等）：普通枚举/列表选择直接$("#id").select2()增强；
弹窗后刷新（第 6810-6843 行）：组合内容变化时先select2("destroy")再重新初始化；
templateResult渲染（第 6921-6922 行）：选项模板使用完整标签文本，保证 Select2 搜索匹配器可用。

这些实现直接印证了 CHANGELOG 中ajax.data/ajax.url回调、placeholder、templateResult、分页（loadMore）与 i18n 键等能力在真实业务代码中的用法。

与 jQuery 3.6.4 的兼容补丁（htdocs/core/js/lib_head.js.php）

源码注释明确指出：Dolibarr 针对 jQuery 3.6.4 新版嵌套焦点保护与 Select2 的冲突做了一个临时补丁，通过监听select2:open事件规避问题，并标记"待上游 issue 修复后移除"。这说明即使内置版本停留在 4.0.13，Dolibarr 也会在集成层自行修补上游遗留缺陷——升级 Select2 内置版本前，应优先确认此类补丁的兼容性。

七、升级与迁移要点汇总

综合 4.0.0 至 4.0.13 的变更，从旧版升级或二次集成时优先核对以下清单：

承载元素：一律使用<select>，不要依赖<input type="hidden">旧方案；
事件命名：统一采用select2:前缀命名空间（select2:open、select2:close、select2:select、select2:unselect等），change事件的added/removed/val附加属性已移除；
选项名：按第二节对照表迁移templateSelection/templateResult/sorter/createTag/selectOnClose/ajax.processResults等新名称；
国际化：language对象按noMatches/searching/inputTooShort/inputTooLong/errorLoading/loadingMore/maximumSelected键组织，并优先利用language回退链；
方法调用：取值/设值用.val()，启用/禁用用.prop("disabled", ...)，重绘下拉用destroy后重建；
行为差异：Enter 只选中不切换、Ctrl/Meta + 点击保持下拉打开、allowClear不再换行、禁用状态严格生效；
依赖与构建：完整构建不含 jQuery，需自行引入；AMD/UMD 加载器均可用；按composer.json/package.json中的文件清单引入dist/js/select2.js、dist/css/select2.css与dist/js/i18n/*.js。

当前仓库内置的 4.0.13 是 Select2 4.x 系列的收官维护版，其后继大版本（4.1+）延续了本文所述的选项与事件体系。开发者如需深入源码级细节，可继续查阅 README.md（浏览器兼容性与集成列表）、package.json（构建产物入口）与 composer.json（组件文件清单）。