jQuery cxSelect插件API

黄弘盛

2023-12-01

#jQuery cxSelect

cxSelect 是基于 jQuery 的多级联动菜单插件，适用于省市、商品分类等联动菜单。

列表数据通过 AJAX 获取，也可以自定义，数据内容使用 JSON 格式。

同时兼容 Zepto，方便在移动端使用。

国内省市县数据来源：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 文件

<script src="jquery.js"></script>
<script src="jquery.cxselect.js"></script>

###DOM 结构

<!--
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>

###设置默认值

<!--
方法一：使用 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

$('#element_id').cxSelect({
  url: 'cityData.min.json'                // 提示：如果服务器不支持 .json 类型文件，请将文件改为 .js 文件
  selects: ['province', 'city', 'area'],  // selects 为数组形式，请注意顺序
  emptyStyle: 'none'
});

###设置参数全局默认值

// 需在引入 <script src="jquery.cxselect.js"></script> 之后，调用之前设置
$.cxSelect.defaults.url = 'cityData.min.json';
$.cxSelect.defaults.emptyStyle = 'none';

###API 接口

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	[]	下拉选框组。输入 select 的 className
url	null	整合数据接口地址（URL）每个选框的内容使用各自的接口地址，详见 [DEMO]
data	null	自定义数据，类型为数组，使用 JSON 格式。[DEMO]
emptyStyle	null	子集无数据时 select 的状态。可设置为："none"(display:none), "hidden"(visibility:hidden)
required	false	是否为必选。设为 false 时，会在列表头部添加 `<option value="firstValue">firstTitle</option>` 选项。
firstTitle	'请选择'	选框第一个项目的标题（仅在 required 为 false 时有效）
firstValue	''	选框第一个项目的值（仅在 required 为 false 时有效）
jsonSpace	''	数据命名空间
jsonName	'n'	数据标题字段名称（用于 option 的标题）
jsonValue	''	数据值字段名称（用于 option 的 value，没有值字段时使用标题作为 value）
jsonSub	's'	子集数据字段名称

##data 属性参数
###父元素上的 data- 属性

<div id="element_id" data-url="cityData.min.json" data-required="true"></select>

名称	说明
data-selects	下拉选框组。输入 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- 属性

<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()	绑定调用时会自动进行绑定，用于使用detach解除绑定后，进行重新绑定。
detach()	解除绑定解除绑定后，不再具有联动效果。
clear(index)	清空选项 index: select 的序号，从 0 开始。清空第 index 个 select 自身及之后的 select 的选项。
setOptions(settings)	重新设置参数 settings: 与调用时参数一致。

##自定义数据及使用纯数组数据
可以使用任何类型的数据作为值，但最终都会被转化为文本。

自定义数据 DEMO

##各选项数据接口独立
可以为每个select设置一个接口，根据接口返回的数据结构，设置json-space、json-name、json-value适应 JSON 结构（包括纯数组）。
当页面加载时，第一个选框已有选项数据，可以不设置第一个选框的接口。

独立接口 DEMO

记得初学的时候整理需求时遇到这样的问题，地点联动插件，本身是想所有的地点是通过交互过来的，而且一级出来下一级才能出来，还可以通过按钮任意设置一个默认的地址。

      <fieldset id="global_location">
        <select class="col-4 form-control country" name="country" data-first-title="请选择国家"  data-url="http:///service/api/getScmGeoList?type=country" data-json-space="data" data-json-name="name" data-json-value="sys_id" style=""></select>
        <select class="col-4 form-control province" name="province" data-first-title="请选择省" data-url="http:///service/api/getScmGeoList?type=province" data-json-space="data" data-json-name="name" data-json-value="sys_id" style=""></select>
        <select class="col-4 form-control city" name="city" data-first-title="请选择市" data-url="http:///service/api/getScmGeoList?type=city" data-json-space="data" data-json-name="name" data-json-value="sys_id" style="">
        </select>
        <button type="button" class="btn btn-primary" "selectFall('中国','上海')">默认值</button>
      </fieldset>

var cxSelectApi = null;
	$('#global_location').cxSelect({
	            selects: [ 'country', 'province', 'city'],
	            jsonSpace:"data",
	            jsonName: 'name',
	            jsonValue: 'sys_id',
	        }, function(api) {
	            cxSelectApi = api;
	        });
	        
	       
function findValue(str,url){
var sys_id
$.ajax({
    url: url,
    type: 'GET',
    dataType: 'json',
    async:false
  }).done(function(msg) {
      if(msg.data[0].name==str) {
        sys_id=msg.data[0].sys_id
      }
  })
  return sys_id
}

function selectInit(str1,str2,str3){
  if(str1==""){
    return false
  }else{
    $(".country option[value="+str1+"]").attr({"selected": true});
    if(!str2==""){
      cxSelectApi.attach();
      setTimeout(function(){
        $(".province option[value="+str2+"]").attr({"selected": true});
      },1000)
          if(!str3==""){
            cxSelectApi.attach();
            setTimeout(function(){
              $(".city option[value="+str3+"]").attr({"selected": true});
            },1000)
          }
    }
  }
}
function selectFall(site1,site2,site3){
   var url1='http:///service/api/getScmGeoList?type=country';
   var url2='http:///service/api/getScmGeoList?type=province';
   var url3='http:///service/api/getScmGeoList?type=city';
   var arr=[];
    if (site1=="") {
      return false
    }else{
      if (!site2=="") {
        arr.push(findValue(site1,url1))
        arr.push(findValue(site2,url2))
      }else{
        if (!site3=="") {
          arr.push(findValue(site3,url3))
        }
      }
    }
    selectInit(...arr)
}

业务上实现了但确是一个失败的例子

jQuery cxSelect插件API

相关阅读

相关文章

相关问答

相关文档