一、基本信息

描述：将按钮聚合起来。

想要实现controlgroup组件，只要将需要聚合的按钮置于一个带data-role=”controlgroup”的容器内即可。jQuery Mobile框架会创建一个垂直的按钮组，移除按钮之间的所有margin和drop shadow，并在最上方和最下方应用圆角。

<div data-role=”controlgroup”>
<a href=”#” class=”ui-btn ui-corner-all”>Yes</a>
<a href=”#” class=”ui-btn ui-corner-all”>No</a>
<a href=”#” class=”ui-btn ui-corner-all”>Maybe</a>
</div>

通过在controlgroup容器上应用data-type=”horizontal”可以水平控件组，jQuery Mobile框架会浮动容器内部的按钮，使它们一个挨着一个地浮动起来，并且使按钮的宽度适应其内容（请注意，如果按钮数太多或者按钮里面的文本长度对屏幕而言过长的话，按钮会因为无法在一行里显示完全而跨行）。

标签label

如果你在controlgroup组件内用了input、button或select按钮，我们建议你将他们包裹在一个fieldset元素内，并且在fieldset元素内添加一个legend元素作为总标签。出于外观需要，jQuery Mobile框架会将具体按钮里面的label元素隐藏掉（只能通过屏幕阅读器访问到）。不过，如果你是将表单元素包裹在label元素内的话，label元素就不会被jQuery Mobile框架隐藏掉，所以通常情况下你需要将label标签和表单元素分开写并在label标签上添加for属性以便将它与表单元素在语义上关联起来。

二、选项

2.1、corners

布尔型，默认值为true。设定是否在controlgroup组件上应用圆角。

亦可通过data-corners=”false”来设定。

在初始化controlgroup组件时指定corners：

$( “.selector” ).controlgroup({
corners: false
});

在controlgroup组件初始化结束后获取、设定corners：

获取：var corners = $( “.selector” ).controlgroup( “option”, “corners” );

设定：$( “.selector” ).controlgroup( “option”, “corners”, false );

2.2、defaults

布尔型，默认值为false。若设定为true，则会告诉jQuery Mobile框架：其他选项都用的是默认值，这会让jQuery Mobile框架不再去读取其他选项的值，这会加快页面启动的速度。

亦可通过data-default=”true”来设定。

在controlgroup组件初始化时指定defaults：

$( “.selector” ).controlgroup({
defaults: true
});

在controlgroup组件初始化结束后获取、设定defaults：

获取：var defaults = $( “.selector” ).controlgroup( “option”, “defaults” );

设定：$( “.selector” ).controlgroup( “option”, “defaults”, true );

2.3、disabled

布尔型，默认值为false。若设定为true会禁用controlgroup组件。亦可通过data-disabled=”true”来设定。

在controlgroup组件初始化时指定disabled：

$( “.selector” ).controlgroup({
disabled: true
});

在controlgroup组件初始化结束后获取、设定disabled：

获取：var disabled = $( “.selector” ).controlgroup( “option”, “disabled” );

设定：$( “.selector” ).controlgroup( “option”, “disabled”, true );

2.4、excludeInvisible

布尔型，默认值为true。规定jQuery Mobile框架在处理圆角时是否要考虑不可见的子部件。

若设定为false，controlgroup组件内的所有子部件（包括隐藏着的子部件）都会在jQuery Mobile框架处理圆角时被考虑到。也就是说，假如controlgroup组件的第一个子部件被隐藏掉了，那么，整个controlgroup的最上方将没有圆角了。

在controlgroup组件初始化时设定excludeInvisible：

$( “.selector” ).controlgroup({
excludeInvisible: false
});

在controlgroup组件初始化结束后获取、设定excludeInvisible：

获取：var excludeInvisible = $( “.selector” ).controlgroup( “option”, “excludeInvisible” );

设定：$( “.selector” ).controlgroup( “option”, “excludeInvisible”, false );

2.5、initSelector

2.6、mini

布尔型，默认值为null (false)。

若设定为true，会实现迷你版的controlgroup组件，迷你版controlgroup组件的高度上会比常规的controlgroup组件小，这个高度的改变是通过在controlgroup组件最外层容器上应用ui-mini类实现的。

亦可通过data-mini=”true”来设定。

2.7、shadow

布尔型，默认值为false。

