在WordPress 4.1中，為所有定制程序對象引入了新擴展的JavaScript API。 整個JavaScript API目前位于單個文件wp-admin / js / customize-controls.js中，其中包含所有對象，核心自定義控件等的模型。 ## 預覽JS和控件JS 定制應用程序當前分為兩個不同的區域：自定義程序控件“窗格”和自定義預覽。 該預覽當前在一個iframe中，這意味著所有的JS都可以在控制窗格或預覽中運行。 postMessage API用于在預覽和控件之間進行通信。 大多數主題只能在自定義預覽中實現JavaScript，并通過postMessage實現即時預覽設置。 但是，控件方面的JS可以用于許多事情，例如基于其他設置的值動態顯示和隱藏控件，更改預覽的URL，重點部分預覽等。 這里是一個與預覽功能交互的控件端JS核心的示例，在這種情況下，當帖子頁面更改時更改預覽的URL： ``` // Change the previewed URL to the selected page when changing the page_for_posts. wp.customize( 'page_for_posts', function( setting ) { setting.bind( function( pageId ) { pageId = parseInt( pageId, 10 ); if ( pageId > 0 ) { api.previewer.previewUrl.set( api.settings.url.home + '?page_id=' + pageId ); } }); }); ``` 可以使用相似的邏輯來根據設置的值激活UI對象。 二十七主題包括一些有用的例子，用于利用自定義JS API來改善用戶體驗。 請注意，控制面板中有一個名為customize-controls.js的JS文件和一個名為customize-preview.js的自定義預覽文件。 為了清楚起見，建議所有主題和插件遵循此命名約定，即使只在控件或預覽中提供了自定義JS，而不是兩者都提供。 本頁的其余部分主要用于WordPress 4.1中內置的控件端JS API。 ## 控件，部分和面板的模型 和PHP一樣，每個Customizer對象類型都有一個JavaScript對應的對象。 有wp.customize.Control，wp.customize.Panel和wp.customize.Section模型，以及wp.customize.panel，wp.customize.section和wp.customize.control集合（是的，他們issingular） 存儲所有控件實例。 您可以通過以下方式迭代面板，部分和控件： ``` wp.customize.panel.each( function ( panel ) { /* ... */ } ); wp.customize.section.each( function ( section ) { /* ... */ } ); wp.customize.control.each( function ( control ) { /* ... */ } ); ``` ## 一起關聯控件，部分和面板 在PHP中注冊新的控件時，您將傳遞父節ID： ``` $wp_customize->add_control( 'blogname', array( 'label' => __( 'Site Title' ), 'section' => 'title_tagline', ) ); ``` 在JavaScript API中，可以可預測地獲得控件的部分： ``` id = wp.customize.control( 'blogname' ).section(); // returns title_tagline by default ``` 要從ID獲取節對象，請按照正常的方式查找該部分：wp.customize.section（id）。 您也可以使用此部分狀態將控件移動到另一部分，此處將其移動到“導航”部分： ``` wp.customize.control( 'blogname' ).section( 'nav' ); ``` 同樣，您可以以相同的方式獲取部分的面板ID： ``` id = wp.customize.section( 'sidebar-widgets-sidebar-1' ).panel(); // returns widgets by default ``` 你可以去另一種方式，讓小孩和小孩的孩子： ``` sections = wp.customize.panel( 'widgets' ).sections(); controls = wp.customize.section( 'title_tagline' ).controls(); ``` 您可以使用這些將所有控件從一個部分移動到另一個部分： ``` _.each( wp.customize.section( 'title_tagline' ).controls(), function ( control ) { control.section( 'nav' ); }); ``` ## 上下文面板，部分和控件 控件，面板和節實例具有活動狀態（一個wp.customize.Value實例）。 當活動狀態發生變化時，面板，部分和控件實例調用各自的onChangeActive方法，該方法默認情況下分別向上和向下滑動容器元素，如果為false和true。 現在還有activate（）和deactivate（）方法用于操作面板，部分和控件的此活動狀態。 這些狀態的主要目的是顯示或隱藏對象，而不必將其完全從定制器中刪除。 ``` wp.customize.section( 'nav' ).deactivate(); // slide up wp.customize.section( 'nav' ).activate({ duration: 1000 }); // slide down slowly wp.customize.section( 'colors' ).deactivate({ duration: 0 }); // hide immediately wp.customize.section( 'nav' ).deactivate({ completeCallback: function () { wp.customize.section( 'colors' ).activate(); // show after nav hides completely } }); ``` >[warning] 請注意，只有在預覽刷新或加載其他URL之前，手動更改活動狀態才會保留。 activate（）/ deactivate（）方法被設計為遵循新擴展狀態的模式。 ## 聚焦UI對象 基于面板，部分和控件的expand（）/ collapse（）方法，這些模型還支持一個focus（）方法，它不僅擴展了所有必需的元素，而且還將目標容器滾動到視圖中，并將瀏覽器 專注于容器中的第一個可重點元素。 例如，要擴展“靜態前端頁面”部分，并將重點放在“首頁”的選擇下拉列表中： ``` wp.customize.control( 'page_on_front' ).focus() ``` 焦點功能用于實現自動對焦：深度鏈接到定制器中的面板，部分和控件。 考慮這些URL： …/wp-admin/customize.php?autofocus[panel]=widgets …/wp-admin/customize.php?autofocus[section]=colors …/wp-admin/customize.php?autofocus[control]=blogname 這在WordPress核心中用于在小部件管理頁面上添加鏈接，以直接鏈接到定制器中的小部件面板，以及將自定義預覽中的可見編輯快捷方式與自定義窗格中的關聯控件進行連接。 ## 重點 在PHP中注冊面板，部分或控件時，可以提供優先級參數。 該值存儲在每個相應的Panel，Section和Control實例的wp.customize.Value實例中。 例如，您可以通過以下方式獲取小部件面板的優先級： ``` priority = wp.customize.panel( 'widgets' ).priority(); // returns 110 by default ``` 然后，您可以動態地更改優先級，并且Customizer UI將自動重新排列以反映新的優先級： ``` wp.customize.panel( 'widgets' ).priority( 1 ); // move Widgets to the top ``` ## 自定義控件，面板和部分 在JS中使用自定義Customizer對象時，通常最容易檢查WordPress核心中的自定義對象來了解代碼結構。 請參閱wp-admin / js / customize-controls.js，特別是wp.customize.Panel | Section |控制模型。 注意核心代碼中的幾個示例，特別是在媒體控件中，它們通過對象層次結構建立在彼此的功能上。