jQuery Core 3.0 升级指南

链接 概览

随着 3.0 大版本的发布，jQuery Core 团队借此机会对 API 进行了清理并修复了漏洞，这对于某些代码来说可能是重大变更。这包括移除之前已弃用的公开 API、更改或移除未公开的 API，以及针对特定输入更改现有 API 的已公开或未公开行为。

link 浏览器支持

自 jQuery 3.0 起，支持以下浏览器

  • Internet Explorer: 9+
  • Chrome, Edge, Firefox, Safari: 当前版本及前一个版本 (Current and Current - 1)
  • Opera: 当前版本
  • Safari Mobile iOS: 7+
  • Android 4.0+

jQuery 团队的政策是仅在重大版本更新时更改浏览器支持，因此此列表将至少适用至 jQuery 4 发布。

链接 jQuery Migrate 插件

与 jQuery 1.9/2.0 中的重大变更一样，我们创建了新版本的 jQuery Migrate 插件，以简化旧代码向 3.0 版本的迁移。我们强烈建议您将此插件用作升级工具，它将针对可能影响您代码的大多数主要变更提供具体建议。

jQuery Migrate 插件 3.0 版本 不会 警告或恢复在之前的重大版本变更（如 jQuery 1.9/2.0）中移除的行为。请按照以下步骤从低于 1.11.0 或 2.1.0 的 jQuery 版本升级到新的 3.0 版本

  1. 将页面上的 jQuery 版本升级到最新的 1.x 或 2.x 版本。
  2. 在页面中添加未压缩的 jQuery Migrate 1.x 插件。
  3. （可选但推荐）更新所有正在使用的插件，因为较新版本通常与最近的 jQuery 版本最兼容。
  4. 测试页面并解决控制台中出现的任何警告，以 JQMIGRATE 1.x 警告文档 为指南。
  5. 移除 jQuery Migrate 1.x 插件，确保页面上更新后的 jQuery 代码在仅使用最新 jQuery 1.x/2.x 的情况下继续正常工作。
  6. 将页面上的 jQuery 版本升级到最新的 3.x 版本，并在页面中添加未压缩的 jQuery Migrate 3.x 插件。
  7. 测试页面并解决控制台中出现的任何警告，以 JQMIGRATE 3.x 警告文档 为指南。将第三方插件中的任何错误报告给插件作者。
  8. 移除 jQuery Migrate 3.x 插件，确保页面在仅使用最新 jQuery 3.x 的情况下继续正常工作。

不支持在同一页面上同时运行 Migrate 1.x 和 Migrate 3.x。

Migrate 插件的未压缩开发版本包含控制台日志输出，可在使用特定的已弃用和/或已移除功能时发出警告。这使其成为一种有价值的迁移调试工具，用于查找和修复现有 jQuery 代码及插件中的问题。

Migrate 插件的压缩版本不会生成任何警告，尽管它会发出一条单独的控制台消息表示已安装，以简化调试。当需要使用 jQuery 3.0 或更高版本，但还必须使用旧的不兼容 jQuery 代码或插件时，可以在生产网站上使用 Migrate。理想情况下，这仅作为短期解决方案，因为恢复旧行为可能会与期望新行为的新 jQuery 代码产生冲突。

link 重要变更摘要

对于像 jQuery 这样广泛使用的库，团队通常很难在发布之前了解哪些变更对开发者的影响最大。尽管此列表很长，但我们相信其中大部分属于边缘情况。许多 jQuery 项目应该只需进行微小改动（甚至无需改动）即可运行 3.0 版本。

变更按其组件类别列出，并附有前缀说明以帮助您了解其影响

  • 重大变更 (Breaking change)： 此变更 可能 会影响现有代码，因为它以某种方式改变了 API 表面。大多数情况下，其影响仅限于注明的特定边缘情况。
  • 特性 (Feature)： 该变更是 API 的新增内容，在大多数情况下不应影响现有代码。但是，新特性仍有可能与现有代码产生负面交互。
  • 已弃用 (Deprecated)： 此功能或 API 在 jQuery 3.0 中仍然存在，但不鼓励使用。它可能会在未来的重大版本更新中被移除。

