組建基礎 · wex5

## 組件的使用 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、由組件構成的界面 [![組織管理界面](https://box.kancloud.cn/2015-09-22_5601597196eeb.jpg)](http://wex5.com/cn/wp-content/uploads/2015/04/comp1.jpg) [![外賣界面](https://box.kancloud.cn/2015-09-22_560159731e617.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_560159788f710.jpg) 復雜組件在左側組件樹中拖動，黑線的位置就是目標位置，根據黑線不同的長短，可以將選中的組件拖動到任意的地方 [![在組件樹中移動復雜組件](https://box.kancloud.cn/2015-09-22_56015979b77c4.jpg)](https://box.kancloud.cn/2015-09-22_56015979b77c4.jpg) 上圖表示將formGroup3移動到formGroup2的上方，也就是調換了formGroup2和formGroup3的位置 [![在組件樹中移動復雜組件](https://box.kancloud.cn/2015-09-22_560159801dad8.jpg)](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)](https://box.kancloud.cn/2015-09-22_56015980ad141.jpg) ### 2、通過右鍵菜單中設置功能復雜的組件只在屬性編輯器中設置屬性是不夠的，設計器給組件提供了右鍵菜單，通過右鍵菜單提供復雜的設置功能。下面列舉了幾個設置了右鍵菜單的組件： * data組件：編輯列、靜態數據、規則 * bizdata組件：編輯規則、增加過濾條件、計算關系、統計關系 * dataTables組件：添加列 * grid組件：添加列、設置分組、設置多列頭 * popMenu組件：在設計區域顯示或隱藏彈出菜單，增加菜單項和分割線 [![組件右鍵菜單](https://box.kancloud.cn/2015-09-22_5601598146402.jpg)](https://box.kancloud.cn/2015-09-22_5601598146402.jpg) ## 3.2、使用表達式配置組件的屬性值分為普通值和表達式，表達式提供了組件屬性的動態能力，即簡化了代碼，又容易設置，是X5的又一亮點。在表達式中，根據不同的情況，可以使用$model\$data\$row等環境變量。關于表達式的詳細用法請參閱介紹綁定的相關文章。 [![表達式屬性](https://box.kancloud.cn/2015-09-22_5601598372821.jpg)](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個屬性， [![button組件API](https://box.kancloud.cn/2015-09-22_560159856a1f0.jpg)](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的步驟，從而保證了系統的統一風格。 ![組件的操作](https://box.kancloud.cn/2015-09-22_560159863ecf6.jpg) # 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)](https://box.kancloud.cn/2015-09-22_5601598835f73.jpg) 此時UI設計器會從設計頁切換到js頁，并生成了新的事件方法。同時將新生成的事件方法名寫入事件值。 ~~~ ~~~ ### 2、使用事件方法中的event參數組件事件提供了event參數，它是一個json對象，其中包含在這個事件中需要用到的參數信息。 [![組件事件API](https://box.kancloud.cn/2015-09-22_560159897a097.jpg)](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)](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列出組件的所有事件。 [![組件API](https://box.kancloud.cn/2015-09-22_5601598b18d31.jpg)](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)](https://box.kancloud.cn/2015-09-22_5601598bcf952.jpg) ### 9.2、調試js代碼在組件的事件中增加debugger;，刷新頁面后，觸發這個事件，就會停在debugger;上，此時，可以在Watch Expressions中查看變量的值，也可以在Console里面輸入變量回車，查看變量的值。 [![調試js代碼](https://box.kancloud.cn/2015-09-22_5601598f200c8.jpg)](https://box.kancloud.cn/2015-09-22_5601598f200c8.jpg)