jquery-4

jQuery 4.0 迁移

状态：已可用于生产环境 最后更新：2026-01-25 依赖项：无 最新版本：[email protected]，[email protected]

---

快速开始（5 分钟）

1. 添加 jQuery Migrate 插件以便安全测试

升级前，添加迁移插件以识别兼容性问题：

<script src="https://code.jquery.com/jquery-4.0.0.js"></script>
<script src="https://code.jquery.com/jquery-migrate-4.0.2.js"></script>

重要性：

• 执行已弃用或已移除的功能时，会记录具体警告
• 找出需要在出问题前更新的代码
• 在迁移期间提供向后兼容垫片

2. 通过 npm 安装（如果使用构建工具）

npm install [email protected]
# Or with migrate plugin for testing
npm install [email protected] [email protected]

3. 检查破坏性变更

运行应用并检查控制台中的迁移插件警告。每条警告都表示有代码需要更新。

---

破坏性变更参考

已移除的 jQuery 工具函数

这些函数已弃用，现已移除。请使用原生 JavaScript 替代方案：

已移除	原生替代方案
$.isArray(arr)	Array.isArray(arr)
$.parseJSON(str)	JSON.parse(str)
$.trim(str)	str.trim() 或 String.prototype.trim.call(str)
$.now()	Date.now()
$.type(obj)	typeof obj + Array.isArray() + instanceof
$.isNumeric(val)	!isNaN(parseFloat(val)) && isFinite(val)
$.isFunction(fn)	typeof fn === 'function'
$.isWindow(obj)	obj != null && obj === obj.window
$.camelCase(str)	自定义函数（见下文）
$.nodeName(el, name)	el.nodeName.toLowerCase() === name.toLowerCase()

camelCase 替代方案：

// Native replacement for $.camelCase
function camelCase(str) {
  return str.replace(/-([a-z])/g, (match, letter) => letter.toUpperCase());
}

已移除的原型方法

jQuery 对象中有三个内部数组方法已移除：

// OLD - No longer works in jQuery 4.0
$elems.push(elem);
$elems.sort(compareFn);
$elems.splice(index, count);

// NEW - Use array methods with call/apply
[].push.call($elems, elem);
[].sort.call($elems, compareFn);
[].splice.call($elems, index, count);

// Or convert to array first
const arr = $.makeArray($elems);
arr.push(elem);

focus/blur 事件顺序已更改

jQuery 4.0 遵循 W3C 规范规定的 focus 事件顺序：

// jQuery 3.x order (non-standard):
// focusout → blur → focusin → focus

// jQuery 4.0 order (W3C standard):
// blur → focusout → focus → focusin

影响：如果代码依赖特定的事件顺序，请务必全面测试。

// Example: code that may need adjustment
$input.on('blur focusout focus focusin', function(e) {
  console.log(e.type); // Order changed in 4.0
});

从精简版构建中移除

精简版构建（jquery-4.0.0.slim.min.js）不再包含：

• Deferred 和 Callbacks（请改用原生 Promises）
• AJAX 功能
• 动画效果

// If using slim build, replace Deferreds with Promises
// OLD - Deferred
const deferred = $.Deferred();
deferred.resolve(value);
deferred.promise();

// NEW - Native Promise
const promise = new Promise((resolve, reject) => {
  resolve(value);
});

toggleClass 变更

toggleClass(boolean) 和 toggleClass(undefined) 签名已移除：

// OLD - No longer works
$elem.toggleClass(true);   // Added all classes
$elem.toggleClass(false);  // Removed all classes

// NEW - Be explicit
$elem.addClass('class1 class2');    // Add classes
$elem.removeClass('class1 class2'); // Remove classes

// Or use toggleClass with class names
$elem.toggleClass('active', true);  // Force add
$elem.toggleClass('active', false); // Force remove

AJAX 脚本执行

通过 AJAX 获取的脚本不再自动执行，除非指定了 dataType：

// OLD - Scripts auto-executed
$.get('script.js');

// NEW - Must specify dataType for auto-execution
$.get({
  url: 'script.js',
  dataType: 'script'
});

// Or use $.getScript (still works)
$.getScript('script.js');

已移除的 CSS 属性

已移除	备注
$.cssNumber	已移除——如有需要，请在本地定义
$.cssProps	不再需要——供应商前缀已过时
$.fx.interval	已移除——此功能由 requestAnimationFrame 处理

---

WordPress 专项迁移

1. 检查 WordPress jQuery 版本

# Check current jQuery version in WordPress
wp eval "echo wp_scripts()->registered['jquery-core']->ver;"

2. WordPress jQuery 迁移路径

WordPress 主题/插件应当：

