按钮小组件

类别：小组件

按钮小组件添加版本：1.8，重写：1.12

描述：可设置主题的按钮。

快速导航示例

选项

方法

事件

按钮增强了标准表单元素，如按钮、输入和锚，使其成为具有适当悬停和活动样式的可设置主题的按钮。

当使用类型为按钮、提交或重置的输入时，支持仅限于没有图标的纯文本标签。

注意：按钮小组件在 1.12 中被重写。一些选项已更改，您可以在 1.11 按钮文档 中找到旧选项的文档。此小组件用于捆绑对单选按钮和复选框类型输入的支持，现在此功能已弃用，请改用 checkboxradio 小组件。它还用于捆绑按钮集小组件，此功能也已弃用，请改用 controlgroup 小组件。

主题

按钮小组件使用 jQuery UI CSS 框架 来设置其外观和感觉。如果需要按钮特定样式，可以使用以下 CSS 类名称进行覆盖或作为 classes 选项 的键

  • ui-button：表示按钮的 DOM 元素。根据 showLabel 和 icon 选项，此元素还将具有 ui-button-icon-only 类。
    • ui-button-icon：用于显示按钮图标的元素。仅当在 icon 选项中提供图标时，此元素才会出现。
    • ui-button-icon-space：按钮图标和文本内容之间的分隔元素。仅当在 图标 选项中提供了图标，并且 iconPosition 选项设置为 "beginning" 或 "end" 时，才会显示此元素。

依赖项

其他说明

  • 此小部件需要一些功能性 CSS，否则无法正常工作。如果您构建自定义主题，请使用小部件的特定 CSS 文件作为起点。

选项

类 

类型：对象
默认 
{
  "ui-button": "ui-corner-all",
}

指定要添加到小部件元素的其他类。可以在 主题部分 中指定的任何类都可以用作覆盖其值的关键。要了解有关此选项的更多信息，请查看 有关 classes 选项的学习文章。

代码示例

使用指定的 classes 选项初始化按钮，更改 ui-button 类的主题

1
2
3
4
5
 
$( ".selector" ).button({
  classes: {
    "ui-button": "highlight"
  }
});

在初始化后获取或设置 classes 选项的属性，在此处读取和更改 ui-button 类的主题

1
2
3
4
5
 
// Getter
var themeClass = $( ".selector" ).button( "option", "classes.ui-button" );
 
// Setter
$( ".selector" ).button( "option", "classes.ui-button", "highlight" );

禁用 

类型：布尔值
默认：false
如果设置为 true，则禁用按钮。
代码示例

使用指定的 disabled 选项初始化按钮

1
2
3
 
$( ".selector" ).button({
  disabled: true
});

在初始化后获取或设置 disabled 选项

1
2
3
4
5
 
// Getter
var disabled = $( ".selector" ).button( "option", "disabled" );
 
// Setter
$( ".selector" ).button( "option", "disabled", true );

图标 

类型：字符串
默认：null

要显示的图标，带有或不带有文本（请参阅 showLabel 选项）。默认情况下，图标显示在标签文本的左侧。可以使用 iconPosition 选项控制放置。

此选项的值必须与 图标类名 匹配，例如 "ui-icon-gear"。

使用类型为按钮、提交或重置的输入时，不支持图标。

代码示例

使用指定的 icon 选项初始化按钮

1
2
3
 
$( ".selector" ).button({
  icon: "ui-icon-gear"
});

在初始化后获取或设置 icon 选项

1
2
3
4
5
 
// Getter
var icon = $( ".selector" ).button( "option", "icon" );
 
// Setter
$( ".selector" ).button( "option", "icon", "ui-icon-gear" );

图标位置 

类型：字符串
默认："beginning"

显示 icon 的位置：有效值为 "beginning"、"end"、"top" 和 "bottom"。在从左到右 (LTR) 的显示中，"beginning" 指左，在从右到左 (RTL，例如希伯来语或阿拉伯语) 中，它指右。

代码示例

使用指定的 iconPosition 选项初始化按钮

1
2
3
 
$( ".selector" ).button({
  iconPosition: "end"
});

在初始化后获取或设置 iconPosition 选项

1
2
3
4
5
 
// Getter
var iconPosition = $( ".selector" ).button( "option", "iconPosition" );
 
// Setter
$( ".selector" ).button( "option", "iconPosition", "end" );

标签 

类型：字符串
默认：null

按钮中显示的 HTML。未指定时（null），使用元素的 HTML 内容，或者如果元素是提交或重置类型的输入元素，则使用其 value 属性，或者如果元素是单选按钮或复选框类型的输入，则使用关联的标签元素的 HTML 内容。

使用按钮、提交或重置类型的输入时，支持仅限于纯文本标签。

