DIV CSS 佈局教程網

jQuery 樹狀控制項 zTree 使用大全:從初始化到自訂右鍵選單
編輯:關於JavaScript     

0. zTree 簡介

樹狀結構在授權、分類、組織架構這類應用裡幾乎是標配。zTree 是一個依附 jQuery 的多功能樹狀外掛,效能優異、設定彈性、功能組合豐富,是它最大的賣點。

主要特色:

• 新版把核心程式碼依功能切分,用不到的不必載入。只用基本功能載入 jquery.ztree.core-3.5.js 即可;需要核取方塊載入 excheck;需要編輯功能載入 exedit。

• 採用延遲載入,上萬個節點也能輕鬆處理,即使在 IE6 下也不至於卡死。

• 相容 IE、Firefox、Chrome、Opera、Safari。

• 支援 JSON 資料格式、靜態與 Ajax 非同步載入節點。

• 可任意更換樣式與自訂圖示(靠 CSS)。

• 核取方塊與單選按鈕的選擇功能極為靈活。

• 提供多種事件回呼。

• 具備完整的增刪改查與拖拉功能,支援多節點拖曳。

• 同一頁面可同時產生多個 Tree 實例。

0.1 檔案結構說明

• metroStyle 資料夾:metro 風格樣式(圖片與 CSS)。

• zTreeStyle 資料夾:標準風格樣式。

• js 資料夾:zTree.all.js 是完整版,單獨載入它就有全部功能。另有依功能切分的 core、excheck、exedit、exhide,分別對應基本、核取、編輯、顯隱功能。

1. 基本使用

1.0 建立第一棵樹

zTree 以 jQuery 為基礎,因此 jQuery 的引用是必須的。

 <!DOCTYPE html>
<HTML>
<HEAD>
<TITLE> ZTREE DEMO </TITLE>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="zTreeStyle/zTreeStyle.css" type="text/css">
<script type="text/javascript" src="jquery-1.4.2.js"></script>
<script type="text/javascript" src="jquery.ztree.core-3.x.js"></script>
<SCRIPT LANGUAGE="JavaScript">
 var zTreeObj;
 var setting = {}; // zTree 參數設定,後面詳解

 var zNodes = [   // zTree 資料,此處使用標準 JSON 格式
   {
     name: "test1", open: true, children: [
       { name: "test1_1" },
       { name: "test1_2" }
     ]
   },
   {
     name: "test2", open: true, children: [
       { name: "test2_1" },
       { name: "test2_2" }
     ]
   }
 ];

 $(document).ready(function () {
   zTreeObj = $.fn.zTree.init($("#treeDemo"), setting, zNodes);
   // 初始化 zTree,三個參數依序為:容器(className 別忘了設為 "ztree")、參數設定、資料來源
 });
 </SCRIPT>
</HEAD>
<BODY>
<div>
  <ul id="treeDemo" class="ztree"></ul>
</div>
</BODY>
</HTML>

運行結果:

1.1 參數設定

設定採用 JSON 格式,依用途分為五大類:view(外觀)、data(資料)、check(核取方塊)、callback(事件回呼)、async(非同步載入)。

 var setting = {
   view: {
     selectedMulti: true,  // 是否可同時選中多個節點
     showIcon: true,       // 是否顯示節點圖示
     showLine: true,       // 是否顯示節點間的連線
     showTitle: true       // 是否顯示節點的 title 提示
   },
   data: {
     simpleData: {
       enable: false,      // 是否啟用簡單資料格式
       idKey: "id",        // 啟用後,id 對應的屬性名稱
       pIdKey: "pId"       // 啟用後,父節點 ID 對應的屬性名稱
     }
   },
   check: {
     enable: true          // 是否顯示核取方塊
   },
   callback: {
     onClick: onClick,             // 節點單擊
     onRightClick: OnRightClick,   // 節點右鍵單擊
     beforeRename: beforeRename,   // 重新命名前的回呼,常用於驗證名稱合法性
     onDblClick: onDblClick,       // 節點雙擊
     onCheck: onCheck              // 核取方塊勾選或取消時
   },
   async: {
     enable: true,                   // 啟用非同步載入
     type: "get",                    // 非同步類型:post 或 get
     contentType: "application/json",// 提交參數的類型
     url: "/Design/Get",             // 資料請求路徑
     autoParam: ["id=id", "name=name"] // = 左側為節點屬性,右側為提交時的參數名
   }
 };

