Customize API是面向對象的。 Customizer對象有四種主要類型：面板，部分，設置和控件。 設置將UI元素（控件）與保存在數據庫中的設置相關聯。 部分是用于控制的UI容器，以改善其組織。 面板是部分的容器，允許將多個部分組合在一起。 每個Customizer對象由PHP類表示，所有對象都由Customize Manager對象WP_Customize_Manager管理。 要添加，刪除或修改任何Customizer對象，并訪問Customizer Manager，請使用customize_register鉤子： ``` function themeslug_customize_register( $wp_customize ) { // Do stuff with $wp_customize, the WP_Customize_Manager object. } add_action( 'customize_register', 'themeslug_customize_register' ); ``` Customizer Manager為每個Customizer對象類型提供add_，get_和remove_方法; 每個都有一個id。 get_方法允許直接修改添加控件時指定的參數。 ``` add_action('customize_register','my_customize_register'); function my_customize_register( $wp_customize ) { $wp_customize->add_panel(); $wp_customize->get_panel(); $wp_customize->remove_panel(); $wp_customize->add_section(); $wp_customize->get_section(); $wp_customize->remove_section(); $wp_customize->add_setting(); $wp_customize->get_setting(); $wp_customize->remove_setting(); $wp_customize->add_control(); $wp_customize->get_control(); $wp_customize->remove_control(); } ``` >[warning] 注意：主題通常不應該使用get方法來修改核心部分和面板，因為主題不應該修改核心的，與主題無關的功能。 鼓勵插件在必要時使用這些功能。 主題不應該“重組”主題未添加的自定義程序部分。 ## 設置 設置可以處理您的定制器對象的實時預覽，保存和清理。 每個設置由控制對象管理。 添加新設置時可以使用幾個參數： ``` $wp_customize->add_setting( 'setting_id', array( 'type' => 'theme_mod', // or 'option' 'capability' => 'edit_theme_options', 'theme_supports' => '', // Rarely needed. 'default' => '', 'transport' => 'refresh', // or postMessage 'sanitize_callback' => '', 'sanitize_js_callback' => '', // Basically to_json. ) ); ``` >[danger] 警報：重要事項：不要使用看起來像widget_ *，sidebars_widgets [*]，nav_menu [*]或nav_menu_item [*]的設置ID。 這些設置ID模式分別保留用于窗口小部件實例，側邊欄，導航菜單和導航菜單項。 如果您需要在設置ID中使用“widget”，請將其用作后綴而不是前綴，例如“homepage_widget”。 有兩種主要的設置類型：選項和主題修改。 選項直接存儲在WordPress數據庫的wp_options表中，并應用于該站點，而不考慮活動主題。 如果添加了選項類型的設置，主題很少。 另一方面，主題模式是針對特定主題的。 大多數主題選項應該是theme_mods。 例如，自定義CSS插件可以將自定義主題css設置注冊為theme_mod，允許每個主題具有獨特的一組CSS規則，而不會在切換主題然后切換時丟失CSS。 - customize-theme-mods-options - Theme_mod與選項設置類型示例。 通常最重要的是設置設置的默認值以及其清理回調，這將確保數據庫中不存儲不安全的數據。 典型主題用法： ``` $wp_customize->add_setting( 'accent_color', array( 'default' => '#f72525', 'sanitize_callback' => 'sanitize_hex_color', ) ); ``` Typical plugin usage: ``` $wp_customize->add_setting( 'myplugin_options[color]', array( 'type' => 'option', 'capability' => 'manage_options', 'default' => '#ff2525', 'sanitize_callback' => 'sanitize_hex_color', ) ); ``` >[warning] 請注意，定制程序可以使用選項類型處理存儲為鍵控數組的選項以進行設置。 這允許將多個設置存儲在不是主題模式的單個選項中。 要檢索并使用您的Customizer選項的值，請使用get_theme_mod()和get_option()與設置標識： ``` function my_custom_css_output() { echo '<style type="text/css" id="custom-theme-css">' . get_theme_mod( 'custom_theme_css', '' ) . '</style>'; echo '<style type="text/css" id="custom-plugin-css">' . get_option( 'custom_plugin_css', '' ) . '</style>'; } add_action( 'wp_head', 'my_custom_css_output'); ``` >[warning] 請注意，get_theme_mod()和get_option()的第二個參數是默認值，它應該與添加設置時設置的默認值相匹配。 ## 控制 控件是用于創建UI的主要Customizer對象。 具體來說，每個控件必須與設置相關聯，并且該設置將將用戶輸入的數據從控件保存到數據庫（除了將其顯示在實時預覽中并將其消毒之外）。 控件可以由定制程序管理器添加，并以極少的努力提供一組強大的UI選項： ``` $wp_customize->add_control( 'setting_id', array( 'type' => 'date', 'priority' => 10, // Within the section. 'section' => 'colors', // Required, core or custom. 'label' => __( 'Date' ), 'description' => __( 'This is a date control with a red border.' ), 'input_attrs' => array( 'class' => 'my-custom-class-for-js', 'style' => 'border: 1px solid #900', 'placeholder' => __( 'mm/dd/yyyy' ), ), 'active_callback' => 'is_front_page', ) ); ``` 添加控件時最重要的參數是它的類型 - 這決定了Customizer將顯示哪種類型的UI。 Core提供了幾種內置控件類型： `<input> `任何允許類型的元素（見下文） - checkbox - textarea - radio （將值的數組=>標簽傳遞給選擇參數） - select （將值的數組=>標簽傳遞給choices參數） - dropdown-pages （使用allow_addition參數允許用戶從控件添加新頁面） 對于html input元素支持的任何輸入類型，只需在添加控件時將type屬性值傳遞給type參數即可。 這允許支持控件類型，如文本，隱藏，數字，范圍，URL，電話，電子郵件，搜索，時間，日期，日期時間和周，等待瀏覽器支持。 必須將控件添加到部分，然后才能顯示（部分必須包含要顯示的控件）。 這是通過在添加控件時指定section參數來完成的。 以下是添加基本textarea控件的示例： ``` $wp_customize->add_control( 'custom_theme_css', array( 'label' => __( 'Custom Theme CSS' ), 'type' => 'textarea', 'section' => 'custom_css', ) ); ``` 這是一個基本的范圍（滑塊）控件的例子。 請注意，大多數瀏覽器將不會顯示此控件的數值，因為范圍輸入類型是為確切值不重要的設置而設計的。 如果數值很重要，請考慮使用數字類型。 input_attrs參數將映射屬性=>值的鍵控數組到輸入元素上的屬性，并且可以用于從占位符文本到數據的用途 - 自定義腳本中的JavaScript引用的數據。 對于數字和范圍控制，它允許我們設置最小值，最大值和步長值。 ``` $wp_customize->add_control( 'setting_id', array( 'type' => 'range', 'section' => 'title_tagline', 'label' => __( 'Range' ), 'description' => __( 'This is the range control description.' ), 'input_attrs' => array( 'min' => 0, 'max' => 10, 'step' => 2, ), ) ); ``` ## 核心自定義控件 如果沒有一個基本的控制類型適合您的需要，您可以輕松地創建和添加自定義控件。 自定義控件在本文后面將會更全面地解釋，但它們基本上是基于WP_Customize_Control對象的子類，允許任何可能需要的html標記和功能。 Core提供了幾個內置的自定義控件，允許開發人員輕松實現豐富的JavaScript驅動功能。 可以添加顏色選擇器控件，如下所示： ``` $wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'color_control', array( 'label' => __( 'Accent Color', 'theme_textdomain' ), 'section' => 'media', ) ) ); ``` MediaPress 4.1和4.2還增加了對任何類型的多媒體內容的支持。 媒體控制實現本地WordPress媒體管理器，允許用戶從其庫中選擇文件或上傳新的文件。 通過在添加控件時指定mime_type參數，可以指示媒體庫顯示為特定類型，如圖像或音頻： ``` $wp_customize->add_control( new WP_Customize_Media_Control( $wp_customize, 'image_control', array( 'label' => __( 'Featured Home Page Image', 'theme_textdomain' ), 'section' => 'media', 'mime_type' => 'image', ) ) ); ``` ``` $wp_customize->add_control( new WP_Customize_Media_Control( $wp_customize, 'audio_control', array( 'label' => _( 'Featured Home Page Recording', 'theme_textdomain' ), 'section' => 'media', 'mime_type' => 'audio', ) ) ); ``` >[warning] 請注意，與WP_Customize_Media_Control關聯的設置保存相關的附件ID，而所有其他媒體相關控件（WP_Customize_Upload_Control的子項）將媒體文件URL保存到該設置。 有關Make WordPress Core的更多信息。 此外，WordPress 4.3引入了WP_Customize_Cropped_Image_Control，它為選擇后的圖像提供了一個界面。 這對于需要特定寬高比的情況很有用。 ## 部分 部分是Customizer控件的UI容器。 雖然您可以將自定義控件添加到核心部分，但如果您有多個選項，則可能需要添加一個或多個自定義部分。 使用WP_Customize_Manager對象的add_section方法添加新的部分： ``` $wp_customize->add_section( 'custom_css', array( 'title' => __( 'Custom CSS' ), 'description' => __( 'Add custom CSS here' ), 'panel' => '', // Not typically needed. 'priority' => 160, 'capability' => 'edit_theme_options', 'theme_supports' => '', // Rarely needed. ) ); ``` 您只需要包含要覆蓋默認值的字段。 例如，默認優先級（外觀順序）通常是可接受的，如果您的選項不言自明，大多數部分不應該需要描述性文本。 如果您想要更改自定義部分的位置，則核心部分的優先級如下所示： |Title |ID| Priority (Order)| |---|---|---| |Site Title & Tagline |title_tagline |20| |Colors |colors |40| |Header Image |header_image |60| |Background Image |background_image |80| |Menus (Panel) |nav_menus |100| |Widgets (Panel) |widgets |110| |Static Front Page |static_front_page| 120| |default ||160| |Additional CSS| custom_css |200| 在大多數情況下，可以添加僅指定一個或兩個參數的節。 以下是添加與主題頁腳相關的選項部分的示例： ``` // Add a footer/copyright information section. $wp_customize->add_section( 'footer' , array( 'title' => __( 'Footer', 'themename' ), 'priority' => 105, // Before Widgets. ) ); ``` ## 面板 Customizer Panels API是在WordPress 4.0中引入的，允許開發人員創建一個超出控件和部分的層次結構。控制面板不僅僅是簡單地分組控件，而是設計為定制工具提供不同的上下文，例如自定義窗口小部件，菜單，或者將來可能編輯帖子。部分和面板對象之間存在重要的技術區別。 在大多數情況下，主題不應該注冊自己的面板。部分不需要嵌套在面板下，每個部分通常應包含多個控件。控件也應該添加到核心提供的部分，例如為顏色部分添加顏色選項。還要確保您的選擇盡可能精簡和高效;看到WordPress的哲學。面板設計為整個功能（如小部件，菜單或帖子）的上下文，而不是用于通用部分的包裝。如果您絕對必須使用面板，您會發現API與章節幾乎完全相同： ``` $wp_customize->add_panel( 'menus', array( 'title' => __( 'Menus' ), 'description' => $description, // Include html tags such as <p>. 'priority' => 160, // Mixed with top-level-section hierarchy. ) ); $wp_customize->add_section( $section_id , array( 'title' => $menu->name, 'panel' => 'menus', ) ); ``` 面板必須包含至少一個必須包含至少一個控件的節，以顯示。 如上例所示，Sections可以添加到面板中，類似于將控件添加到Sections。 但是，與控件不同，如果Panel參數在注冊Section時為空，則它將顯示在主要的頂級定制程序上下文中，因為大多數部分不應包含在面板中。 ## 自定義控件，部分和面板 通過對與每個Customizer對象相關聯的PHP對象進行子類化，可以輕松創建自定義控件，部分和面板：WP_Customize_Control，WP_Customize_Section和WP_Customize_Panel（這也可以用于WP_Customize_Setting，但自定義設置通常使用自定義設置類型更好地實現，如 在下一節概述）。 以下是基本自定義控件的示例： ``` class WP_New_Menu_Customize_Control extends WP_Customize_Control { public $type = 'new_menu'; /** * Render the control's content. */ public function render_content() { ?> <button class="button button-primary" id="create-new-menu-submit" tabindex="0"><?php _e( 'Create Menu' ); ?></button> <?php } } ``` 通過對基本控件類進行子類化，您可以使用自定義功能覆蓋任何功能，也可以根據需要使用核心功能。 要覆蓋的最常用的功能是render_content（），因為它允許您從頭開始使用HTML創建自定義UI。 應該謹慎使用自定義控件，因為它們可能會引入與周圍的核心UI不一致的UI，并導致用戶混淆。 自定義定制器對象可以類似于添加默認控件，部分和面板的方式添加： ``` $wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, // WP_Customize_Manager 'accent_color', // Setting id array( // Args, including any custom ones. 'label' => __( 'Accent Color' ), 'section' => 'colors', ) ) ); ``` 添加控件時傳遞的參數映射到控件類中的類變量，因此您可以添加和使用自定義對象的特定部分在不同實例之間不同的自定義對象。 在創建自定義控件，部分或面板時，強烈建議引用核心代碼，以便完全了解可以覆蓋的可用功能。 Core還包括每種類型的自定義對象的示例。 這可以在wp-includes / class-wp-customize-control.php，wp-includes / class-wp-customize-section.php和wp-includes / class-wp-customize-panel.php中找到。 每個Customizer對象類型還有一個JavaScript API，可以使用自定義對象進行擴展; 有關更多詳細信息，請參閱Customizer JavaScript API部分。 ## 定制界面UI標準 自定義定制程序控件，部分和面板應盡可能匹配核心UI實踐。 這包括依賴于wp-admin的標準，例如使用.button和.button-primary類。 還有一些特定于定制器的標準（從WordPress 4.7開始）： - 白色背景顏色僅用于指示導航和可操作的項目（如輸入） - 一般的#eee背景顏色提供與白色元素的視覺對比 - 1px #ddd將背景邊框和彼此之間的導航元素分開 - 在需要視覺分離的元素之間提供15px的間距 - 導航元素一側使用4px邊框顯示懸停或焦點，顏色為＃0073aa - 定制器文本使用顏色：＃555d66，＃0073aa用于導航元素上的懸停和焦點狀態 ## 自定義設置類型 默認情況下，定制程序支持將設置保存為選項或主題修改。 但是，可以輕松地覆蓋此行為，以手動保存和預覽WordPress數據庫的wp_options表外的設置，或應用其他自定義處理。 要開始使用，請在添加設置時指定除選項或theme_mod之外的類型（您幾乎可以使用任何字符串）： ``` $wp_customize-&gt;add_setting( $nav_menu_setting_id, array( 'type' =&gt; 'nav_menu', 'default' =&gt; $item_ids, ) ); ``` 當相關控件中的值更改時，該設置將不再保存或預覽。 現在，您可以使用customize_update_ $ setting-> type和customize_preview_ $ setting->類型操作來實現自定義保存和預覽功能。 以下是從菜單定制程序項目中保存菜單項的順序屬性的示例（設置的值是菜單ID的有序數組）： ``` function menu_customizer_update_nav_menu( $value, $setting ) { $menu_id = str_replace( 'nav_menu_', '', $setting-&gt;id ); // ... $i = 0; foreach( $value as $item_id ) { // $value is ordered array of item ids. menu_customizer_update_menu_item_order( $menu_id, $item_id, $i ); $i++; } } add_action( 'customize_update_nav_menu', 'menu_customizer_update_nav_menu', 10, 2 ); ``` 而且這里是同一個插件實現導航菜單項的預覽（請注意，此示例需要PHP 5.3或更高版本）： ``` function menu_customizer_preview_nav_menu( $setting ) { $menu_id = str_replace( 'nav_menu_', '', $setting->id ); add_filter( 'wp_get_nav_menu_items', function( $items, $menu, $args ) use ( $menu_id, $setting ) { $preview_menu_id = $menu->term_id; if ( $menu_id == $preview_menu_id ) { $new_ids = $setting->post_value(); foreach ( $new_ids as $item_id ) { $item = wp_setup_nav_menu_item( $item ); $item->menu_order = $i; $new_items[] = $item; $i++; } return $new_items; } else { return $items; } }, 10, 3 ); } add_action( 'customize_preview_nav_menu', 'menu_customizer_preview_nav_menu', 10, 2 ); ```