请记住，上述 jQuery Migrate 插件可以检测并警告其中许多变更，以便在您的代码中进行修复。

有关所有代码变更的完整详细列表，请参阅 jQuery Core 问题追踪器 中的 3.0 里程碑或 版本差异 (diff)。

link Ajax

link 重大变更：从 jQuery.ajax 中移除特殊情况的 Deferred 方法

从 jQuery.ajax() 返回的 jqXHR 对象是一个 jQuery Deferred 对象，历史上它额外拥有三个名称与 success、error 和 complete 参数对象相匹配的方法。这常使那些未意识到返回对象应被视为 Deferred 的开发者感到困惑。自 jQuery 3.0 起，这些方法已被移除。作为替代方案，请使用 Deferred 的标准方法 done、fail 和 always，或者使用符合 Promises/A+ 规范的新 then 和 catch 方法。

请注意，这对于通过 options 对象传递的同名 ajax 回调没有任何影响，它们仍然存在且未被弃用。这仅影响 jqXHR 方法。

https://github.com/jquery/jquery/issues/2084

link 重大变更：必须声明跨域脚本请求

当通过 jQuery.ajax() 或 jQuery.get() 请求非当前托管文档域名下的脚本时，您现在必须在选项中明确指定 dataType: "script"。这可以防止潜在的攻击：即远程站点传送非脚本内容，但稍后决定提供具有恶意意图的脚本。由于 jQuery.getScript() 明确设置了 dataType: "script"，因此不受此变更影响。

link 重大变更：jQuery.ajax() 调用中会保留 URL 中的哈希值 (Hash)

如果提供的 URL 中包含哈希值，jQuery.ajax() 方法不再将其剥离，而是将完整 URL 发送给传输层（xhr、script、jsonp 或自定义传输）。如果连接另一端的服务器无法处理带有哈希值的 URL，请在发送请求前将其剥离。

https://github.com/jquery/jquery/issues/1732

link 特性：jQuery.get() 和 jQuery.post() 的新签名

jQuery 3 为 jQuery.get() 和 jQuery.post() 函数通过增加 settings 参数添加了新签名。它是一个可以包含多种属性的对象，与您可以提供给 jQuery.ajax() 的对象相同。

https://github.com/jquery/jquery/issues/1986

link 属性 (Attributes)

link 重大变更：.removeAttr() 不再将属性设置为 false

在 jQuery 3.0 之前，在 checked、selected 或 readonly 等布尔属性上使用 .removeAttr() 也会将相应的同名 属性 (property) 设置为 false。这种行为是古老版本 Internet Explorer 所需的，但对于现代浏览器来说是不正确的，因为 Attribute（特性）代表初始值，而 Property（属性）代表当前的（动态）值。

在 DOM 元素上使用 .removeAttr( "checked" ) 几乎总是一个错误。唯一有用的情况是稍后要将 DOM 序列化回 HTML 字符串。在所有其他情况下，应改为使用 .prop( "checked", false )。

https://github.com/jquery/jquery/issues/1759
https://github.com/jquery/jquery/issues/2913

link 重大变更：未选中任何项的多选框 (select-multiple) 返回空数组

在 jQuery 3.0 之前，在未选中任何元素的情况下对 <select multiple> 元素调用 .val() 会返回 null。这很不方便，因为如果至少选中了一个值，返回值就会是一个数组。此外，如果所有选项都被禁用，jQuery 已经返回了空数组。为了提高一致性，现在未选中的情况也返回一个空数组。

https://github.com/jquery/jquery/issues/2562

link 特性：SVG 文档支持类操作

jQuery 从未完全支持过 SVG，且在 jQuery 3 中也并未改变。尽管如此，许多 jQuery 方法同样适用于 SVG 文档。自 jQuery 3 起，操作类名的各种方法（如 .addClass() 和 .hasClass()）已支持 SVG。

https://github.com/jquery/jquery/issues/2199

link 已弃用：不带参数的 .toggleClass() 和 .toggleClass( Boolean )

虽然文档中记录了这两种情况的签名，但其实际行为从未被完整定义。这种未定义的行为现已弃用，因此将不再记录。您可能会发现自己之前在意外地使用该功能，因为 .toggleClass( undefined ) 的行为与不带参数的调用相同，即使它是无效输入。

