萬盛學電腦網

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

LigerUI 彈出編輯對話框完整實作指南

LigerUI 彈出編輯框架構概覽

LigerUI 彈出編輯框採用「隱藏 DIV 容器 + ligerDialog.open() + ligerForm 動態建構」模式。核心流程:工具列按鈕觸發 → 判斷新增/編輯/檢視 → 動態建構表單 → 彈窗顯示 → 資料繫結 → 存檔驗證 → 關閉刷新。

一、必要資源引入

<!-- CSS -->
<link href="../lib/ligerUI/skins/Aqua/css/ligerui-all.css" rel="stylesheet" />
<link href="../lib/css/common.css" rel="stylesheet" />

<!-- JS 核心 -->
<script src="../lib/jquery/jquery-1.5.2.min.js"></script>
<script src="../lib/ligerUI/js/ligerui.min.js"></script>
<script src="../lib/ligerUI/js/plugins/ligerForm.js"></script>
<script src="../lib/ligerUI/js/plugins/ligerGrid.js"></script>
<script src="../lib/ligerUI/js/plugins/ligerDateEditor.js"></script>

<!-- 專案通用 -->
<script src="../lib/js/common.js"></script>
<script src="../lib/js/LG.js"></script>          <!-- LG.showSuccess 等封裝 -->
<script src="../lib/js/ligerui.expand.js"></script> <!-- 擴充元件 -->

<!-- 驗證 -->
<script src="../lib/jquery-validation/jquery.validate.min.js"></script>
<script src="../lib/jquery-validation/jquery.metadata.js"></script>
<script src="../lib/jquery-validation/messages_cn.js"></script>

二、HTML 容器定義

<!-- 彈窗容器:初始隱藏,內含表單 -->
<div id="Editdetail" style="display:none;">
  <form id="EditForm" method="post"></form>
</div>

<!-- 工具列 (通常在 Grid 上方) -->
<div id="toolbar"></div>

三、工具列事件與彈窗啟動邏輯

var detailWin = null;        // ligerDialog 實例快取
var currentData = null;      // 當前編輯資料
var currentIsAddNew = false; // 是否新增模式
var currentIsView = false;   // 是否檢視模式

// 工具列按鈕點擊事件
function toolbarBtnItemClick(item) {
  var grid = $("#grid").ligerGetGridManager();
  
  switch (item.id) {
    case "add":
      // 新增:傳入空物件,isAddNew=true, 隱藏唯讀欄位
      addbill({}, true, '新增記錄', false);
      break;
      
    case "view":
      // 檢視:需選取行,isAddNew=false, 唯讀模式
      var selected = grid.getSelected();
      if (!selected) { LG.tip('請選擇一行記錄!'); return; }
      addbill(selected, false, '檢視記錄', true);
      break;
      
    case "modify":
      // 編輯:需選取行,isAddNew=false, 可編輯
      var selected = grid.getSelected();
      if (!selected) { LG.tip('請選擇一行記錄!'); return; }
      addbill(selected, false, '修改記錄', false);
      break;
      
    case "delete":
      // 刪除:二次確認
      var selected = grid.getSelected();
      if (!selected) { LG.tip('請選擇一行記錄!'); return; }
      $.ligerDialog.confirm('確定刪除選中記錄?', function(yes) {
        if (yes) f_delete(selected);
      });
      break;
  }
}

四、核心 addbill 函式:彈窗建構與表單動態生成

