jQuery UI 如何使用部件库（Widget Factory）

jQuery UI 如何使用部件库（Widget Factory）

jQuery UI 的所有小部件（Datepicker、Tabs、Dialog 等）都基于 Widget Factory（$.widget）构建。作为开发者，你可以直接使用 Widget Factory 来：

1. 创建全新的自定义小部件。
2. 扩展现有的 jQuery UI 小部件（最常见的使用方式）。
3. 利用其统一的 API 和生命周期来管理复杂交互。

下面一步步说明如何在项目中使用 Widget Factory。

1. 前提：引入 jQuery UI

Widget Factory 是 jQuery UI 的一部分，必须引入 jQuery UI 的 JS 文件（它会自动在 jQuery.ui 命名空间下暴露 $.widget）。

<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="https://code.jquery.com/ui/1.14.1/jquery-ui.min.js"></script>

2. 创建一个全新自定义小部件

使用 $.widget() 定义一个独立的新部件。

// 定义一个简单的计数器小部件
$.widget("custom.counter", {
    // 默认选项
    options: {
        value: 0,
        step: 1
    },

    // 创建时调用（初始化 DOM 和事件）
    _create: function() {
        this.element.addClass("custom-counter ui-widget ui-corner-all");

        this.display = $("<span>")
            .addClass("counter-display")
            .text(this.options.value)
            .appendTo(this.element);

        this.incrementBtn = $("<button>")
            .text("+")
            .addClass("ui-button ui-state-default")
            .on("click", () => this._increment())
            .appendTo(this.element);

        this.decrementBtn = $("<button>")
            .text("-")
            .addClass("ui-button ui-state-default")
            .on("click", () => this._decrement())
            .appendTo(this.element);
    },

    // 自定义方法：增加计数
    _increment: function() {
        this.value(this.options.value + this.options.step);
    },

    // 自定义方法：减少计数
    _decrement: function() {
        this.value(this.options.value - this.options.step);
    },

    // 公共方法：获取或设置值
    value: function(newValue) {
        if (newValue === undefined) {
            return this.options.value;
        }
        this._setOption("value", newValue);
    },

    // 选项改变时自动调用
    _setOption: function(key, value) {
        this._super(key, value);  // 调用父类
        if (key === "value") {
            this.display.text(value);
            this._trigger("change", null, { value: value });  // 触发 change 事件
        }
    },

    // 销毁时清理
    _destroy: function() {
        this.element.removeClass("custom-counter ui-widget ui-corner-all").empty();
        this._super();
    }
});

使用自定义小部件：

<div id="myCounter"></div>

<script>
$(function() {
    $("#myCounter").customCounter({ value: 10, step: 5 });

    // 绑定事件
    $("#myCounter").on("customcounterchange", function(event, ui) {
        console.log("当前值:", ui.value);
    });

    // 调用方法
    $("#myCounter").customCounter("value", 50);
});
</script>

3. 扩展现有 jQuery UI 小部件（最实用的方式）

继承官方小部件，只添加或修改需要的功能。

// 扩展 Dialog，添加默认的“帮助”按钮和标题图标
$.widget("custom.helpDialog", $.ui.dialog, {
    options: {
        helpText: "点击这里获取帮助",
        iconClass: "ui-icon-help"
    },

    _create: function() {
        this._super();  // 先调用父类的 _create

        // 添加标题图标
        if (this.options.iconClass) {
            $("<span>")
                .addClass(this.options.iconClass + " ui-dialog-title-icon")
                .prependTo(this.uiDialogTitlebar.find(".ui-dialog-title"));
        }

        // 添加帮助按钮
        var buttons = this.options.buttons || {};
        buttons["帮助"] = () => alert(this.options.helpText);
        this.option("buttons", buttons);
    }
});

使用扩展后的 Dialog：

<div id="helpDlg" title="使用说明">这是一个带帮助按钮的对话框。</div>

<script>
$("#helpDlg").customHelpDialog({
    modal: true,
    helpText: "本功能用于演示 Widget Factory 扩展",
    iconClass: "ui-icon-info"
});
$("#helpDlg").customHelpDialog("open");
</script>

4. 常见 Widget Factory 使用技巧

• 调用父类方法：始终在重写的方法中先调用 this._super() 或 this._superApply(arguments)。
• 触发事件：this._trigger("eventName", event, uiData)，用户可通过 .on("widgetNameeventName", handler) 绑定。
• 访问实例：$("#elem").data("custom-counter") 获取内部实例（高级用法）。
• 命名空间：推荐使用自定义命名空间（如 custom.、ui.、myapp.）避免冲突。

总结

在实际项目中，你使用 Widget Factory 的常见场景是：

• 需要对官方小部件进行小改动（如给 Tabs 加关闭按钮、给 Datepicker 加节假日高亮）。
• 需要创建项目专用的可复用组件（如表单验证提示、加载按钮、富文本工具栏）。

Widget Factory 提供了统一、一致、可继承的开发方式，让你的自定义组件与 jQuery UI 原生组件无缝融合，并自动享有主题支持、事件系统、状态管理等优势。

如果您有具体需求（如扩展某个官方部件的完整代码），告诉我，我可以提供针对性的实现示例！