WordPress 如何正確載入 Owl Carousel?用 wp_enqueue 解決套件衝突

在開發 WordPress 主題或自訂頁面時,常會遇到需要導入 Owl Carousel 來製作輪播圖的需求。如果直接在 header.php 或 footer.php 手寫 HTML 標籤來引入 CSS 和 JS,很容易導致 jQuery 重複載入或載入順序錯誤,最終造成 Slider 無法正常運作或 JavaScript 報錯。這是因為 WordPress 有一套專門的資源管理機制,必須遵循這套規範才能確保外掛與主題間的相容性。

為什麼要使用 wp_enqueue_scripts?

WordPress 的 wp_enqueue_scripts 鉤子(Hook)是用來管理前端資源的核心機制。透過這個方式載入套件有三大優點:第一,它可以處理「相依性」,例如確保 Owl Carousel 的 JS 一定在 jQuery 之後才執行;第二,它可以避免重複載入相同的函式庫;第三,它能讓其他外掛有機會對這些資源進行優化(如合併或壓縮)。

實作程式碼

/** 
 * 將 Owl Carousel 的 CSS / JS 佇列到前端 
 * 前綴統一使用 rs_ 
 */
function rs_enqueue_owl_carousel() {
    /* ===== CSS ===== */
    wp_enqueue_style(
        'rs-owl-carousel', 
        'https://cdnjs.cloudflare.com/ajax/libs/OwlCarousel2/2.3.4/assets/owl.carousel.min.css', 
        array(), 
        '2.3.4'
    );

    wp_enqueue_style(
        'rs-owl-carousel-theme', 
        'https://cdnjs.cloudflare.com/ajax/libs/OwlCarousel2/2.3.4/assets/owl.theme.default.min.css', 
        array('rs-owl-carousel'), 
        '2.3.4'
    );

    /* ===== JS ===== */
    // WordPress 內建 jQuery,這裡確保它被加入
    wp_enqueue_script('jquery');

    wp_enqueue_script(
        'rs-owl-carousel', 
        'https://cdnjs.cloudflare.com/ajax/libs/OwlCarousel2/2.3.4/owl.carousel.min.js', 
        array('jquery'), 
        '2.3.4', 
        true // 放在 footer,減少 render-blocking
    );
}
add_action('wp_enqueue_scripts', 'rs_enqueue_owl_carousel');

步驟拆解與說明

  1. 定義唯一識別碼(Handle):在 wp_enqueue_style 中,第一個參數(如 ‘rs-owl-carousel’)是該資源的 ID,建議加上專案前綴以防與其他外掛衝突。
  2. 處理 CSS 相依性:載入 Theme CSS 時,我們在 array('rs-owl-carousel') 中填入核心 CSS 的 ID,這樣 WordPress 就會確保核心樣式一定排在主題樣式前面。
  3. 呼叫內建 jQuery:不需要另外從 CDN 引入 jQuery,直接使用 wp_enqueue_script('jquery') 即可呼叫 WordPress 核心內建的版本。
  4. 放置於頁面底部:在 JS 函式的最後一個參數設為 true,這會將 <script> 標籤放在 </body> 之前,有助於提升頁面的載入速度分數(LCP/FCP)。

實務踩坑提醒

  • noConflict 模式:WordPress 內建的 jQuery 預設開啟 noConflict 模式。這意味著在寫初始化 JS 時,不能直接使用 $('.owl-carousel'),必須使用 jQuery('.owl-carousel'),或是將代碼包在 (function($){ ... })(jQuery); 的匿名函式中。
  • 版本號更新:在開發環境修改 CSS 後,如果發現前端沒變化,記得更新 wp_enqueue 中的版本號參數(如從 ‘2.3.4’ 改成日期),這能強迫瀏覽器抓取新檔案,避開快取問題。
  • HTTPS 協議:從 CDN 引入資源時,務必檢查連結是否包含 https:。如果網站有安裝 SSL 但資源連結是 http:,瀏覽器會因為安全性考量封鎖該資源,導致輪播圖破圖。

看不懂沒關係,照做就能用

以上的原理看不懂沒關係,只要照著下面的步驟操作就能直接套用:

操作步驟

  1. 安裝並啟用 FluentSnippets 外掛
  2. 在後台選單進入 FluentSnippets,點擊「Create New」新增 PHP 片段
  3. 將文章中的 PHP 程式碼完整複製並貼入編輯區域
  4. 點擊儲存並將狀態切換為啟用 (Status: On)
  5. 清除網站快取並前往前台確認輪播圖功能
如果啟用後網站出現異常,回到 Snippets 將該片段停用即可立刻復原,不會影響其他設定。
文章分享