萬盛學電腦網

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

jQuery 拖拽佈局插件 Gridster.js 使用指南:打造類 Win8 磁貼儀表板

插件特色

  • **網格化拖拽**:元素吸附到虛擬網格,對齊整齊。
  • **多尺寸支援**:元素可佔據 1×1、2×1、1×2 等多格。
  • **動態增減**:運行時添加/移除元件,網格自動重排。
  • **響應式**:容器寬度變化自動調整列數。
  • **序列化儲存**:`serialize()` 輸出佈局 JSON,便於持久化。

官網 Demo:https://gridster.net/ (藍色區域白塊可隨意拖拽)

快速上手

1. 引入資源

<script src="jquery-1.7.2.min.js"></script>
<script src="jquery.gridster.js"></script>
<link rel="stylesheet" href="style.css" /> <!-- 包含 gridster 基礎樣式 -->

2. HTML 結構

<div class="gridster">
    <ul id="dashboard">
        <li data-row="1" data-col="1" data-sizex="1" data-sizey="1"><div class="handle">1</div></li>
        <li data-row="2" data-col="1" data-sizex="1" data-sizey="1"><div class="handle">2</div></li>
        <li data-row="3" data-col="1" data-sizex="1" data-sizey="1"><div class="handle">3</div></li>
        <li data-row="1" data-col="2" data-sizex="2" data-sizey="1"><div class="handle">4 (寬2格)</div></li>
        <li data-row="2" data-col="2" data-sizex="2" data-sizey="2"><div class="handle">5 (2x2)</div><p>內容...</p></li>
        <li data-row="1" data-col="4" data-sizex="1" data-sizey="1"><div class="handle">6</div></li>
    </ul>
</div>

屬性說明:`data-row/col` 起始位置 (1-based);`data-sizex/sizey` 佔用格數。

3. 關鍵 CSS (必須)

.gridster { position: relative; background: #ccc; min-height: 400px; }
.gridster > ul { list-style: none; margin: 0; padding: 0; }
.gridster li {
    background: #fff; border: 2px solid #333;
    box-sizing: border-box; /* 關鍵:含邊框在寬高內 */
    /* 內容樣式自定 */
}
.handle { height: 30px; background: #eee; border-bottom: 1px solid #ccc; cursor: move; padding: 5px; font-weight: bold; }
/* Gridster 內部類別 (勿修改核心邏輯類別) */
.gs_w { position: absolute; }           /* 元件包裹器 */
.preview-holder { opacity: 0.3; background: #fff; border: 2px dashed #999; } /* 拖拽預覽位置 */
.player-revert { z-index: 10!important; transition: left .3s, top .3s!important; } /* 歸位動畫 */
.dragging { z-index: 10!important; transition: none!important; } /* 拖拽中無動畫 */

4. JS 初始化

$(function() {
    var $grid = $(".gridster ul").gridster({
        widget_margins: [5, 5],           // 元件間距 [垂直, 水平]
        widget_base_dimensions: [100, 100], // 基礎格尺寸 [寬, 高] (px)
        min_cols: 6,                      // 最小列數 (響應式下限)
        max_cols: 12,                     // 最大列數
        min_rows: 3,                      // 最小行數
        autogrow_cols: true,              // 寬度不足時自動增列
        autogenerate_stylesheet: true,    // 自動生成定位 CSS
        resize: { enabled: true, axes: ['both'], handle_append_to: '.handle' }, // 可調整大小
        draggable: {
            handle: '.handle',            // 僅拖拽手柄觸發
            start: function(e, ui) { console.log('開始拖拽', this); },
            stop: function(e, ui) { console.log('結束拖拽', this); saveLayout(); }
        }
    }).data('gridster'); // 取得實例

    // 動態添加元件
    $('#addWidget').click(function() {
        $grid.add_widget('
  • New
  • ', 1, 1); // sizex, sizey }); // 序列化儲存 function saveLayout() { var layout = $grid.serialize(); // [{col, row, size_x, size_y}, ...] localStorage.setItem('dashboardLayout', JSON.stringify(layout)); console.log('佈局已儲存', layout); } // 載入佈局 var saved = JSON.parse(localStorage.getItem('dashboardLayout') || '[]'); if (saved.length) { saved.forEach(function(w) { $grid.add_widget('
  • Loaded
  • ', w.size_x, w.size_y, w.col, w.row); }); } });

    核心 API 速查

    方法說明
    `add_widget(html, size_x, size_y, col, row)`添加元件,可指定位置/尺寸
    `remove_widget(el, silent)`移除元件,silent=true 不觸發回調
    `resize_widget(el, size_x, size_y)`調整元件尺寸
    `serialize()`返回陣列 `[{col, row, size_x, size_y}, ...]`
    `disable()` / `enable()`禁用/啟用拖拽
    `destroy()`完全銷毀實例,恢復原始 DOM

    已知問題與修正

    • 黑點/殘影:舊版本拖拽時可能出現 1px 黑點。升級至 gridster.js 0.5.0+ 或修補 CSS:`.gs_w { outline: none; }`。
    • 拖拽卡頓:大量元件時關閉 `autogenerate_stylesheet`,手動管理樣式;或使用 `requestAnimationFrame` 節流 `resize` 事件。
    • 觸控裝置:原版觸控支援弱,建議引入 `gridster-touch.js` 或改用 Muuri / GridStack.js (現代、支援觸控、TypeScript、React/Vue 綁定)。

    現代替代推薦

    庫特點框架整合
    GridStack.jsTypeScript 原生、觸控完美、響應式、調整大小、動畫、序列化React, Vue, Angular, Svelte 官方綁定
    Muuri極高性能、WebGL 加速、拖拽/排序/佈局統一、無依賴原生 JS,易封裝
    React-Grid-LayoutReact 專用、斷點響應式、靜態/動態佈局、服務端渲染友好React Hooks API
    Vue-Grid-LayoutVue 版 Grid-LayoutVue 2/3 Composition API
    copyright © 萬盛學電腦網 all rights reserved