程序員總結：2017年jQuery 3.0 升級指南

概述

在3.0主版本中，jQuery Core團隊對API進行更改及清理，並修復某些代碼更改引起的bug。這包括刪除以前棄用的公開API，更改或刪除未記錄的API，並更改現有API的記錄或未記錄的行為用於特定輸入。

瀏覽器支持

jQuery 3.0 支持以下瀏覽器：

• Internet Explorer: 9+
• Chrome, Edge, Firefox, Safari: 當前版本 和 當前版本 – 1
• Opera: 當前版本
• Safari Mobile iOS: 7+
• Android 4.0+

jQuery團隊策略是主版本更新只針對這些瀏覽器，所以這個瀏覽器列表至少支持到jQuery 4。

jQuery Migrate 插件

與jQuery 1.9 / 2.0中的主要更改一樣，我們已經創建了一個新版本的jQuery Migrate插件,以簡化舊代碼遷移到3.0版本。我們強烈建議您使用這個插件作為升級工具，它將給出 可能影響您的代碼的關於大多數主要更改的具體建議。

分享之前我還是要推薦下我自己的前端學習群：180442230，不管你是小白還是大牛，小編我都挺歡迎，不定期分享乾貨，包括我自己整理的一份2017最新的前端資料和零基礎入門教程，送給大家，歡迎初學和進階中的小夥伴

jQuery Migrate插件 3.0 版本，不會警告或恢復以前主版本更改（如jQuery 1.9 / 2.0）中刪除的行為。使用以下步驟從 1.11.0 或 2.1.0 之前的jQuery版本升級到3.0新版本：

• 將頁面上的jQuery版本升級到最新的1.x或2.x版本（目前為1.12.3或2.2.3）(愚人碼頭註：3.0之前的最新版本)。
• 將未壓縮的jQuery Migrate 1.x插件添加到頁面。
• 可選但是建議，更新正在使用的任何插件，因為最新版本通常是與最新版本的jQuery是兼容的。
• 測試頁面並解決出現在控制台上的任何警告，使用JQMIGRATE 1.x警告文檔作為指南。
• 刪除jQuery Migrate 1.x插件，並確保該頁面在只使用最新的jQuery 1.x / 2.x的情況下，更新的jQuery代碼能繼續正常工作。
• 將頁面上的jQuery版本升級到最新的3.0版本（目前為3.0.0 ）(愚人碼頭註：目前最新版本為3.1.1)，並將未壓縮的jQuery Migrate 3.x插件添加到頁面。
• 測試頁面並解決控制台上顯示的任何警告，使用JQMIGRATE 3.x警告文檔作為指南。如果插件報錯，向第三方插件作者報告插件中的錯誤。
• 刪除jQuery Migrate 3.x插件，並確保該頁面在只使用最新的jQuery 3.x的情況下，能繼續正常工作。

不支持在同一頁面上同時運行Migrate 1.x和Migrate 3.x。

當使用特定的過時和/或移除的特徵時，Migrate插件的未壓縮開發版本會在控制台日誌中輸出以警告。在查找和修復現有jQuery代碼和插件中的問題的時候，它很有用，可以作為遷移調試工具。

Migrate插件的壓縮版本不會生成任何警告，然而它發出一個單獨的控制台消息，告訴我們它已經被安裝引用，以簡化調試。jQuery 3.0或更高版本的生產站點上可以根據自己的需要使用Migrate插件，但對於舊的不兼容的jQuery代碼或插件也必須使用。理想情況下，這只是作為一個短期解決方案，因為恢復舊的行為可能會導致與預期新行為的新jQuery代碼的衝突。

重要變更摘要

jQuery作為一個廣泛使用的類庫，團隊通常很難知道在發布之前哪些更改可能會影響到開發人員。儘管這份名單很長，我們認為大多數是邊緣案例。許多jQuery項目應該能夠運行3.0版本，如果有問題的話，一般只要做輕微的更改。

通過其組件類別列出更改，並以前綴描述，以幫助您了解其影響：

• 更改：此更改可能會影響現有代碼，因為它以某種方式改變了API。大多數時候，影響僅針對特定邊緣情況。
• 功能：此更改是添加API，並且在大多數情況下不應影響現有代碼。但是，新功能可能與現有代碼相互影響。
• 已棄用：此功能或API仍然存在於jQuery 3.0中，但不建議使用。它可能會在未來的主版本更新中刪除。

請記住，上述的jQuery Migrate插件可以檢測和警告這些更改，以便它們可以在現有的代碼中修復。

