jQuery 1.9升級指南

jQuery 1.9升級指南原文地址：http://jquery.com/upgrade-guide/1.9/ 翻譯的不對或者不通順的地方歡迎拍磚留言。概述

jQuery 1.9刪除或修改了幾個過去行為不一致或效率低下的幾個API。在做這些變化中，團隊的目標是修複jQuery的行為不一致或比較難使用的地方，在這個過程中提高整體效能，減小了檔案的體積。

此列表是看似給你一些不祥的預感。因為jQuery 1.9刪除和修改一些以前做特殊需求的API，比如jQuery.browser。如何升級？首先，看看你的代碼，最好的方法是嘗試用jQuery 1.9和Migrate（遷移）外掛程式（如下文所述）。

jQuery Migrate（遷移）外掛程式

我們認識到，現有的網站和外掛程式可能會受到這些變化的影響，所以提供一個過渡性的升級路徑—— jQuery Migrate（遷移）外掛程式。下面的說明中，在1.9中變化或刪除的API，大部分可以使用jQuery Migrate（遷移）外掛程式恢複。請注意，jQuery 1.9中所有的變化也將應用到jQuery 2.0中，jQuery Migrate（遷移）外掛程式在jQuery2.0中也是可用的。

未壓縮，開發版本的jQuery Migrate（遷移）外掛程式使用時會在控制台中顯示警告資訊，詳細的指出不相容或刪除等資訊及解決方案。這使得它在現有的jQuery代碼和外掛程式上尋找和修複問題時非常有用。jQuery Migrate（遷移）外掛程式包含了1.6.4以來存在但1.9已不支援所有API。

壓縮版本的的jQuery Migrate（遷移）外掛程式，不會在瀏覽器控制台中產生任何不相容或刪除等資訊，並且可以在jQuery 1.9或更高版本，或者舊的不相容的jQuery代碼或外掛程式中使用。

理想情況下，這將只能作為一個短期的解決方案，但是這要你自己做出決定。

更多的資訊請參見： jQuery Migrate plugin。

譯者註：哥過一句嘴，儘早的修改原來不相容的代碼，畢竟使用jQuery Migrate（遷移）外掛程式不是一個長久之計啊。

jQuery1.9中改變的地方

下面列表中說的並不代表jQuery 1.9中所有改變，只是我們預期的改變。完整的，詳細的更改列表，請參閱jQuery的部落格或訪問bugs.jquery.com中發布的公告。

.toggle(function, function, … ) 方法刪除

這個方法綁定兩個或多個處理常式到匹配的元素，用來執行交替的點擊事件。因為它沒有過時。前者被刪除，以減少混亂和提高模組化程度。jQuery Migrate（遷移）外掛程式可以恢複此功能。

jQuery.browser() 方法刪除

jQuery.browser()方法從jQuery 1.3開始已經過時了，在1.9中被刪除。 如果需要的話，jQuery Migrate（遷移）外掛程式可以恢複此功能。我們建議如特徵檢測，請使用Modernizr庫。

.live() 方法移除

.live()方法從jQuery 1.7開始已經過時了，在1.9中被刪除。 我們建議使用.on()方法來替換升級你的代碼。要完全符合$(“a.foo”).live(“click”, fn)，例如，你可以寫$(document).on(“click”, “a.foo”, fn)（譯者註：因為原來的live事件其實是綁定在文檔document上的）。在此期間，你可以使用jQuery Migrate（遷移）外掛程式來恢複.live() 功能。

.die() 方法移除

.die()方法從jQuery 1.7開始已經過時了，在1.9中被刪除。 我們建議使用. off()方法來替換升級你的代碼。要完全符合$(“a.foo”).die(“click”)，例如，你可以寫$(document).off(“click”, “a.foo”)。在此期間，你可以使用jQuery Migrate（遷移）外掛程式來恢複. die() 功能。

jQuery.sub() 方法移除

jQuery.sub()方法被移到jQuery Migrate（遷移）外掛程式中。使用的頻率證明它沒有必要再保留在核心程式碼程式庫中，jQuery Migrate（遷移）外掛程式添加了此功能。

.add() 方法修改

.add()方法返回的結果總是按照節點在document（文檔）中的順序排列。在1.9之前，如果上下文或輸入的集合中任何一個以脫離文檔的節點（未在文檔中）開始，使用.add()方法節點不會按照document（文檔）中的順序排序。現在，返回的節點按照文檔中的順序排序，並且脫離文檔的節點被放置在集合的末尾。

.addBack(selector) 替換 .andSelf()

從jQuery1.8開始，.andSelf()方法已經被標註過時，在jQuery1.8和更高版本中應使用.addBack()。

