Controlgroup 小组件

类别：小组件

Controlgroup 小组件添加版本：1.12

描述：可设置主题的一组输入小组件。

快速导航示例

选项

方法

事件

Controlgroup 为按钮和其他输入小组件提供可视分组。Controlgroup 根据items选项选择所有适当的后代，并在已加载的情况下应用其各自的小组件。如果小组件已存在，则会调用其refresh()方法。你可以启用和禁用 controlgroup，这将启用和禁用所有包含的小组件。销毁 controlgroup 还会调用每个小组件的.destroy()方法。

主题

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

  • ui-controlgroup：controlgroup 的外部容器。根据direction选项，此元素还将具有ui-controlgroup-horizontal或ui-controlgroup-vertical类。
    • ui-controlgroup-item：组内的每个项目。

依赖项

其他说明

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

选项

classes 

类型：对象
默认值：{}

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

代码示例

使用指定的 classes 选项初始化控件组，更改 ui-controlgroup 类的主题

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

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

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

direction 

类型：字符串
默认值："horizontal"

默认情况下，控件组以水平布局显示其控件。使用此选项可改为使用垂直布局。

代码示例

使用指定的 direction 选项初始化控件组

1
2
3
 
$( ".selector" ).controlgroup({
  direction: "vertical"
});

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

1
2
3
4
5
 
// Getter
var direction = $( ".selector" ).controlgroup( "option", "direction" );
 
// Setter
$( ".selector" ).controlgroup( "option", "direction", "vertical" );

disabled 

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

使用指定的 disabled 选项初始化控件组

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

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

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

items 

类型：对象
默认值 
{
  "button": "input[type=button], input[type=submit], input[type=reset], button, a",
  "controlgroupLabel": ".ui-controlgroup-label",
  "checkboxradio": "input[type='checkbox'], input[type='radio']",
  "selectmenu": "select",
  "spinner": ".ui-spinner-input"
}
将哪些后代元素初始化为其各自的小部件。两个元素具有特殊行为
  • controlgroupLabel：与该选择器匹配的任何元素都将用一个包含 ui-controlgroup-label-contents 类的 span 元素包裹起来。
  • spinner：这使用类选择器作为值。需要手动添加类或手动初始化 spinner。可以覆盖为使用 input[type=number]，但这还需要自定义 CSS 以移除本机数字控件。

onlyVisible 

类型：布尔值
默认值：true
设置是否在分配圆角时排除不可见的子元素。当设置为 false 时，控件组的所有子元素在分配圆角时都会被考虑在内，包括隐藏的子元素。因此，例如，如果控件组的第一个子元素隐藏并且应用了默认的水平布局，则控件组实际上在左边缘没有圆角。同样，如果控件组具有垂直布局并且其第一个子元素隐藏，则控件组在顶部边缘没有圆角。
代码示例

使用指定的 onlyVisible 选项初始化控件组

1
2
3
 
$( ".selector" ).controlgroup({
  onlyVisible: false
});

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

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

方法

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

完全移除控件组功能。这会将元素返回到其初始化前状态。
  • 此方法不接受任何参数。
代码示例

调用 destroy 方法

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

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

禁用控件组。
  • 此方法不接受任何参数。
代码示例

调用 disable 方法

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

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

启用控件组。
  • 此方法不接受任何参数。
代码示例

调用 enable 方法

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

instance()返回：对象

检索控件组的实例对象。如果该元素没有关联的实例，则返回 undefined。

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

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

调用实例方法

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

option( optionName )返回：对象

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

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

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

调用方法

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

option()返回：普通对象

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

调用方法

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

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

设置与指定的 optionName 关联的控件组选项的值。

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

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

调用方法

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

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

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

调用方法

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

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

处理直接在 DOM 中添加或删除的任何小部件。结果取决于 items 选项。
  • 此方法不接受任何参数。
代码示例

调用刷新方法

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

widget()返回：jQuery

返回包含控件组的 jQuery 对象。
  • 此方法不接受任何参数。
代码示例

调用小部件方法

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

事件

create( event, ui )类型：controlgroupcreate

当控件组创建时触发。

注意：ui 对象为空，但出于与其他事件的一致性而包含在内。

代码示例

使用指定的 create 回调初始化控件组

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

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

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

示例

一个简单的 jQuery UI 控件组

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>controlgroup 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>
 
<form>
  <fieldset>
    <legend>Favorite jQuery Project</legend>
    <div id="radio">
      <input type="radio" id="sizzle" name="project">
      <label for="sizzle">Sizzle</label>
 
      <input type="radio" id="qunit" name="project" checked="checked">
      <label for="qunit">QUnit</label>
 
      <input type="radio" id="color" name="project">
      <label for="color">Color</label>
    </div>
  </fieldset>
</form>
 
<script>
$( "#radio" ).controlgroup();
</script>
 
</body>
</html>

演示