有關所有代碼更改的完整詳細列表，請參閱 jQuery Core問題跟蹤器 中的3.0規劃 或版本差異。

Ajax更改：特殊情況的Deferred方法從jQuery.ajax中刪除

從jQuery.ajax返回的jqXHR對象是一個jQuery Deferred,並且歷史上有三個名稱與參數對象的success, error, 和 complete 相匹配的額外的方法。這經常讓人困惑,返回的對象應該像Deferred一樣處理。從jQuery 3.0開始，這些方法已被刪除。作為替代，使用Deferred標準的done，fail和always方法，或者使用新的符合Promises/A+規範的then 和 catch 方法 。

注意,這對通過options對象傳遞的同名的ajax回調根本沒有任何影響，它們繼續存在並且不會被棄用。這隻影響jqXHR方法。

更改：跨域腳本請求必須聲明

通過jQuery.ajax或jQuery.get請求跨域腳本的時候,您現在必須在選項中顯式指定dataType: "script"。這是為了防止遠程站點提供非腳本內容攻擊的可能性，但稍後決定提供具有惡意意圖的腳本。由於jQuery.getScript顯式設置dataType: "script"，所以它不受此更改的影響。

更改：URL中的 hash 保存在jQuery.ajax調用中

jQuery.ajax方法不再自動刪除URL中提供的 hash 值，並將完整的URL發送傳輸（xhr，script，jsonp或自定義傳輸）。如果伺服器端無法處理URL上的hash，請在發送請求之前刪除它。

功能：jQuery.get和jQuery.post增加新的簽名

jQuery 3 通過添加settings參數,為jQuery.get和jQuery.post函數添加了一個新的簽名。 它是一個對象，可以擁有許多屬性,它和你提供給jQuery.ajax( [settings ] )的settings 對象基本相同(愚人碼頭註： type選項將自動設置為GET；另：實際上這個簽名的添加版本為1.12/2.2)。

屬性(Attribute)更改：.removeAttr不再設置 property（特性值） 為 false

在jQuery 3.0之前，在布爾屬性（例如checked, selected, 或者 readonly）上使用.removeAttr方法，將會設置其名稱相應的 property（特性）為false。此行為在Internet Explorer的舊版本上是必需的，但對於現代瀏覽器是不正確因為屬性（attribute）表示初始值，並且 property（特性）表示當前（動態）值。

在DOM元素上使用.removeAttr( "checked" )幾乎總是錯誤。唯一可能有用的情況是，DOM以後要被序列化回HTML字元串。在所有其他情況下，使用.prop( "checked", false )代替。

更改：多選下拉框（select-multiple）不選擇選項將返回空數組

在jQuery 3.0之前，在未選擇任何選項的 元素上調用.val返回null。這是不方便的，因為如果選擇至少一個選項，返回值將是一個數組。此外，如果所有選項都被禁用，jQuery返回值將是一個空數組。為了提高一致性，無選項選擇的情況下現在返回一個空數組。

功能：SVG文檔支持類名（class）操作

SVG從來沒有被jQuery完全支持，並且這點在jQuery 3中沒有改變。儘管如此，許多jQuery方法也可以在SVG文檔上使用。從jQuery 3開始，操作類名的方法，例如 .addClass 和 .hasClass，支持SVG。

棄用：不帶參數的 .toggleClass 和 .toggleClass( Boolean )

雖然文檔記錄了這兩種情況的簽名，其實際行為從未完全定義。這個不明確的行為現在已被廢棄，因此不會被記錄。您可能會發現您不小心使用了該功能，因為.toggleClass( undefined )的行為和沒有參數的調用是相同的，即使它是無效的輸入。

回調（ Callback ）功能：SVG文檔支持類名（class）操作

如果一個回調對象有一個處理函數在.fire之後調用.lock方法，它只阻止未來執行回調列表並且不立即中止當前列表的執行。要停止當前執行，請使用stopOnFalse選項。

Core更改： 在嚴格模式下運行jQuery 3.0

現在大多數瀏覽器都支持通過jQuery 3.0使用」use strict」，jQuery 就是用這個指令構建的。您的代碼不需要在嚴格模式下運行，所以大多數現有代碼不需要做任何修改。我們三年前遇到的一個案件是ASP.NET 4.0使用arguments.caller.callee在其__doPostBack方法中嘗試跟蹤調用堆棧。如果你仍然使用仍然這樣做的ASP.NET版本，推薦繼續使用jQuery 2.x或更早版本。現代瀏覽器通過error.stack支持堆棧跟蹤,所以它不應該有必要檢查arguments.caller.callee。

更改：文檔就緒（document-ready）處理程序現在是非同步的

