# jQuery cxSelect cxSelect 是基于 jQuery 的多级联动菜单插件,适用于省市、商品分类等联动菜单。 列表数据通过 AJAX 获取,也可以自定义,数据内容使用 JSON 格式。 同时兼容 Zepto,方便在移动端使用。 国内省市县数据来源:[basecss/cityData](https://github.com/basecss/cityData) Date: 2014.03.31 全球主要城市数据来源:整理国内常用网站和软件 Date: 2014.07.29 **版本:** * jQuery v1.7+ | Zepto v1.0+ * jQuery cxSelect v1.4.0 文档:http://code.ciaoca.com/jquery/cxselect/ 示例:http://code.ciaoca.com/jquery/cxselect/demo/ ## 使用方法 ### 载入 JavaScript 文件 ```html <script src="jquery.js"></script> <script src="jquery.cxselect.js"></script> ``` ### DOM 结构 ```html <!-- select 必须放在元素 id="element_id" 的内部,不限层级 select 的 class 任意取值,也可以附加多个 class,如 class="province otherclass",在调用时只需要输入其中一个即可,但是不能重复 --> <div id="element_id"> <select class="province"></select> <select class="city"></select> <select class="area"></select> </div> ``` ### 设置默认值 ```html <!-- 方法一:使用 option 的 value 和 selected 属性 --> <select class="province"> <option value="浙江省" selected>浙江省</option> </select> <!-- 方法二:使用 select 的 data-value 属性 当同时设置 option 的 value 和 select 的 data-value 时,优先使用 data-value 的值 --> <select class="province" data-value="浙江省"></select> ``` ### 调用 cxSelect ``` javascript $('#element_id').cxSelect({ url: 'cityData.min.json' // 提示:如果服务器不支持 .json 类型文件,请将文件改为 .js 文件 selects: ['province', 'city', 'area'], // selects 为数组形式,请注意顺序 emptyStyle: 'none' }); ``` ### 设置参数全局默认值 ``` javascript // 需在引入 <script src="jquery.cxselect.js"></script> 之后,调用之前设置 $.cxSelect.defaults.url = 'cityData.min.json'; $.cxSelect.defaults.emptyStyle = 'none'; ``` ### API 接口 ``` javascript var cxSelectApi; // 方法一: cxSelectApi = $.cxSelect($('#element_id'), { selects: ['province', 'city', 'area'] }); // 方法二: $('#element_id').cxSelect({ selects: ['province', 'city', 'area'] }, function(api) { cxSelectApi = api; }); cxSelectApi.attach(); cxSelectApi.detach(); cxSelectApi.clear(); cxSelectApi.setOptions(); ``` ## 参数说明 名称|默认值|说明 ---|---|--- selects|[]|下拉选框组。<br>输入 select 的 className url|null|整合数据接口地址(URL);<br>每个选框的内容使用各自的接口地址,详见 [DEMO](http://code.ciaoca.com/jquery/cxselect/demo/oneself.html) data|null|自定义数据,类型为数组,使用 JSON 格式。[DEMO](http://code.ciaoca.com/jquery/cxselect/demo/custom.html) emptyStyle|null|子集无数据时 select 元素的显示状态。<br>可设置为:**"none"**(display:none), **"hidden"**(visibility:hidden) required|false|是否为必选。<br>设为 `false` 时,会在列表头部添加 `<option value="firstValue">firstTitle</option>` 选项。 firstTitle|'请选择'|选框第一个项目的标题(仅在 `required` 为 `false` 时有效) firstValue|''|选框第一个项目的值(仅在 `required` 为 `false` 时有效) jsonSpace|''|数据命名空间 jsonName|'n'|数据标题字段名称(用于 option 的标题) jsonValue|''|数据值字段名称(用于 option 的 value,没有值字段时使用标题作为 value) jsonSub|'s'|子集数据字段名称 ## data 属性参数 ### 父元素的 data- 属性 ```html <div id="element_id" data-url="cityData.min.json" data-required="true"></select> ``` 名称|说明 ---|--- data-selects|下拉选框组。<br>输入 select 的 className,使用英文逗号分隔的字符串 data-url|列表数据接口地址 data-empty-style|子集无数据时 select 的显示状态 data-required|是否为必选 data-first-title|选框第一个项目的标题 data-first-value|选框第一个项目的值 data-json-space|数据命名空间 data-json-name|数据标题字段名称 data-json-value|数据值字段名称 data-json-sub|子集数据字段名称 ### select 元素的 data- 属性 ```html <select class="province" data-value="浙江省" data-first-title="选择省"></select> ``` 名称|说明 ---|--- data-value|默认选中值 data-url|列表数据接口地址 data-required|是否为必选 data-query-name|传递上一个选框值的参数名称(默认使用上一个选框的 name 属性值) data-first-title|选框第一个项目的标题 data-first-value|选框第一个项目的值 data-json-space|数据命名空间 data-json-name|数据标题字段名称 data-json-value|数据值字段名称 ##API 接口 名称|说明 ---|--- attach()|绑定。<br>调用时会自动进行绑定,用于使用detach解除绑定后,进行重新绑定。 detach()|解除绑定。<br>解除绑定后,不再具有联动效果。 clear(index)|清空选项。<br>清空第 index 个 select 自身及之后的 select 的选项。<br>`index`: select 的序号,从 0 开始 setOptions(settings)|重新设置参数。<br>`settings`: 与调用时参数一致 ##自定义数据及使用纯数组数据 可以使用任何类型的数据作为值,但最终都会被转化为文本。 [自定义数据 DEMO](http://code.ciaoca.com/jquery/cxselect/demo/custom.html) ##各选项数据接口独立 可以为每个```select```设置一个接口,根据接口返回的数据结构,设置```json-space```、```json-name```、```json-value```适应 JSON 结构(包括纯数组)。 当页面加载时,第一个选框已有选项数据,可以不设置第一个选框的接口。 [独立接口 DEMO](http://code.ciaoca.com/jquery/cxselect/demo/oneself.html)