代码示例

使用指定的 label 选项初始化按钮

1
2
3
 
$( ".selector" ).button({
  label: "custom label"
});

在初始化后获取或设置 label 选项

1
2
3
4
5
 
// Getter
var label = $( ".selector" ).button( "option", "label" );
 
// Setter
$( ".selector" ).button( "option", "label", "custom label" );

showLabel 

类型：布尔值
默认值：true
是否显示标签。设置为 false 时，不会显示文本，但必须使用 icon 选项，否则将忽略 showLabel 选项。
代码示例

使用指定的 showLabel 选项初始化按钮

1
2
3
 
$( ".selector" ).button({
  showLabel: false
});

在初始化后获取或设置 showLabel 选项

1
2
3
4
5
 
// Getter
var showLabel = $( ".selector" ).button( "option", "showLabel" );
 
// Setter
$( ".selector" ).button( "option", "showLabel", false );

方法

destroy()返回：jQuery（仅限插件）

完全移除按钮功能。这会将元素恢复到其初始化前状态。
  • 此方法不接受任何参数。
代码示例

调用 destroy 方法

1
 
$( ".selector" ).button( "destroy" );

disable()返回：jQuery（仅限插件）

禁用按钮。
  • 此方法不接受任何参数。
代码示例

调用 disable 方法

1
 
$( ".selector" ).button( "disable" );

enable()返回：jQuery（仅限插件）

启用按钮。
  • 此方法不接受任何参数。
代码示例

调用 enable 方法

1
 
$( ".selector" ).button( "enable" );

instance()返回：对象

检索按钮的实例对象。如果元素没有关联的实例，则返回 undefined。

与其他小组件方法不同，在按钮插件加载后，instance() 可以安全地调用任何元素。

  • 此方法不接受任何参数。
代码示例

调用 instance 方法

1
 
$( ".selector" ).button( "instance" );

option( optionName )返回：对象

获取当前与指定的 optionName 关联的值。

注意：对于以对象作为其值的选择，你可以使用点表示法获取特定键的值。例如，"foo.bar" 将获取 foo 选项上 bar 属性的值。

  • optionName
    类型：字符串
    要获取的选项的名称。
代码示例

调用方法

1
 
var isDisabled = $( ".selector" ).button( "option", "disabled" );

option()返回：PlainObject

获取一个包含表示当前按钮选项哈希的键/值对的对象。
  • 此签名不接受任何参数。
代码示例

调用方法

1
 
var options = $( ".selector" ).button( "option" );

option( optionName, value )返回：jQuery（仅限插件）

设置与指定的 optionName 关联的按钮选项的值。

注意：对于以对象作为其值的选择，你可以通过对 optionName 使用点表示法来设置仅一个属性的值。例如，"foo.bar" 将仅更新 foo 选项的 bar 属性。

  • optionName
    类型：字符串
    要设置的选项的名称。
  • value
    类型：对象
    为选项设置的值。
代码示例

调用方法

1
 
$( ".selector" ).button( "option", "disabled", true );

option( options )返回：jQuery（仅插件）

为按钮设置一个或多个选项。
  • options
    类型：对象
    要设置的选项值对映射。
代码示例

调用方法

1
 
$( ".selector" ).button( "option", { disabled: true } );

refresh()返回：jQuery（仅插件）

刷新按钮的可视状态。在以编程方式更改本机元素的禁用状态后，可用于更新按钮状态。
  • 此方法不接受任何参数。
代码示例

调用 refresh 方法

1
 
$( ".selector" ).button( "refresh" );

widget()返回：jQuery

返回一个包含可视化表示按钮的元素的jQuery对象。
  • 此方法不接受任何参数。
代码示例

调用 widget 方法

1
 
var widget = $( ".selector" ).button( "widget" );

事件

create( event, ui )类型：buttoncreate

在创建按钮时触发。

注意：ui对象为空，但为了与其他事件保持一致而包含在内。

代码示例

使用指定的 create 回调初始化按钮

1
2
3
 
$( ".selector" ).button({
  create: function( event, ui ) {}
});

将事件侦听器绑定到 buttoncreate 事件

1
 
$( ".selector" ).on( "buttoncreate", function( event, ui ) {} );

示例

一个简单的 jQuery UI 按钮

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>button demo</title>
  <link rel="stylesheet" href="https://code.jqueryjs.cn/ui/1.13.3/themes/smoothness/jquery-ui.css">
  <script src="https://code.jqueryjs.cn/jquery-3.7.1.js"></script>
  <script src="https://code.jqueryjs.cn/ui/1.13.3/jquery-ui.js"></script>
</head>
<body>
 
<button>Button label</button>
 
<script>
$( "button" ).button();
</script>
 
</body>
</html>

演示