在jQuery中，自jQuery 1.6以來,document-ready 處理由jQuery.Deferred實現提供支持。作為符合 Promises/A+ 規範的jQuery 3.0 隊列的一部分，document-ready 處理程序被非同步調用，即使是文檔當前已經準備就緒，再添加處理程序。這樣提供了代碼執行順序的一致性，與文檔是否準備就緒無關。例如，考慮這個代碼：

JavaScript 代碼:

在jQuery 3.0中，將總是log 「outside ready」，緊接著是」ready」，不管文檔在執行時候是否準備就緒。早期版本可以按任一順序log消息。

由於處理程序是彼此獨立地執行，所以在一個document-ready處理程序中的異常或失敗不會阻止其他document-ready處理程序運行。

如果是自定義構建的jQuery，排除了deferred模塊，有一種可供選擇的document-ready替代品。這個實現支持jQuery.ready promise,但不是一個jQuery.Deferred對象,所以它應該只能通過jQuery.when使用。

更改： jQuery.isNumeric 和自定義的.toString

jQuery.isNumeric方法旨在與原始數字,以及可以強制轉換為有限數字的字元串一起使用。尤其是，它不再嘗試從對象的.toString方法上獲取數字。需要對其他數字進行專門檢查的用戶可以創建自己的驗證函數。

更改：棄用.context 並且移除.selector屬性

這些屬性在jQuery 1.9中已棄用，因為它們只用於過時的.live方法,並且從未準確地表示當前集合的上下文或選擇器。

更改：文檔中從未記錄的內部方法不再暴露

3.0版本從視圖中刪除了幾個方法，意圖是私有方法，並且文檔中從未記錄過：

• jQuery.swap
• jQuery.buildFragment
• jQuery.domManip

更改：空集合上返回 undefined 值

除了少數例外，任何有返回值的jQuery方法在空的jQuery集合上應該返回undefined，以符合我們的API指南。以下API已更改,以符合此規則：

• 尺寸方法: .width, .height, .innerWidth, .innerHeight, .outerWidth, 和 .outerHeight
• 位置方法: .offsetTop 和 .offsetLeft

以前，這些方法對於空集合返回null而不是undefined。

功能：for...of循環可以用於jQuery集合

jQuery 3.0支持ES2015中引入的for...of循環。它允許循環迭代對象，包括Array, Map, 和Set。當使用這個循環時，獲得的值是jQuery集合的DOM元素，一次一個。請注意，使用for...of循環請注意支持的環境，支持ES2015或如Babel轉換器。這裡是一個例子：功能：jQuery.ready promise 正式被支持

從jQuery版本1.8開始,jQuery.ready已經作為一個類似 promise 的對象被使用（」thenable」在Promise中的術語）。從jQuery 3.0開始，這個對象通過jQuery.when或原生的Promise.resolve被支持。不要假設這個對象是一個jQuery Deferred或一些其他類型的promise對象，例如原生的Promise。典型用法如下所示：

棄用：jQuery.unique, 重命名為 jQuery.uniqueSort

jQuery.unique方法已重命名為jQuery.uniqueSort，以使其行為更容易理解。這裡沒有改變其功能，只有重命名。

棄用：jQuery.parseJSON

由於jQuery 3.0支持的所有瀏覽器都支持原生的JSON.parse方法，因此我們不推薦使用jQuery.parseJSON。

棄用：除了 jQuery(function) 以外的 document-ready 處理器

由於歷史兼容性問題，有多種方式設置 document-ready 處理程序。以下所有方式都是等效的，並在 document-ready 時調用函數fn：

從jQuery 3.0開始，添加 document-ready 處理程序的推薦方式是第一個方法，$(fn)。如事件部分所述，$(document).on("ready", fn)事件形式具有略微不同的語義並在jQuery 3.0中被刪除。

Data更改：.data名稱包含中劃線

從jQuery 3.0開始，所有 data 名稱都以駝峰拼寫方式（例如，clickCount）存儲在jQuery內部的數據對象中,而不是中劃線形式（例如,click-count）。將中劃線名稱轉換為駝峰拼寫法的方式，這與標準DOM在CSS和 data 屬性中的JavaScript名稱是一致的。

一般來說，當設置或獲取指定數據項時，例如 .data("right-aligned")，中劃線形式在jQuery 3.0中仍然能夠工作，但是如果取回data對象，它將具有駝峰拼寫法的形式的 data 項（rightAligned）。3.0中的主要區別是 當你在data對象上使用中劃線形式的名稱時，不要使用.dataAPI 來獲取或設置他們。

