在表單中選擇層級數據(如地區、部門、分類)時,彈窗樹形選擇器是經典交互模式。本文詳細講解如何整合 jQuery UI Dialog(彈窗容器)與 zTree(樹形控件),構建一個支持異步加載、單/多選、回調回填、鍵盤無障礙的完整選擇器組件。
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>彈窗樹形選擇器示例</title>
<!-- CSS -->
<link rel="stylesheet" href="jquery-ui.min.css">
<link rel="stylesheet" href="zTreeStyle/zTreeStyle.css">
<style>
.tree-dialog-trigger { padding: 8px 16px; cursor: pointer; }
#treeContainer { min-width: 300px; max-height: 400px; overflow: auto; }
.ztree li span.button { margin-right: 2px; }
</style>
</head>
<body>
<div class="form-group">
<label>所屬部門:</label>
<input type="text" id="deptInput" class="tree-dialog-trigger" readonly placeholder="點擊選擇部門" />
<input type="hidden" id="deptId" name="deptId" />
</div>
<!-- 隱藏的樹容器,Dialog 會將其移動到彈窗中 -->
<div id="treeContainer" class="ztree" style="display:none;"></div>
<!-- JS -->
<script src="jquery.min.js"></script>
<script src="jquery-ui.min.js"></script>
<script src="jquery.ztree.all.min.js"></script>
<script src="tree-selector.js"></script> <!-- 組件封裝文件 -->
<script>
$('#deptInput').treeSelector({
url: '/api/dept/tree', // 異步加載數據接口
multiple: false, // 單選
onSelect: function(nodes) { // 選中回調
$('#deptInput').val(nodes.map(n => n.name).join(' / '));
$('#deptId').val(nodes.map(n => n.id).join(','));
}
});
</script>
</body>
</html>
;(function($) {
'use strict';
$.fn.treeSelector = function(options) {
return this.each(function() {
const $trigger = $(this);
const opts = $.extend({
url: '',
multiple: false,
chkStyle: 'checkbox', // 'radio' | 'checkbox'
onSelect: $.noop,
dialogOptions: {
title: '請選擇',
width: 400,
height: 500,
modal: true,
resizable: false,
closeOnEscape: true,
draggable: true
},
zTreeSetting: {
view: { dblClickExpand: false, showLine: true, selectedMulti: false },
data: { simpleData: { enable: true, idKey: 'id', pIdKey: 'pId', rootPId: 0 } },
callback: { onClick: onTreeClick, onCheck: onTreeCheck }
}
}, options);
let zTreeInstance = null;
let $dialog = null;
let $treeContainer = null;
// 初始化 Dialog 與 zTree
function initDialog() {
if ($dialog) return;
// 找到或創建樹容器
$treeContainer = $('#treeContainer').length ? $('#treeContainer') : $('').appendTo('body');
// 創建 Dialog
$dialog = $treeContainer.dialog($.extend({}, opts.dialogOptions, {
autoOpen: false,
open: function() {
loadTreeData();
// 聚焦第一個可聚焦元素 (無障礙)
$(this).find('.ztree a:first, button:first').focus();
},
close: function() {
// 可選:關閉時銷毀樹以釋放內存,或保留供下次打開
// zTreeInstance?.destroy();
}
}));
}
// 異步加載樹數據
function loadTreeData() {
if (zTreeInstance) return; // 已加載不重複
$.ajax({
url: opts.url,
type: 'GET',
dataType: 'json',
beforeSend: () => $treeContainer.addClass('loading'),
success: function(data) {
// 後端返回格式: [{ id, pId, name, open: true, ... }, ...]
zTreeInstance = $.fn.zTree.init($treeContainer, opts.zTreeSetting, data);
// 默認展開第一級
const nodes = zTreeInstance.getNodes();
if (nodes.length) zTreeInstance.expandNode(nodes[0], true);
},
error: function() {
$treeContainer.html('數據加載失敗,請重試');
},
complete: () => $treeContainer.removeClass('loading')
});
}
// 點擊節點 (單選模式)
function onTreeClick(event, treeId, treeNode) {
if (!opts.multiple) {
selectNodes([treeNode]);
}
}
// 勾選節點 (多選模式)
function onTreeCheck(event, treeId, treeNode) {
if (opts.multiple) {
const nodes = zTreeInstance.getCheckedNodes(true);
selectNodes(nodes);
}
}
// 統一選中處理
function selectNodes(nodes) {
if (!nodes.length) return;
opts.onSelect.call($trigger[0], nodes);
closeDialog();
}
function openDialog() {
initDialog();
$dialog.dialog('open');
}
function closeDialog() {
$dialog?.dialog('close');
}
// 綁定觸發事件
$trigger.on('click focus', openDialog).prop('readonly', true);
// 暴露實例方法
$trigger.data('treeSelector', {
open: openDialog,
close: closeDialog,
destroy: () => {
$trigger.off('click focus', openDialog);
$dialog?.dialog('destroy');
zTreeInstance?.destroy();
$treeContainer?.remove();
}
});
});
};
})(jQuery);
// Spring MVC 示例
@RestController
@RequestMapping("/api/dept")
public class DeptController {
@GetMapping("/tree")
public List tree() {
return deptService.getTreeNodes(); // 返回 List
}
}
// 節點對象 (需符合 zTree simpleData 格式)
class DeptNode {
private Long id;
private Long pId; // 父節點 ID,頂級為 0
private String name;
private Boolean open; // 是否默認展開
private Boolean isParent; // 是否父節點 (異步加載時需標識)
// getter/setter
}
<!-- web.xml 或 Spring 配置 -->
<mvc:annotation-driven>
<mvc:message-converters>
<bean class="org.springframework.http.converter.json.MappingJackson2HttpMessageConverter"> <!-- Jackson 2.x -->
<property name="supportedMediaTypes">
<list><value>application/json;charset=UTF-8</value></list>
</property>
</bean>
</mvc:message-converters>
</mvc:annotation-driven>
<!-- 依賴 -->
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.15.x</version>
</dependency>
// 在 Dialog 頂部添加搜索框
$dialog.dialog('widget').find('.ui-dialog-titlebar').after(
''
);
$('.tree-search input').on('input', debounce(function() {
const keyword = $(this).val().toLowerCase();
zTreeInstance.getNodes().forEach(node => {
const match = node.name.toLowerCase().includes(keyword);
zTreeInstance.showNode(node); // 簡易版:需遞歸顯示/隱藏父子節點
});
}, 200));
zTreeSetting: {
async: {
enable: true,
url: '/api/dept/children',
autoParam: ['id=parentId'],
dataFilter: function(treeId, parentNode, responseData) {
return responseData; // 格式化返回數據
}
},
callback: { onAsyncSuccess: (event, treeId, treeNode, msg) => { /* 可選 */ } }
}
// 初始化時傳入已選 ID
opts: { selectedIds: '101,102' }
// open 時勾選
open: function() {
if (opts.selectedIds) {
const ids = opts.selectedIds.split(',');
ids.forEach(id => {
const node = zTreeInstance.getNodeByParam('id', id);
if (node) zTreeInstance.checkNode(node, true, true); // check, checkType, addFlag
});
}
loadTreeData(); // 確保樹已初始化
}
| 問題 | 原因 | 解決 |
|---|---|---|
| 彈窗打開但樹空白 | zTree 容器隱藏時初始化導致尺寸計算為 0 | 在 `dialog.open` 回調中初始化樹,或調用 `zTreeInstance.reAsyncChildNodes()` 重繪 |
| 複選框不顯示 | CSS 衝突或 `chkStyle` 配置錯誤 | 檢查 `zTreeSetting.check.enable=true, chkStyle='checkbox'` 且引入 zTree CSS |
| 雙擊無反應 | `dblClickExpand` 衝突 | 設置 `view.dblClickExpand: false`,改用單擊/勾選選中 |
| 彈窗關閉後無法再次打開 | Dialog `destroy` 了但 zTree 實例未銷毀,或容器被移動 | 統一在 `destroy` 中銷毀 zTree,或 `close` 時不銷毀僅隱藏 |
| 中文亂碼 | 後端編碼/響應頭未設置 UTF-8 | Spring MVC 配置 `MappingJackson2HttpMessageConverter` 支持 UTF-8 |
jQuery UI Dialog 提供強大的彈窗容器能力(模態、拖拽、定位、動畫),zTree 提供專業的樹形數據展示與交互。兩者結合的關鍵在於:**生命週期同步**(Dialog open → zTree init/load)、**事件橋接**(zTree 選中 → Dialog close → 回調回填)、**資源釋放**(銷毀順序)。封裝為 `$.fn.treeSelector` 插件後,業務頁面僅需一行調用,實現關注點分離與代碼復用。現代項目優先選用成熟 UI 庫內置組件,僅在存量 jQuery 項目或極度定制場景下採用此方案。