一個重要慣例:zTree 幾乎每個事件都對應一個 beforeXXX 版本,例如 onClick 對應 beforeOnClick。before 事件主要用來決定該動作是否允許執行——回傳 false 就取消後續行為。做權限檢查時非常好用。

1.2 資料格式

每個節點都是一個 treeNode 物件,常用屬性:

 treeNode: {
   name,       // 節點顯示的文字
   checked,    // 是否勾選(啟用核取方塊時有效)
   open,       // 是否展開
   icon,       // 節點圖示
   iconOpen,   // 展開時的圖示
   iconClose,  // 折疊時的圖示
   id,         // 節點標識,對應 simpleData.idKey 指定的屬性名
   pId,        // 父節點 ID,命名規則同 id
   children,   // 直接子節點集合(若要取得所有層級,需自行遞迴)
   isParent,   // 是否為父節點。常用於限制只有葉節點可操作
   getPath()   // 取得節點路徑(含所有父節點與自己),回傳陣列,適合做麵包屑導航
 }

標準資料格式

靠 children 屬性建立層級關係:

 var nodes = [
   { name: "父節點1", children: [
       { name: "子節點1" },
       { name: "子節點2" }
   ]}
 ];

簡單資料格式

靠 id 與 pId 建立層級關係:

 var nodes = [
   { id: 1,  pId: 0, name: "父節點1" },
   { id: 11, pId: 1, name: "子節點1" },
   { id: 12, pId: 1, name: "子節點2" }
 ];

關聯式資料庫撈出來的資料天生就是這個形狀,所以實務上大多用簡單格式。但要注意:zTree 預設不啟用簡單格式,務必在 setting 裡把 simpleData.enable 設為 true。

1.3 常用方法

取得樹物件:

 var treeObj = $.fn.zTree.getZTreeObj("tree");

addNodes(parentNode, index, newNodes, isSilent)——新增節點。parentNode 傳 null 表示加在根層;index 從 0 起算,-1 表示加在最後;isSilent 為 true 時不自動展開父節點。

checkAllNodes(checked)——全選或全不選。

checkNode(node, checked, checkTypeFlag, callbackFlag)——勾選或取消單一節點。checkTypeFlag 為 true 時父子節點狀態會連動;callbackFlag 為 true 時會觸發 beforeOnCheck 與 onCheck。

editName(node)——讓節點進入編輯狀態,需載入 exedit 擴充。

expandAll(expand)——展開或折疊全部節點。

getNodesByParam(key, value, parentNode)——依屬性搜尋節點,parentNode 傳 null 表示全樹搜尋。

getCheckedNodes(checked)——取得所有被勾選(true)或未被勾選(false)的節點。

getChangeCheckedNodes()——取得勾選狀態「已被改變」的節點集合,大資料量時效能遠優於 getCheckedNodes。

2. 常用操作實作

2.0 用 Ajax 載入資料並建立樹

 $(function () {
   var setting = {
     view: { selectedMulti: false },
     data: { simpleData: { enable: true } },
     callback: {
       onClick: onDesignTreeClick,
       onRightClick: OnRightClick,
       beforeRename: beforeRename,
       onCheck: onCheck
     }
   };

   $.ajax({
     type: "Get",
     url: "/Design/GetDesignTreeData",
     success: function (data) {
       $.fn.zTree.init($("#treeZo"), setting, data);
     }
   });
 });

後端可以回傳任何你需要的欄位,前端透過 treeNode.屬性名 就能取用,介面邏輯都靠這些自訂屬性串起來:

 public ActionResult GetDesignTreeData()
 {
   var result = _designAppService.GetDesignTreeData();
   List<ModelTreeViewModel> treeModels = new List<ModelTreeViewModel>();

   foreach (var design in result.Designs)
   {
     bool open = design.ParentId == Guid.Empty;
     treeModels.Add(new ModelTreeViewModel()
     {
       Id = design.Id.ToString(),
       PId = design.ParentId.ToString(),
       Name = design.Name,
       Open = open,
       Data = design.Remarks ?? "",
       ViewPoint = design.ViewPoint ?? "",
       Checked = true
     });
   }

   return Json(treeModels, JsonRequestBehavior.AllowGet);
 }

2.1 節點單擊