link 回调 (Callbacks)

link 特性：锁定回调仅阻止未来的列表执行

如果一个 Callback 对象拥有在 .fire() 后调用 .lock() 方法的处理函数，它仅会阻止回调列表未来的执行，而不会立即中止当前列表的执行。要停止当前执行，请使用 stopOnFalse 选项。

https://github.com/jquery/jquery/issues/1990

link 核心 (Core)

link 重大变更：jQuery 3.0 在严格模式下运行

由于 jQuery 3.0 支持的大多数浏览器都已经支持 "use strict"，因此 jQuery 现在是带着这一指令构建的。您的代码不被要求在严格模式下运行，因此大多数现有代码应该不需要任何更改。我们三年前遇到的一个特例是 ASP.NET 4.0 在其 __doPostBack() 方法中使用 arguments.caller.callee 尝试追踪调用栈。如果您仍在使用会这样做旧版本 ASP.NET，请继续使用 jQuery 2.x 或更早版本。现代浏览器通过 error.stack 支持堆栈跟踪，因此检查 arguments.caller.callee 绝非必要。

https://github.com/jquery/jquery/pull/3061
https://bugs.jquery.com/ticket/13335

link 重大变更：document-ready 处理程序现在是异步的

自 jQuery 1.6 以来，jQuery 中的 document-ready 处理一直由 jQuery.Deferred 实现驱动。作为 jQuery 3.0 与 Promises/A+ 标准对齐的一部分，document-ready 处理程序现在是异步调用的，即使在添加处理程序时文档已经处于就绪状态。这提供了一致的代码执行顺序，且独立于文档是否就绪。例如，考虑以下代码

1
2
3
4
 
$( function() {
   console.log( "ready" );
} );
console.log( "outside ready" );

在 jQuery 3.0 中，无论文档在执行点是否就绪，这都将始终先记录 "outside ready" 然后是 "ready"。早期版本可能会以任一顺序记录这些消息。

由于处理程序现在彼此独立执行，一个 document-ready 处理程序中的异常或失败不再阻止其他 document-ready 处理程序的运行。

在排除了 deferred 模块的自定义构建中，会使用 document-ready 代码的另一种替代实现。该实现支持 jQuery.ready promise，但它不是 jQuery.Deferred 对象，因此只能通过 jQuery.when() 使用。

https://github.com/jquery/jquery/issues/1823
https://github.com/jquery/jquery/pull/2891

link 重大变更：jQuery.isNumeric() 和自定义 .toString()

jQuery.isNumeric() 方法旨在用于原始数字和可被强制转换为有限数字的字符串。特别地，它不再尝试从拥有 .toString() 方法的对象中获取数字。需要对其他数值进行专门检查的用户应创建自己的验证函数。

https://github.com/jquery/jquery/issues/2662

link 重大变更：移除已弃用的 .context 和 .selector 属性

这些属性在 jQuery 1.9 中已弃用，因为它们仅用于已过时的 .live() 方法，且从未准确代表过当前集合的上下文或选择器。

https://github.com/jquery/jquery/issues/1908

link 重大变更：移除已弃用的 .size()

.size() 从 jQuery 1.8 起已弃用，并在 jQuery 3.0 中被移除，取而代之的是 .length 属性。

link 重大变更：不再公开未公开的内部方法

3.0 版本从视野中移除了几个原本打算作为私有且从未被记录的方法

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

https://github.com/jquery/jquery/issues/2224
https://github.com/jquery/jquery/issues/2225

link 重大变更：空集合的返回值为 undefined

为了符合我们的 API 指南，除了少数例外，任何有返回值的 jQuery 方法在空 jQuery 集合上都应返回 undefined。以下 API 已更改以符合此规则

  • 尺寸方法：.width(), .height(), .innerWidth(), .innerHeight(), .outerWidth(), 和 .outerHeight()
  • 偏移方法：.offsetTop() 和 .offsetLeft()

此前，这些方法对空集合返回 null 而非 undefined。

https://github.com/jquery/jquery/issues/2319

link 特性：for...of 循环可用于 jQuery 集合

