jQuery Mobile: Controlgroup Widget ​

一、基本信息 ​

描述：将按钮聚合起来。 想要实现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");\mathrm{设}\mathrm{定}：$( ".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");\mathrm{设}\mathrm{定}：$( ".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");\mathrm{设}\mathrm{定}：$( ".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");\mathrm{设}\mathrm{定}：$( ".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");\mathrm{设}\mathrm{定}：$( ".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");\mathrm{设}\mathrm{定}：$( ".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");\mathrm{设}\mathrm{定}：$( ".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日于上海。