如何使用WordPress Customizer API

使用 WordPress 自定義器 API 的關鍵步驟如下：1. 在 customize_register 鉤子中添加 setting、control 和 section 來註冊自定義選項，例如添加網站副標題；2. 設置 transport 為 postMessage 並配合 JavaScript 實現即時預覽效果；3. 利用 panel 和 section 組織自定義選項結構，提升用戶體驗；掌握這些核心概念與技巧即可實現靈活的主題自定義功能。

要使用 WordPress 自定義器 API（Customizer API），其實不難，但需要理解它的工作流程和結構。它的核心作用是讓你在主題中添加可自定義的選項，用戶可以即時預覽變更效果，而無需刷新頁面。

以下幾個部分是你實際操作中最常用到的功能與技巧：

添加自定義設置項

要在自定義器裡添加新的設置項，你需要在 customize_register 鉤子中註冊它們。這包括設置項本身、控制項以及對應的面板或區塊。

舉個例子：
如果你想添加一個網站副標題的文字輸入框，你可以這樣寫：

function mytheme_customize_register( $wp_customize ) {
    $wp_customize->add_setting( 'subtitle_text', array(
        'default'   => '默認副標題',
        'transport' => 'refresh', // 或 postMessage 用於即時更新
    ));

    $wp_customize->add_control( 'subtitle_text', array(
        'label'      => __( '首頁副標題', 'mytheme' ),
        'section'    => 'title_tagline',
        'settings'   => 'subtitle_text',
        'type'       => 'text',
    ));
}
add_action( 'customize_register', 'mytheme_customize_register' );

這裡要注意的是：

• setting 是存儲值的地方。
• control 是 UI 界面元素，比如文字框、下拉選單等。
• section 決定這個控制項放在哪個區域裡。

使用 JS 即時預覽更改

如果你希望用戶在調整設定時能實時看到變化，而不是點擊「發佈」後才生效，就需要使用 JavaScript 的 postMessage 傳輸方式。

例如，你想實時改變網站標題顏色：

1. 在 PHP 中設置 transport 為 postMessage：

   $wp_customize->add_setting( 'title_color', array(
    'default'   => '#000000',
    'transport' => 'postMessage',
   ));

2. 在 JS 中監聽變化並更新 DOM：

   ( function( $ ) {
    wp.customize( 'title_color', function( value ) {
        value.bind( function( to ) {
            $( '.site-title a' ).css( 'color', to );
        });
    });
   } )( jQuery );

記得把這個腳本加載進去，在主題的 functions.php 裡用 customize_preview_init 鉤子引入即可。

組織面板與區塊結構

WordPress 自定義器支援將相關的控制項分組到不同的面板（panel）和區塊（section）中。如果你的主題有很多自定義選項，合理組織結構會提升用戶體驗。

例如創建一個名為“首頁設置”的面板：

$wp_customize->add_panel( 'homepage_settings', array(
    'title'       => __( '首頁設置', 'mytheme' ),
    'description' => '調整首頁顯示內容',
    'priority'    => 160,
));

$wp_customize->add_section( 'slider_settings', array(
    'title'       => __( '輪播圖設置', 'mytheme' ),
    'panel'       => 'homepage_settings',
));

這樣就可以在自定義器中把相關設置集中管理，看起來也更有條理。

基本上就這些。WordPress Customizer API 的功能還挺多，比如支持多種類型的控制項（checkbox、radio、dropdown-pages 等），也可以配合主題修改做深度定制。只要掌握好 setting、control、section 和 panel 之間的關係，再加上一點 JS 實時預覽的技巧，就能做出非常實用的主題自定義功能了。

以上是如何使用WordPress Customizer API的詳細內容。更多資訊請關注PHP中文網其他相關文章！