在使用 WordPress 傳統編輯器(TinyMCE)撰寫文章時,若想讓圖片具備點擊放大效果,編輯人員通常需要手動點擊圖片、設定連結至「媒體檔案」,並進入進階設定開啟燈箱屬性。這種重複性的操作在處理多圖文章時效率極低,且容易遺漏設定,導致前台頁面圖片無法正常啟動幻燈片功能。
內容導覽
為什麼需要自定義 Lightbox 按鈕
雖然現代的區塊編輯器已有良好的圖片處理機制,但許多企業網站仍維持使用傳統編輯器。透過在 TinyMCE 工具列中新增一個專用按鈕,可以直接抓取選取的圖片路徑,並利用 JavaScript 自動將其包覆在含有特定屬性(如 Elementor 的 Lightbox 標籤)的連結中。這樣不僅確保了 HTML 結構的一致性,也讓非技術人員能一鍵完成複雜的標籤設定。
步驟一:注入後台控制腳本
首先使用 admin_head 鉤子將 JavaScript 邏輯直接輸出到文章與頁面的編輯頁面。這段腳本會監聽 TinyMCE 的載入狀態,並在編輯器準備就緒後,註冊一個名為 image_lightbox 的外掛。
步驟二:圖片連結處理與路徑還原
當使用者點擊按鈕時,程式會判斷選取的節點是否為圖片。如果是縮圖,則利用正規表示式移除檔名末尾的尺寸標註(例如 300×200),還原出最原始的圖檔路徑,確保燈箱放大後看到的是清晰的原圖。
實作程式碼
<?php
/**
* TinyMCE Image Lightbox Button
* 在傳統編輯器加入 Lightbox 按鈕
*/
// 1. 用 admin_head 把 JS 直接輸出到後台頁面
add_action('admin_head', 'ilb_inject_tinymce_script');
function ilb_inject_tinymce_script() {
global $pagenow, $typenow;
// 只在文章/頁面編輯頁載入
if (!in_array($pagenow, ['post.php', 'post-new.php'])) return;
?>
<script type="text/javascript">
(function waitForTinymce() {
if (typeof tinymce === 'undefined') {
setTimeout(waitForTinymce, 300);
return;
}
tinymce.PluginManager.add('image_lightbox', function(editor) {
editor.addButton('image_lightbox_btn', {
text: '🔍 Lightbox',
tooltip: '為選取的圖片加上 Lightbox 連結',
onclick: function() {
var node = editor.selection.getNode();
if (node.nodeName !== 'IMG') {
editor.windowManager.alert('請先點選一張圖片!');
return;
}
var imgSrc = node.getAttribute('src');
var parent = node.parentNode;
if (parent && parent.nodeName === 'A') {
editor.windowManager.confirm(
'此圖片已有連結:\n' + parent.getAttribute('href') + '\n\n要覆蓋成 Lightbox 連結嗎?',
function(confirmed) {
if (confirmed) {
applyLightbox(editor, node, imgSrc, parent);
}
}
);
return;
}
applyLightbox(editor, node, imgSrc, null);
}
});
function applyLightbox(editor, imgNode, imgSrc, existingAnchor) {
// 還原原圖路徑,移除如 -300x200 這種尺寸後綴
var originalSrc = imgSrc.replace(/-\d+x\d+(\.[a-zA-Z]+)$/, '$1');
if (existingAnchor) {
existingAnchor.setAttribute('href', originalSrc);
existingAnchor.setAttribute('data-elementor-open-lightbox', 'yes');
} else {
editor.dom.setOuterHTML(
imgNode,
'<a href="' + originalSrc + '" data-elementor-open-lightbox="yes">' +
editor.dom.getOuterHTML(imgNode) +
'</a>'
);
}
editor.windowManager.alert('Lightbox 連結已套用!');
}
});
})();
</script>
<?php
}
// 2. 註冊外掛名稱到 TinyMCE
add_filter('mce_external_plugins', 'ilb_register_tinymce_plugin');
function ilb_register_tinymce_plugin($plugins) {
// 實際邏輯已在 admin_head 注入,這裡用空的 Data URI 佔位
$plugins['image_lightbox'] = 'data:text/javascript,';
return $plugins;
}
// 3. 在工具列加入按鈕
add_filter('mce_buttons', 'ilb_add_tinymce_button');
function ilb_add_tinymce_button($buttons) {
$buttons[] = 'image_lightbox_btn';
return $buttons;
}
踩坑提醒與實務建議
- 圖檔路徑規則:程式中的 Regex 假設縮圖命名規則為「寬x高」,若網站使用了特殊的外掛改變圖片命名(例如 scaled 字樣),可能需要微調正規表示式以精確抓取原圖。
- Elementor 以外的支援:範例中使用了
data-elementor-open-lightbox。若您使用的是其他 Lightbox 外掛(如 FooBox 或 WP Featherlight),請將屬性名稱改為對應外掛要求的 Class 或 Data 屬性。 - 快取問題:由於邏輯是透過
admin_head注入,若有安裝後台優化或快取外掛,修改 code 後可能需要強制重新載入頁面才能看到按鈕。 - 結構完整性:如果圖片已經被包裹在其他連結中,程式會跳出警告。建議在套用前先確認該圖片是否需要保留原有的超連結,避免覆蓋掉重要的外部導向。
實作懶人包,照作就能用
操作步驟
- 安裝 FluentSnippets 外掛
- 新增一個 PHP 片段
- 複製文章中的實作程式碼並完整貼入
- 將該片段設定為啟用
- 清除網站快取
- 回到文章或頁面編輯頁面,在傳統編輯器中點選一張圖片,並點擊工具列新出現的 Lightbox 按鈕即可一鍵套用效果
如果啟用後網站出現異常,回到 Snippets 將該片段停用即可立刻復原,不會影響其他設定。