jQuery 3.0 支持 ES2015 中引入的 for...of 循环。它允许遍历包括 Array、Map 和 Set 在内的可迭代对象。使用此循环时，获得的值是 jQuery 集合中的 DOM 元素，一次一个。请注意，您需要使用支持 ES2015 的环境或类似 Babel 的转译器才能使用 for...of。示例如下

1
2
3
4
5
6
7
8
9
10
11
 
var elems = $( ".someclass" );
 
// Classic jQuery way
$.each( function( i, elem ) {
  // work with elem (or "this" object)
} );
 
// Prettier ES2015 way
for ( let elem of elems ) {
  // work with elem
}

https://github.com/jquery/jquery/issues/1693

link 特性：正式支持 jQuery.ready promise

自 jQuery 1.8 版本起，jQuery.ready 就可以作为一个类 promise 对象（Promise 术语中称为 "thenable"）来使用。自 jQuery 3.0 起，该对象被记录为支持通过 jQuery.when 或原生的 Promise.resolve() 使用。任何代码都不应假设此对象是 jQuery Deferred 还是其他类型的 promise 对象（如原生 Promise）。典型用法如下

1
2
3
4
5
 
$.when( $.ready, $.getScript( "optional.js" ) ).then( function() {
   // the document is ready and optional.js has loaded/run
} ).catch( function() {
   // an error occurred
} );

https://github.com/jquery/api.jquery.com/pull/530

link 已弃用：jQuery.unique()，已重命名为 jQuery.uniqueSort()

jQuery.unique() 方法已重命名为 jQuery.uniqueSort()，以使其行为更容易理解。功能上没有变化，仅是更名。

link 已弃用：jQuery.parseJSON()

由于 jQuery 3.0 支持的所有浏览器都支持原生的 JSON.parse() 方法，我们正弃用 jQuery.parseJSON()。

https://github.com/jquery/jquery/issues/2800

link 已弃用：除 jQuery( function ) 以外的 document-ready 处理程序

由于历史兼容性问题，设置文档就绪处理程序的方式有很多种。以下所有方式都是等效的，并会在文档就绪时调用函数 fn

1
2
3
4
 
$( fn );
$().ready( fn );
$( document ).ready( fn );
$( "selector" ).ready( fn );

自 jQuery 3.0 起，推荐添加就绪处理程序的方式是第一种：$(fn)。正如“事件”部分所述，$( document ).on( "ready", fn ) 事件形式具有略微不同的语义，且已在 jQuery 3.0 中移除。

link 数据 (Data)

link 重大变更：包含连字符的 .data() 名称

自 jQuery 3.0 起，所有数据名称都以小驼峰式 (camelCase，例如 clickCount) 而非短横线隔开式 (kebab-case，例如 click-count) 存储在 jQuery 的内部数据对象中。这与标准 DOM 在 CSS 和 data 属性中将带连字符的名称转换为 JavaScript 驼峰式名称的方式一致。

通常情况下，在 jQuery 3.0 中设置或获取特定数据项时，短横线命名法仍然有效（例如 .data( "right-aligned" )），但如果您检索内部数据对象，它现在将以驼峰式 (rightAligned) 包含该数据项。3.0 中的主要区别在于，如果您直接在数据对象上使用短横线名称，而不是使用 .data() API 来获取或设置它们时会出现差异。

例如

1
2
3
4
5
6
7
8
9
10
11
12
13
14
 
var $div = $( "<div />" );
$div.data( "clickCount", 2 );
$div.data( "clickCount" ); // 2
$div.data( "click-count", 3 );
$div.data( "clickCount" ); // 3
$div.data( "click-count" ); // 3
 
var allData = $div.data();
allData.clickCount; // 3
allData[ "click-count" ]; // undefined
allData[ "click-count" ] = 14;
$div.data( "click-count" ); // 3, NOT 14 as it would be in jQuery 2.x
allData.clickCount; // 3
allData[ "click-count" ]; // 14

https://github.com/jquery/jquery/issues/2070
https://github.com/jquery/jquery/issues/2257
https://github.com/jquery/jquery/issues/1751

link Deferred (延迟对象)

link 重大变更与特性：jQuery.Deferred 现在兼容 Promises/A+

