ydTreeSelect

ydTreeSelect 提供可以在下拉框中选择的树，支持单选、多选以及其他常用设置。

引入组件库

• ydTreeSelect 只包含一个 js 文件 ydl.treeselect.js，或者使用压缩的版本 ydl.treeselect.min.js
• ydTreeSelect 依赖 jQuery 和 zTree，使用时必须先加载 jquery.js 和 zTree 的 js 和 css 文件，并且能引用到 zTree 的相关图片

在HTML页面中引入

• 请将必需的库文件放到合适的目录下，然后在页面中引入

<link rel="stylesheet" href="ztree.css" />
<script src="jquery.min.js"></script>
<script src="jquery.ztree.all.min.js"></script>
<script src="ydl.treeselect.js"></script>

在YDPX页面中引入

• 相关的库文件已经包含在 yd-ydpx.jar 中，直接引入即可
• 可以选择 ztree1.css 或 ztree2.css 两种树的样式

<styles>
  <style include="ztree1.css" />
</styles>
<scripts>
  <script include="ztree.js" />
  <script include="ydl.treeselect.js" />
  <script>
  ……
  </script>
</scripts>

初始化组件

• 通过ydTreeSelect方法，可以将一个普通文本框初始化为下拉树组件
• 在HTML页面中，可以把初始化代码写在页面加载完成后的事件处理函数中
• 在YDPX页面中，可以把初始化代码写在pageOnload回调函数中

默认初始化

• 下拉树目前只支持一次性加载全部数据，数据中必须包含id、pId、name三个属性，还可以包含其他业务字段，通过组件方法的第一个参数传递数据

<input type="text" id="input1" />

var data1 = [
    {id: 1, pId: 0, name: '北京'},
    {id: 2, pId: 0, name: '天津'},
    {id: 5, pId: 0, name: '河北省'},
    {id: 51, pId: 5, name: '石家庄'},
    {id: 52, pId: 5, name: '保定'},
    {id: 6, pId: 0, name: '广东省'},
    {id: 61, pId: 6, name: '广州'},
    {id: 62, pId: 6, name: '深圳'}
];
$('#input1').ydTreeSelect(data1);

• 支持使用相同的数据和参数同时将多个文本框初始化为下拉树组件

$('#input1,#input2').ydTreeSelect(data1);

自定义初始化参数

• 通过组件方法的第二个参数，可以在初始化时传递自定义设置参数，例如

var data2 = [
	{id: 1, pId: 0, name: '北京', areacode: '010'},
	{id: 2, pId: 0, name: '天津', areacode: '022'},
	{id: 3, pId: 0, name: '上海', areacode: '021'},
	{id: 4, pId: 0, name: '重庆', areacode: '023'},
	{id: 5, pId: 0, name: '河北省', areacode: '03xx'},
	{id: 51, pId: 5, name: '石家庄', areacode: '0311'},
	{id: 52, pId: 5, name: '保定', areacode: '0312'},
	{id: 53, pId: 5, name: '邯郸', areacode: '0310'},
	{id: 54, pId: 5, name: '承德', areacode: '0314'},
	{id: 6, pId: 0, name: '广东省', areacode: '07xx'},
	{id: 61, pId: 6, name: '广州', areacode: '020'},
	{id: 62, pId: 6, name: '深圳', areacode: '0755'},
	{id: 63, pId: 6, name: '东莞', areacode: '0769'},
	{id: 64, pId: 6, name: '佛山', areacode: '0757'},
	{id: 7, pId: 0, name: '福建省', areacode: '059x'},
	{id: 71, pId: 7, name: '福州', areacode: '0591'},
	{id: 72, pId: 7, name: '厦门', areacode: '0592'},
	{id: 73, pId: 7, name: '泉州', areacode: '0595'},
	{id: 74, pId: 7, name: '三明', areacode: '0598'}
];
//在树上显示单选按钮，返回选中节点的电话区号，选中后自动关闭下拉面板
$('#input1').ydTreeSelect(data2, {
	type: 'radio',
	retAttr: 'areacode',
	hideOnCheck: true
});