我們認為對於“添加並返回”以前的結果集合這是一個更好的名字。新方法可以接受一個可選的選取器，該選取器可以用來過濾之前集合，將它添加到當前集合并返回。$(“section, aside”).children(“ul”).addBack(“aside”) 會根據他們在文檔中的順序，得到section與aside下所有ul子項目，外加所有aside元素。雖然.addSelf()在1.9中仍然可以使用，我們建議您儘快修改名稱。如果使用.addSelf()，jQuery Migrate外掛程式會提出警告。

.after(), .before(), 和 .replaceWith()使用脫離文檔的節點

1.9以前，.after(), .before(), 和 .replaceWith()將嘗試在當前的jQuery集合中添加或改變節點，如果在當前的jQuery集的節點未串連到文檔（註：即脫離文檔的節點），在這種情況下，返回一個新的jQuery集合，而不是原來的那個集合。這將產生一些前後矛盾和徹底的錯誤 – 該方法可能會，也可能不會返回一個新的結果，這取決於它的參數！從1.9開始，這些方法總是返回原始未修改集並且試圖在一個沒有父節點的節點上使用.after(), .before(), or .replaceWith() 有沒有任何效果 – 即這個集或它包含的節點兩者都不被改變。

.appendTo, .insertBefore, .insertAfter, 和 .replaceAll