回呼會收到事件物件 e、樹的唯一標識 treeId、當前節點 treeNode 三個參數。

 function onClick(e, treeId, treeNode) {
   if (treeNode.isParent) return;   // 不是葉節點就結束
   alert(treeNode.name);            // 依需求取用屬性並執行邏輯
 }

2.2 核取方塊事件

一般做法是 treeObj.getCheckedNodes(true) 取得全部勾選節點再遍歷。但資料量大時這樣很慢——更好的做法是只處理狀態真正變動的節點。

 function onCheck() {
   var treeObj = $.fn.zTree.getZTreeObj("treeDemo");
   var nodes = treeObj.getChangeCheckedNodes();   // 只取狀態改變的節點
   var designIds = [];
   var status = 0;

   if (nodes[0].checked) status = 1;   // 狀態變更節點為勾選,代表這次是「未勾 → 已勾」

   $.each(nodes, function (i, item) {
     designIds.push(item.id);
     // 關鍵:把節點的基準狀態更新為當前狀態,
     // 否則每次比較的都是初始狀態,判斷會出錯
     item.checkedOld = item.checked;
   });

   $.ajax({
     type: "Post",
     url: "/Design/GetRelationComponentIdsByDesigns",
     data: { "designIds": designIds },
     success: function (data) {
       RealBimOcx.BatchAddSubClrInfoBegin();
       $.each(data.result, function (i, item) {
         if (status == 1) RealBimOcx.AddSubClrInfo(item, 255, 255, 0);
         else             RealBimOcx.AddSubClrInfo(item, 0, 255, 0);

         if (i % 100 == 0) {   // 每 100 筆分批送出,避免一次呼叫過大
           RealBimOcx.BatchAddSubClrInfoEnd();
           RealBimOcx.BatchAddSubClrInfoBegin();
         }
       });
       RealBimOcx.BatchAddSubClrInfoEnd();
     }
   });
 }

item.checkedOld = item.checked 這一行是整段的靈魂。少了它,每次比對的基準永遠是初始狀態,第二次之後的判斷就會全部出錯。

2.3 右鍵選單:增刪改

先定義面板:

 <div id="rMenu" style="z-index:100;">
  <ul>
    <li id="m_add" onclick="addTreeNode();">新增節點</li>
    <li id="m_del" onclick="removeTreeNode();">刪除節點</li>
    <li id="m_edit" onclick="editTreeNode();" style="border-bottom:1px solid #cecece">編輯節點</li>
    <li id="m_left">升級</li>
    <li id="m_right">降級</li>
    <li id="m_up">上移</li>
    <li id="m_down" style="border-bottom:1px solid #cecece">下移</li>
    <li id="m_reset" onclick="resetTree();">重置節點</li>
    <li id="m_open" onclick="treeOpen()">展開所有</li>
    <li id="m_stop" onclick="treeStop()">收起所有</li>
  </ul>
</div>

右鍵回呼與面板控制:

 // 右鍵單擊回呼
 function OnRightClick(event, treeId, treeNode) {
   $("#treeZo").hide();

   if (!treeNode && event.target.tagName.toLowerCase() != "button"
       && $(event.target).parents("a").length == 0) {
     zTree.cancelSelectedNode();
     showRMenu("root", event.clientX, event.clientY);   // 空白處,顯示根層操作
   } else if (treeNode && !treeNode.noR) {
     zTree.selectNode(treeNode);
     showRMenu("node", event.clientX, event.clientY);   // 節點上,顯示完整操作
   }

   $("#treeZo").show();
 }

 // 依節點類型決定哪些項目可用
 function showRMenu(type, x, y) {
   $("#rMenu ul").show();
   if (type == "root") {
     $("#m_del").hide();
     $("#m_edit").hide();
     $("#m_left").hide();
     $("#m_right").hide();
     $("#m_up").hide();
     $("#m_down").hide();
     $("#m_add").addClass('mboder');
   } else {
     $("#m_del").show();
     $("#m_edit").show();
     $("#m_left").show();
     $("#m_right").show();
     $("#m_up").show();
     $("#m_down").show();
     $("#m_add").removeClass('mboder');
   }
   rMenu.css({ "top": y + "px", "left": x + "px", "visibility": "visible" });
   $("body").bind("mousedown", onBodyMouseDown);
 }

 function hideRMenu() {
   if (rMenu) rMenu.css({ "visibility": "hidden" });
   $("body").unbind("mousedown", onBodyMouseDown);
 }

 // 點擊頁面其他位置時隱藏面板
 function onBodyMouseDown(event) {
   if (!(event.target.id == "rMenu" || $(event.target).parents("#rMenu").length > 0)) {
     rMenu.css({ "visibility": "hidden" });
   }
 }