function addbill(data, isAddNew, title, isView) {
  currentData = data;
  currentIsAddNew = isAddNew;
  currentIsView = isView;
  
  // 1. 若彈窗已存在,直接更新標題並顯示
  if (detailWin) {
    detailWin.set('title', title);
    detailWin.show();
    bindFormData(data, isView); // 重新繫結資料
    return;
  }
  
  // 2. 首次建構:定義表單欄位配置
  var formFields = [
    // 隱藏欄位:主鍵 ID
    { name: "Id", type: "hidden" },
    
    // 產品選擇 (下拉框 + 隱藏 ID)
    { display: "產品", name: "ProductName", comboboxName: "ProductId", 
      newline: true, labelWidth: 100, width: 250, type: "select", 
      options: { url: "/api/products", valueField: "Id", textField: "Name" } },
    { name: "ProductId", type: "hidden" },
    
    // 規格選擇
    { display: "規格", name: "FormatName", comboboxName: "FormatId",
      newline: true, labelWidth: 100, width: 250, type: "select",
      options: { url: "/api/formats", valueField: "Id", textField: "Name" } },
    { name: "FormatId", type: "hidden" },
    
    // 等級選擇
    { display: "等級", name: "DegreeName", comboboxName: "DegreeId",
      newline: true, labelWidth: 100, width: 250, type: "select",
      options: { url: "/api/degrees", valueField: "Id", textField: "Name" } },
    { name: "DegreeId", type: "hidden" },
    
    // 附件掃描件 (觸發上傳彈窗)
    { display: "掃描件", name: "AppendBill", comboboxName: "AppendBillPath2",
      newline: true, labelWidth: 100, width: 250, type: "select", options: {} },
    { name: "AppendBillPath1", type: "hidden" }, // 實際路徑
    
    // 箱號
    { display: "箱號", name: "BoxNum", newline: true, labelWidth: 100, 
      width: 250, type: "text", validate: { required: true, maxlength: 50 } },
    
    // 製造日期
    { display: "製造日期", name: "MadeDate", newline: true, labelWidth: 100,
      width: 250, type: "date", format: "yyyy-MM-dd" },
    
    // 備註
    { display: "備註", name: "Remark", newline: true, labelWidth: 100,
      width: 520, type: "textarea", height: 80 }
  ];
  
  // 3. 動態建構 ligerForm
  $("#EditForm").ligerForm({
    fields: formFields,
    labelWidth: 100,
    space: 20,
    rightToken: ':',
    inputWidth: 180,
    validate: true
  });
  
  // 4. 綁定特定欄位事件 (如掃描件觸發上傳)
  var appendCombo = $("#AppendBillPath2").ligerGetComboBoxManager();
  if (appendCombo) {
    appendCombo.set('onBeforeOpen', f_selectAppendBillPath_1);
  }
  
  // 5. 建立 ligerDialog
  detailWin = $.ligerDialog.open({
    target: $("#Editdetail"),
    title: title,
    width: 650,
    height: 480,
    top: 50,
    isResize: true,
    isHidden: false,
    showMax: true,
    showToggle: true,
    showMin: true,
    buttons: [
      { 
        text: isView ? '關閉' : '儲存', 
        cls: isView ? '' : 'btn-primary',
        onclick: function(item, dialog) {
          if (isView) {
            dialog.hide();
          } else {
            saveFormData(dialog);
          }
        }
      },
      { 
        text: '取消', 
        onclick: function(item, dialog) { dialog.hide(); } 
      }
    ]
  });
  
  // 6. 繫結資料
  bindFormData(data, isView);
}

// 資料繫結
function bindFormData(data, isView) {
  var form = $("#EditForm").ligerGetFormManager();
  if (!form) return;
  
  form.setData(data);
  
  // 檢視模式:禁用所有輸入
  if (isView) {
    form.setDisabled(true);
  } else {
    form.setDisabled(false);
    // 新增模式:清空 ID、設定預設值
    if (currentIsAddNew) {
      form.setData({ Id: 0, MadeDate: new Date() });
    }
  }
}

五、表單儲存與驗證