Deferred 已针对 Promises/A+ 和 ES2015 (又名 ES6) Promise 兼容性进行了更新，这一更改具有重大影响。

https://github.com/jquery/jquery/issues/1722
https://github.com/jquery/jquery/issues/2102

link 解析 (Resolution)

.resolve、.reject 和 .notify 现在会设置 undefined 上下文，而不是使用与其关联的 Deferred 对象的 promise。要设置明确的上下文，请使用 .resolveWith、.rejectWith 和 .notifyWith。

https://github.com/jquery/jquery/issues/3060

link 回调退出

.then() 方法发生了重大变化。特别是，在 .then() 回调中抛出的任何异常现在都会被捕获并转换为拒绝值 (rejection value)，并且从 拒绝 (rejection) 处理程序返回的任何非 thenable 值都会变成兑现值 (fulfillment value)。我们强烈建议您在 promise 链的末尾添加一个 .catch() 方法（3.0 中新增），以避免难以调试的问题。您最可能遇到这种新行为的地方是使用由 jQuery.ajax() 产生的 Deferred，因为返回的 jQXHR 对象是 jQuery.Deferred 的超集。

在 jQuery 1.x 和 2.x 中，回调函数内未捕获的异常会停止代码执行。抛出的异常会向上冒泡，直到在 try/catch 中被捕获，或者到达 window 并触发 window.onerror。

例如，考虑以下使用新标准 Promises/A+ 行为的代码

1
2
3
4
5
6
7
8
9
10
 
$.ajax( "/status" )
   .then( function( data ) {
      whoops();
      // console shows "jQuery.Deferred exception: whoops is not a function"
      // no further code executes in this function
   } )
   .catch( function( arg ) {
      // this code executes after the error above
      // arg is an Error object, "whoops is not a function"
   } );

将其与旧式的 Deferred 方法进行对比

1
2
3
4
5
6
7
8
9
 
$.ajax( "/status" )
   .done( function( data ) {
      whoops();
      // console shows: "whoops is not a function"
      // no further code executes in this function
   } )
   .fail( function( arg ) {
      // this code does not execute since the exception was not caught
   } );

请注意，当在 Deferred 内部发生 JavaScript 异常时，jQuery 会向控制台记录一条消息。这些消息的形式为 jQuery.Deferred exception: (错误消息)。如果您不希望在这些异常上产生任何控制台输出，请将 jQuery.Deferred.exceptionHook 设置为 undefined。如果您在查找以此方式报告的错误时需要进一步帮助，请在开发期间使用 jquery-deferred-reporter 插件 以获取堆栈跟踪。

https://github.com/jquery/jquery/issues/2736

link 回调调用

Promises/A+ 规范规定，promise 始终以 单个值 解析，且调用处理程序时没有 this 上下文，而 jQuery Deferred 有时会向其处理程序传递上下文和/或多个值。但在大多数情况下，第一个参数是这些值中最重要的。如果您将其他 Promises/A+ 实现与 jQuery 的实现混合使用，您的处理程序可能只会接收到一个参数。为了保持现有代码的完全兼容性，请仅使用 jQuery Deferred，并切换到旧的 .done() 和 .fail() 方法，这些方法保留了所有向后兼容的行为。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
 
// Typical old uses of .then() that are not Promises/A+ compatible
$.ajax( "url" ).then(
    // success
    function( data, textStatus, jqXHR ) { /* code */ },
    // error
    function( jqXHR, textStatus, errorThrown ) { /* code */ }
);
 
// Rewrite to this in order to maintain previous behavior
$.ajax( "url" )
    // success
    .done( function( data, textStatus, jqXHR ) { /* code */ } )
    // error
    .fail( function( jqXHR, textStatus, errorThrown ) { /* code */ } );

Promises/A+ 合规性所需的另一个行为变化是，Deferred 的 .then() 回调 始终 是异步调用的。此前，如果向一个已经解析 (resolved) 或拒绝 (rejected) 的 Deferred 添加 .then() 回调，该回调会立即同步运行。

link 向后兼容性