// Dequeue old jQuery and enqueue 4.0 (testing only)
function upgrade_jquery_for_testing() {
  if (!is_admin()) {
    wp_deregister_script('jquery-core');
    wp_deregister_script('jquery');

    wp_register_script('jquery-core',
      'https://code.jquery.com/jquery-4.0.0.min.js',
      array(), '4.0.0', true);

    wp_register_script('jquery', false, array('jquery-core'), '4.0.0', true);

    // Add migrate plugin for debugging
    wp_enqueue_script('jquery-migrate',
      'https://code.jquery.com/jquery-migrate-4.0.2.min.js',
      array('jquery'), '4.0.2', true);
  }
}
add_action('wp_enqueue_scripts', 'upgrade_jquery_for_testing', 1);

3. 常见 WordPress 插件问题

许多 WordPress 插件使用了已移除的 jQuery 方法：

// Common pattern in older plugins - BROKEN in 4.0
if ($.isArray(data)) { ... }
var json = $.parseJSON(response);
var cleaned = $.trim(userInput);

// Fix: Update to native methods
if (Array.isArray(data)) { ... }
var json = JSON.parse(response);
var cleaned = userInput.trim();

---

迁移模式

模式 1：类型检查迁移

// OLD jQuery type checking
if ($.type(value) === 'array') { ... }
if ($.type(value) === 'function') { ... }
if ($.type(value) === 'object') { ... }
if ($.type(value) === 'string') { ... }
if ($.type(value) === 'number') { ... }

// NEW Native type checking
if (Array.isArray(value)) { ... }
if (typeof value === 'function') { ... }
if (value !== null && typeof value === 'object' && !Array.isArray(value)) { ... }
if (typeof value === 'string') { ... }
if (typeof value === 'number') { ... }

模式 2：工具函数垫片

如果你需要快速兼容，而不想修改所有代码：

// Polyfill removed methods (temporary migration aid)
if (typeof $.isArray === 'undefined') {
  $.isArray = Array.isArray;
}
if (typeof $.parseJSON === 'undefined') {
  $.parseJSON = JSON.parse;
}
if (typeof $.trim === 'undefined') {
  $.trim = function(str) {
    return str == null ? '' : String.prototype.trim.call(str);
  };
}
if (typeof $.now === 'undefined') {
  $.now = Date.now;
}
if (typeof $.isFunction === 'undefined') {
  $.isFunction = function(fn) {
    return typeof fn === 'function';
  };
}
if (typeof $.isNumeric === 'undefined') {
  $.isNumeric = function(val) {
    return !isNaN(parseFloat(val)) && isFinite(val);
  };
}

重要：这只是临时措施。请更新代码，改用原生方法。

模式 3：ES 模块导入

jQuery 4.0 支持 ES 模块：

// ES Module import (new in 4.0)
import $ from 'jquery';

// Or with named export
import { $ } from 'jquery';

// In package.json, ensure module resolution
{
  "type": "module"
}

模式 4：Trusted Types 合规

针对启用了 Trusted Types 的 CSP：

// jQuery 4.0 accepts TrustedHTML in DOM manipulation
import DOMPurify from 'dompurify';

// Create trusted HTML
const clean = DOMPurify.sanitize(untrustedHTML, {RETURN_TRUSTED_TYPE: true});

// Safe to use with jQuery 4.0
$('#container').html(clean);

---

关键规则

务必做到

• 升级生产环境之前，先添加 jquery-migrate 插件
• 全面测试 focus/blur 事件处理程序
• 将已移除的工具函数替换为原生等效方法
• 加载 AJAX 脚本时指定 dataType: 'script'
• 现代项目尽可能使用 ES 模块导入

切勿

• 未先使用迁移插件测试就升级生产环境
• 假定 WordPress 插件兼容 jQuery 4.0
• 需要 AJAX 或 Deferred 时使用精简版构建
• 依赖 $.type()——请使用原生类型检查
• 使用 toggleClass(boolean) 签名

---

预防已知问题

此技能可预防 8 个已记录的问题：

问题 #1：$.isArray 不是一个函数

错误：TypeError: $.isArray is not a function 来源：https://github.com/jquery/jquery/issues/5411 原因：该方法已在 jQuery 4.0 中移除 预防措施：改用 Array.isArray()

问题 #2：$.parseJSON 不是一个函数

错误：TypeError: $.parseJSON is not a function 来源：https://jquery.com/upgrade-guide/4.0/ 原因：该方法自 3.0 起已弃用，并在 4.0 中移除 预防措施：改用 JSON.parse()

问题 #3：$.trim 不是一个函数

错误：TypeError: $.trim is not a function 来源：https://jquery.com/upgrade-guide/4.0/ 原因：原生的 String.prototype.trim 已在所有环境中可用 预防措施：使用 str.trim() 或 String.prototype.trim.call(str)

问题 #4：焦点事件触发顺序错误