function saveFormData(dialog) {
  var form = $("#EditForm").ligerGetFormManager();
  if (!form) return;
  
  // 1. 前端驗證
  if (!form.valid()) {
    LG.tip('請檢查必填欄位!');
    return;
  }
  
  // 2. 取得表單資料
  var data = form.getData();
  data.Id = currentData.Id || 0;
  
  // 3. 發送 AJAX 請求
  var url = currentIsAddNew ? "/api/items" : "/api/items/" + data.Id;
  var method = currentIsAddNew ? "POST" : "PUT";
  
  LG.showLoading('儲存中...');
  
  $.ajax({
    url: url,
    type: method,
    dataType: "json",
    contentType: "application/json",
    data: JSON.stringify(data),
    success: function(result) {
      LG.hideLoading();
      if (result.success) {
        LG.showSuccess(currentIsAddNew ? "新增成功!" : "修改成功!");
        dialog.hide();
        refreshGrid(); // 重新載入 Grid
      } else {
        LG.showError("儲存失敗:" + (result.message || "未知錯誤"));
      }
    },
    error: function(xhr) {
      LG.hideLoading();
      LG.showError("請求異常:" + xhr.statusText);
    }
  });
}

function refreshGrid() {
  var grid = $("#grid").ligerGetGridManager();
  if (grid) grid.reload();
}

六、刪除功能實作

function f_delete(selected) {
  var ids = Array.isArray(selected) ? selected.map(r => r.Id) : [selected.Id];
  
  LG.showLoading('刪除中...');
  
  $.ajax({
    url: "/api/items/batch",
    type: "DELETE",
    dataType: "json",
    contentType: "application/json",
    data: JSON.stringify({ ids: ids }),
    success: function(result) {
      LG.hideLoading();
      if (result.success) {
        LG.showSuccess("刪除成功,共 " + ids.length + " 筆");
        refreshGrid();
      } else {
        LG.showError("刪除失敗:" + result.message);
      }
    },
    error: function() {
      LG.hideLoading();
      LG.showError("網路錯誤,請稍後再試");
    }
  });
}

七、常見問題與優化

問題 1:下拉框資料未載入就開啟彈窗

// 解決:在 addbill 中預先載入下拉資料,或使用 onBeforeOpen 延遲載入
var productCombo = $("#ProductId").ligerGetComboBoxManager();
productCombo.set('url', '/api/products'); // 設定資料源
productCombo.reload(); // 手動觸發載入

問題 2:日期元件格式錯誤

{ 
  display: "日期", name: "DateField", type: "date",
  options: { 
    format: "yyyy-MM-dd",      // 顯示格式
    initValue: new Date(),     // 預設今天
    showTime: false,           // 不顯示時間
    labelWidth: 100,
    width: 180
  }
}

問題 3:彈窗重複開啟、記憶體洩漏

// 正確模式:全域快取 detailWin,關閉時 hide() 而非 destroy()
// 需要真正銷毀時:
function closeDialog() {
  if (detailWin) {
    detailWin.destroy(); // 徹底銷毀 DOM 與事件
    detailWin = null;
    $("#EditForm").empty(); // 清空表單內容
  }
}

效能優化:表單欄位懶加載

// 僅在首次開啟時建構表單,後續復用
var formInitialized = false;

function addbill(data, isAddNew, title, isView) {
  if (!formInitialized) {
    buildFormFields(); // 建構欄位
    formInitialized = true;
  }
  // ... 後續邏輯
}

八、現代化遷移建議

LigerUI 已停止維護 (最後更新 2016 年)。新專案建議遷移至:

  • Element Plus / Ant Design Vue / Arco Design (Vue 3 生態)
  • Ant Design / MUI / Chakra UI (React 生態)
  • 原生 + 輕量表單庫 (無框架依賴)

遷移關鍵點:

  1. 將 `ligerForm` 欄位定義轉換為目標框架的 Schema 格式 (JSON Schema / Formily / VeeValidate)
  2. 將 `ligerDialog.open()` 替換為目標框架的 Modal/Drawer 元件
  3. Grid 編輯模式改為行內編輯或抽屉編輯
  4. 驗證邏輯遷移至統一驗證庫 (Yup, Zod, VeeValidate)

總結

LigerUI 彈出編輯框核心在於:ligerForm 動態建構表單、ligerDialog.open() 管理彈窗生命週期、setData()/getData() 資料雙向繫結、工具列事件分發新增/編輯/檢視/刪除四大模式。掌握此模式可快速維護既有專案,新專務請採用現代框架。

copyright © 萬盛學電腦網 all rights reserved