jQuery UI 教程

<link rel="stylesheet" href="jquery-ui.css">
<script src="jquery.js"></script>
<script src="jquery-ui.js"></script>

<script>
$(function () {
  $("#datepicker").datepicker();   // 一行代码生成日期选择器
});
</script>

<!-- jQuery UI CSS -->
<link rel="stylesheet"
  href="https://code.jquery.com/ui/1.13.2/themes/base/jquery-ui.css">

<!-- jQuery + jQuery UI JS -->
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="https://code.jquery.com/ui/1.13.2/jquery-ui.min.js"></script>

npm install jquery jquery-ui-dist

// 引入
import $ from "jquery";
import "jquery-ui-dist/jquery-ui";
import "jquery-ui-dist/jquery-ui.css";

1. 打开 jqueryui.com/download
2. 勾选需要的组件(如只需 datepicker + dialog)
3. 选择主题,点击下载
4. 得到精简版 jquery-ui.min.js + css

// 无参数初始化
$("#myDiv").draggable();

// 带选项初始化
$("#datepicker").datepicker({
  dateFormat: "yy-mm-dd",
  minDate: 0,           // 不能选过去的日期
  changeYear: true
});

// 初始化后调用方法
$("#dialog").dialog("open");
$("#tabs").tabs("option", "active", 2);
$("#accordion").accordion("destroy");   // 销毁组件

// 获取选项值
var format = $("#datepicker").datepicker("option", "dateFormat");

// 设置选项(可链式)
$("#datepicker")
  .datepicker("option", "minDate", new Date())
  .datepicker("option", "maxDate", "+1M");

// 初始化时通过选项绑定
$("#slider").slider({
  min: 0, max: 100, value: 50,
  slide: function (event, ui) {
    $("#amount").val(ui.value);
  },
  change: function (event, ui) {
    console.log("最终值:", ui.value);
  }
});

// 或通过 on 绑定(组件触发 jQuery 事件)
$("#dialog").on("dialogclose", function () {
  console.log("对话框已关闭");
});

$("#myWidget")
  .widgetName("option", "disabled", false)
  .widgetName("refresh");
  // 部分组件支持 refresh 重绘

jqueryui.com/themeroller
→ 可视化调整颜色/圆角/字体
→ 一键下载定制后的 CSS

在 download 页只勾选用到的组件:
✓ Interactions: draggable, droppable
✓ Widgets: datepicker, dialog
✓ Effects: show, hide
→ 生成的 JS 比全量小很多

$("#dialog").dialog({
  title: "自定义标题",
  width: 500,
  modal: true,               // 模态
  draggable: true,           // 可拖动
  resizable: false,          // 禁止缩放
  buttons: [
    { text: "确定", click: function () { $(this).dialog("close"); } },
    { text: "取消", click: function () { $(this).dialog("close"); } }
  ]
});

// 修改所有 datepicker 的默认值
$.datepicker.setDefaults({
  dateFormat: "yy-mm-dd",
  showWeek: true
});

// 修改所有 dialog 默认值
$.widget("ui.dialog", $.ui.dialog, {
  options: $.extend($.ui.dialog.prototype.options, {
    modal: true,
    width: 480
  })
});

// jQuery UI 组件本质是 jQuery 插件
// 给元素添加方法,数据存到元素上
$.fn.draggable = function (options) {
  // 首次调用:初始化,数据存 $.data(el, 'ui-draggable')
  // 再次调用:按字符串方法名分发
  return this.each(function () {
    if (typeof options === "string") {
      // 方法调用:$(el).draggable('destroy')
      handleMethod(this, options);
    } else {
      // 初始化
      initWidget(this, options);
    }
  });
};

// 选项优先级: 默认值 < 全局默认 < 实例选项
$.widget("ui.dialog", {
  options: { modal: false, width: 300 },   // 默认
  _create: function () {
    // this.options 已合并所有层级的选项
    console.log(this.options.modal);
  }
});

<!-- 组件运行时添加 ui-* 类控制样式 -->
<div class="ui-dialog ui-widget ui-widget-content
     ui-corner-all ui-front">
  <div class="ui-dialog-titlebar ui-widget-header">...</div>
  <div class="ui-dialog-content">...</div>
</div>

// 组件事件 = 选项回调 + jQuery 事件 双重支持
$("#slider").slider({
  change: function (e, ui) { }   // 选项回调
});
// 等价于
$("#slider").on("slidechange", function (e, ui) { });

/* 覆盖 jquery-ui.css 之后的样式 */
.ui-widget-header {
  background: #2f6fb2;
  color: #fff;
}
.ui-state-default {
  background: #f5f5f5;
  border-radius: 4px;
}
.ui-state-hover {
  background: #e8f0fb;
}

<!-- 所有组件都用同一套 ui-* 类,主题一致 -->
<div class="ui-widget">
  <button class="ui-button ui-widget ui-state-default
         ui-corner-all">按钮</button>
</div>

<!-- 输入框统一样式 -->
<input class="ui-widget ui-state-default ui-corner-all">

1. 打开 jqueryui.com/themeroller
2. 调整各类颜色:
   - 基本色(背景/边框/文字)
   - 标题栏颜色
   - 悬停/激活/高亮/错误状态色
   - 圆角大小、图标风格
3. 右上角点击 "Download theme"
4. 获取定制后的 jquery-ui.css