错误：表单验证出现意外行为 来源：https://blog.jquery.com/2026/01/17/jquery-4-0-0/ 原因：jQuery 4.0 遵循 W3C 规范，而非旧版顺序 预防措施：测试并更新依赖事件顺序的事件处理程序

问题 #5：精简版构建中 Deferreds 未定义

错误：TypeError: $.Deferred is not a function 来源：https://blog.jquery.com/2026/01/17/jquery-4-0-0/ 原因：Deferreds 已从 4.0 的精简版构建中移除 预防措施：使用完整构建或原生 Promise

问题 #6：AJAX 加载的脚本未执行

错误：脚本已加载但未执行 来源：https://jquery.com/upgrade-guide/4.0/ 原因：未显式指定 dataType 时会禁用自动执行 预防措施：在 AJAX 选项中添加 dataType: 'script'

问题 #7：toggleClass 无效

错误：toggleClass(true) 不起作用 来源：https://jquery.com/upgrade-guide/4.0/ 原因：布尔值参数形式已移除 预防措施：使用 addClass/removeClass，或传入类名调用 toggleClass

问题 #8：WordPress 插件冲突

错误：出现各种“is not a function”错误 来源：WordPress 生态中常见 原因：插件使用了已移除的 jQuery 方法 预防措施：升级前使用 jquery-migrate 检查插件

---

浏览器支持

jQuery 4.0 支持的浏览器

• Chrome（最近 3 个版本）
• Firefox（最近 2 个版本 + ESR）
• Safari（最近 3 个版本）
• Edge（基于 Chromium）
• iOS Safari（最近 3 个版本）
• Android Chrome（最近 3 个版本）

已停止支持的浏览器

• IE 10 及更早版本（IE 11 将支持至 jQuery 5.0）
• Edge Legacy（EdgeHTML）
• 非常旧的移动浏览器

---

精简版与完整构建对比

功能	完整构建	精简版构建
大小（gzip 压缩后）	~27.5k	~19.5k
DOM 操作	是	是
事件	是	是
AJAX	是	否
效果/动画	是	否
Deferreds	是	否
Callbacks	是	否

适用精简版构建的情况：静态网站、不需要 AJAX、使用原生 fetch/Promises

适用完整构建的情况：WordPress、以 AJAX 为主的应用、需要 $.animate 或 Deferreds

---

迁移检查清单

• 在开发环境中添加 [email protected]
• 完整测试整个网站，检查控制台中的警告
• 将 $.isArray() 替换为 Array.isArray()
• 将 $.parseJSON() 替换为 JSON.parse()
• 将 $.trim() 替换为 str.trim()
• 将 $.now() 替换为 Date.now()
• 将 $.type() 替换为原生类型检查
• 将 $.isFunction() 替换为 typeof 检查
• 将 $.isNumeric() 替换为 isNaN/isFinite 检查
• 更新 toggleClass(boolean) 的用法
• 为脚本 AJAX 调用添加 dataType
• 测试焦点/失焦事件的触发顺序
• 如适用，检查 WordPress 插件
• 修复所有问题后移除 jquery-migrate
• 在生产环境中升级到 [email protected]

---

官方文档

• jQuery 4.0.0 发布公告：https://blog.jquery.com/2026/01/17/jquery-4-0-0/
• 升级指南：https://jquery.com/upgrade-guide/4.0/
• jQuery Migrate 插件：https://github.com/jquery/jquery-migrate
• API 文档：https://api.jquery.com/
• npm 软件包：https://www.npmjs.com/package/jquery

---

软件包版本（已于 2026-01-25 验证）

{
  "dependencies": {
    "jquery": "^4.0.0"
  },
  "devDependencies": {
    "jquery-migrate": "^4.0.2"
  }
}

---

故障排除

问题：升级 jQuery 后，WordPress 管理后台出现异常

解决方案：只升级前端 jQuery。管理后台使用自己的版本。使用条件逻辑，避免影响 wp-admin。

问题：第三方插件无法正常工作

解决方案：在插件更新之前，保留已加载的 jquery-migrate。查看插件更新日志，确认是否有 jQuery 4.0 兼容性更新。

问题：AJAX 请求正常，但脚本没有执行

解决方案：在 $.ajax 选项中添加 dataType: 'script'，或使用 $.getScript() 加载脚本。

问题：表单验证在错误的时机触发

解决方案：检查 focus/blur/focusin/focusout 处理程序。jQuery 4.0 的触发顺序为：blur → focusout → focus → focusin（W3C 顺序）。

---

有疑问？遇到问题？

1. 检查控制台中的 jquery-migrate 警告
2. 查看升级指南：https://jquery.com/upgrade-guide/4.0/
3. 查看 jQuery GitHub 问题：https://github.com/jquery/jquery/issues