## 组件的使用 X5的界面是由组件构成的，组件是一个可以以图形化方式显示在屏幕上，并能与用户进行交互的对象。组件是对数据和方法的封装，有自己的属性、事件和方法等。本文从组件的创建、属性、方法、操作、事件、样式、API、调试等方面介绍组件的使用。 # 目录 * [1、由组件构成的界面](http://wex5.com/cn/?p=4202#1) * [2、组件的创建](http://wex5.com/cn/?p=4202#2.1) * [2.1、设计时摆放组件](http://wex5.com/cn/?p=4202#2.1) * [2.2、动态创建组件](http://wex5.com/cn/?p=4202#2.2) * [3、组件的属性](http://wex5.com/cn/?p=4202#3.1) * [3.1、使用设计器设置](http://wex5.com/cn/?p=4202#3.1) * [3.2、使用表达式配置](http://wex5.com/cn/?p=4202#3.2) * [3.3、使用js代码修改](http://wex5.com/cn/?p=4202#3.3) * [4、组件的方法](http://wex5.com/cn/?p=4202#4.1) * [4.1、公共方法](http://wex5.com/cn/?p=4202#4.1) * [4.2、私有方法](http://wex5.com/cn/?p=4202#4.2) * [5、组件的操作](http://wex5.com/cn/?p=4202#5) * [6、组件的事件](http://wex5.com/cn/?p=4202#6.1) * [6.1、on开头的事件（回调型事件）](http://wex5.com/cn/?p=4202#6.1) * [6.2、bind开头的事件（标准的dom事件）](http://wex5.com/cn/?p=4202#6.2) * [7、组件的样式](http://wex5.com/cn/?p=4202#7.1) * [7.1、自定义组件样式](http://wex5.com/cn/?p=4202#7.1) * [7.2、修改系统样式](http://wex5.com/cn/?p=4202#7.2) * [7.3、引用样式文件](http://wex5.com/cn/?p=4202#7.3) * [8、组件的API](http://wex5.com/cn/?p=4202#8) * [9、组件的调试](http://wex5.com/cn/?p=4202#9.1) * [9.1、调试样式](http://wex5.com/cn/?p=4202#9.1) * [9.2、调试js代码](http://wex5.com/cn/?p=4202#9.2) # 1、由组件构成的界面 [](http://wex5.com/cn/wp-content/uploads/2015/04/comp1.jpg) [](http://wex5.com/cn/wp-content/uploads/2015/04/comp2.jpg) # 2、组件的创建 ## 2.1、设计时摆放组件 1. 选择合适的组件摆放到合适的位置 2. 调整组件的位置的两种方法 简单组件在设计器中拖动，红线的位置就是目标位置 [](https://box.kancloud.cn/2015-09-22_560159788f710.jpg) 复杂组件在左侧组件树中拖动，黑线的位置就是目标位置，根据黑线不同的长短，可以将选中的组件拖动到任意的地方 [](https://box.kancloud.cn/2015-09-22_56015979b77c4.jpg) 上图表示将formGroup3移动到formGroup2的上方，也就是调换了formGroup2和formGroup3的位置 [](https://box.kancloud.cn/2015-09-22_560159801dad8.jpg) 上图表示将formGroup3移动到formGroup1的col12节点下，也就是col12下面会有两个节点了，一个是原来的fWPBM，另一个是新移动过来的formGroup3 注：移动的位置不对，可以按Ctrl+Z撤销 ## 2.2、动态创建组件 ### 1、动态创建X5组件 使用new方法，创建X5组件 首先引用组件的js文件 var Button = require("$UI/system/components/justep/button/button"); 第一种方法，在参数中给出父节点parentNode，在new时会在父节点下直接创建出新的组件 var parentNode = this.getElementByXid("bar"); if (parentNode) { var xid = "--" + (++this.i) + "--"; var flag = { xid : xid, label : xid, parentNode : parentNode, 'class' : "btn btn btn-default" }; var button = new Button(flag); button.on("onClick", function(event) { alert(event.source.get('label')); }); } 第二种方法，不给出parentNode参数，在new时创建组件，调用addComponent方法后将新的组件加入到页面中 var newContent = this.comp('contents1').add({}); this.button = new Button({ label : '新按钮' }); this.button.on('onClick', function(event) { alert('单击事件'); }, this); justep.Component.addComponent(newContent.domNode, this.button); ### 2、动态创建html节点 var newContent = this.comp('contents1').add({}); var div = $("<div data-bind='click:divClick'>新的页面</div>"); justep.Bind.addNodes(newContent.domNode, div); //div的click事件调用的divClick方法 Model.prototype.divClick = function(){ alert('单击事件'); }; # 3、组件的属性 ## 3.1、使用设计器设置 ### 1、在属性编辑器中设置 组件都有xid属性，在同一个w文件中不能重复，通过xid可以获取组件的js对象和jQuery对象。注意：X5使用单页模式，系统会根据xid给组件生成不重复的id，因此不要自己增加id属性。容易造成id重复。 蓝色的属性是必填属性，属性值可以输入、下拉选择、弹出窗口选择 [](https://box.kancloud.cn/2015-09-22_56015980ad141.jpg) ### 2、通过右键菜单中设置 功能复杂的组件只在属性编辑器中设置属性是不够的，设计器给组件提供了右键菜单，通过右键菜单提供复杂的设置功能。下面列举了几个设置了右键菜单的组件： * data组件：编辑列、静态数据、规则 * bizdata组件：编辑规则、增加过滤条件、计算关系、统计关系 * dataTables组件：添加列 * grid组件：添加列、设置分组、设置多列头 * popMenu组件：在设计区域显示或隐藏弹出菜单，增加菜单项和分割线 [](https://box.kancloud.cn/2015-09-22_5601598146402.jpg) ## 3.2、使用表达式配置 组件的属性值分为普通值和表达式，表达式提供了组件属性的动态能力，即简化了代码，又容易设置，是X5的又一亮点。在表达式中，根据不同的情况，可以使用$model\$data\$row等环境变量。关于表达式的详细用法请参阅介绍绑定的相关文章。 [](https://box.kancloud.cn/2015-09-22_5601598372821.jpg) 下面列举一些常用的表达式 * 场景：mainData中当前行的fState字段的值为启用时，禁用按钮显示，否则不显示 * 做法：设置按钮组件 的bind-visible属性为$model.mainData.val(‘fState’)==’启用’ * 场景：mainData中当前行的fState字段的值为启用时，禁用按钮可用，否则不可用 * 做法：设置按钮组件 的bind-enable属性为$model.mainData.val(‘fState’)==’启用’ * 场景：在list组件中，突出显示选中的当前行 * 做法：设置list组件下面的li节点 的bind-css属性为{‘bg-primary':val(‘fID’)==data.val(‘fID’)}，其中bg-primary是Bootstrap里的一个样式class * 场景：表格中，当数量等于1时显示粉底色，否则显示黄底色 * 做法：设置grid组件或者dataTables组件的rowAttr属性为 $row.val(‘fSL’)==’1’?{style:’background:pink;’}:{style:’background:yellow;’} * 场景：表格中，计算金额列（fMoney）的合计值 * 做法：设置grid组件或者dataTables组件的金额列（fMoney）的footerData属性为 $model.mainData.sum(‘fMoney’) ## 3.3、使用js代码修改 组件提供了set方法，用来修改组件的属性。设计器中的属性有些只能在设计时设置，不能在运行时修改，因此set方法中能修改哪些属性，还需要看API文档中的具体说明。 看一下Button组件的API中set方法的描述，可以修改disabled、label等4个属性， [](https://box.kancloud.cn/2015-09-22_560159856a1f0.jpg) 例如：调整按钮的标签为启用，状态为不可用，图标换成icon-play this.comp('stateBtn').set({disabled:true,label:"启用",icon:"icon-play"}); 注意：set方法可以一次修改多个属性，因此set方法中的参数是json，一定要写大括号 # 4、组件的方法 ## 4.1、公共方法 ### 1、获取和设置组件的属性（get和set） 组件提供了set方法用于修改组件的属性。在上面（二、组件的属性（三）、使用js代码修改）中介绍了set方法。set方法可以一次修改多个属性，因此**set方法中的参数是json，一定要写大括号**。 组件提供了get方法用于获取组件的属性，get方法一次只获取一个属性的值，所以参数不是json，是string，直接传属性名即可。 例如：获取按钮组件的标签 alert(this.comp('stateBtn').get('label')); ### 2、增加和取消组件的事件（on和off） 组件提供了on方法用于添加事件处理器，提供了off方法用于取消事件处理器。 例如：给按钮添加（取消）单击事件 var Model = function() { this.callParent(); this.clickEventFn; }; Model.prototype.addEventBtnClick = function(event){ this.clickEventFn = function() { alert("新增的单击事件"); }; this.comp('button1').on('onClick',this.clickEventFn,this); }; Model.prototype.delEventBtnClick = function(event){ this.comp('button1').off('onClick',this.clickEventFn,this); }; 上面可以增加的事件处理器是组件的on开头的事件，如果要增加组件的其它事件，可以使用jQuery的on方法，例如：给input组件增加值改变添加监听事件（oninput事件） this.comp('input1').$domNode.on('input',function(){alert(this.value);}); 其中 * this.comp(‘input1′)获得组件的js对象 * this.comp(‘input1′).$domNode获得组件的jQuery对象 ## 4.2、私有方法 组件提供了很多方法，用于更灵活的使用它。在这些方法中，必须掌握的是data组件的方法，因为X5的组件是数据感知组件，只需针对数据进行编程即可。 data组件的常用方法（bizData组件继承自data组件，因此方法相同） * 新增、删除行及保存数据　newData deleteData saveData * 对列取值赋值　 getValue setValue * 设置过滤条件及刷新数据　 setFilter refreshData * 遍历数据及数据查找　 each find * 获取所有列名　 getColumnIDs * 获取当前行　 getCurrentRow getCurrentRowID * 聚合函数　 sum avg count max min 其它组件常用方法 * 打开弹出窗口：使用widowDialog组件open方法 * 弹出菜单：使用popMenu组件show方法 * 显示流程图：使用process组件showChart # 5、组件的操作 将组件的常用方法和图标icon、标题label组合为操作，在组件的单击事件中关联操作，就减少了写js代码调用组件方法的工作量，同时操作中的icon和label也会应用到组件上。例如：在按钮的单击事件onClick中选择data组件的保存操作，按钮将会使用保存操作设置的icon和label，省去了选择icon和设置label的步骤，从而保证了系统的统一风格。  # 6、组件的事件 ## 6.1、on开头的事件（回调型事件） on开头的事件是组件特意提供的事件，在触发和执行效率方面优于标准的dom事件。在操作组件和调用组件的方法时，会触发相关事件。还特别提供了在onClick事件中绑定组件的操作，从而减少代码量。 以data组件的两个数据改变事件为例，说明事件的触发和使用。data组件有两个数据改变事件，分别是数据改变onValueChange事件和数据改变后onValueChanged事件。为什么要提供两个事件呢？这两个事件又有什么区别呢？ 在修改数据时，首先触发data组件的onValueChange事件，这个事件提供了本次修改的新旧值，提供了判断新值是否合法的时机，新值如果不合法，可以通过重新设置新值，避免出现错误数据，之后触发onValueChanged事件，在这个事件中可以得到修改后的值，进行其它的处理。 ### 1、添加组件事件 如何添加data组件的onValueChange事件呢，选中data组件，将属性编辑器切换到事件编辑器，找到onValueChange事件，在右侧事件值的空白区域双击。 [](https://box.kancloud.cn/2015-09-22_5601598835f73.jpg) 此时UI设计器会从设计页切换到js页，并生成了新的事件方法。同时将新生成的事件方法名写入事件值。 ~~~ ~~~ ### 2、使用事件方法中的event参数 组件事件提供了event参数，它是一个json对象，其中包含在这个事件中需要用到的参数信息。 [](https://box.kancloud.cn/2015-09-22_560159897a097.jpg) 在事件方法中使用event参数 Model.prototype.mainDataValueChange = function(event){ alert('新值是'+event.newValue); alert('原值是'+event.oldValue); event.newValue = "";//新值不合法，清空输入 }; ### 3、event参数里面的三个常用的参数 * event.source：组件的js对象 * event.bindingContext：组件绑定的上下文，包含$model、$object等 * event.cancel：可修改，设置为true后中断当前动作 ## 6.2、bind开头的事件（标准的dom事件） * 标准事件，可向上冒泡。 * 使用event.currentTarget获取组件的jQuery对象 # 7、组件的样式 X5基于Bootstrap样式，同时又定义了一些新的样式，它们的区别是 * x-开头的样式是X5定义的样式 * 其它开头的样式是Bootstrap原生样式 [](https://box.kancloud.cn/2015-09-22_5601598aa2111.jpg) ## 7.1、自定义组件样式 1. 在css文件中定义新的class 2. 在组件的class属性中输入新定义的class名称 3. 如果定义在同名css文件（例如：当前是mainAcitivity.w，样式定义在mainAcitivity.css）中，不用引用这个css文件，否则需要在js文件中引用css文件 ## 7.2、修改系统样式 X5使用单页模式，在加载了新的样式后，原来的同名样式失效，为了避免样式覆盖，在修改系统样式时，在系统class前面增加一个class，例如：form-control是系统样式，重定义时定义为 .oa .form-control{ border: none; box-shadow: none; font-size:14px; padding:8px 0px; } 同时，在w文件的window组件的class属性中加上oa，这个样式就会在这个w文件上生效，不会影响其它使用form-control的w文件。 ## 7.3、引用样式文件 在js文件中，用下面第4行的写法引用/UI2/OA/config/pub.css 文件 define(function(require) { var $ = require("jquery"); var justep = require("$UI/system/lib/justep"); require("css!$UI/OA/config/pub").load(); # 8、组件的API ### 1、打开API文档 API在studio中，可以通过菜单打开。点击studio的菜单WeX5（BeX5），选择API文档，就打开了X5的API文档。 ### 2、查看组件API 在左侧目录中选择UI2，再选择COMPONENT，就列出了所有的组件，选中一个组件，右侧就列出了该组件的API。分为属性Properties、方法Methods、事件Events、常量Constants几大类。点击Properties列出组件的所有属性，点击Methods列出组件的所有方法，点击Events列出组件的所有事件。 [](https://box.kancloud.cn/2015-09-22_5601598b18d31.jpg) ### 3、查看组件全部的API component **BizData **extends [Data](http://wex5.com/cn/Data.html) 注意API文档中的这一句，说明BizData组件继承自Data组件，意味着继承了Data组件的所有属性、方法和事件。因此在查看BizData组件的API时，不能只看BizData列出的这些API，还要打开Data组件，查看Data组件的API， # 9、组件的调试 使用chrome浏览器的开发人员工具（按F12），进行调试 ### 9.1、调试样式 点放大镜图标，在页面上点击要查看样式的组件，Elements页中显示出了这个组件的html代码，Styles里面显示出了这个组件的样式，在这里修改即可直接看到效果。调整到满意后，写入css文件。 [](https://box.kancloud.cn/2015-09-22_5601598bcf952.jpg) ### 9.2、调试js代码 在组件的事件中增加debugger;，刷新页面后，触发这个事件，就会停在debugger;上，此时，可以在Watch Expressions中查看变量的值，也可以在Console里面输入变量回车，查看变量的值。 [](https://box.kancloud.cn/2015-09-22_5601598f200c8.jpg)