萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

jQuery UI Dialog 與 zTree 結合實現彈窗樹形選擇器完整教程

在表單中選擇層級數據(如地區、部門、分類)時,彈窗樹形選擇器是經典交互模式。本文詳細講解如何整合 jQuery UI Dialog(彈窗容器)與 zTree(樹形控件),構建一個支持異步加載、單/多選、回調回填、鍵盤無障礙的完整選擇器組件。

技術棧與依賴

  • jQuery 1.12+ / 3.x
  • jQuery UI 1.12+ (需包含 Dialog, Draggable, Resizable, Position 模塊)
  • zTree v3.x (核心 js + css)
  • 圖標字體或 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>

組件封裝:tree-selector.js (核心邏輯)


;(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
}

Spring MVC 配置要點 (解決 @ResponseBody JSON 輸出)


<!-- 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>

進階功能擴展

1. 搜索/過濾節點


// 在 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));

2. 異步加載子節點 (大數據量)


zTreeSetting: {
  async: {
    enable: true,
    url: '/api/dept/children',
    autoParam: ['id=parentId'],
    dataFilter: function(treeId, parentNode, responseData) {
      return responseData; // 格式化返回數據
    }
  },
  callback: { onAsyncSuccess: (event, treeId, treeNode, msg) => { /* 可選 */ } }
}

3. 回填已選值 (編輯頁面)


// 初始化時傳入已選 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-8Spring MVC 配置 `MappingJackson2HttpMessageConverter` 支持 UTF-8

現代化替代方案

  • Element Plus / Ant Design Vue / Naive UI:內置 ``、``,開箱即用、TypeScript 支持、無障礙完善。
  • 無依賴輕量選擇器:vanilla-select + 自定義樹渲染。
  • Headless UI + 自定義樣式:完全可控的無樣式組件庫。

總結

jQuery UI Dialog 提供強大的彈窗容器能力(模態、拖拽、定位、動畫),zTree 提供專業的樹形數據展示與交互。兩者結合的關鍵在於:**生命週期同步**(Dialog open → zTree init/load)、**事件橋接**(zTree 選中 → Dialog close → 回調回填)、**資源釋放**(銷毀順序)。封裝為 `$.fn.treeSelector` 插件後,業務頁面僅需一行調用,實現關注點分離與代碼復用。現代項目優先選用成熟 UI 庫內置組件,僅在存量 jQuery 項目或極度定制場景下採用此方案。

copyright © 萬盛學電腦網 all rights reserved