• 所有的初始化参数如下表所示

| 参数名 | 缺省值 | 参数含义 |--------------|------------|---------------------------------------------------------------------------------- | width | undefined | 设置下拉面板宽度，一般不需要设置此参数，缺省为自动，与文本框同宽 | height | 300 | 设置下拉面板高度 | zIndex | 10 | 叠放顺序，当被其他组件遮挡时才需要设置；当文本框在模态框（.modal）中时会自动调整 | type | 'checkbox' | 选项类型：单选'radio'，复选'checkbox' | checkParent | false | 是否可选择父节点（如果是异步加载树节点，此参数无效，需要使用者自行编码处理排除父节点） | retAttr | name | 选中后返回的属性 | expand | true | 初始时是否展开全部节点（在异步加载树节点时此参数无效） | trigger | null | 点击时显示下拉面板的触发元素id或对象，null为文本框的下一个紧邻元素，空串为不设置触发元素（当不想将下一个紧邻元素作为触发元素时使用） | showOnFocus | true | 获得焦点时是否显示下拉面板，如果设为false，则只能通过触发元素或show方法显示 | hideOnCheck | false | 选中后是否自动关闭下拉面板 | cloneData | false | 是否使用克隆的数据，只有在使用同一组数据初始化多个组件，且参数不同或需要手工调整数据时才需要设置，以防止原始数据被修改，造成多个组件互相影响，在大数据量的情况下可能影响性能；在异步加载树节点时无需配置此参数 | init | null | 组件初始化之前的回调函数，init: function (treeSettings, treeData) { }，参数是zTree初始化参数和树数据，可以在创建树之前进行修改（如果设置了cloneData: true，这里就是克隆后的数据，修改它不会影响原数据对象），不需要返回值，上下文对象是文本框，在这个函数里可以返回一个新的对象作为树的初始化参数，或者修改原有参数对象 | inited | null | 组件初始化之后的回调函数，inited: function ($tree, $panel) { }，参数是zTree对象和下拉面板对象，不需要返回值，上下文对象是文本框 | shown | null | 下拉面板显示后的回调函数，shown: function ($tree, $panel) { }，参数是zTree对象和下拉面板对象，不需要返回值，上下文对象是文本框 | hidden | null | 下拉面板隐藏后的回调函数，hidden: function ($tree, $panel) { }，参数是zTree对象和下拉面板对象，不需要返回值，上下文对象是文本框 | check | null | 勾选或取消勾选复选框之前的回调函数，check: function ($tree, node, isCheck) { return true; }，参数是zTree对象、树节点对象、当前操作是否为选择（true=选择，false=取消选择），需要返回true/false，返回false可阻止选择，上下文对象是文本框 | checked | null | 勾选或取消勾选复选框之前的回调函数，checked: function ($tree, node, isCheck) { }，参数是zTree对象、树节点对象、当前操作是否为选择（true=选择，false=取消选择），不需要返回值，上下文对象是文本框 | selector | 'body' | 指定新创建的下拉面板所属的父元素选择器，此参数影响滚动时定位，应设为与文本框最近的可滚动父元素 | modalClass | 'modal' | 模态框样式名，用于识别文本框是否在模态框内，缺省为bootstrap使用的.modal样式，如果模态框使用其他实现方式，请配置这个参数；设为null则不对模态框进行处理

组件接口方法

• 组件接口方法通过 $(input).ydTreeSelect('方法名', 其他参数...) 调用
• 方法名不区分大小写
• 必须先对组件进行初始化成功后，才能调用组件方法
• 除了取值方法（如getValue）以外，其他所有方法的返回值均是当前组件自身，以支持链式操作，例如

//在输入框input1的下拉树中选中id为15的节点，然后给文本框设置焦点
$('#input1').ydTreeSelect('setValue', '15').focus();

show

• 显示下拉面板

$('#input1').ydTreeSelect('show');

hide

• 隐藏下拉面板

$('#input1').ydTreeSelect('hide');

expand

• 展开全部树节点