.done()、.fail() 和 .pipe() 等 Deferred 方法保留了旧行为，因此不符合 Promises/A+ 规范。如果您需要同步解析，不希望异常转换为拒绝值，不希望拒绝回调的返回转换为兑现值，或者希望抛出的错误能从发生函数中冒泡出来，您可以使用这些方法替代 .then() 和 .catch()。

link 重大变更与特性：jQuery.when() 参数

jQuery.when 现在会将任何带有 then 方法的输入参数解释为兼容 Promise 的 "thenable"。这允许更广泛的输入范围，包括原生的 ES6 Promise 和 Bluebird promise。

此外，现在对 jQuery.when 的多参数调用与单参数或无参数调用有了更清晰的区别。多参数调用的行为类似于 Promise.all，将兑现值聚合到一个兑现数组中（具有 jQuery 特有的增强功能，即同时也聚合兑现上下文并支持多值兑现），或者以第一个拒绝值进行拒绝。单参数和无参数调用的行为类似于 Promise.resolve，返回一个 Deferred，其解析方式与 thenable 或类 Promise 输入相同，或以其非 Promise 输入兑现（视情况而定）。自 jQuery 3.0 起，两者都会返回一个新的 Deferred（以前的版本在调用单个 Deferred 输入时不会创建新的 Deferred）。

https://github.com/jquery/jquery/issues/2018
https://github.com/jquery/jquery/issues/2546
https://github.com/jquery/jquery/issues/3029

link 重大变更：jQuery.when() 进度通知

自 jQuery 3.0 起，jQuery.when() 方法不再将输入 Deferred 的进度通知传递给输出 Deferred。进度消息不属于 Promises/A+ 规范的一部分，且 jQuery.when() 中的进度通知行为此前也未在 jQuery API 中记录。

https://github.com/jquery/jquery/issues/2710

link 尺寸 (Dimensions)

link 重大变更：.width()、.height()、.css( "width" ) 和 .css( "height" ) 可以返回非整数值

在 3.0 版本之前，jQuery 使用 DOM offsetWidth 和 offsetHeight 属性来确定元素的尺寸，而这些属性始终返回整数。通过 jQuery 3.0，我们通过 DOM getBoundingClientRect API 获得了更精确的值，这些值可能不是整数。如果您的代码始终期望尺寸为整数，则可能需要进行调整以处理这种额外的精度。

https://github.com/jquery/jquery/issues/1724

link 重大变更：window 上的 .outerWidth() 或 .outerHeight() 包含滚动条宽度/高度

对 $(window).width() 的调用会返回“内容宽度”，如果内容超过元素高度，这不包括浏览器添加的任何滚动条。这与 CSS 用于媒体查询的宽度不同，后者包含滚动条宽度。为了提供一个与 CSS 媒体查询宽度概念等效的测量值，$(window).outerWidth() 方法现在返回包含滚动条在内的宽度。这等同于 DOM 属性 window.innerWidth。.outerHeight() 同理。

https://github.com/jquery/jquery/issues/1729

link 特效 (Effects)

link 重大变更：.show()、.hide() 和 .toggle() 方法现在遵循更多的样式表更改

jQuery 用于显示和隐藏元素的代码已更新，重点关注内联样式而非计算样式，尽可能遵循样式表中的 display 值，以增强与响应式设计技术的兼容性（在响应式设计中，活动的样式表规则可以随设备方向改变/窗口缩放等动态变化）。因此，脱离文档流的元素不再被视为隐藏，除非它们具有内联的 display: none，因此自 jQuery 3.0 起，.toggle() 将不再区分它们与文档流内的元素。

此外，虽然 .show() 及类似调用将继续强制显示被样式表规则隐藏的元素，但支持此功能会减慢所有显示/隐藏操作，因此不建议使用。在此类情况下确定要设置哪个 display 值的逻辑也已简化，当 body 级别的规则按类型隐藏元素时，默认设置为 "block"。

任何期望隐藏元素以其之前的 计算 (computed) display 样式重新显示，或期望脱离文档流的元素被视为隐藏的代码，都应进行审查。团队创建了一个关于显示状态和显示/隐藏操作所有可能性的 表格，以尽量减少非空内联样式的设置。

link 特性：动画现在使用 requestAnimationFrame

