外掛簡介
Wookmark 使用 position: absolute 計算元素位置,實現類 Pinterest 的瀑布流佈局。支援自動重排、響應式、AJAX 追加資料。
安裝與引入
<script src="jquery-1.8.2.min.js"></script>
<script src="jquery.wookmark.min.js"></script>
HTML 結構
<div id="main">
<ul id="tiles">
<li><img src="images/1.jpg" alt=""></li>
<li><img src="images/2.jpg" alt=""></li>
<li><img src="images/3.jpg" alt=""></li>
</ul>
</div>
基礎初始化
$('#tiles li').wookmark({
autoResize: true, // 視窗縮放自動重排
container: $('#main'), // 容器 (需 position:relative)
offset: 12, // 元素間距 (px)
itemWidth: 222, // 單元格寬度 (固定)
resizeDelay: 50 // 重排防抖延遲 (ms)
});
容器 CSS 必備
#main {
position: relative; /* 必須!否則所有元素堆疊在左上角 */
}
#tiles {
list-style: none;
margin: 0; padding: 0;
}
#tiles li {
display: block; /* wookmark 會設為 absolute */
}
AJAX 無限捲動載入完整範例
var handler = null;
var options = {
autoResize: true,
container: $('#main'),
offset: 2,
itemWidth: 210
};
function onScroll() {
// 判斷是否接近底部 (預留 100px)
var closeToBottom = ($(window).scrollTop() + $(window).height() > $(document).height() - 100);
if (closeToBottom && !loading) {
loading = true;
$.ajax({
url: 'data.html', // 回傳 HTML 片段:
...
dataType: 'html',
success: function(html) {
$('#tiles').append(html); // 追加到列表
// 重新初始化 wookmark
if (handler) handler.wookmarkClear(); // 清除舊定位
handler = $('#tiles li');
handler.wookmark(options);
loading = false;
},
error: function() {
loading = false;
}
});
}
}
$(document).ready(function() {
$(document).bind('scroll', onScroll);
// 首次佈局
handler = $('#tiles li');
handler.wookmark(options);
});
核心 API 方法
| 方法 | 說明 |
.wookmark(options) | 初始化/重新佈局 |
.wookmarkClear() | 清除定位樣式 (position/left/top),恢復靜態流 |
.wookmark('layout') | 手動觸發重新佈局 (不重新計算選項) |
選項完整說明
| 選項 | 型別 | 預設 | 說明 |
| container | jQuery/Selector | parent | 佈局容器,需 position:relative |
| itemWidth | Number | auto | 單元格寬度,auto 時取第一個元素寬度 |
| offset | Number | 2 | 元素間隙 (px) |
| autoResize | Boolean | false | 視窗 resize 時自動重排 |
| resizeDelay | Number | 50 | resize 事件防抖延遲 (ms) |
| flexibleWidth | Number | 0 | 容器寬度變化時項目寬度調整比例 (0=固定) |
| align | String | 'left' | 對齊: 'left', 'center', 'right' |
| outerOffset | Number | 0 | 容器邊緣額外偏移 |
常見問題與解決
- 元素堆疊左上角:容器缺少
position:relative。
- 圖片載入後佈局錯亂:圖片載入會改變元素高度。解決:圖片
onload 後呼叫 .wookmark('layout'),或使用 imagesLoaded 外掛。
- 動態新增元素不生效:需呼叫
wookmarkClear() 後重新 wookmark()。
- IE 相容:需 jQuery 1.7+,IE8+ 基本支援,建議使用現代瀏覽器。
現代替代方案
- Masonry:功能更豐富、支援動畫、Webpack 模組化、原生 JS 版本。
- CSS Grid + Masonry Auto-placement:純 CSS 實現瀑布流 (有限支援)。
- Vue/React 專用元件:
vue-masonry、react-masonry-css 等。