$('#input1').ydTreeSelect('expand');
//或者
$('#input1').ydTreeSelect('expand', true);

• 收起全部树节点

$('#input1').ydTreeSelect('expand', false);

attr

• 设置组件属性
• 目前只支持设置只读属性readonly，如果设置readonly为true，将不能显示下拉面板进行选择，设置readonly为false后即可恢复下拉选择
• 设置只读

$('#input1').ydTreeSelect('attr', 'readonly', true);

• 取消只读

$('#input1').ydTreeSelect('attr', 'readonly', false);

setValue

• 调用方法：$(input).ydTreeSelect('setValue', 树节点关键属性值, 关键属性名);

• 关键属性值可以是半角逗号分隔的字符串，也可以是字符串数组

• 关键属性名可以省略，缺省为id

• 选中指定id的树节点

//选中id分别为2、52、61的树节点
$('#input1').ydTreeSelect('setValue', '2,52,61');
//或者
$('#input1').ydTreeSelect('setValue', ['2', '52', '61']);

• 选中指定属性的树节点

//选中name分别为'北京'、'上海'的树节点
$('#input1').ydTreeSelect('setValue', '北京,上海', 'name');
//或者
$('#input1').ydTreeSelect('setValue', ['北京','上海'], 'name');

//选中areacode分别为'0310'、'0755'、'0592'的树节点
$('#input2').ydTreeSelect('setValue', '0310,0755,0592', 'areacode');
//或者
$('#input2').ydTreeSelect('setValue', ['0310','0755','0592'], 'areacode');

• 支持同时给多个下拉树组件统一设置相同的值

//在input1和input2的下拉树中分别选中id为2、52、61的树节点
$('#input1,#input2').ydTreeSelect('setValue', '2,52,61');

getValue

• 调用方法：var values = $(input).ydTreeSelect('getValue', 树节点关键属性名);

• 关键属性名可以省略，缺省为id

• 返回值是所有已选中节点指定属性值的数组，如果需要逗号分隔的字符串，可以再自行.join(',')

• 获取下拉树已选中节点的指定属性值数组

//缺省返回id的数组
var values = $('#input1').ydTreeSelect('getValue');
//结果：values = ['2', '52', '61']

//返回逗号分隔的字符串
var values = $('#input1').ydTreeSelect('getValue').join(',');
//结果：values = '2,52,61'

//指定返回name的数组
var values = $('#input1').ydTreeSelect('getValue', 'name');
//结果：values = ['天津', '保定', '广州']

//指定返回areacode的数组
var values = $('#input2').ydTreeSelect('getValue', 'areacode');
//结果：values = ['022', '0312', '020']

get

• 获取组件内部对象，可获取的对象包括：
  • panel 下拉面板对象

  var $panel = $('#input1').ydTreeSelect('get', 'panel');

  • trigger 触发元素对象

  var $trigger = $('#input1').ydTreeSelect('get', 'trigger');

  • tree zTree树对象

  var $tree = $('#input1').ydTreeSelect('get', 'tree');

  • settings 初始化设置选项

  var settings = $('#input1').ydTreeSelect('get', 'settings');

  • treeSettings 树初始化参数设置选项

  var settings = $('#input1').ydTreeSelect('get', 'treeSettings');

destroy

• 销毁下拉树组件，恢复成原始的文本输入框
• 组件销毁之后，就无法再对其使用组件方法。不过根据需要，还可以重新调用初始化方法，再次将文本框初始化成下拉树组件
• 当需要删除原始文本框的时候，才需要调用销毁方法，以避免内存泄露；如果只是临时禁用下拉树，请使用设置只读的方法

$('#input1').ydTreeSelect('destroy');

setDefaults

• 修改全局默认初始化参数，对设置之后所有初始化的下拉树组件生效
• 调用时可不必指定具体文本框元素，使用$()即可
• 如果需要使用此方法的话，建议写在项目公共的脚本中，对整个项目中的下拉树组件统一设置

$().ydTreeSelect('setDefaults', {
	checkParent: true
	selector: '#page_main'
});

版权所有

©华信永道（北京）科技股份有限公司