在支持 requestAnimationFrame API 的平台（除 IE9 以外的几乎所有地方）上，jQuery 现在将在执行动画时使用该 API。这应该会使动画更流畅、占用更少的 CPU 时间，并在移动设备上节省电池。

几年前 jQuery 曾尝试使用 requestAnimationFrame，但由于与现有代码存在严重的兼容性问题，我们不得不将其撤回。我们认为通过在浏览器标签页不可见时暂停动画，已经克服了大部分问题。尽管如此，任何依赖动画始终近乎实时运行的代码都在做一种不切实际的假设。

link 已弃用：jQuery.fx.interval

既然 requestAnimationFrame 已用于动画，jQuery.fx.interval 属性在大多数浏览器中都会被忽略。它在 jQuery 3.0 中仍然存在并用于 IE9 等浏览器，但在未来的主要版本中将被移除。

link 已弃用：额外的缓动函数参数

由 .animate() 调用的缓动函数会被传递单个参数，即完成百分比。一些较旧的代码假设它会被传递由百分比衍生的额外参数。在未来的重大版本更新中，这些其他参数可能不再存在。

旧缓动方法示例

1
2
3
 
$.easing.easeInOutSine = function( x, t, b, c, d ) {
  return -c / 2 * ( Math.cos( Math.PI * t / d ) - 1 ) + b;
};

重写后的相同缓动方法

1
2
3
 
$.easing.easeInOutSine = function( x ) {
  return -0.5 * ( Math.cos( Math.PI * x ) - 1 );
};

https://github.com/jquery/api.jquery.com/issues/912

link 事件 (Event)

link 重大变更：移除 .load()、.unload() 和 .error()

这些方法是事件操作的快捷方式，但存在若干 API 限制。事件 .load() 方法与 ajax .load() 方法冲突。由于 DOM 方法定义方式的原因，.error() 方法无法与 window.onerror 一起使用。如果您需要通过这些名称附加事件，请使用 .on() 方法，例如将 $( "img" ).load( fn ) 更改为 $( "img" ).on( "load", fn )。

https://github.com/jquery/jquery/issues/2286

link 重大变更：移除 .on( "ready", fn )

jQuery 不再支持名为 "ready" 的合成事件。该事件容易出错且在 jQuery 1.8 中已弃用，因为它只有在文档就绪之前附加时才会调用回调。请将其任何用法替换为 $(fn)，这种方式可以可靠地工作。

https://github.com/jquery/jquery/issues/2264

link 重大变更：移除 event.pageX 和 event.pageY 规范化

jQuery 3.0 正式支持的所有浏览器都在其事件中提供了 pageX 和 pageY 属性，因此从其他事件属性计算这些值的 jQuery 代码已被移除。此更改不应影响主流浏览器，但在某些罕见环境中这些属性可能不存在。如果您发现此类情况，请提交 issue。

https://github.com/jquery/jquery/issues/3092

link 重大变更：移除 jQuery.event.props 和 jQuery.event.fixHooks

由于重新组织了事件属性管理，jQuery 的事件处理性能得到了提升。主要改进在于 jQuery 现在仅在第一次访问时才计算或复制属性，而不是预先计算并复制。对于那些可能强制布局而事件处理程序甚至可能不需要的属性，这是一个巨大的进步。我们已知的最常见用途是为指针事件添加属性，这在 jQuery 3.0 中已不再必要，因为这些事件已得到支持。如果您仍然需要这些属性，jQuery Migrate 插件提供了支持。相关但未公开的 mouseHooks 和 keyHooks 列表也被移除了。团队有兴趣在定义新 API 之前了解其他用例，欢迎提交 issue。

https://github.com/jquery/jquery/issues/3103
https://github.com/jquery/jquery/issues/1746
https://learn.jquery.org.cn/events/event-extensions/

link 重大变更：选择器错误的委托事件会 立即 抛出异常

在 jQuery 3.0 之前，委托事件中使用的选择器直到该事件第一次发生在元素上时才会被使用。这有时会导致难以调试的情况，即错误发生的时间和代码与出错的地方相隔甚远。现在，选择器在附加事件时就会进行测试，如果无效则抛出错误。将其视为重大变更的唯一原因是：代码可能会在附加从未发生的事件时使用无效选择器，而这种情况以前永远不会抛出错误。

