Select2 文檔中心導讀基于 jQuery 的可搜索、可標記、支持遠程數據的選擇框增強方案【免費下載鏈接】select2Select2 is a jQuery based replacement for select boxes. It supports searching, remote data sets, and infinite scrolling of results.項目地址: https://gitcode.com/gh_mirrors/se/select2Select2 是一款基于 jQuery 的select下拉框增強插件本倉庫gh_mirrors/se/select2對應官方版本 4.1.0見 package.json同時承載了其完整源碼、單元測試與官方文檔站點。本篇技術指南以倉庫docs/目錄下文檔站首頁docs/README.md為核心脈絡系統講解 Select2 的六大核心能力——國際化i18n、遠程數據AJAX、主題化Theming、插件化擴展Adapters Decorators、動態(tài)創(chuàng)建標簽Tagging與瀏覽器兼容——并給出每項能力對應的配置示例、源碼實現位置與測試依據幫助讀者快速建立對 Select2 的整體認知并據此上手深度定制。一、項目定位jQuery 對原生 select 框的完整替代文檔站首頁對項目的定位是一句話The jQuery replacement for select boxesjQuery 對 select 框的替代方案。它并不是一個簡單的樣式美化庫而是在原生select的能力基礎上提供了一套完整的增強體系可搜索用戶可以直接在控件內輸入關鍵字過濾候選結果標簽Tagging允許用戶輸入一個不在候選列表中的值并即時創(chuàng)建為新選項遠程數據集Remote data通過 AJAX 從服務器按需加載數據無限滾動Infinite scrolling對大型遠程數據集支持分頁加載以及 RTL 語言環(huán)境、變音符號diacritics匹配、自定義渲染等眾多高頻需求。倉庫根目錄的 README.md 進一步列出了典型使用場景增強原生 select 的搜索能力、提供更好的多選界面、通過 AJAX 加載可搜索數據、支持多級optgroup嵌套原生 select 只允許一層嵌套Select2 不受此限制、即時創(chuàng)建新標簽、基于搜索詞部分加載大型遠程數據集、滾動到底部自動加載下一頁、以及自定義結果與已選內容的渲染模板。事實邊界說明關于瀏覽器兼容性文檔站首頁聲明支持現代與舊版瀏覽器包括Internet Explorer 11倉庫根目錄 README.md 中給出的兼容清單為 IE 8、Chrome 8、Firefox 10、Safari 3、Opera 10.6。二者均屬項目官方聲明具體以你所使用版本的發(fā)布說明為準。二、文檔首頁六大核心特性詳解文檔站首頁用六張?zhí)匦钥ㄆ爬?Select2 的核心賣點以下逐一展開并結合倉庫源碼與docs/下對應章節(jié)的詳細文檔進行深入說明。2.1 國際化40 內置語言、RTL 與變音符號特性卡片原文In your language —— Select2 comes with support for RTL environments and diacritics, and over 40 languages built-in.內置語言數量docs/README.md聲明內置40 種語言。從倉庫源碼目錄 src/js/select2/i18n 可以看到 60 個獨立語言模塊文件覆蓋中文zh-CN.js、zh-TW.js、日文、韓文、阿拉伯文、希伯來文、印地語、歐洲各主要語種等每種語言均以 AMD 模塊形式提供翻譯對象。消息翻譯Message translations當出現沒有搜索結果還需要輸入更多字符才能搜索等提示時Select2 會展示翻譯后的消息。使用方式詳見 docs/i18n.md加載語言文件在頁面引入select2.js之后、按相同順序引入對應語言文件如dist/js/i18n/es.js初始化時指定語言$(.js-example-language).select2({ language: es });通過 HTML 屬性聲明語言語言不必在初始化時定義也可以直接設置在任何父元素的[lang]屬性上如[langes]Select2 會自動向上查找自定義翻譯對象當語言文件中找不到指定字符串時Select2 會回退到內置語言同時你也可以直接傳入一個翻譯對象覆蓋任意消息language: { // 所有條目都必須是返回字符串的函數 inputTooShort: function() { return You must enter more characters...; } }從源碼結構看翻譯機制由select2/translation模塊統一處理參見 src/js/select2/translation.jslanguage配置項既可以傳字符串解析為語言文件/內置語言也可以直接傳翻譯對象。RTL 支持Select2 在select或其任何父元素設置了dirrtl屬性時自動以 RTL 方式工作也可以顯式初始化$(.js-example-rtl).select2({ dir: rtl });變音符號diacritics轉寫匹配Select2 默認的 matcher 會把帶變音符號的字母轉寫為對應的 ASCII 字母后再匹配例如輸入aero也能命中Aeróbics、águilas等選項。該能力由源碼 src/js/select2/diacritics.js 提供——該文件包含一張約 800 行的 Unicode 字符到 ASCII 字母的映射表如\u00C0→A、\u00E9→e等初始化時無需任何額外配置即可生效。2.2 遠程數據支持基于 AJAX 的高效大數據集搜索特性卡片原文Using AJAX you can efficiently search large lists of items.Select2 內置了基于 jQuery AJAX 方法的遠程數據支持詳細教程見 docs/data-sources/ajax.md。最簡用法只需提供 URL 與數據類型select classjs-example-data-ajax/select$(.js-example-data-ajax).select2({ ajax: { url: https://api.github.com/search/repositories, dataType: json } });ajax配置對象中的所有選項都會被原樣傳給 jQuery 的$.ajax或你指定的transport函數。請求參數用戶打開控件時除非設置了minimumInputLength以及每次在搜索框輸入時Select2 都會發(fā)起請求默認攜帶以下查詢參數參數含義term搜索框中的當前搜索詞q與term內容相同兼容舊接口_type請求類型通常為query分頁請求時為query_appendpage請求的頁碼僅分頁無限滾動搜索時發(fā)送典型請求形如https://api.github.com/search/repositories?termsel_typequeryqsel。可通過重寫ajax.data增加自定義查詢參數$(#mySelect2).select2({ ajax: { url: https://api.github.com/orgs/select2/repos, data: function(params) { var query { search: params.term, type: public } // 實際請求參數為 ?search[term]typepublic return query; } } });響應轉換通過ajax.processResults把 API 返回結構轉換為 Select2 期望的{ results: [...] }格式processResults: function(data) { // 把響應頂層 key 從 items 轉為 results return { results: data.items }; }性能關鍵點原文檔明確提示對于遠程數據源Select2 在某個選項第一次被選中之前不會創(chuàng)建對應的option元素這是出于性能考慮一旦創(chuàng)建該option會保留在 DOM 中即使后續(xù)選擇被改變也不移除。此外遠程接口的結果過濾應在服務端完成原文檔引用了 issue #2321 的官方解釋若無法服務端過濾可改用數組數據源見 docs/data-sources/arrays.md。預置默認值可以為 AJAX 數據源預置已選項在 HTML 中直接寫帶selectedselected的option其中包含要顯示的 value 與 text以編程方式添加則需動態(tài)創(chuàng)建并追加新的Option對象參見 docs/programmatic-control/add-select-clear-items.md。分頁與無限滾動通過重寫ajax.data加入page參數當前頁碼在params.page中并在響應中返回pagination.more布爾值告知是否還有更多頁$(#mySelect2).select2({ ajax: { url: https://api.github.com/search/repositories, data: function(params) { var query { search: params.term, page: params.page || 1 } return query; } } });{ results: [ { id: 1, text: Option 1 }, { id: 2, text: Option 2 } ], pagination: { more: true } }若服務端不返回pagination.more可在processResults中自行推算例如 API 返回count_filtered總數、每頁 10 條時processResults: function(data, params) { params.page params.page || 1; return { results: data.results, pagination: { more: (params.page * 10) data.count_filtered } }; }請求限流用ajax.delay毫秒讓 Select2 在用戶停止輸入一段時間后再發(fā)請求ajax: { delay: 250 // 用戶停止輸入 250ms 后再觸發(fā)請求 }動態(tài) URLajax.url支持傳入回調函數根據params含當前搜索詞params.term動態(tài)生成 URLajax: { url: function(params) { return /some/url/ params.term; } }自定義 transport默認 transport 是jQuery.ajax可通過ajax.transport替換為自定義請求庫ajax: { transport: function(params, success, failure) { var request new AjaxRequest(params.url, params); request.on(success, success); request.on(failure, failure); } }底層實現佐證源碼 src/js/select2/data/ajax.js 中的AjaxAdapter繼承自ArrayAdapter。其_applyDefaults方法為ajax配置提供默認實現默認data回調把params擴展為{ q: params.term }默認transport即$.ajax(...)并鏈式調用then(success)/fail(failure)query方法會先abort()上一次未完成的請求JSONP 請求除外以避免競態(tài)同時支持函數形式的url與data并在收到響應后用processResults歸一化結果、校驗results必須為數組否則在debug: true時向控制臺輸出錯誤。docs/data-sources/ajax.md末尾還提供了完整的 GitHub 倉庫搜索示例結合了delay、data、processResults、cache: true、minimumInputLength與自定義templateResult/templateSelection是很好的落地參考。2.3 主題化基于 Sass 構建、可完全換膚特性卡片原文Fully skinnable, CSS built with Sass and an optional theme for Bootstrap 4.Select2 的樣式體系由 Sass 構建源碼位于 src/scsscore.scss 為樣式入口_dropdown.scss、_multiple.scss、_single.scss分別對應下拉、多選、單選的布局細節(jié)內置兩套主題目錄theme/default默認主題與 theme/classic每套主題內部通過_defaults.scss定義 Sass 變量、_single.scss/_multiple.scss定義單/多選外觀、layout.scss組織整體布局主題還使用了 src/scss/mixins/_gradients.scss 中的漸變 mixin 來實現經典的立體按鈕效果。初始化時通過theme配置項選擇主題默認default還可通過dropdownCssClass/selectionCssClass追加自定義 CSS 類其中:all:特殊值可把原生select元素上的所有 CSS 類原樣拷貝到對應容器上。外觀相關的完整說明見 docs/appearance.md。2.4 插件化擴展Adapter 模式 Decorator 裝飾器特性卡片原文The plugin system allows you to easily customize Select2 to work exactly how you want it to.從版本 4.0 起Select2 采用Adapter適配器模式作為擴展機制幾乎所有的內置功能搜索、遠程數據、標簽、占位符、清除按鈕等都是由內置適配器實現的詳細文檔見 docs/advanced/adapters-and-decorators.md。所有自定義適配器必須實現Adapter接口的四個方法// 返回要渲染的 jQuery/DOM 元素Select2 會自動將其放入 DOM Adapter.render function() { return $jq; }; // 綁定 Select2 與 DOM 事件container 上可用 on/trigger 監(jiān)聽和觸發(fā)事件 Adapter.bind function(container, $container) {}; // 定位渲染出的元素數據適配器dataAdapter不會調用此方法 Adapter.position function($rendered, $defaultContainer) {}; // 銷毀事件與 DOM在調用 select2(destroy) 時觸發(fā) Adapter.destroy function() {};覆蓋默認selectionAdapter的適配器還需實現SelectionAdapter.update(data)始終傳入數組即使只支持單選覆蓋默認dataAdapter的適配器還需實現DataAdapter.current(callback)與DataAdapter.query(params, callback)params.term為用戶搜索詞params.page為分頁頁碼。各內置適配器的詳細接口說明分布在 docs/advanced/default-adapters 目錄data、results、selection、dropdown 等。Decorator裝飾器用于把適配器的能力通過配置選項暴露出來。通過Utils.Decorate可組合裝飾器$.fn.select2.amd.require( [select2/utils, select2/selection/single, select2/selection/placeholder], function(Utils, SingleSelection, Placeholder) { var CustomSelectionAdapter Utils.Decorate(SingleSelection, Placeholder); } );AMD 兼容性Select2 自帶支持 AMD 與 CommonJS 的 UMD 封裝可配合 RequireJS 等加載器使用當構建環(huán)境改變了模塊名導致找不到語言文件時可用amdLanguageBase手動指定語言文件的前綴路徑見 docs/getting-started/builds-and-modules.md。2.5 動態(tài)創(chuàng)建選項Tagging 標簽功能特性卡片原文Allow users to type in a new option and add it on the fly.除了預置選項菜單Select2 還允許用戶把搜索框中輸入的新文本即時創(chuàng)建為選項詳見 docs/tagging.md。啟用方式是在初始化時設置tags: trueselect option selectedselectedorange/option optionwhite/option optionpurple/option /select$(.js-example-tags).select2({ tags: true });開啟后用戶既可選擇既有選項也可通過下拉中排第一的當前輸入內容創(chuàng)建新選項。多選 標簽multiplemultiple與tags: true可組合使用用戶輸入一個下拉里不存在的值即可新增。自動分詞tokenization用tokenSeparators指定分隔符用戶輸入分隔符時自動把前面的內容提交為標簽$(.js-example-tokenizer).select2({ tags: true, tokenSeparators: [,, ] })自定義創(chuàng)建邏輯通過createTag回調控制標簽的創(chuàng)建與屬性。返回null可禁用創(chuàng)建如要求必須包含符號返回對象可為新標簽附加自定義屬性如newTag: true$(select).select2({ createTag: function(params) { var term $.trim(params.term); if (term ) { return null; } return { id: term, text: term, newTag: true // 附加自定義屬性 } } });控制標簽在下拉中的位置通過insertTag回調調整新標簽插入結果數組的位置$(select).select2({ insertTag: function(data, tag) { data.push(tag); // 把標簽插到結果末尾 } });兼容性說明在 v3.5 時代tags選項用于加載數組數據v4.0 起tags專指標簽功能為向后兼容tags仍可接受對象數組并按data選項的方式處理見 docs/data-sources/arrays.md。2.6 瀏覽器支持文檔站首頁聲明 Select2 對現代與舊版瀏覽器均有內置支持包括 Internet Explorer 11倉庫根目錄 README.md 給出的兼容清單為 IE 8、Chrome 8、Firefox 10、Safari 3、Opera 10.6。在docs/README.md的表述中這一能力被概括為Full browser support。三、配置項總覽docs/configuration/options-api.md羅列了 Select2 的全部配置項下表匯總了文檔站首頁六大特性所涉及的關鍵配置完整表格見 docs/configuration/options-api.md配置項類型默認值對應能力ajaxobjectnullAJAX 遠程數據源dataarray of objectsnull數組數據源languagestring / object英文翻譯消息翻譯 / 國際化dirstringltrRTL 文本方向themestringdefault主題appearancetagsboolean / arrayfalse標簽taggingtokenizercallback—自由文本自動分詞tokenSeparatorsarraynull分詞分隔符dataAdapter—SelectAdapter覆蓋內置數據適配器dropdownAdapter—DropdownAdapter覆蓋內置下拉適配器resultsAdapter—ResultsAdapter覆蓋內置結果適配器selectionAdapter—Single/MultipleSelection覆蓋內置選擇適配器matchercallback—自定義結果匹配minimumInputLengthinteger0觸發(fā)搜索的最小字符數maximumInputLengthinteger0搜索詞最大長度限制minimumResultsForSearchinteger0結果數下限控制是否顯示搜索框maximumSelectionLengthinteger0多選控件可選最大項數小于 1 不限制placeholderstring / objectnull占位提示文本allowClearbooleanfalse可清除已選項multiplebooleanfalse多選pillbox模式初始化時自動映射 HTML 的multiple屬性widthstringresolve容器寬度策略closeOnSelectbooleantrue選中后是否關閉下拉selectOnClosebooleanfalse關閉下拉時自動選中高亮項templateResult/templateSelectioncallback—自定義結果 / 已選項渲染escapeMarkupcallbackUtils.escapeMarkup自定義模板內容自動轉義debugbooleanfalse在瀏覽器控制臺輸出調試信息disabledbooleanfalse禁用控件dropdownAutoWidthbooleanfalse打開時動態(tài)計算下拉寬度dropdownParentjQuery 選擇器 / DOM 節(jié)點$(document.body)自定義下拉容器位置dropdownCssClass/selectionCssClassstring追加 CSS 類:all:復制原生元素全部類sortercallback—自定義結果排序amdLanguageBasestring./i18n/AMD 加載器語言文件路徑scrollAfterSelectbooleanfalse多選 closeOnSelect: false時控制結果列表是否回滾到首個選項四、安裝與分發(fā)方式docs/getting-started/installation.md與docs/getting-started/builds-and-modules.md介紹了多種安裝途徑docs/README.md首頁的 Releases / GitHub 按鈕即引導至對應發(fā)布渠道1. CDN 引入最快上手Select2 托管于 jsDelivr 與 cdnjs在頁面head中引入編譯好的 CSS 與 JS 即可link hrefhttps://cdn.jsdelivr.net/npm/select24.1.0/dist/css/select2.min.css relstylesheet/ script srchttps://cdn.jsdelivr.net/npm/select24.1.0/dist/js/select2.min.js /script注意新版本發(fā)布后CDN 同步需要一定時間。2. Bower 安裝在bower.json中聲明依賴后執(zhí)行bower installdependencies: { select2: ~4.1 }或直接運行bower install select2。編譯產物位于項目的vendor/select2/dist/css/與vendor/select2/dist/js/之后按上述方式引入select2.min.css與select2.min.js。3. Webpack Encore先yarn install select2再在 JS 中require(select2)、在 SCSS 中import ~select2;。當前倉庫版本 4.1.0見 package.json其main指向dist/js/select2.jsstyle指向dist/css/select2.css。4. 手動安裝可從 GitHub 倉庫 Releases 頁面下載指定版本的發(fā)布包把dist目錄中的文件復制進項目并引入link hrefpath/to/select2.min.css relstylesheet/ script srcpath/to/select2.min.js /script構建類型選擇Select2 提供兩種構建——標準構建select2.js/select2.min.js覆蓋絕大多數常用功能大多數用戶應選擇它與全量構建select2.full.js/select2.full.min.js僅在需要 jquery.mousewheel 等推薦包含項時使用。dist目錄下的文件同時兼容 AMD也可直接以src目錄源碼jquery.select2或select2/core作為模塊入口。五、數據源機制對比docs/data-sources目錄對三種數據來源做了系統說明理解其差異有助于正確選型數據源配置項特點關鍵行為數組data本地數據立即可用立即渲染為option元素可通過option selected預置選中項AJAXajax遠程大數據集、按需搜索選項首次被選中前不創(chuàng)建option結果過濾須在服務端完成格式化id/text字段自定義數據對象結構通過id/text屬性定義每個數據對象的標識與顯示文本六、文檔站結構地圖docs/目錄即官方文檔站基于 MkDocs 構建配置見 mkdocs.yml的全部 Markdown 源文件除本文已展開的章節(jié)外還可按需查閱入門basic-usage.md單/多選初始化、installation.md、builds-and-modules.md配置options-api.md全量配置表、defaults.md全局默認值、data-attributes.mdHTML 屬性驅動配置外觀與交互appearance.md、dropdown.md、selections.md、placeholders.md、searching.md、tagging.md、i18n.md程序化控制methods.md、events.md、retrieving-selections.md、add-select-clear-items.md高級主題adapters-and-decorators.md 與 default-adapters 系列升級與排查migrating-from-35.mdv3.5 → v4.0、new-in-40.md、common-problems.md。七、質量保障測試與工程化倉庫的健壯性有完整的自動化測試支撐tests/目錄按模塊分門別類tests/data/覆蓋數組、標簽、tokenizer、最小/最大輸入長度等數據層行為如 tags-tests.js、tokenizer-tests.jstests/selection/覆蓋單選、多選、占位符、清除、搜索等交互tests/dropdown/與tests/results/覆蓋下拉定位、搜索、無限滾動等tests/integration/驗證與 jQuery 調用的集成。測試通過 QUnit 運行入口見tests/unit-jq*.html、tests/integration-jq*.html構建由 Gruntfile.js 驅動涉及源碼合并、壓縮、Sass 編譯與 QUnit 測試任務。綜上docs/README.md文檔站首頁為 Select2 劃定了搜索、標簽、遠程數據、無限滾動、主題化、可擴展六大能力邊界。以它為索引配合本倉庫的源碼src/js/select2/、樣式src/scss/、測試tests/與各章節(jié) Markdown 文檔即可從會用走向懂原理、能定制這也是本倉庫作為完整可研讀代碼庫的最大價值所在?！久赓M下載鏈接】select2Select2 is a jQuery based replacement for select boxes. It supports searching, remote data sets, and infinite scrolling of results.項目地址: https://gitcode.com/gh_mirrors/se/select2創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 Select2 文檔中心導讀：基于 jQuery 的可搜索、可標記、支持遠程數據的選擇框增強方案
Select2 文檔中心導讀基于 jQuery 的可搜索、可標記、支持遠程數據的選擇框增強方案【免費下載鏈接】select2Select2 is a jQuery based replacement for select boxes. It supports searching, remote data sets, and infinite scrolling of results.項目地址: https://gitcode.com/gh_mirrors/se/select2Select2 是一款基于 jQuery 的select下拉框增強插件本倉庫gh_mirrors/se/select2對應官方版本 4.1.0見 package.json同時承載了其完整源碼、單元測試與官方文檔站點。本篇技術指南以倉庫docs/目錄下文檔站首頁docs/README.md為核心脈絡系統講解 Select2 的六大核心能力——國際化i18n、遠程數據AJAX、主題化Theming、插件化擴展Adapters Decorators、動態(tài)創(chuàng)建標簽Tagging與瀏覽器兼容——并給出每項能力對應的配置示例、源碼實現位置與測試依據幫助讀者快速建立對 Select2 的整體認知并據此上手深度定制。一、項目定位jQuery 對原生 select 框的完整替代文檔站首頁對項目的定位是一句話The jQuery replacement for select boxesjQuery 對 select 框的替代方案。它并不是一個簡單的樣式美化庫而是在原生select的能力基礎上提供了一套完整的增強體系可搜索用戶可以直接在控件內輸入關鍵字過濾候選結果標簽Tagging允許用戶輸入一個不在候選列表中的值并即時創(chuàng)建為新選項遠程數據集Remote data通過 AJAX 從服務器按需加載數據無限滾動Infinite scrolling對大型遠程數據集支持分頁加載以及 RTL 語言環(huán)境、變音符號diacritics匹配、自定義渲染等眾多高頻需求。倉庫根目錄的 README.md 進一步列出了典型使用場景增強原生 select 的搜索能力、提供更好的多選界面、通過 AJAX 加載可搜索數據、支持多級optgroup嵌套原生 select 只允許一層嵌套Select2 不受此限制、即時創(chuàng)建新標簽、基于搜索詞部分加載大型遠程數據集、滾動到底部自動加載下一頁、以及自定義結果與已選內容的渲染模板。事實邊界說明關于瀏覽器兼容性文檔站首頁聲明支持現代與舊版瀏覽器包括Internet Explorer 11倉庫根目錄 README.md 中給出的兼容清單為 IE 8、Chrome 8、Firefox 10、Safari 3、Opera 10.6。二者均屬項目官方聲明具體以你所使用版本的發(fā)布說明為準。二、文檔首頁六大核心特性詳解文檔站首頁用六張?zhí)匦钥ㄆ爬?Select2 的核心賣點以下逐一展開并結合倉庫源碼與docs/下對應章節(jié)的詳細文檔進行深入說明。2.1 國際化40 內置語言、RTL 與變音符號特性卡片原文In your language —— Select2 comes with support for RTL environments and diacritics, and over 40 languages built-in.內置語言數量docs/README.md聲明內置40 種語言。從倉庫源碼目錄 src/js/select2/i18n 可以看到 60 個獨立語言模塊文件覆蓋中文zh-CN.js、zh-TW.js、日文、韓文、阿拉伯文、希伯來文、印地語、歐洲各主要語種等每種語言均以 AMD 模塊形式提供翻譯對象。消息翻譯Message translations當出現沒有搜索結果還需要輸入更多字符才能搜索等提示時Select2 會展示翻譯后的消息。使用方式詳見 docs/i18n.md加載語言文件在頁面引入select2.js之后、按相同順序引入對應語言文件如dist/js/i18n/es.js初始化時指定語言$(.js-example-language).select2({ language: es });通過 HTML 屬性聲明語言語言不必在初始化時定義也可以直接設置在任何父元素的[lang]屬性上如[langes]Select2 會自動向上查找自定義翻譯對象當語言文件中找不到指定字符串時Select2 會回退到內置語言同時你也可以直接傳入一個翻譯對象覆蓋任意消息language: { // 所有條目都必須是返回字符串的函數 inputTooShort: function() { return You must enter more characters...; } }從源碼結構看翻譯機制由select2/translation模塊統一處理參見 src/js/select2/translation.jslanguage配置項既可以傳字符串解析為語言文件/內置語言也可以直接傳翻譯對象。RTL 支持Select2 在select或其任何父元素設置了dirrtl屬性時自動以 RTL 方式工作也可以顯式初始化$(.js-example-rtl).select2({ dir: rtl });變音符號diacritics轉寫匹配Select2 默認的 matcher 會把帶變音符號的字母轉寫為對應的 ASCII 字母后再匹配例如輸入aero也能命中Aeróbics、águilas等選項。該能力由源碼 src/js/select2/diacritics.js 提供——該文件包含一張約 800 行的 Unicode 字符到 ASCII 字母的映射表如\u00C0→A、\u00E9→e等初始化時無需任何額外配置即可生效。2.2 遠程數據支持基于 AJAX 的高效大數據集搜索特性卡片原文Using AJAX you can efficiently search large lists of items.Select2 內置了基于 jQuery AJAX 方法的遠程數據支持詳細教程見 docs/data-sources/ajax.md。最簡用法只需提供 URL 與數據類型select classjs-example-data-ajax/select$(.js-example-data-ajax).select2({ ajax: { url: https://api.github.com/search/repositories, dataType: json } });ajax配置對象中的所有選項都會被原樣傳給 jQuery 的$.ajax或你指定的transport函數。請求參數用戶打開控件時除非設置了minimumInputLength以及每次在搜索框輸入時Select2 都會發(fā)起請求默認攜帶以下查詢參數參數含義term搜索框中的當前搜索詞q與term內容相同兼容舊接口_type請求類型通常為query分頁請求時為query_appendpage請求的頁碼僅分頁無限滾動搜索時發(fā)送典型請求形如https://api.github.com/search/repositories?termsel_typequeryqsel。可通過重寫ajax.data增加自定義查詢參數$(#mySelect2).select2({ ajax: { url: https://api.github.com/orgs/select2/repos, data: function(params) { var query { search: params.term, type: public } // 實際請求參數為 ?search[term]typepublic return query; } } });響應轉換通過ajax.processResults把 API 返回結構轉換為 Select2 期望的{ results: [...] }格式processResults: function(data) { // 把響應頂層 key 從 items 轉為 results return { results: data.items }; }性能關鍵點原文檔明確提示對于遠程數據源Select2 在某個選項第一次被選中之前不會創(chuàng)建對應的option元素這是出于性能考慮一旦創(chuàng)建該option會保留在 DOM 中即使后續(xù)選擇被改變也不移除。此外遠程接口的結果過濾應在服務端完成原文檔引用了 issue #2321 的官方解釋若無法服務端過濾可改用數組數據源見 docs/data-sources/arrays.md。預置默認值可以為 AJAX 數據源預置已選項在 HTML 中直接寫帶selectedselected的option其中包含要顯示的 value 與 text以編程方式添加則需動態(tài)創(chuàng)建并追加新的Option對象參見 docs/programmatic-control/add-select-clear-items.md。分頁與無限滾動通過重寫ajax.data加入page參數當前頁碼在params.page中并在響應中返回pagination.more布爾值告知是否還有更多頁$(#mySelect2).select2({ ajax: { url: https://api.github.com/search/repositories, data: function(params) { var query { search: params.term, page: params.page || 1 } return query; } } });{ results: [ { id: 1, text: Option 1 }, { id: 2, text: Option 2 } ], pagination: { more: true } }若服務端不返回pagination.more可在processResults中自行推算例如 API 返回count_filtered總數、每頁 10 條時processResults: function(data, params) { params.page params.page || 1; return { results: data.results, pagination: { more: (params.page * 10) data.count_filtered } }; }請求限流用ajax.delay毫秒讓 Select2 在用戶停止輸入一段時間后再發(fā)請求ajax: { delay: 250 // 用戶停止輸入 250ms 后再觸發(fā)請求 }動態(tài) URLajax.url支持傳入回調函數根據params含當前搜索詞params.term動態(tài)生成 URLajax: { url: function(params) { return /some/url/ params.term; } }自定義 transport默認 transport 是jQuery.ajax可通過ajax.transport替換為自定義請求庫ajax: { transport: function(params, success, failure) { var request new AjaxRequest(params.url, params); request.on(success, success); request.on(failure, failure); } }底層實現佐證源碼 src/js/select2/data/ajax.js 中的AjaxAdapter繼承自ArrayAdapter。其_applyDefaults方法為ajax配置提供默認實現默認data回調把params擴展為{ q: params.term }默認transport即$.ajax(...)并鏈式調用then(success)/fail(failure)query方法會先abort()上一次未完成的請求JSONP 請求除外以避免競態(tài)同時支持函數形式的url與data并在收到響應后用processResults歸一化結果、校驗results必須為數組否則在debug: true時向控制臺輸出錯誤。docs/data-sources/ajax.md末尾還提供了完整的 GitHub 倉庫搜索示例結合了delay、data、processResults、cache: true、minimumInputLength與自定義templateResult/templateSelection是很好的落地參考。2.3 主題化基于 Sass 構建、可完全換膚特性卡片原文Fully skinnable, CSS built with Sass and an optional theme for Bootstrap 4.Select2 的樣式體系由 Sass 構建源碼位于 src/scsscore.scss 為樣式入口_dropdown.scss、_multiple.scss、_single.scss分別對應下拉、多選、單選的布局細節(jié)內置兩套主題目錄theme/default默認主題與 theme/classic每套主題內部通過_defaults.scss定義 Sass 變量、_single.scss/_multiple.scss定義單/多選外觀、layout.scss組織整體布局主題還使用了 src/scss/mixins/_gradients.scss 中的漸變 mixin 來實現經典的立體按鈕效果。初始化時通過theme配置項選擇主題默認default還可通過dropdownCssClass/selectionCssClass追加自定義 CSS 類其中:all:特殊值可把原生select元素上的所有 CSS 類原樣拷貝到對應容器上。外觀相關的完整說明見 docs/appearance.md。2.4 插件化擴展Adapter 模式 Decorator 裝飾器特性卡片原文The plugin system allows you to easily customize Select2 to work exactly how you want it to.從版本 4.0 起Select2 采用Adapter適配器模式作為擴展機制幾乎所有的內置功能搜索、遠程數據、標簽、占位符、清除按鈕等都是由內置適配器實現的詳細文檔見 docs/advanced/adapters-and-decorators.md。所有自定義適配器必須實現Adapter接口的四個方法// 返回要渲染的 jQuery/DOM 元素Select2 會自動將其放入 DOM Adapter.render function() { return $jq; }; // 綁定 Select2 與 DOM 事件container 上可用 on/trigger 監(jiān)聽和觸發(fā)事件 Adapter.bind function(container, $container) {}; // 定位渲染出的元素數據適配器dataAdapter不會調用此方法 Adapter.position function($rendered, $defaultContainer) {}; // 銷毀事件與 DOM在調用 select2(destroy) 時觸發(fā) Adapter.destroy function() {};覆蓋默認selectionAdapter的適配器還需實現SelectionAdapter.update(data)始終傳入數組即使只支持單選覆蓋默認dataAdapter的適配器還需實現DataAdapter.current(callback)與DataAdapter.query(params, callback)params.term為用戶搜索詞params.page為分頁頁碼。各內置適配器的詳細接口說明分布在 docs/advanced/default-adapters 目錄data、results、selection、dropdown 等。Decorator裝飾器用于把適配器的能力通過配置選項暴露出來。通過Utils.Decorate可組合裝飾器$.fn.select2.amd.require( [select2/utils, select2/selection/single, select2/selection/placeholder], function(Utils, SingleSelection, Placeholder) { var CustomSelectionAdapter Utils.Decorate(SingleSelection, Placeholder); } );AMD 兼容性Select2 自帶支持 AMD 與 CommonJS 的 UMD 封裝可配合 RequireJS 等加載器使用當構建環(huán)境改變了模塊名導致找不到語言文件時可用amdLanguageBase手動指定語言文件的前綴路徑見 docs/getting-started/builds-and-modules.md。2.5 動態(tài)創(chuàng)建選項Tagging 標簽功能特性卡片原文Allow users to type in a new option and add it on the fly.除了預置選項菜單Select2 還允許用戶把搜索框中輸入的新文本即時創(chuàng)建為選項詳見 docs/tagging.md。啟用方式是在初始化時設置tags: trueselect option selectedselectedorange/option optionwhite/option optionpurple/option /select$(.js-example-tags).select2({ tags: true });開啟后用戶既可選擇既有選項也可通過下拉中排第一的當前輸入內容創(chuàng)建新選項。多選 標簽multiplemultiple與tags: true可組合使用用戶輸入一個下拉里不存在的值即可新增。自動分詞tokenization用tokenSeparators指定分隔符用戶輸入分隔符時自動把前面的內容提交為標簽$(.js-example-tokenizer).select2({ tags: true, tokenSeparators: [,, ] })自定義創(chuàng)建邏輯通過createTag回調控制標簽的創(chuàng)建與屬性。返回null可禁用創(chuàng)建如要求必須包含符號返回對象可為新標簽附加自定義屬性如newTag: true$(select).select2({ createTag: function(params) { var term $.trim(params.term); if (term ) { return null; } return { id: term, text: term, newTag: true // 附加自定義屬性 } } });控制標簽在下拉中的位置通過insertTag回調調整新標簽插入結果數組的位置$(select).select2({ insertTag: function(data, tag) { data.push(tag); // 把標簽插到結果末尾 } });兼容性說明在 v3.5 時代tags選項用于加載數組數據v4.0 起tags專指標簽功能為向后兼容tags仍可接受對象數組并按data選項的方式處理見 docs/data-sources/arrays.md。2.6 瀏覽器支持文檔站首頁聲明 Select2 對現代與舊版瀏覽器均有內置支持包括 Internet Explorer 11倉庫根目錄 README.md 給出的兼容清單為 IE 8、Chrome 8、Firefox 10、Safari 3、Opera 10.6。在docs/README.md的表述中這一能力被概括為Full browser support。三、配置項總覽docs/configuration/options-api.md羅列了 Select2 的全部配置項下表匯總了文檔站首頁六大特性所涉及的關鍵配置完整表格見 docs/configuration/options-api.md配置項類型默認值對應能力ajaxobjectnullAJAX 遠程數據源dataarray of objectsnull數組數據源languagestring / object英文翻譯消息翻譯 / 國際化dirstringltrRTL 文本方向themestringdefault主題appearancetagsboolean / arrayfalse標簽taggingtokenizercallback—自由文本自動分詞tokenSeparatorsarraynull分詞分隔符dataAdapter—SelectAdapter覆蓋內置數據適配器dropdownAdapter—DropdownAdapter覆蓋內置下拉適配器resultsAdapter—ResultsAdapter覆蓋內置結果適配器selectionAdapter—Single/MultipleSelection覆蓋內置選擇適配器matchercallback—自定義結果匹配minimumInputLengthinteger0觸發(fā)搜索的最小字符數maximumInputLengthinteger0搜索詞最大長度限制minimumResultsForSearchinteger0結果數下限控制是否顯示搜索框maximumSelectionLengthinteger0多選控件可選最大項數小于 1 不限制placeholderstring / objectnull占位提示文本allowClearbooleanfalse可清除已選項multiplebooleanfalse多選pillbox模式初始化時自動映射 HTML 的multiple屬性widthstringresolve容器寬度策略closeOnSelectbooleantrue選中后是否關閉下拉selectOnClosebooleanfalse關閉下拉時自動選中高亮項templateResult/templateSelectioncallback—自定義結果 / 已選項渲染escapeMarkupcallbackUtils.escapeMarkup自定義模板內容自動轉義debugbooleanfalse在瀏覽器控制臺輸出調試信息disabledbooleanfalse禁用控件dropdownAutoWidthbooleanfalse打開時動態(tài)計算下拉寬度dropdownParentjQuery 選擇器 / DOM 節(jié)點$(document.body)自定義下拉容器位置dropdownCssClass/selectionCssClassstring追加 CSS 類:all:復制原生元素全部類sortercallback—自定義結果排序amdLanguageBasestring./i18n/AMD 加載器語言文件路徑scrollAfterSelectbooleanfalse多選 closeOnSelect: false時控制結果列表是否回滾到首個選項四、安裝與分發(fā)方式docs/getting-started/installation.md與docs/getting-started/builds-and-modules.md介紹了多種安裝途徑docs/README.md首頁的 Releases / GitHub 按鈕即引導至對應發(fā)布渠道1. CDN 引入最快上手Select2 托管于 jsDelivr 與 cdnjs在頁面head中引入編譯好的 CSS 與 JS 即可link hrefhttps://cdn.jsdelivr.net/npm/select24.1.0/dist/css/select2.min.css relstylesheet/ script srchttps://cdn.jsdelivr.net/npm/select24.1.0/dist/js/select2.min.js /script注意新版本發(fā)布后CDN 同步需要一定時間。2. Bower 安裝在bower.json中聲明依賴后執(zhí)行bower installdependencies: { select2: ~4.1 }或直接運行bower install select2。編譯產物位于項目的vendor/select2/dist/css/與vendor/select2/dist/js/之后按上述方式引入select2.min.css與select2.min.js。3. Webpack Encore先yarn install select2再在 JS 中require(select2)、在 SCSS 中import ~select2;。當前倉庫版本 4.1.0見 package.json其main指向dist/js/select2.jsstyle指向dist/css/select2.css。4. 手動安裝可從 GitHub 倉庫 Releases 頁面下載指定版本的發(fā)布包把dist目錄中的文件復制進項目并引入link hrefpath/to/select2.min.css relstylesheet/ script srcpath/to/select2.min.js /script構建類型選擇Select2 提供兩種構建——標準構建select2.js/select2.min.js覆蓋絕大多數常用功能大多數用戶應選擇它與全量構建select2.full.js/select2.full.min.js僅在需要 jquery.mousewheel 等推薦包含項時使用。dist目錄下的文件同時兼容 AMD也可直接以src目錄源碼jquery.select2或select2/core作為模塊入口。五、數據源機制對比docs/data-sources目錄對三種數據來源做了系統說明理解其差異有助于正確選型數據源配置項特點關鍵行為數組data本地數據立即可用立即渲染為option元素可通過option selected預置選中項AJAXajax遠程大數據集、按需搜索選項首次被選中前不創(chuàng)建option結果過濾須在服務端完成格式化id/text字段自定義數據對象結構通過id/text屬性定義每個數據對象的標識與顯示文本六、文檔站結構地圖docs/目錄即官方文檔站基于 MkDocs 構建配置見 mkdocs.yml的全部 Markdown 源文件除本文已展開的章節(jié)外還可按需查閱入門basic-usage.md單/多選初始化、installation.md、builds-and-modules.md配置options-api.md全量配置表、defaults.md全局默認值、data-attributes.mdHTML 屬性驅動配置外觀與交互appearance.md、dropdown.md、selections.md、placeholders.md、searching.md、tagging.md、i18n.md程序化控制methods.md、events.md、retrieving-selections.md、add-select-clear-items.md高級主題adapters-and-decorators.md 與 default-adapters 系列升級與排查migrating-from-35.mdv3.5 → v4.0、new-in-40.md、common-problems.md。七、質量保障測試與工程化倉庫的健壯性有完整的自動化測試支撐tests/目錄按模塊分門別類tests/data/覆蓋數組、標簽、tokenizer、最小/最大輸入長度等數據層行為如 tags-tests.js、tokenizer-tests.jstests/selection/覆蓋單選、多選、占位符、清除、搜索等交互tests/dropdown/與tests/results/覆蓋下拉定位、搜索、無限滾動等tests/integration/驗證與 jQuery 調用的集成。測試通過 QUnit 運行入口見tests/unit-jq*.html、tests/integration-jq*.html構建由 Gruntfile.js 驅動涉及源碼合并、壓縮、Sass 編譯與 QUnit 測試任務。綜上docs/README.md文檔站首頁為 Select2 劃定了搜索、標簽、遠程數據、無限滾動、主題化、可擴展六大能力邊界。以它為索引配合本倉庫的源碼src/js/select2/、樣式src/scss/、測試tests/與各章節(jié) Markdown 文檔即可從會用走向懂原理、能定制這也是本倉庫作為完整可研讀代碼庫的最大價值所在?！久赓M下載鏈接】select2Select2 is a jQuery based replacement for select boxes. It supports searching, remote data sets, and infinite scrolling of results.項目地址: https://gitcode.com/gh_mirrors/se/select2創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考