樹狀結構在授權、分類、組織架構這類應用裡幾乎是標配。zTree 是一個依附 jQuery 的多功能樹狀外掛,效能優異、設定彈性、功能組合豐富,是它最大的賣點。
主要特色:
• 新版把核心程式碼依功能切分,用不到的不必載入。只用基本功能載入 jquery.ztree.core-3.5.js 即可;需要核取方塊載入 excheck;需要編輯功能載入 exedit。
• 採用延遲載入,上萬個節點也能輕鬆處理,即使在 IE6 下也不至於卡死。
• 相容 IE、Firefox、Chrome、Opera、Safari。
• 支援 JSON 資料格式、靜態與 Ajax 非同步載入節點。
• 可任意更換樣式與自訂圖示(靠 CSS)。
• 核取方塊與單選按鈕的選擇功能極為靈活。
• 提供多種事件回呼。
• 具備完整的增刪改查與拖拉功能,支援多節點拖曳。
• 同一頁面可同時產生多個 Tree 實例。

• metroStyle 資料夾:metro 風格樣式(圖片與 CSS)。
• zTreeStyle 資料夾:標準風格樣式。
• js 資料夾:zTree.all.js 是完整版,單獨載入它就有全部功能。另有依功能切分的 core、excheck、exedit、exhide,分別對應基本、核取、編輯、顯隱功能。
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>
運行結果:

設定採用 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 就取消後續行為。做權限檢查時非常好用。
每個節點都是一個 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。
取得樹物件:
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。
$(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);
}
回呼會收到事件物件 e、樹的唯一標識 treeId、當前節點 treeNode 三個參數。
function onClick(e, treeId, treeNode) {
if (treeNode.isParent) return; // 不是葉節點就結束
alert(treeNode.name); // 依需求取用屬性並執行邏輯
}
一般做法是 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 這一行是整段的靈魂。少了它,每次比對的基準永遠是初始狀態,第二次之後的判斷就會全部出錯。
先定義面板:
<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("刪除失敗。");
}
});
}
}
}
}
樹狀控制項最常用來做授權或關聯設定。典型流程是「先全部取消勾選,再依關聯資料把該勾的勾上」。資料量小時沒問題,但節點來到幾萬筆時,這串操作在瀏覽器裡會非常慢。
比較好的做法是把邏輯搬到後端:重新組織資料來源,直接在每筆資料上帶入 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 事件是同步判斷的,非同步請求回來時改名動作可能已經結束。若需要嚴格把關,考慮改為同步處理,或在伺服器端再驗一次。