https://github.com/jquery/jquery/issues/3071

link 已弃用：.bind() 和 .delegate()

五年前在 jQuery 1.7 中，我们引入了 .on() 方法来附加事件处理程序。旧的 .bind()、.unbind()、.delegate() 和 .undelegate() 方法自 3.0 起被弃用，但仍然存在。API 文档解释了如何使用 .on() 和 .off() 方法重写这些调用。

link 操作 (Manipulation)

link 重大变更：.wrapAll( function ) 仅调用一次函数

在之前的版本中，当传递函数时，.wrapAll() 方法的行为类似于 .wrap()。现在这一点已得到纠正；.wrapAll( function ) 仅调用其函数一次，并使用函数调用的字符串结果来包裹整个集合。

https://github.com/jquery/jquery/issues/1843

link 偏移 (Offset)

link 重大变更：.offset() 方法的无效输入

使用 .offset() 方法时，jQuery 集合中的第一项必须是具有 DOM getBoundingClientRect() 方法的 DOM 元素。（jQuery 3.0 支持的所有浏览器都具备此 API。）任何其他输入都可能导致 jQuery 抛出错误。另请注意，该元素必须是可见的且当前位于文档中（即未脱离文档流）。

https://github.com/jquery/jquery/issues/2115
https://github.com/jquery/jquery/issues/2114

link 选择器 (Selector)

link 重大变更：:hidden 和 :visible 的行为

如果一个元素由 DOM getClientRects() 方法返回了布局盒（layout box），即使该盒的高度和/或宽度为零，现在也被认为是可见的。这意味着像 <br /> 或没有高度的空 <span> 元素现在被认为是可见的。

https://github.com/jquery/jquery/issues/2227
https://github.com/jquery/jquery/issues/2604

link 重大变更：jQuery( "#" ) 和 .find( "#" ) 是无效语法

如果选择器字符串仅由一个井号组成，jQuery 3.0 会抛出语法错误。在之前的版本中，$("#") 返回一个空集合，而 .find( "#" ) 会抛出错误。

https://github.com/jquery/jquery/pull/1682

link 特性：新方法 jQuery.escapeSelector()

新的 jQuery.escapeSelector( selector ) 方法接收一个选择器字符串，并对在 CSS 选择器中具有特殊含义的任何字符进行转义。它本质上是 CSS 工作组 CSS.escape() 方法 的垫片 (shim)，可在 jQuery 支持的所有浏览器上运行。该方法在类名或 ID 包含 CSS 特殊含义字符（如点或分号）的情况下非常有用。

例如，如果页面上一个元素的 ID 为 "abc.def"，则不能使用 $( "#abc.def" ) 选中它，因为该选择器会被解析为“ID 为 'abc' 且同时具有类 'def' 的元素”。但是，可以使用 $( "#" + $.escapeSelector( "abc.def" ) ) 来选中它。

https://github.com/jquery/jquery/issues/1761

link 已弃用：jQuery.expr[":"] 和 jQuery.expr.filters

这两个用于通过 jQuery 的 Sizzle 选择引擎定义自定义选择器的名称与 jQuery.expr.pseudos 相同，因此我们正弃用这些冗余名称。

link 序列化 (Serialize)

link 重大变更：jQuery.param() 不再将 %20 转换为加号

在通过 jQuery.ajax() 提交的表单中，application/x-www-form-urlencoded 编码的 规范 指出，任何出现的空格都应转换为 + 字符。以前，jQuery 通过在 jQuery.param() 中进行转换来实现这一点。现在，该转换已移至 jQuery.ajax() 中。通过 jQuery.param() 编码的数据会将空格转换为 %20，这使其与原生 JavaScript 的 encodeURIComponent() 和 decodeURIComponent() 方法的使用直接兼容。

https://github.com/jquery/jquery/issues/2658

link 遍历 (Traversing)

link 重大变更：移除 .andSelf()，请使用 .addBack()

.andSelf() 方法在 jQuery 1.8 中已弃用，现已在 3.0 中移除，取而代之的是 .addBack() 方法，它能更好地解释其功能，并接受一个可选的选择器来过滤加回的内容。