设定是否在controlgroup组件周围应用drop shadow效果。

该选项亦可通过data-shadow=”false”来设定。

在controlgroup组件初始化时指定shadow：

$( “.selector” ).controlgroup({
shadow: true
});

在controlgroup组件初始化结束后获取、设定shadow：

获取：var shadow = $( “.selector” ).controlgroup( “option”, “shadow” );

设定：$( “.selector” ).controlgroup( “option”, “shadow”, true );

2.8、theme

字符串型，无默认值，会从外部继承相应的值。

亦可通过data-theme=”b”来设定。

在controlgroup组件初始化时指定theme：

$( “.selector” ).controlgroup({
theme: “b”
});

在controlgroup组件初始化结束后获取、设定theme：

获取：var theme = $( “.selector” ).controlgroup( “option”, “theme” );

设定：$( “.selector” ).controlgroup( “option”, “theme”, “b” );

2.9、type

字符串型，默认值为”vertical”。

规定是在竖直方向上（vertical）堆砌子部件还是让子部件在水平方向上（horizontal）一个挨着一个地排列。

在controlgroup组件初始化时指定type：

$( “.selector” ).controlgroup({
type: “horizontal”
});

在controlgroup组件初始化结束后获取、设定type：

获取：var type = $( “.selector” ).controlgroup( “option”, “type” );

设定：$( “.selector” ).controlgroup( “option”, “type”, “horizontal” );

三、方法

3.1、container()

获取controlgroup组件中子部件所处的容器元素。

该方法不接受任何参数。

调用container方法：$( “.selector” ).controlgroup( “container” );

3.2、destroy()

彻底移除controlgroup组件功能。这会让相应的元素回到它们被初始化为controlgroup组件之前的状态。

该方法不接受任何参数。

调用destroy方法：$( “.selector” ).controlgroup( “destroy” );

3.3、disable()

禁用controlgroup组件。

该方法不接受任何参数。

调用disable方法：$( “.selector” ).controlgroup( “disable” );

3.4、enable()

启用controlgroup组件。

该方法不接受任何参数。

调用enable方法：$( “.selector” ).controlgroup( “enable” );

3.5、option( optionName )

获取optionName选项当前的值。optionName参数为字符串型。

调用该方法：var isDisabled = $( “.selector” ).controlgroup( “option”, “disabled” );

3.6、option()

获取一个由名值对构成的对象，其内的名值对反应了controlgroup组件当前的选项名及其配值。

该方法不接受任何参数。

调用该方法：var options = $( “.selector” ).controlgroup( “option” );

3.7、option( optionName, value )

将controlgroup组件中选项optionName的值设定为value。

optionName参数为字符串型。

调用该方法：$( “.selector” ).controlgroup( “option”, “disabled”, true );

3.8、option( options )

设定controlgroup组件中的一个或多个值。

options参数为由名值对组成的object。

调用该方法：$( “.selector” ).controlgroup( “option”, { disabled: true } );

四、事件

4.1、create( event, ui )

当controlgroup组件被创建完毕时会触发该事件。event参数为event类型，ui参数为object类型。

注意，虽然ui对象为空对象，但请不要省略掉它。

在controlgroup组件初始化时指定create回调函数：

$( “.selector” ).controlgroup({
create: function( event, ui ) {}
});

绑定一个事件监听器到controlgroupcreate事件上：

$( “.selector” ).on( “controlgroupcreate”, function( event, ui ) {} );

五、DEMO

<!doctype html>
<html lang=”en”>
<head>
<meta charset=”utf-8″>
<meta name=”viewport” content=”width=device-width, initial-scale=1″>
<title>controlgroup demo</title>
<link rel=”stylesheet” href=”//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css”>
<script src=”//code.jquery.com/jquery-1.10.2.min.js”></script>
<script src=”//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js”></script>
</head>
<body>

<div data-role=”page” id=”page1″>
<div role=”main” class=”ui-content”>
<div data-role=”controlgroup”>
<a href=”#” class=”ui-btn ui-corner-all”>Yes</a>
<a href=”#” class=”ui-btn ui-corner-all”>No</a>
<a href=”#” class=”ui-btn ui-corner-all”>Maybe</a>
</div>
</div>
</div>

</body>
</html>

以上，滕运锋，2016年1月2日于上海。