/* 生成两套主题:base(默认) 与 dark(深色) */
/* 深色主题中,组件根加 dark 类即可切换 */
.dark .ui-widget-header { background: #333; color: #fff; }
.dark .ui-state-default { background: #555; color: #eee; }

<!-- 默认/悬停/激活状态切换 -->
<a class="ui-state-default" href="#">按钮</a>

/* CSS */
.ui-state-default { background:#e6e6e6; border:1px solid #ccc; }
.ui-state-hover   { background:#dadada; border-color:#999; }
.ui-state-active  { background:#fff; border-color:#007fff; }

// 平滑切换状态(需要引入 effects 模块)
$("#btn")
  .on("mouseenter", function () {
    $(this).addClass("ui-state-hover", 200);   // 200ms 动画
  })
  .on("mouseleave", function () {
    $(this).removeClass("ui-state-hover", 200);
  });

<!-- ui-icon 图标(配合主题图片) -->
<span class="ui-icon ui-icon-circle-triangle-e"></span>

/* 常见图标: */
/* ui-icon-gear 齿轮  ui-icon-search 搜索 */
/* ui-icon-closethick 关闭  ui-icon-check 对勾 */

// 折叠面板
$("#accordion").accordion({ collapsible: true });

// 自动完成
$("#tags").autocomplete({
  source: ["HTML", "CSS", "JavaScript", "Python"]
});

// 工具提示
$(document).tooltip();

// 进度条
$("#progressbar").progressbar({ value: 60 });

// 基于 dialog 创建 myDialog,增加自动居中功能
$.widget("custom.myDialog", $.ui.dialog, {
  // 新增选项
  options: {
    autoCenter: true
  },

  // 覆盖创建逻辑
  _create: function () {
    this._super();          // 调用原 dialog 的 _create
    if (this.options.autoCenter) {
      this.element.addClass("auto-centered");
    }
  },

  // 新增方法
  showMessage: function (msg) {
    this.element.html("<p>" + msg + "</p>");
    this.open();
  },

  // 覆盖销毁逻辑
  _destroy: function () {
    this._super();          // 调用原销毁
    console.log("自定义 dialog 已销毁");
  }
});

// 使用
$("#dlg").myDialog({
  autoCenter: true,
  title: "自定义对话框"
});
$("#dlg").myDialog("showMessage", "你好！");

$.widget("custom.quickDatepicker", $.ui.datepicker, {
  _create: function () {
    this._super();
    var self = this;
    this.element.on("focus", function () {
      self.element.datepicker("setDate", new Date());
    });
  }
});

// 初始化(传对象)
$("#dialog").dialog({ modal: true });

// 调用方法(传字符串)
$("#dialog").dialog("open");
$("#dialog").dialog("close");
$("#dialog").dialog("isOpen");     // 返回布尔

// 带参数
$("#datepicker").datepicker("setDate", "2026-08-17");
$("#tabs").tabs("option", "active", 0);

// 返回值(可赋给变量)
var isOpen = $("#dialog").dialog("isOpen");
var date = $("#datepicker").datepicker("getDate");

// 读
var w = $("#dialog").dialog("option", "width");

// 写(单个)
$("#dialog").dialog("option", "width", 600);

// 写(多个)
$("#dialog").dialog("option", {
  width: 600,
  height: 400,
  title: "新标题"
});

// 刷新(数据或布局变化后重绘)
$("#accordion").accordion("refresh");
$("#slider").slider("refresh");

// 禁用/启用
$("#datepicker").datepicker("disable");
$("#datepicker").datepicker("enable");

// 销毁(移除所有行为与数据,回到初始)
$("#tabs").tabs("destroy");

// 获取部件实例对象,直接访问内部
var instance = $("#slider").slider("instance");
instance.options.max = 200;        // 直接改选项
instance.refresh();

// 通过 data 获取
// $(el).data("ui-slider") 或 $(el).data("uiSlider")

// 每个组件都要重复处理:
// 1. 选项默认值与合并
// 2. 方法调用分发
// 3. 主题类添加/移除
// 4. 事件触发
// 5. 销毁时清理资源
// 6. 与 jQuery 链式调用兼容
$.fn.myWidget = function (options) {
  // 每个组件都要手写这一大坨……
};

// 所有组件都长这样,学习成本低
$("#a").accordion("option", "active", 1);
$("#b").datepicker("option", "minDate", 0);
$("#c").dialog("option", "modal", true);
//        ↑ 同一个 option 方法

<!-- HTML 结构 -->
<div id="tabs">
  <ul>
    <li><a href="#tabs-1">标签一</a></li>
    <li><a href="#tabs-2">标签二</a></li>
  </ul>
  <div id="tabs-1">内容一</div>
  <div id="tabs-2">内容二</div>
</div>

// 一行初始化
$("#tabs").tabs();

// 对话框里放日期选择器 + 滑块
$("#dlg").dialog({
  buttons: [{ text: "确定", click: close }]
});

$("#date").datepicker({
  onSelect: function (date) {
    $("#dlg").dialog("option", "title", "选择了 " + date);
  }
});

$("#range").slider({
  slide: function (e, ui) {
    $("#val").text(ui.value);
  }
});

$.widget("custom.starRating", {
  options: { max: 5, value: 0 },
  _create: function () {
    this._render();
  },
  _render: function () {
    var self = this, html = "";
    for (var i = 1; i <= this.options.max; i++) {
      html += "<span class='star" + (i <= this.options.value ? " on" : "") + "' data-v='" + i + "'>★</span>";
    }
    this.element.html(html).addClass("ui-widget");
    this.element.on("click", ".star", function () {
      self._setOption("value", $(this).data("v"));
    });
  },
  _setOption: function (key, value) {
    this._super(key, value);
    if (key === "value") this._render();
  }
});

// 使用
$("#rating").starRating({ value: 3 });
$("#rating").starRating("option", "value", 4);

api.jqueryui.com
├── datepicker/
│   ├── 选项(Options)     —— 配置项,含默认值
│   ├── 方法(Methods)     —— 可调用的方法
│   ├── 事件(Events)      —— 回调/触发的事件
│   └── 示例(Examples)
├── interactions/          —— 交互类组件
├── widgets/               —— 小部件类组件
└── effects/               —— 特效类

// 查 datepicker 的 dateFormat 选项
// 文档显示: dateFormat (默认 "mm/dd/yy")
$("#datepicker").datepicker({
  dateFormat: "yy-mm-dd"
});

// 查 dialog 的 buttons 选项
// 文档显示: buttons (默认 [])
$("#dlg").dialog({
  buttons: [{ text: "OK", click: function () {} }]
});

// 查 slider 的 slide 事件
// 文档显示: slide(event, ui)  ui.value 为当前值
$("#slider").slider({
  slide: function (event, ui) { console.log(ui.value); }
});

// 应用特效(隐藏时)
$("#box").hide("explode", 600);
$("#box").show("bounce", { times: 3 }, 500);

// 通用 effect 方法
$("#box").effect("shake", { distance: 10 }, 300);
$("#box").effect("highlight", { color: "#ff0" }, 1000);

// 一次性多特效
$("#box").effect("pulsate", { times: 2 }, 800);

// 每个特效有自己的参数对象
$("#box").effect("scale", {
  percent: 200,        // 放大到 200%
  origin: ["middle", "center"]
}, 500);

$("#box").effect("transfer", {
  to: "#target",       // 转移到目标元素
  className: "ui-effects-transfer"
}, 400);

// 全局关闭动画(测试/低功耗模式)
$.fx.off = true;

// 调整动画帧率(默认 13ms)
$.fx.interval = 16;

// 原生 jQuery 不支持颜色渐变,特效核心让它支持
$("#box").animate({
  backgroundColor: "#ff6600",
  color: "#ffffff"
}, 800);

// addClass 带时长 = 平滑过渡
$("#btn").addClass("ui-state-hover", 300);

// removeClass 带时长
$("#btn").removeClass("ui-state-hover", 300);

// switchClass:从一个类切到另一个类
$("#box").switchClass("old-state", "new-state", 400);

// 内置缓动: swing(默认) / linear
// 引入 jquery.easing 插件后可用的更多
$("#box").show("slide", { direction: "left" }, 500, "easeOutBounce");

// 回调
$("#box").hide("explode", 500, function () {
  console.log("隐藏完成");
});

// 交互事件分三个阶段: start / (过程) / stop
$("#box").draggable({
  start: function (event, ui) {
    console.log("开始拖动");
  },
  drag: function (event, ui) {
    // 拖动中持续触发
    console.log(ui.position.left, ui.position.top);
  },
  stop: function (event, ui) {
    console.log("拖动结束");
  }
});

// droppable 事件: activate/deactivate/over/out/drop
$("#target").droppable({
  drop: function (event, ui) {
    // ui.draggable 是拖来的元素
    console.log("收到:", ui.draggable.text());
  }
});

// 无参:返回整个选项对象
var all = $("#dlg").dialog("option");

// 一个字符串:返回该选项值
var w = $("#dlg").dialog("option", "width");

// 字符串+值:设置单个选项
$("#dlg").dialog("option", "width", 600);

// 对象:批量设置
$("#dlg").dialog("option", { width: 600, height: 400 });

// datepicker 的 setDate 重载
$("#dp").datepicker("setDate");                // 设为今天
$("#dp").datepicker("setDate", "2026-08-17");  // 指定日期
$("#dp").datepicker("setDate", new Date());    // Date 对象

// tabs 的 active 选项重载
$("#tabs").tabs("option", "active");        // 读当前索引
$("#tabs").tabs("option", "active", 2);     // 激活第 3 个
$("#tabs").tabs("option", "active", false); // 全部收起

// 无返回值的方法:返回 jQuery 对象,可链式
$("#box").draggable("enable").draggable("refresh");

// 有返回值的方法:返回结果,不可链式
var date = $("#dp").datepicker("getDate");
var open = $("#dlg").dialog("isOpen");
var val = $("#slider").slider("value");

// option:读写配置(见方法重载章)
$("#slider").slider("option", "value", 80);

// 值类方法(组件特有)
$("#slider").slider("value");            // 读值
$("#slider").slider("value", 60);        // 设值
$("#dp").datepicker("getDate");          // 读日期
$("#spinner").spinner("value");          // 读数字
$("#progressbar").progressbar("value");  // 读进度

// dialog
$("#dlg").dialog("open");
$("#dlg").dialog("close");
$("#dlg").dialog("moveToTop");

// tabs / accordion
$("#tabs").tabs("select", 1);            // 老版本
$("#tabs").tabs("option", "active", 1);  // 新版本
$("#acc").accordion("option", "active", 0);

// autocomplete
$("#tags").autocomplete("search", "py"); // 触发搜索
$("#tags").autocomplete("close");
$("#tags").autocomplete("widget").hide();

// 表单提交前统一校验并取值
function collectForm() {
  var result = {
    date: $("#dp").datepicker("getDate"),
    price: $("#spinner").spinner("value"),
    range: $("#slider").slider("value")
  };
  return result;
}

// 找出容器内所有可聚焦元素
var focusables = $("#panel").find(":focusable");
console.log(focusables.length);

// 实现 Tab 键循环焦点
$("#dlg").on("keydown", function (e) {
  if (e.key === "Tab") {
    var items = $(this).find(":focusable");
    var idx = items.index(document.activeElement);
    e.preventDefault();
    items.eq((idx + 1) % items.length).trigger("focus");
  }
});

// 只匹配可通过 Tab 顺序聚焦的元素(排除 disabled)
$("#dlg").find(":tabbable").first().trigger("focus");

// 对话框打开时自动聚焦第一个输入框
$("#dlg").dialog({
  open: function () {
    $(this).find(":tabbable").first().trigger("focus");
  }
});

<!-- 对话框/菜单等组件自动添加 ARIA 属性 -->
<div role="dialog" aria-labelledby="dlg-title" aria-modal="true">
  <div id="dlg-title">提示</div>
</div>

/* 使用 :focusable 等选择器实现键盘导航,
   提升无障碍体验(accessibility) */

// 给组件结构的不同部分附加自定义类
$("#tabs").tabs({
  classes: {
    "ui-tabs": "my-tabs",
    "ui-tabs-tab": "my-tab",
    "ui-tabs-panel": "my-panel"
  }
});

// 效果:组件默认类与自定义类并存
// <div class="ui-tabs my-tabs">...

主题相关选项

// 通过选项控制主题状态类
$("#btn").button({
  classes: {
    "ui-state-active": "active-btn"
  }
});

// icon 选项(与主题图标配合)
$("#btn").button({
  icon: "ui-icon-gear",       // 图标类
  showLabel: false            // 只显示图标
});

动态切换主题

<!-- 引入多套主题 CSS,通过 link 标签切换 -->
<link id="themeLink" rel="stylesheet" href="themes/base.css">

function switchTheme(name) {
  $("#themeLink").attr("href", "themes/" + name + ".css");
}

// 换肤按钮
$(".theme-btn").on("click", function () {
  switchTheme($(this).data("theme"));
});

主题定制示例

/* 覆盖主题变量(在主题 CSS 之后) */
:root {
  --ui-accent: #7c3aed;
}

.ui-widget-header {
  background: var(--ui-accent);
}
.ui-state-active {
  border-color: var(--ui-accent);
  background: color-mix(in srgb, var(--ui-accent), white 90%);
}

API 类别 - UI 核心

UI 核心（UI Core）是 jQuery UI 的底层基础，包含：部件工厂（Widget Factory）、CSS 框架、键盘交互辅助、鼠标交互辅助、位置工具（Position）等。

UI Core 组成

键盘码常量

// $.ui.keyCode 提供可读的键名
$.ui.keyCode.BACKSPACE;  // 8
$.ui.keyCode.ENTER;      // 13
$.ui.keyCode.ESCAPE;     // 27
$.ui.keyCode.UP / DOWN / LEFT / RIGHT;
$.ui.keyCode.TAB;
$.ui.keyCode.SPACE;

// 使用示例
$(document).on("keydown", function (e) {
  if (e.keyCode === $.ui.keyCode.ESCAPE) {
    $("#dlg").dialog("close");
  }
});

鼠标交互基类

// $.ui.mouse 是 draggable/resizable 等的基础
// 统一处理 mousedown/mousemove/mouseup 与距离阈值
// 通常不需要直接使用,组件已封装好

版本与检测

// 查看版本
console.log($.ui.version);

// 判断某个组件是否存在
if ($.ui && $.ui.dialog) {
  $("#dlg").dialog();
} else {
  console.warn("dialog 组件未加载");
}

API 类别 - 实用工具

jQuery UI 提供几个实用工具（Utilities），独立于组件使用：$.ui.position（定位）、$.fn.position()、数据存储约定等。

position 工具(元素定位)

// 把元素定位到目标元素旁边
$("#tooltip").position({
  my: "left top",        // 自身位置
  at: "right top",       // 相对目标的位置
  of: "#trigger",        // 目标元素
  collision: "flip"      // 空间不足时翻转
});

// 居中定位
$("#dlg").position({
  my: "center",
  at: "center",
  of: window
});

position 常用选项

对话框跟随按钮

$("#menuBtn").on("click", function (e) {
  $("#menu").show().position({
    my: "left top",
    at: "left bottom",
    of: e          // 直接传事件对象(鼠标位置)
  });
});

数据存储约定

// jQuery UI 组件把实例存在元素 data 上
// 命名: $.data(el, 'ui-' + 组件名) 或 camelCase
var inst = $("#slider").data("ui-slider");
var inst2 = $("#slider").data("uiSlider");

// 两者等价,可访问实例内部(慎用,建议用公开 API)

API 类别 - 小部件

「小部件（Widgets）」类别收录 jQuery UI 的全部 11 个官方小部件，本教程给出总览与选型建议。

小部件总览

选型速查

需要折叠内容  → accordion
需要联想搜索  → autocomplete
需要选日期    → datepicker
需要弹窗      → dialog
需要标签切换  → tabs
需要数值范围  → slider + spinner
需要进度展示  → progressbar
需要悬停说明  → tooltip

组合实战

// 一个典型的「商品筛选面板」
$("#filter").accordion();                       // 折叠分类
$("#priceRange").slider({ range: true });       // 价格区间
$("#dateRange").datepicker({ rangeSelect: true }); // 日期范围
$("#apply").button();                           // 统一按钮
$("#tip").tooltip();                            // 提示

jQuery UI 实例

综合运用所学，构建一个「订单管理」演示页：日期筛选 + 标签页 + 对话框 + 进度条 + 排序，展示 jQuery UI 的组合能力。

页面结构

<div id="tabs">
  <ul>
    <li><a href="#tab-orders">订单列表</a></li>
    <li><a href="#tab-stats">数据统计</a></li>
  </ul>

  <div id="tab-orders">
    <p>
      日期:<input id="filterDate">
      <button id="filterBtn">筛选</button>
    </p>
    <ul id="orderList"></ul>
  </div>

  <div id="tab-stats">
    <p>本月目标完成率</p>
    <div id="progress"></div>
    <p id="progressText"></p>
  </div>
</div>

初始化各组件

$(function () {
  // 标签页
  $("#tabs").tabs();

  // 日期选择器
  $("#filterDate").datepicker({ dateFormat: "yy-mm-dd" });

  // 按钮
  $("#filterBtn").button({ icon: "ui-icon-search", showLabel: false });

  // 进度条
  $("#progress").progressbar({ value: 65 });
  $("#progressText").text("65%");

  // 订单列表(可排序)
  $("#orderList").sortable({ handle: ".drag" }).disableSelection();
});

筛选与详情

// 筛选按钮
$("#filterBtn").on("click", function () {
  var date = $("#filterDate").val();
  renderOrders(getOrdersByDate(date));
});

// 点击订单弹详情
function renderOrders(list) {
  $("#orderList").empty();
  $.each(list, function (i, o) {
    $("<li>")
      .addClass("drag")
      .text(o.id + " | " + o.customer + " | ¥" + o.amount)
      .on("click", function () { showDetail(o); })
      .appendTo("#orderList");
  });
}

function showDetail(order) {
  $("#dlg").dialog({
    title: "订单 " + order.id,
    buttons: [{ text: "关闭", click: function () { $(this).dialog("close"); } }]
  }).html("<p>客户:" + order.customer + "</p><p>金额:¥" + order.amount + "</p>");
}

拖动（Draggable）

draggable 让元素可以拖动，是交互组件中使用率最高的一个，常用于拖拽排序、拖到购物车、自定义布局。

基本用法

$("#box").draggable();

// 带选项
$("#box").draggable({
  axis: "x",             // 只允许水平拖动
  handle: ".title",      // 只有标题栏可拖动
  containment: "parent", // 限制在父容器内
  cursor: "move",
  opacity: 0.7,          // 拖动时半透明
  revert: true           // 松手后回到原位
});

常用选项

事件

$("#box").draggable({
  start: function (event, ui) {
    $(this).addClass("dragging");
  },
  drag: function (event, ui) {
    // ui.position 为当前位置
    $("#pos").text(ui.position.left + ", " + ui.position.top);
  },
  stop: function (event, ui) {
    $(this).removeClass("dragging");
    console.log("停在:", ui.position);
  }
});

方法

$("#box").draggable("disable");   // 禁用
$("#box").draggable("enable");    // 启用
$("#box").draggable("destroy");   // 销毁
$("#box").draggable("option", "containment", "#wrap");

放置（Droppable）

droppable 定义放置目标：当可拖动元素被拖到目标上时触发事件，实现「拖拽到回收站、拖入购物车、拖拽分配」等交互。

基本用法

$("#dropZone").droppable({
  accept: ".item",          // 只接受 class 为 item 的元素
  hoverClass: "drop-hover", // 悬停时的样式类
  drop: function (event, ui) {
    // ui.draggable 是被拖来的元素
    console.log("收到:", ui.draggable.text());
  }
});

完整拖放示例

<div class="item">📄 文件1</div>
<div class="item">📄 文件2</div>

<div id="trash" style="width:200px;height:120px;
     border:2px dashed #999;">🗑️ 拖到这里删除</div>

$(function () {
  $(".item").draggable({
    revert: "invalid",       // 拖到无效目标才回弹
    helper: "clone"
  });

  $("#trash").droppable({
    accept: ".item",
    hoverClass: "trash-hover",
    drop: function (event, ui) {
      ui.draggable.remove();          // 从页面移除
      alert("已删除 " + ui.draggable.text());
    }
  });
});

事件与状态

$("#dropZone").droppable({
  activate: function () { /* 有元素开始拖动 */ },
  deactivate: function () { /* 所有拖动结束 */ },
  over: function (event, ui) { /* 元素进入 */ },
  out: function (event, ui) { /* 元素离开 */ },
  drop: function (event, ui) { /* 元素放下 */ }
});

缩放（Resizable）

resizable 让元素可以调整大小（拖拽边缘/角），常用于可调面板、图片裁剪、编辑器尺寸调节。

基本用法

$("#box").resizable();

// 带选项
$("#box").resizable({
  minWidth: 100,
  minHeight: 100,
  maxWidth: 500,
  maxHeight: 400,
  handles: "e, s, se",      // 允许拖动的方向
  aspectRatio: true,        // 保持宽高比(图片)
  grid: [20, 20]            // 步进吸附
});

handles 方向

n 北(上)  s 南(下)  e 东(右)  w 西(左)
ne / nw / se / sw 四角
'se' 表示只有右下角可拖; 'all' 全部

事件

$("#box").resizable({
  start: function (event, ui) { },
  resize: function (event, ui) {
    // ui.size 实时尺寸
    $("#size").text(ui.size.width + " × " + ui.size.height);
  },
  stop: function (event, ui) {
    console.log("最终尺寸:", ui.size);
  }
});

图片缩放裁剪示例

$("#cropBox").resizable({
  handles: "se",
  minWidth: 50,
  minHeight: 50,
  maxWidth: 400,
  maxHeight: 400,
  aspectRatio: 1,        // 保持正方形
  stop: function (event, ui) {
    $("#cropSize").text(ui.size.width + "×" + ui.size.height);
  }
});

选择（Selectable）

selectable 让列表元素可以被框选/点选（类似文件管理器的多选），支持鼠标拖框与 Ctrl 加选。

基本用法

<ul id="files">
  <li>报告.docx</li>
  <li>数据.xlsx</li>
  <li>图片.png</li>
  <li>代码.py</li>
</ul>

$("#files").selectable({
  filter: "li",              // 只对 li 生效
  selectedClass: "selected"  // 选中样式类
});

选中事件与批量操作

$("#files").selectable({
  stop: function () {
    var selected = $(".ui-selected", this).map(function () {
      return $(this).text();
    }).get();
    $("#result").text("已选 " + selected.length + " 个: " + selected.join("、"));
  }
});

// 全选按钮
$("#selectAll").on("click", function () {
  $("#files li").addClass("ui-selected");
});

选项

排序（Sortable）

sortable 让列表项可以拖拽排序，是最实用的交互组件之一：排序菜单、拖动调整顺序、列排序。

基本用法

<ul id="menu">
  <li>首页</li>
  <li>关于</li>
  <li>服务</li>
  <li>联系</li>
</ul>

$("#menu").sortable({
  axis: "y",               // 垂直排序
  placeholder: "sort-ph",  // 占位符类
  update: function (event, ui) {
    // 排序变化后保存新顺序
    var order = $("#menu li").map(function () {
      return $(this).text();
    }).get();
    console.log("新顺序:", order);
    // $.post("save_order.php", { order: order });
  }
});
// 阻止文本选中
$("#menu").disableSelection();

拖动手柄与连接列表

// 只允许拖动手柄(handle)排序
$("#menu").sortable({
  handle: ".drag-handle"
});

// 两个列表互拖
$("#listA, #listB").sortable({
  connectWith: "#listA, #listB",
  update: function () {
    // 任意列表变化后同步数据
    syncLists();
  }
});

事件

$("#menu").sortable({
  start: function (event, ui) { ui.item.addClass("dragging"); },
  change: function (event, ui) { /* 顺序变化 */ },
  stop: function (event, ui) { ui.item.removeClass("dragging"); },
  update: function (event, ui) { /* 排序完成,保存 */ }
});

折叠面板（Accordion）

accordion 折叠面板一次展开一个区块，适合 FAQ、侧边栏导航、设置分组。

基本用法

<div id="acc">
  <h3>前端开发</h3>
  <div><p>HTML、CSS、JavaScript 教程</p></div>
  <h3>后端开发</h3>
  <div><p>Python、Node.js、Go 教程</p></div>
  <h3>数据库</h3>
  <div><p>MySQL、Redis 教程</p></div>
</div>

$("#acc").accordion({
  collapsible: true,      // 允许全部收起
  active: 0,              // 默认展开第 0 个
  heightStyle: "content", // 高度自适应内容
  animate: 200
});

选项

事件与方法

// 事件
$("#acc").accordion({
  activate: function (event, ui) {
    console.log("展开:", ui.newHeader.text());
  }
});

// 方法
$("#acc").accordion("option", "active", 2);  // 展开第3个
$("#acc").accordion("option", "collapsible", true);
$("#acc").accordion("refresh");              // 内容变化后刷新

自动完成（Autocomplete）

autocomplete 在输入时提供联想补全，数据源支持本地数组或远程接口（含异步加载）。

本地数据源

$("#tags").autocomplete({
  source: ["HTML", "CSS", "JavaScript", "Python", "PHP", "Java", "Go"]
});

远程数据源

$("#search").autocomplete({
  source: function (request, response) {
    $.getJSON("search.php", { term: request.term }, response);
    // 返回格式: [{label:'xxx', value:'xxx'}, ...]
  },
  minLength: 2,            // 至少输入2个字符才搜索
  delay: 300,              // 防抖
  select: function (event, ui) {
    console.log("选择了:", ui.item.value);
  }
});

自定义显示

$("#search").autocomplete({
  source: users,
  // label 显示, value 赋值
  _renderItem: function (ul, item) {
    return $("<li>")
      .append("<div>" + item.label + " <small>" + item.dept + "</small></div>")
      .appendTo(ul);
  }
});

事件

$("#search").autocomplete({
  search: function (event, ui) { /* 发起搜索 */ },
  open: function (event, ui) { /* 下拉打开 */ },
  select: function (event, ui) { /* 选中一项 */ },
  close: function (event, ui) { /* 下拉关闭 */ }
});

// 方法
$("#search").autocomplete("search", "py");  // 程序触发搜索
$("#search").autocomplete("close");
$("#search").autocomplete("widget").hide(); // 隐藏下拉

按钮（Button）

button 增强按钮外观，还支持把复选框、单选按钮变成按钮组样式，以及图标按钮。

基本用法

// 普通按钮
$("#btn").button();

// 带图标按钮
$("#btn").button({
  icon: "ui-icon-print",
  showLabel: false         // 只显示图标
});

// 图标 + 文字
$("#btnSave").button({
  icons: { primary: "ui-icon-disk" }
});

按钮组(复选框/单选)

<div id="toolbar">
  <input type="checkbox" id="bold"><label for="bold">加粗</label>
  <input type="checkbox" id="italic"><label for="italic">斜体</label>
</div>

<div id="sizeGroup">
  <input type="radio" id="s" name="size" checked><label for="s">小</label>
  <input type="radio" id="m" name="size"><label for="m">中</label>
  <input type="radio" id="l" name="size"><label for="l">大</label>
</div>

$("#toolbar").buttonset();     // 复选框按钮组
$("#sizeGroup").buttonset();    // 单选按钮组(radio)

状态与方法

$("#btn").button("disable");
$("#btn").button("enable");
$("#btn").button("refresh");    // 文本/图标变化后刷新
$("#btn").button("destroy");

日期选择器（Datepicker）

datepicker 是 jQuery UI 最受欢迎的小部件：日历选日期，支持范围、国际化、日期格式自定义。

基本用法

$("#date").datepicker();

// 常用配置
$("#date").datepicker({
  dateFormat: "yy-mm-dd",     // 输出格式
  changeMonth: true,          // 下拉选月份
  changeYear: true,           // 下拉选年份
  minDate: 0,                 // 今天及以后
  maxDate: "+1Y",             // 一年内
  showButtonPanel: true       // 今天/关闭按钮
});

日期范围选择

// 两个日期框联动
$("#from").datepicker({
  dateFormat: "yy-mm-dd",
  onSelect: function (date) {
    $("#to").datepicker("option", "minDate", date);  // 到 >= 从
  }
});
$("#to").datepicker({
  dateFormat: "yy-mm-dd",
  onSelect: function (date) {
    $("#from").datepicker("option", "maxDate", date);
  }
});

事件与方法

// 事件
$("#date").datepicker({
  onSelect: function (dateText, inst) {
    console.log("选了:", dateText);
  },
  onChangeMonthYear: function (year, month, inst) { }
});

// 方法
$("#date").datepicker("getDate");                 // Date 对象
$("#date").datepicker("setDate", "2026-08-17");   // 设置
$("#date").datepicker("show");                    // 弹出日历
$("#date").datepicker("hide");

中文汉化

$.datepicker.regional["zh-CN"] = {
  closeText: "关闭", prevText: "上月", nextText: "下月",
  currentText: "今天", monthNames: ["一月","二月",..."十二月"],
  dayNamesMin: ["日","一","二","三","四","五","六"],
  weekHeader: "周", dateFormat: "yy-mm-dd", firstDay: 1
};
$.datepicker.setDefaults($.datepicker.regional["zh-CN"]);

对话框（Dialog）

dialog 提供弹窗能力：模态/非模态、标题栏、按钮区、拖拽缩放，是表单弹窗与确认框的首选。

基本用法

<div id="dlg" title="新增用户" style="display:none;">
  <p>用户名:<input id="u"></p>
</div>

$("#dlg").dialog({
  modal: true,           // 模态遮罩
  width: 400,
  autoOpen: false,       // 不自动打开
  buttons: [
    { text: "保存", icon: "ui-icon-check",
      click: function () { saveUser(); } },
    { text: "取消",
      click: function () { $(this).dialog("close"); } }
  ]
});

// 打开
$("#openBtn").on("click", function () {
  $("#dlg").dialog("open");
});

选项

事件与方法

$("#dlg").dialog({
  open: function () { console.log("打开"); },
  close: function () { console.log("关闭"); }
});

$("#dlg").dialog("open");
$("#dlg").dialog("close");
$("#dlg").dialog("isOpen");
$("#dlg").dialog("moveToTop");    // 置顶
$("#dlg").dialog("option", "title", "新标题");

确认对话框封装

function confirmDlg(message, onOk) {
  var dlg = $("<div>").html(message).dialog({
    modal: true,
    buttons: [
      { text: "确定", click: function () { $(this).dialog("close"); onOk(); } },
      { text: "取消", click: function () { $(this).dialog("close"); } }
    ],
    close: function () { $(this).dialog("destroy").remove(); }
  });
}

// 使用
confirmDlg("确定删除这条记录吗?", function () {
  // 执行删除
});

菜单（Menu）

menu 组件创建多级菜单（含图标、分隔线、快捷键），支持键盘导航。

基本用法

<ul id="menu">
  <li><div>文件</div>
    <ul>
      <li><div>新建</div></li>
      <li><div>打开</div></li>
      <li class="ui-menu-divider"></li>
      <li><div>退出</div></li>
    </ul>
  </li>
  <li><div>编辑</div></li>
  <li><div>帮助</div></li>
</ul>

$("#menu").menu({
  icons: { submenu: "ui-icon-circle-triangle-e" }
});

右键菜单

$("#table").on("contextmenu", function (e) {
  e.preventDefault();
  $("#menu").menu("refresh");
  $("#menu").show().position({
    my: "left top",
    at: "left top",
    of: e
  });
});

// 点击菜单项
$("#menu").on("menuselect", function (event, ui) {
  var text = ui.item.text();
  console.log("选择了:", text);
  $("#menu").hide();
});

图标与快捷键

<ul id="menu2">
  <li><div><span class="ui-icon ui-icon-copy"></span>复制<span class="ui-menu-item-wrapper" style="float:right">Ctrl+C</span></div></li>
  <li><div><span class="ui-icon ui-icon-scissors"></span>剪切</div></li>
</ul>

进度条（Progressbar）

progressbar 显示任务进度，支持确定进度（0-100）与不确定状态（动画循环），常用于上传、加载、任务执行。

基本用法

$("#pb").progressbar({ value: 40 });

// 读/写值
$("#pb").progressbar("value");          // 读
$("#pb").progressbar("value", 70);      // 写

模拟上传进度

var progress = 0;
var timer = setInterval(function () {
  progress += Math.random() * 15;
  if (progress >= 100) {
    progress = 100;
    clearInterval(timer);
    $("#status").text("上传完成 ✅");
  }
  $("#pb").progressbar("value", Math.floor(progress));
  $("#status").text("上传中... " + Math.floor(progress) + "%");
}, 300);

不确定状态(忙碌动画)

// value 设为 false = 不确定进度
$("#pb").progressbar({ value: false });

// 事件
$("#pb").progressbar({
  change: function () { /* 值变化 */ },
  complete: function () { console.log("完成!"); }
});

自定义显示百分比

<div style="position:relative;">
  <div id="pb"></div>
  <span id="pbLabel" style="position:absolute;left:50%;top:50%;transform:translate(-50%,-50%);">0%</span>
</div>

$("#pb").progressbar({
  value: 0,
  change: function () {
    $("#pbLabel").text($("#pb").progressbar("value") + "%");
  }
});

滑块（Slider）

slider 滑块用于数值选择，支持单值、范围（区间）、步进、垂直方向，是价格筛选、音量控制的标配。

基本用法

$("#slider").slider({
  min: 0,
  max: 100,
  value: 50,
  step: 5,
  slide: function (event, ui) {
    $("#amount").val(ui.value);   // 拖动中实时更新
  }
});

范围滑块(价格区间)

$("#range").slider({
  range: true,             // 双滑块
  min: 0, max: 1000,
  values: [200, 600],      // 两个值
  slide: function (event, ui) {
    $("#min").val(ui.values[0]);
    $("#max").val(ui.values[1]);
  }
});

// 读两个值
var vals = $("#range").slider("values");
console.log(vals[0], vals[1]);

垂直滑块

$("#volume").slider({
  orientation: "vertical",
  min: 0, max: 100, value: 80
});
// CSS 需设置高度: #volume { height: 200px; }

事件与方法

$("#slider").slider({
  start: function (event, ui) { },
  slide: function (event, ui) { },   // 拖动中
  change: function (event, ui) { },  // 松手后
  stop: function (event, ui) { }     // 停止
});

// 方法
$("#slider").slider("value");           // 读
$("#slider").slider("value", 80);       // 写
$("#slider").slider("values", [20, 70]); // 范围写
$("#slider").slider("option", "disabled", true);

旋转器（Spinner）

spinner 数字步进输入框：上下箭头调节、支持步长、范围、格式化与本地化。

基本用法

$("#num").spinner({
  min: 0,
  max: 100,
  step: 1,
  value: 10
});

// 读/写值
var v = $("#num").spinner("value");      // 数字类型
$("#num").spinner("value", 25);
$("#num").spinner("pageUp");             // 加一步
$("#num").spinner("pageDown");           // 减一步

带格式化(价格/百分比)

$("#price").spinner({
  min: 0,
  step: 0.5,
  numberFormat: "n",          // 千分位
  change: function () {
    console.log($(this).spinner("value"));
  }
});

// 自定义格式化
$("#percent").spinner({
  min: 0, max: 100,
  culture: "en",
  numberFormat: "C"           // 货币格式
});

事件

$("#num").spinner({
  spin: function (event, ui) {
    // 每次加减时触发,ui.value 为新值
    if (ui.value > 100) return false;   // 返回 false 阻止
  },
  change: function (event) { },
  start: function (event, ui) { },
  stop: function (event, ui) { }
});

标签页（Tabs）

tabs 标签页在同一区域切换内容，是后台系统最常用的内容组织方式。

基本用法

<div id="tabs">
  <ul>
    <li><a href="#tab-1">概览</a></li>
    <li><a href="#tab-2">明细</a></li>
    <li><a href="#tab-3">日志</a></li>
  </ul>
  <div id="tab-1">概览内容</div>
  <div id="tab-2">明细内容</div>
  <div id="tab-3">日志内容</div>
</div>

$("#tabs").tabs();

AJAX 加载标签内容

<div id="tabs">
  <ul>
    <li><a href="view.php?id=1">详情</a></li>
    <li><a href="edit.php?id=1">编辑</a></li>
  </ul>
  <div id="loading">加载中...</div>
</div>

// href 指向真实 URL 时自动 AJAX 加载
$("#tabs").tabs({
  beforeLoad: function (event, ui) {
    ui.jqXHR.fail(function () {
      ui.panel.html("加载失败");
    });
  }
});

事件与方法

$("#tabs").tabs({
  activate: function (event, ui) {
    console.log("激活:", ui.newTab.text());
  }
});

$("#tabs").tabs("option", "active", 1);   // 切换到第2个
$("#tabs").tabs("load", 1);               // 重新加载AJAX
$("#tabs").tabs("refresh");               // 刷新结构
$("#tabs").tabs("destroy");

可关闭标签

$("#tabs").tabs({
  closable: true,
  close: function (event, ui) { }
});

// 动态添加标签
function addTab(title, content) {
  $("#tabs").tabs("option", "active",
    $("#tabs").find(".ui-tabs-nav li").length - 1);
  $("#tabs").append(
    "<li><a href='#tab-new'>" + title + "</a></li>" +
    "<div id='tab-new'>" + content + "</div>"
  ).tabs("refresh");
}

工具提示框（Tooltip）

tooltip 为元素提供悬停提示，默认读取 title 属性，可全局启用、自定义内容与位置。

基本用法

<!-- 全局启用:所有 title 属性变为 tooltip -->
<a href="#" title="点击查看帮助">帮助</a>
<input title="请输入用户名">

$(document).tooltip();   // 一键全局启用

自定义提示内容

// 从元素 data 属性读取内容
$("#box").tooltip({
  items: "[data-tip]",
  content: function () {
    return $(this).data("tip");
  }
});

// 固定内容
$("#btn").tooltip({
  content: "点击保存当前配置"
});

位置控制

$("#box").tooltip({
  position: {
    my: "left+15 center",
    at: "right center",
    collision: "flipfit"
  }
});

// 样式类
$("#box").tooltip({
  classes: {
    "ui-tooltip": "custom-tip"   // 自定义类
  }
});

事件

$(document).tooltip({
  open: function (event, ui) {
    ui.tooltip.css("max-width", "300px");
  },
  close: function (event, ui) { }
});

// 手动控制
$("#box").tooltip("open");
$("#box").tooltip("close");
$("#box").tooltip("destroy");

特效（Effect）

effect 方法给元素应用一次性动画特效，如摇晃、弹跳、爆炸、高亮等，用于反馈与视觉强调。

基本用法

// 摇晃(错误提示)
$("#errBox").effect("shake", { distance: 10 }, 400);

// 弹跳
$("#icon").effect("bounce", { times: 3 }, 500);

// 高亮
$("#updatedRow").effect("highlight", { color: "#ffff99" }, 1500);

// 脉动
$("#badge").effect("pulsate", { times: 2 }, 800);

常用特效参数

特效回调

$("#box").effect("shake", 300, function () {
  console.log("动画完成");
});

// 特效后执行后续动作
$("#delBtn").on("click", function () {
  $("#row").effect("explode", 600, function () {
    $(this).remove();   // 动画完成后删除
  });
});

组合动画

// 依次执行
$("#box")
  .effect("highlight", { color: "#ff0" }, 500)
  .delay(300)
  .effect("bounce", { times: 2 }, 400);

显示（Show）

show 是带特效的显示方法：$('#el').show('特效名', 时长)，比原生 show() 更生动。

基本用法

// 带特效显示
$("#panel").show("slide", { direction: "up" }, 400);
$("#panel").show("drop", { direction: "down" }, 300);
$("#panel").show("blind", 400);
$("#panel").show("fade", 600);
$("#panel").show("scale", { percent: 110 }, 300);

// 显示后回调
$("#panel").show("slide", 400, function () {
  console.log("已显示");
});

可用的显示特效

场景:侧边栏滑出

$("#sidebarBtn").on("click", function () {
  $("#sidebar").show("slide", { direction: "left" }, 300);
});

// 菜单下拉
$("#menuBtn").on("click", function () {
  $("#dropdown").show("drop", { direction: "down" }, 200);
});

隐藏（Hide）

hide 是带特效的隐藏方法，与 show 对称：$('#el').hide('特效名', 时长)。

基本用法

// 带特效隐藏
$("#panel").hide("slide", { direction: "up" }, 400);
$("#panel").hide("drop", { direction: "down" }, 300);
$("#panel").hide("explode", 500);
$("#panel").hide("fold", 400);

// 隐藏后回调(常用于移除)
$("#row").hide("drop", 400, function () {
  $(this).remove();   // 动画后删除 DOM
});

场景:删除行动画

$("#delBtn").on("click", function () {
  var $row = $("#row");
  $row.hide("explode", 500, function () {
    $row.remove();
  });
});

// 关闭提示条
$("#closeTip").on("click", function () {
  $("#tip").hide("drop", { direction: "left" }, 300);
});

隐藏后显示切换

// 用 toggle 切换显示/隐藏
$("#toggleBtn").on("click", function () {
  $("#panel").toggle("slide", { direction: "up" }, 300);
});

切换（Toggle）

toggle 在显示/隐藏之间自动切换，支持特效：$('#el').toggle('特效名', 时长)。

基本用法

// 点击按钮切换面板
$("#toggleBtn").on("click", function () {
  $("#panel").toggle("slide", { direction: "left" }, 300);
});

// 多种特效
$("#panel").toggle("blind", 400);
$("#panel").toggle("drop", 300);
$("#panel").toggle("fade", 500);

判断当前状态

// 判断元素是否可见
if ($("#panel").is(":visible")) {
  $("#panel").hide("slide", 300);
} else {
  $("#panel").show("slide", 300);
}

// 等价于一行 toggle
$("#panel").toggle("slide", 300);

场景:手风琴菜单

$(".menu-item").on("click", function () {
  var $sub = $(this).next(".submenu");
  // 关闭其他
  $(".submenu").not($sub).hide("slide", { direction: "up" }, 200);
  // 切换当前
  $sub.toggle("slide", { direction: "up" }, 200);
});

.addClass()

jQuery UI 扩展了 .addClass()：增加过渡动画（指定时长），原生 jQuery 的 addClass 是瞬时切换。

带动画添加类

// 原生(瞬时)
$("#box").addClass("highlight");

// jQuery UI(平滑过渡)
$("#box").addClass("highlight", 500);

// 过渡完成回调
$("#box").addClass("highlight", 500, function () {
  console.log("过渡完成");
});

典型应用:状态切换

// 按钮悬停/激活平滑过渡
$("#btn")
  .on("mouseenter", function () {
    $(this).addClass("ui-state-hover", 200);
  })
  .on("mouseleave", function () {
    $(this).removeClass("ui-state-hover", 200);
  });

// 表单验证通过高亮
$("#input").on("blur", function () {
  if ($(this).val()) {
    $(this).addClass("valid", 300);
  } else {
    $(this).addClass("invalid", 300);
  }
});

实现原理

// jQuery UI 的 addClass 动画原理:
// 1. 计算元素当前样式 → 添加类后的目标样式
// 2. 用 animate 在时长内渐变过渡
// 3. 完成后再真正添加类(避免影响其他逻辑)
// 需要引 effects core 模块

.removeClass()

.removeClass() 的 UI 扩展：平滑移除类，与 addClass 对称。

带动画移除类

// 原生(瞬时)
$("#box").removeClass("highlight");

// UI 版(平滑过渡回原样式)
$("#box").removeClass("highlight", 500);

// 回调
$("#box").removeClass("highlight", 500, function () {
  console.log("已移除");
});

示例:加载状态

// 加载中
$("#content").addClass("loading", 200);

// 数据返回后移除
$("#content").removeClass("loading", 300, function () {
  $("#content").text("数据已加载");
});

类切换动画

// 先移除旧类再添加新类(两步动画)
$("#box").removeClass("state-a", 200, function () {
  $(this).addClass("state-b", 200);
});

// 更简单:用 switchClass(见后续章节)
$("#box").switchClass("state-a", "state-b", 400);

.toggleClass()

.toggleClass() 的 UI 扩展：在添加/移除之间切换并带动画。

基本用法

// 点击切换高亮
$("#item").on("click", function () {
  $(this).toggleClass("selected", 300);
});

// 带开关条件
$("#checkAll").on("change", function () {
  var on = $(this).is(":checked");
  $(".item").toggleClass("selected", on, 200);
});

场景:收藏/点赞切换

$("#favBtn").on("click", function () {
  var isFav = $(this).hasClass("fav-active");
  $(this).toggleClass("fav-active", !isFav, 300);
  // 同步图标文字
  $(this).find(".icon").toggleClass("ui-icon-star", !isFav)
                       .toggleClass("ui-icon-star-hollow", isFav);
});

与原生 toggleClass 区别

.switchClass()

.switchClass() 是 jQuery UI 特有方法：从一个类平滑切换到另一个类（removeClass + addClass 的动画合成）。

基本用法

// 从 state-a 平滑过渡到 state-b
$("#box").switchClass("state-a", "state-b", 400);

// 无时长(瞬时,等价于 remove+add)
$("#box").switchClass("state-a", "state-b");

典型应用:多状态切换

.state-idle   { background: #f5f5f5; }
.state-loading{ background: #fff3cd; }
.state-done   { background: #d4edda; }
.state-error  { background: #f8d7da; }

function setState(el, from, to) {
  $(el).switchClass(from, to, 300);
}

// 流程: 加载中 → 成功
setState("#status", "state-idle", "state-loading");
// ...请求完成
setState("#status", "state-loading", "state-done");

// 失败
setState("#status", "state-loading", "state-error");

回调

$("#box").switchClass("old", "new", 400, function () {
  console.log("类已切换完成");
});

颜色动画

颜色动画（Color Animation）让 animate() 支持颜色属性（background、color、border 等）渐变，原生 jQuery 不支持颜色渐变。

基本用法

// 背景色渐变(需引入颜色动画模块)
$("#box").animate({
  backgroundColor: "#ff6600",
  color: "#ffffff"
}, 800);

// 边框色渐变
$("#box").animate({
  borderColor: "#22c55e"
}, 600);

支持的格式

// 支持的颜色写法
$("#box").animate(
  { backgroundColor: "#ff0" },      // 十六进制
  { backgroundColor: "rgb(255,0,0)" },  // rgb
  { backgroundColor: "red" },       // 颜色名
  { backgroundColor: "rgba(0,0,255,0.5)" }  // rgba(部分)
);

应用:保存成功反馈

$("#btnSave").on("click", function () {
  $(this).animate({ backgroundColor: "#22c55e" }, 400, function () {
    // 变回原色
    $(this).animate({ backgroundColor: "#e6e6e6" }, 400);
  });
});

配合高亮特效

// highlight 特效本质就是颜色动画
$("#row").effect("highlight", { color: "#ffff99" }, 1200);

定位（Position）

position 工具精确定位元素：相对另一个元素/窗口/鼠标位置对齐，是下拉、提示、弹层的定位基础。

基本用法

$("#tooltip").position({
  my: "left top",       // 自身左上角
  at: "right top",      // 对齐目标右上角
  of: "#trigger",       // 目标元素
  collision: "flip"     // 空间不足翻转
});

定位方向速查

my/at 取值: left/center/right + top/center/bottom
示例:
  "left top"    左上
  "center"      居中
  "right bottom" 右下
  "left+15 center" 左偏15px居中

of: 目标元素 / window / 事件对象
collision: flip(翻转) fit(收缩) none

下拉菜单定位

$("#menuBtn").on("click", function (e) {
  $("#menu").show().position({
    my: "left top",
    at: "left bottom",
    of: "#menuBtn"     // 按钮下方
  });
});

对话框居中

// dialog 的 position 选项直接支持
$("#dlg").dialog({
  position: { my: "center", at: "center", of: window }
});

// 或动态重定位
$("#dlg").dialog("option", "position", { my: "center", at: "center", of: window });

跟随鼠标

$(document).on("mousemove", function (e) {
  $("#cursorTip").position({
    my: "left+10 top+10",
    at: "left top",
    of: e            // 事件对象 = 鼠标位置
  });
});

部件库（Widget Factory）

部件工厂（Widget Factory）是 jQuery UI 创建组件的核心机制：$.widget()，它规范了组件结构，让所有组件 API 统一。

为什么需要部件工厂

// 手写插件的问题:每次都要处理
// 选项默认值、方法分发、事件、销毁……
$.fn.myPlugin = function (method) { /* 手动写一堆 */ };

// 部件工厂自动处理以上所有,只需写业务逻辑

创建一个组件

$.widget("custom.progressRing", {
  // 选项与默认值
  options: {
    radius: 50,
    percent: 0,
    color: "#4a90d9"
  },

  // 创建时调用
  _create: function () {
    this._canvas = $("<canvas></canvas>")
      .appendTo(this.element);
    this._draw();
  },

  // 选项变化时调用
  _setOption: function (key, value) {
    this._super(key, value);
    if (key === "percent" || key === "color") {
      this._draw();
    }
  },

  // 私有方法
  _draw: function () {
    var ctx = this._canvas[0].getContext("2d");
    var pct = this.options.percent;
    ctx.clearRect(0, 0, 200, 200);
    ctx.beginPath();
    ctx.arc(100, 100, this.options.radius,
      0, pct / 100 * Math.PI * 2);
    ctx.strokeStyle = this.options.color;
    ctx.lineWidth = 10;
    ctx.stroke();
  },

  // 公开方法
  setPercent: function (value) {
    this._setOption("percent", value);
  },

  // 销毁时清理
  _destroy: function () {
    this._canvas.remove();
  }
});

使用自定义组件

<div id="ring"></div>

$("#ring").progressRing({
  radius: 60,
  percent: 45,
  color: "#22c55e"
});

// 统一 API: option / 方法 / destroy
$("#ring").progressRing("setPercent", 80);
$("#ring").progressRing("option", "color", "#e4393c");
$("#ring").progressRing("destroy");

命名与继承

// 命名空间.组件名 (必须有点)
$.widget("ns.myWidget", { ... });

// 继承已有组件
$.widget("ns.enhancedDialog", $.ui.dialog, {
  _create: function () {
    this._super();          // 调用父类
    // 增强逻辑
  }
});