例如：

Deferred更改和功能：jQuery.Deferred 現在兼容 Promises/A+

Deferred已更新，兼容了 Promises/A+ 和 ES2015（也稱為 ES6）Promise ，這個變化帶來重大影響。

更改和功能：jQuery.when的參數

jQuery.when現在能給解析then方法輸入的任何參數，作為Promise兼容的「thenable」。這允許更大範圍的輸入，包括原生的ES6 Promises和Bluebird promises。

此外，現在可以更清楚的識別，多參數調用jQuery.when和單參數或無參數調用之間的區別。多參數調用的行為類似於Promise.all，將 fulfillment 值聚合到 fulfillment 數組中（具有jQuery特有的增強功能，也集合 fulfillment 上下文和支持多值的fulfillments），或者拒收第一個rejection值。單參數和無參數調用的行為類似於Promise.resolve，返回一個Deferred，相同地解析為 thenable 或 類似 Promise-like 輸入，或滿足其 non-Promise 輸入（如適用）。從jQuery 3.0開始，這兩個都返回一個新的Deferred（以前版本在使用單個Deferred輸入調用時，不會創建新的Deferred）。

更改：jQuery.when 的進度通知

從jQuery 3.0開始，jQuery.when 方法不再傳遞進度通知從輸入Deferred到輸出Deferred。進度消息不是 Promises/A+ 規範的一部分，並且jQuery.when中進度通知的行為之前就沒有出現在jQuery API文檔中。

尺寸大小更改： .width, .height, .css(「width」), 和 .css(「height」)能夠返回非整數值

在3.0版之前，jQuery使用DOM的offsetWidth和offsetHeight屬性來確定元素的尺寸大小(寬高)，並且這些屬性總是返回整數。使用jQuery 3.0，我們通過DOM getBoundingClientRect API來獲得更精確的值，並且這些值可以不是整數。如果你的代碼總是期望尺寸大小(寬高)為整數，它可能需要調整處理返回值的精度。

Effects（效果）更改：.show, .hide, and .toggle 方法不考慮更多的樣式表更改

jQuery用來顯示和隱藏元素的代碼已被更新，更新后的代碼只專註於內聯樣式，而不是計算樣式，對於樣式表的display值，應該儘可能增加以兼容響應式設計技巧（其中活動的樣式表規則可以在設備改變方向（愚人碼頭註：橫屏，豎屏）/窗口調整大小等時動態地改變）。因此，未關聯元素不再被視為 hidden (隱藏)，除非它們有內聯樣式display: none,同樣的 ，從jQuery 3.0開始，.toggle將不再區分關聯和未關聯元素。

此外，雖然.show和類似的調用將繼續強制迫使 被樣式表規則隱藏的元素 可見，支持此功能會減慢所有顯示/隱藏操作，並且不建議使用它。在這種情況下，確定設置哪個display（顯示）值也已經被簡化，當body級別規則按類型隱藏元素時，默認為「block」。

任何代碼，希望隱藏的元素通過他們之前的 計算 display（顯示）樣式來重新顯示，或未關聯的元素處理為隱藏，應予以審查。團隊創建了一個 與顯示狀態和顯示/隱藏操作 所有可能相關的表格,以便簡化非空內聯樣式的設置。

功能：動畫現在使用requestAnimationFrame

在支持requestAnimationFrame API的平台上，jQuery現在執行動畫時使用這個API，對於老的瀏覽器（如IE9），它會使用之前的API。這將使得動畫更流暢，更少的CPU處理時間 – 並在移動設備上更加省電。

jQuery幾年前嘗試使用了requestAnimationFrame，但與現在的代碼存在嚴重的兼容性問題，所以我們不得不重新實現它。我們認為，我們已經在瀏覽器標籤頁在視圖中不可見的時候，通過暫停動畫解決了大部分的問題。仍然，任何依賴於動畫的代碼總是實時運行是一個不切實際的假設。

棄用： jQuery.fx.interval

現在requestAnimationFrame正在應用於動畫，所以jQuery.fx.interval屬性在大多數瀏覽器上被忽略。但是它仍然存在於jQuery 3.0中，並在一些瀏覽器（如IE9）中仍然需要使用，但將在未來的主要版本中會被刪除。

棄用：附加 easing（緩動）函數參數

通過.animate調用的 easing（緩動）函數傳遞單個參數，完成的百分比。一些較舊的代碼假設它傳遞派生自百分比的額外參數。這些額外參數可能不會出現在未來的主版本更新中。

一個老的 easing（緩動）方法的例子：

同樣的 easing（緩動）方法重寫：