萬盛學電腦網

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

jQuery 拖拽插件 JQ.MoveBox.js 開發實戰教程

插件功能

  • 任意元素可拖拽移動
  • 可選限制在父容器內 (`out: false`) 或允許拖出 (`out: true`)
  • 自動處理邊界檢測 (含 border 寬度計算)
  • 拖拽時提升 z-index 置頂
  • 支持多實例同時拖拽

插件完整代碼 (JQ.MoveBox.js)

(function($) {
  var zIndexCounter = 1; // 全局層級計數器
  var dragState = {};    // 存儲拖拽狀態
  
  $.fn.MoveBox = function(options) {
    var opts = $.extend({}, $.fn.MoveBox.defaults, options);
    
    return this.each(function() {
      var $this = $(this);
      
      // 確保元素可定位
      if ($this.css('position') === 'static') {
        $this.css('position', 'absolute');
      }
      
      $this.on('mousedown', function(e) {
        // 僅左鍵觸發
        if (e.which !== 1) return;
        
        e.preventDefault(); // 防止文本選擇
        
        var $parent = $this.parent();
        var parentOffset = $parent.offset();
        var parentBorderLeft = parseInt($parent.css('border-left-width')) || 0;
        var parentBorderTop = parseInt($parent.css('border-top-width')) || 0;
        
        // 記錄初始狀態
        dragState = {
          startX: e.pageX,
          startY: e.pageY,
          startLeft: $this.position().left,
          startTop: $this.position().top,
          $this: $this,
          $parent: $parent,
          parentOffset: parentOffset,
          parentBorderLeft: parentBorderLeft,
          parentBorderTop: parentBorderTop,
          opts: opts
        };
        
        // 提升層級
        zIndexCounter++;
        $this.css('z-index', zIndexCounter);
        
        // 綁定文檔級事件
        $(document).on('mousemove.moveBox', onMouseMove)
                   .on('mouseup.moveBox', onMouseUp);
      });
    });
    
    function onMouseMove(e) {
      var state = dragState;
      if (!state.$this) return;
      
      var dx = e.pageX - state.startX;
      var dy = e.pageY - state.startY;
      
      var newLeft = state.startLeft + dx;
      var newTop = state.startTop + dy;
      
      // 邊界限制
      if (state.opts.out) {
        // 允許拖出父容器,但限制在文檔可視區內
        var maxLeft = $(document).width() - state.$this.outerWidth() - state.parentBorderLeft;
        var maxTop = $(window).height() + $(document).scrollTop() - state.$this.outerHeight() - state.parentBorderTop;
        var minLeft = -state.parentOffset.left - state.parentBorderLeft;
        var minTop = -state.parentOffset.top - state.parentBorderTop + $(document).scrollTop();
        
        newLeft = Math.max(minLeft, Math.min(maxLeft, newLeft));
        newTop = Math.max(minTop, Math.min(maxTop, newTop));
      } else {
        // 限制在父容器內
        var maxLeft = state.$parent.width() - state.$this.outerWidth() - state.parentBorderLeft - parseInt(state.$this.css('border-right-width')) || 0;
        var maxTop = state.$parent.height() - state.$this.outerHeight() - state.parentBorderTop - parseInt(state.$this.css('border-bottom-width')) || 0;
        
        newLeft = Math.max(0, Math.min(maxLeft, newLeft));
        newTop = Math.max(0, Math.min(maxTop, newTop));
      }
      
      state.$this.css({ left: newLeft, top: newTop });
    }
    
    function onMouseUp() {
      $(document).off('.moveBox'); // 移除命名空間事件
      dragState = {};
    }
  };
  
  $.fn.MoveBox.defaults = {
    out: false // 默認限制在父容器內
  };
  
})(jQuery);

使用示例

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>JQ.MoveBox Demo</title>
  <style>
    #container { width: 600px; height: 400px; margin: 50px auto; border: 2px solid #333; position: relative; background: #f9f9f9; }
    .box { width: 120px; height: 120px; position: absolute; cursor: move; font: 14px/120px 'Microsoft YaHei'; text-align: center; color: #fff; user-select: none; }
    .box1 { background: #3498db; left: 20px; top: 20px; border-right: 5px solid #2980b9; }
    .box2 { background: #e74c3c; left: 200px; top: 100px; border-bottom: 5px solid #c0392b; }
    .box3 { background: #2ecc71; left: 400px; top: 200px; }
  </style>
</head>
<body>
  <div id="container">
    <div class="box box1">限制在容器內</div>
    <div class="box box2">允許拖出</div>
    <div class="box box3">限制在容器內</div>
  </div>

  <script src="https://cdn.jsdelivr.net/npm/jquery@3.6.0/dist/jquery.min.js"></script>
  <script src="JQ.MoveBox.js"></script>
  <script>
    $(function() {
      $('.box1, .box3').MoveBox(); // 默認 out: false
      $('.box2').MoveBox({ out: true }); // 允許拖出
    });
  </script>
</body>
</html>

插件開發核心知識點

  1. 閉包封裝:`(function($){ ... })(jQuery)` 避免全局污染,支持 `jQuery.noConflict()`。
  2. 鏈式調用支持**:`return this.each(...)` 保持 jQuery 鏈式風格。
  3. 默認配置合併**:`$.extend({}, defaults, options)` 實現選項覆蓋。
  4. 事件命名空間**:`mousemove.moveBox` / `mouseup.moveBox` 方便精準解綁,不影響其他監聽器。
  5. 文檔級事件綁定**:`mousedown` 在元素上,`mousemove/mouseup` 在 `document` 上,解決鼠標移出元素事件丟失問題。
  6. 邊界計算細節**:使用 `outerWidth/outerHeight` 含 border,`position()` 相對父元素定位,`offset()` 相對文檔,`parseInt(css('border-x-width'))` 精確計算邊框佔用空間。
  7. z-index 管理**:全局計數器遞增,確保當前拖拽元素始終置頂。

進階擴展方向

  • 觸屏支持**:添加 `touchstart/touchmove/touchend` 事件處理。
  • 吸附對齊**:靠近邊緣/其他元素時自動吸附。
  • 拖拽手柄**:`handle` 選項指定觸發拖拽的子元素 (如標題欄)。
  • 網格對齊**:`grid: [20, 20]` 步長移動。
  • 回調函數**:`onDragStart`、`onDrag`、`onDragEnd` 暴露生命周期。
  • 碰撞檢測**:防止重疊或實現磁性吸附。

結語

編寫 jQuery 插件是理解「組件化思維」的絕佳練習。`JQ.MoveBox` 雖小,但包含了配置合併、事件命名空間、狀態管理、邊界計算、鏈式調用、多實例隔離等插件開發所有核心要素。掌握這些模式,即可開發出專業級的 jQuery UI 組件。

copyright © 萬盛學電腦網 all rights reserved