新增節點:

 function addTreeNode() {
   hideRMenu();

   var name = new Date().getTime();   // 用時間戳保證名稱唯一
   var newNode = { name: name };

   if (zTree.getSelectedNodes()[0]) {
     newNode.checked = zTree.getSelectedNodes()[0].checked;
     newNode.pid = zTree.getSelectedNodes()[0].id;
     zTree.addNodes(zTree.getSelectedNodes()[0], newNode);
   } else {
     zTree.addNodes(null, newNode);
   }

   var node = zTree.getNodeByParam("name", name, null);
   zTree.selectNode(node);   // 選中新節點
   zTree.editName(node);     // 立刻進入編輯狀態
 }

編輯節點:

 function editTreeNode() {
   var nodes = zTree.getSelectedNodes();
   if (nodes && nodes.length > 0) {
     var parent = nodes[0].getParentNode();
     if (parent) nodes[0].pid = parent.id;
     zTree.editName(nodes[0]);
   }
   hideRMenu();
 }

離開編輯狀態時驗證並存回後端:

 function beforeRename(treeId, treeNode, newName, isCancel) {
   if (newName.length == 0) {
     alert("名稱不能為空。");
     return false;   // 回傳 false 會取消這次改名
   }

   $.ajax({
     type: "Post",
     url: "/Design/InsertOrUpdate",
     data: {
       "dto": { "Id": treeNode.id, "ParentId": treeNode.pid, "Name": newName }
     },
     success: function (data) {
       if (data.result == "Faild") {
         alert("儲存失敗。");
         return false;
       } else {
         treeNode.id = data.result;   // 把新 ID 寫回節點
         return true;
       }
     }
   });
 }

刪除節點:

 function removeTreeNode() {
   hideRMenu();
   var nodes = zTree.getSelectedNodes();

   if (nodes && nodes.length > 0) {
     if (nodes[0].children && nodes[0].children.length > 0) {
       alert("包含下級,無法刪除。");
     } else {
       if (confirm("該操作會將關聯資料同步刪除,是否確認刪除?")) {
         $.ajax({
           type: "Post",
           url: "/Design/Delete",
           data: { "id": nodes[0].id },
           success: function (data) {
             if (data.result == "Success") zTree.removeNode(nodes[0]);
             else alert("刪除失敗。");
           }
         });
       }
     }
   }
 }

2.4 效能經驗:大量勾選別用 JS 硬做

樹狀控制項最常用來做授權或關聯設定。典型流程是「先全部取消勾選,再依關聯資料把該勾的勾上」。資料量小時沒問題,但節點來到幾萬筆時,這串操作在瀏覽器裡會非常慢。

比較好的做法是把邏輯搬到後端:重新組織資料來源,直接在每筆資料上帶入 checked 屬性,然後重新載入整棵樹。

 $.ajax({
   type: "Get",
   url: "/Model/GetRelationModelTreeData?designId=" + treeNode.id + "&t=" + new Date(),
   success: function (data) {
     // 不要用 JS 迴圈逐個勾選,速度很慢:
     // $.each(data.result, function (i, item) {
     //   var node = modelTree.getNodeByParam("id", item, null);
     //   modelTree.checkNode(node, true, true);
     // });

     // 改為重新載入,速度差異明顯
     $.fn.zTree.init($("#treejian"), setting1, data.result);
   }
 });

URL 後面那個 &t= 時間戳是用來避免快取的,這招在 IE 上尤其必要。

幾個實作上的提醒

• 容器的 className 一定要設為 "ztree",否則樣式會跑掉。

• 用簡單資料格式前先開 simpleData.enable,這是最常見的「節點全疊在一起」的原因。

• 右鍵選單記得解除綁定。在 body 上 bind mousedown 之後,若面板關閉時沒有 unbind,會一層層累積。

• beforeRename 裡發 Ajax 要留意回呼時序。zTree 的 before 事件是同步判斷的,非同步請求回來時改名動作可能已經結束。若需要嚴格把關,考慮改為同步處理,或在伺服器端再驗一次。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved