jQuery Expander 是一款輕量級圖片彈出/翻轉特效外掛,支援 6 種 3D 翻轉動畫。本文完整解析其引入方式、核心配置、HTML 結構、初始化邏輯、以及客製化擴充技巧。
<!-- CSS -->
<link href="css/expander.css" rel="stylesheet">
<link href="css/theme.css" rel="stylesheet">
<!-- jQuery (必須在 expander 之前) -->
<script src="js/jquery-latest.min.js"></script>
<script src="js/expander.min.js"></script>
<section class="main">
<article>
<div class="imgContainer">
<h5>效果一:預設翻轉</h5>
<img src="images/photo1.jpg" data-expander='{ "animation": "default" }'>
</div>
<div class="imgContainer">
<h5>效果二:鑽石翻轉</h5>
<img src="images/photo2.jpg" data-expander='{ "animation": "diamond" }'>
</div>
<div class="imgContainer">
<h5>效果三:3D 翻轉</h5>
<img src="images/photo3.jpg" data-expander='{ "animation": "turn3d" }'>
</div>
<div class="imgContainer">
<h5>效果四:3D 翻面</h5>
<img src="images/photo4.jpg" data-expander='{ "animation": "flip3d" }'>
</div>
<div class="imgContainer">
<h5>效果五:旋轉</h5>
<img src="images/photo5.jpg" data-expander='{ "animation": "rotate" }'>
</div>
<div class="imgContainer">
<h5>效果六:淡入淡出</h5>
<img src="images/photo6.jpg" data-expander='{ "animation": "fade" }'>
</div>
</article>
</section>
| animation 值 | 效果描述 | 適用場景 |
|---|---|---|
default | 基礎縮放淡入 | 通用、效能最佳 |
diamond | 菱形旋轉展開 | 創意展示 |
turn3d | 3D 翻轉 (Y 軸) | 卡片翻面效果 |
flip3d | 3D 翻面 (X 軸) | 名片/票券翻面 |
rotate | 2D 旋轉縮放 | 活潑風格 |
fade | 單純淡入淡出 | 極簡風格、效能最好 |
透過 data-expander JSON 物件傳遞:
<img src="photo.jpg"
data-expander='{
"animation": "turn3d",
"theme": "dark", // "dark" | "light" - 顏色主題
"speed": "normal", // "slow" | "normal" | "fast" - 動畫速度
"url": "large-photo.jpg" // 點擊後顯示的大圖 (選填,預設用原圖)
}'>
外掛核心邏輯:
$(document).ready 時尋找所有 img[data-expander].expander-container 絕對定位疊加層,複製原圖至容器內position: absolute; top/left/width/height).anim-{speed} .animation-{type})resize/scroll 時重新計算容器位置
/* 動畫速度 */
.anim-slow { transition-duration: 0.8s; }
.anim-normal { transition-duration: 0.4s; }
.anim-fast { transition-duration: 0.2s; }
/* 動畫類型 - 以 turn3d 為例 */
.animation-turn3d {
transform-style: preserve-3d;
transform-origin: center center;
}
.animation-turn3d.open {
transform: rotateY(0deg) scale(1);
opacity: 1;
}
.animation-turn3d:not(.open) {
transform: rotateY(90deg) scale(0.8);
opacity: 0;
}
/* 遮罩層 */
.expander-siv {
position: fixed; top: 0; left: 0; width: 100%; height: 100%;
background: rgba(0,0,0,0.8); opacity: 0; visibility: hidden; transition: opacity 0.3s;
z-index: 9998;
}
.expander-siv.show { opacity: 1; visibility: visible; }
.expander-siv.dark { background: rgba(0,0,0,0.9); }
.expander-siv.light { background: rgba(255,255,255,0.9); }
/* 容器開啟狀態 */
.expander-container.open {
position: fixed; top: 0; left: 0; width: 100%; height: 100%;
display: flex; align-items: center; justify-content: center;
z-index: 9999;
}
// 手動觸發展開/關閉 (需先初始化)
$('#my-image').trigger('expand'); // 程式化開啟
$('#my-image').trigger('retract'); // 程式化關閉
// 取得實例 (內部儲存於 data)
const $img = $('img[data-expander]');
const container = $img.data('container'); // .expander-container 元素
const options = $img.data('options'); // 解析後的選項物件
const original = $img.data('original'); // { parent, position }
| 問題 | 原因 | 解決 |
|---|---|---|
| 動畫卡頓/閃爍 | 圖片未預載、CSS transform 觸發重繪 | 預載大圖:new Image().src = largeUrl;使用 will-change: transform |
| 行動裝置觸控無法關閉 | 觸控事件與 click 衝突 | 容器綁定 touchend 或使用 pointerdown |
| 固定版頭遮擋 | 容器 z-index 不足 | 調整 .expander-container.open z-index > 版頭 |
| 動態新增圖片不生效 | 初始化只跑一次 | 新增後手動呼叫 $.expander.init() 或重新掃描 |
| data-expander JSON 解析失敗 | 單引號/雙引號混用、特殊字元未轉義 | 屬性值用單引號包裹,內部 JSON 用雙引號:data-expander='{...}' |
// 1. 定義 CSS 動畫
@keyframes my-custom-anim {
0% { transform: scale(0) rotate(-180deg); opacity: 0; }
100% { transform: scale(1) rotate(0); opacity: 1; }
}
.animation-myCustom.open {
animation: my-custom-anim 0.5s cubic-bezier(0.175, 0.885, 0.32, 1.275) forwards;
}
// 2. 使用
<img src="..." data-expander='{ "animation": "myCustom" }'>
| 方案 | 體積 | 依賴 | 動畫豐富度 | 維護狀態 |
|---|---|---|---|---|
| jQuery Expander | ~8KB | jQuery | 6 種 3D | 較舊、輕量 |
| Magnific Popup | ~20KB | jQuery | 基礎縮放 | 成熟、功能豐富 |
| PhotoSwipe | ~25KB | 無 (Vanilla) | 手勢縮放、分享 | 現代、行動優先 |
| GLightbox | ~15KB | 無 | CSS 動畫 | 現代、無依賴 |
jQuery Expander 適合需要**快速整合、輕量級、特定 3D 翻轉效果** 的 jQuery 專案。核心價值在於:自動建立疊加容器、位置同步、動畫類別切換。若專案已移除 jQuery 依賴,或需觸控手勢縮放、圖庫瀏覽等豐富功能,建議改用 PhotoSwipe 或 GLightbox 等現代原生庫。