在1.9中，這些方法總是返回一個新的集合，使他們可以使用的鏈式調用和.end()方法。1.9之前，只有當他們是一個單獨的目標元素時，他們將返回舊的集合。需要注意的是這些方法總是返回所有元素附加到目標元素的彙總集合。如果沒有元素被目標選取器選中（例如，$(elements).appendTo(“#not_found”)）那麼返回的集合是空的。

AJAX 事件需要綁定到document

在jQuery 1.9中， 全域的AJAX事件(ajaxStart, ajaxStop, ajaxSend, ajaxComplete, ajaxError, and ajaxSuccess) 只能在document元素上觸發。修改AJAX事件監聽程式到document元素上。例如，如果目前的代碼看起來像這樣：

$("#status").ajaxStart(function(){ $(this).text("Ajax started"); });

修改成：

$(document).ajaxStart(function(){ $("#status").text("Ajax started"); });

.trigger() “click” 事件時Checkbox/radio 的狀態

當使用者點擊一個複選框或選項按鈕時，如果節點上沒調用event.preventDefault(),事件處理常式中會根據複選框或單選按的目前狀態判斷並且得到它的新狀態。因此，例如，如果使用者點擊一個未選中的checkbox，事件處理常式將選中（checked）這個checkbox。1.9之前，.trigger(“click”) 或 .click()任何一個將觸發一個合成事件，根據使用者點擊行為，我們可以看到checkbox與實際checked屬性相反的狀態。在1.9中修複了這個bug，使用者行為會得到相應的狀態。

focus事件觸發順序

當使用者再表單元素上點擊或者按tab鍵，使元素擷取焦點，瀏覽器首先在焦點元素上觸發一個blur(失去焦點)事件，然後在新元素上觸發一個focus(擷取焦點)事件。在1.9之前，使用.trigger(“focus”) 或 .focus() 綁定一個focus事件，新元素將觸發一個focus事件，然後觸發先前焦點元素的blur事件，1.9已修正此問題。

如果目標元素沒有擷取焦點並且可以成功的擷取焦點（譯者註：比如disabled被禁用的表單元素擷取不到焦點），那麼使用DOM原生的focus事件，瀏覽器只訪問focus事件處理常式。jQuery總是調用.trigger(“focus”) 或 .focus()綁定的處理常式，無論元素是否擷取焦點。在jQuery 1.9中還是這樣處理的。和DOM的.focus()方法不同之處在於，在許多情況下，元素已經擷取焦點或者元素被禁用，DOM的.focus()方法不會呼叫事件處理常式。

不幸的是，所有版本的Internet Explorer（6-10）觸發焦時間點事件是非同步。當你在IE中使用.trigger(“focus”)，jQuery無法“預知”非同步focus事件以後會發生什麼。所以它總是會觸發一個自己的focus事件，以確保功能正常。這可能會造成focus事件重覆執行，建議改用DOM內建的focus()較單純，例如: $(“#boo”).get(0).focus()。

jQuery(htmlString)與jQuery(selectorString)

在1.9以前，如果一個字串中有任何HTML標籤，那麼這個字串將被認為是一個HTML字串。這有可能造成意外的代碼執行和拒絕有效選取器字串。 1.9開始，以一個小於符號（“<”）字元開頭的字串才被認為是HTML字串。Migrate（延遲）外掛程式可以恢複到1.9以前的行為。

如果一個字串被認為是HTML，但可能會以不是一個HTML標籤的任意文本開始，將它傳遞給jQuery.parseHTML（）將返回一個DOM節點數組表示的標記。我們可以通過它來建立一個jQuery集合，例如：$($.parseHTML(htmlString))。例如，在處理HTML模板方面這被認為是最佳實務。簡單使用文字字串，如$(“<p>Testing</p>”).appendTo(“body”)不會受此影響。

總之：HTML字串傳遞給jQuery()，除了以一個小於符號（“<”）字元開始以外的其他字串都將被解釋為一個選取器。因為字串通常不能被解釋為一個選取器，最有可能的結果是Sizzle選取器引擎錯誤拋出的“無效的選取器文法”。使用jQuery.parseHTML（）來解析任意的HTML。

使用jQuery Migrate（遷移）外掛程式，如果該字串傳遞給$()，“看起來像HTML”，它會使用舊的規則來確定。

.data()中名稱包含點(“.”)改變

.data()有一個未公開並且令人難以置信的非高效能監控值的設定和擷取，1.9中被移除。這已經影響到了包含點的資料名稱的解析。從1.9開始，調用 .data(“abc.def”)只能通過名稱為“abc.def”檢索資料，原本還可以通過“abc”取得的技巧已被取消。需要注意的是較低層級的jQuery.data()方法不支援事件，所以它並沒有改變。即使使用jQuery Migrate（遷移）外掛程式也恢複不到原來的行為。

脫離文檔節點在jQuery集合中的順序

對於許多版本，幾乎所有的jQuery的方法，返回一組新的節點集合，這個集合是一個使用他們在文檔中順序排序的結果集。（有幾個方法，如.parents()返回的結果是他們在文檔反向順序排序，但在1.9中這些例外情況已經記錄並沒有改變。）

在1.9之前，若jQuery集合中混雜DOM的節點及未放進DOM的脫離文檔節點，則可能出現不可預期的隨機排序。從1.9開始，在文檔中的串連節點都總是按文檔順序放置在集合的開頭，脫離文檔節點被放置在他們的後面。即使使用jQuery Migrate（遷移）外掛程式也恢複不到原來的行為。

載入並且執行HTML內容中的scripts

在1.9之前，任何接受HTML字串的方法（例如，$()、.append()、.wrap()）會執行HTML字串中所包含的Script，並且將它們從文檔中移除，以防止他們再次被執行。在特殊情況下，使用這些方法一個指令碼可能會被移除並重新插入到文檔中，比如.wrap()。從1.9開始，插入到文檔的指令碼會執行，但仍然保留在文檔中並且標記為已經被執行過的，這樣它們就不會被再次執行，即使它們被刪除並重新插入。

儘管這種變化，在HTML標記中混合可執行檔JavaScript是非常不好的習慣；它對設計，安全性，可靠性和效能有影響。例如，外部指令碼標籤包含在HTML中同步地取出，然後評估執行，這可能需要大量的時間。沒有任何介面通知這些指令碼何時何地載入，或者當有錯誤產生的時候獲得糾正提示。

試圖通過複製一個現有的指令碼標籤載入和注入指令碼，複製到文檔將不再起作用，因為複製的指令碼標記已經被標記為已執行。要載入一個新的指令碼，建議使用jQuery.getScript()代替。

.attr() 和 .prop()對比

jQuery 1.6 介紹了.prop()方法設定或擷取節點上的對象屬性（property），並且不建議使用.attr()方法設定對象屬性（property）。然而版本一直到1.9，在某些特殊情況下繼續支援使用.attr()方法。當選取器是用來區分標籤屬性（attributes）和對象屬性（properties）時，這種行為在向後相容的命名方面會引起混亂。

例如，一個複選框的布爾標籤屬性（attributes），如checked和disabled受到這種變化的影響。”input[checked]“的正確行為是選擇有checked屬性的複選框，不管是它的字串值，還是它當前的狀態。與此相反， “input:checked” 選擇當前checked屬性的布爾值（true或false）為true的複選框，例如當使用者單擊複選框時，會受到影響。1.9之前版本這些選取器有時不選擇正確的節點。

這裡有一些例子，當在複選框上設定一個checked屬性時正確的和不正確的使用方法；同樣的規則也適用於disabled屬性。請注意只有對象屬性（property）在所有的瀏覽器始終反映和更新的複選框的目前狀態；你很少會需要設定的屬性（attribute）。

// Correct if changing the attribute is desired$(elem).attr("checked", "checked");// Correct for checking the checkbox$(elem).prop("checked", true);// Correct if removing the attribute is desired$(elem).removeAttr("checked");// Correct for clearing the checkbox$(elem).prop("checked", false);

input元素的特性（property）和標籤屬性（attribute）是這個歧義的另一個例子。標籤屬性（attribute）一般體現讀取HTML標記的值；屬性反映了當前值。由於.val()方法是jQuery推薦的用來擷取或設定表單元素的值的方式，這種混淆通常不會影響使用者。

然而，當一個選取器，如”input[value=abc]” 被使用，它應該始終選擇的value標籤屬性（attribute）並且使用者對於對象屬性（property）沒有任何改變，例如，從這些選取器中鍵入到一個文本輸入框。從jQuery 1.9開始，此行為正確並且一貫的。早期jQuery版本當應該使用標籤屬性（attribute），有時會使用他們的對象屬性（property）。

jQuery Migrate（遷移）外掛程式可以恢複原來的對象屬性（property）和標籤屬性（attribute）規則。

老IE中的$(“input”).attr(“type”, newValue)

在1.9版之前， 在所有的瀏覽器中，任何企圖設定一個input或者button元素的類型（type屬性），jQuery都將拋出一個異常。這樣做時為了符合最低標準的相容；因為如果你試圖改變input元素的類型，IE6/7/8拋出一個錯誤。從 jQuery 1.9開始，如果瀏覽器允許的話，我們允許您設定元素的類型。但是，你需要知道自己的代碼，在老IE（IE6/7/8）下試圖做到這一點還是會拋出一個錯誤。當你試圖設定類型屬性時，jQuery Migrate（遷移）外掛程式會發出警告，但不會拋出一個JavaScript錯誤。

“hover”偽事件

從1.9開始，事件名稱字串“hover”不再支援為“mouseenter mouseleave”的代名詞縮寫。允許應用程式綁定和觸發自訂的”hover”事件。修改現有的代碼是一個簡單的尋找/替換，並且jQuery Migrate（延遲）外掛程式可以恢複”hover”偽事件。

jQuery對象上的.selector屬性

jQuery對象上過時的selector屬性保留的目的是為了支援過時的.live()事件。在1.9中，jQuery不再試圖在鏈方法上保留這個屬性，因為1.9已經移除了.live()事件。不要使用jQuery對象的.selector屬性。jQuery Migrate（遷移）外掛程式也沒支援這個屬性。

jQuery.attr()

1.9版移除了jQuery.attr(elem, name, value, pass)方法，用jQuery Migrate（遷移）外掛程式可恢複這個方法。

jQuery.ajax返回一個Null 字元串的JSON結果

1.9之前，一個AJAX調用預期返回JSON或JSONP的資料類型，當傳回值是一個Null 字元串時會被認為是成功的狀態，但返回一個null給success處理常式或承諾（promise）。從1.9開始，JSON資料返回一個Null 字元串被認為是畸形的JSON（因為它本來就是）;這將拋出一個錯誤。這種情況下，使用error（錯誤）處理常式捕獲。

jQuery.proxy()

1.9版前，$.proxy(null, fn)、$.proxy(undefined, fn)的this會指向window，而$.proxy(false, fn)的this則指向new Boolean(false) ；1.9起若context傳入null/undefined/false，函數的this會維持原先context，不被改變。

.data(“events”)

1.9以前,如果沒有其他的代碼定義一個名稱為“events”的資料元素，.data(“events”) 可以用來檢索一個元素上，jQuery未公開的內部事件數目據結構。這種特殊的情況，在1.9中已被刪除。沒有公用的介面來擷取這個內部資料結構，

它是不公開的。jQuery Migrate（遷移）外掛程式可以恢複原來的行為。

移除Event對象的部分屬性

Event對象的attrChange、attrName、realtedNote和srcElement屬性自1.7版因無法跨瀏覽器已被宣告過時；從jQuery 1.9開始，它們不再被複製到Event對象傳遞給事件處理常式。在jQuery所有版本中，這些屬性依然可以在支援他們的瀏覽器上通過event.orginalEvent存取，以取代event。jQuery Migrate（遷移）外掛程式在Event對象有加回了這些屬性。

API方法未公開的參數

1.9之前，幾個API方法未公開改變了他們的行為的參數，並存在潛在的意外誤用。這些參數已經被刪除。受影響的方法包括jQuery.data()，jQuery.removeData()，和jQuery.attr()。jQuery Migrate（遷移）外掛程式也不支援的代碼。

其他未公開的屬性和方法

下面的內部屬性和方法從未被收入到文檔，並已在1.9中刪除。

• jQuery.deletedIds
• jQuery.uuid
• jQuery.attrFn
• jQuery.clean()
• jQuery.event.handle()
• jQuery.offset.bodyOffset()