プレビューJSとコントロールJS

カスタマイザーアプリは現在、カスタマイザーコントロールの「ペイン」とカスタマイズプレビューの2つの異なるエリアに分かれています。プレビューは現在iframe内にあり、すべてのJSはコントロールペインまたはプレビューのいずれかで実行されます。postMessage APIは、プレビューとコントロール間の通信に使用されます。

ほとんどのテーマは、カスタマイズプレビュー内でのみJavaScriptを実装し、postMessageを介して設定のインスタントプレビューを実装するために使用します。しかし、コントロール側のJSは、他の設定の値に基づいてコントロールを動的に表示および非表示にしたり、プレビューされたURLを変更したり、プレビューの一部にフォーカスを当てたりするなど、多くのことに使用できます。以下は、投稿のページが変更されたときにプレビューされたURLを変更するコントロール側のJSのコアからの例です： 

  1. // Change the previewed URL to the selected page when changing the page_for_posts.
  2. wp.customize(
  3.     'page_for_posts',
  4.     function( setting ) {
  5.         setting.bind( function( pageId ) {
  6.             pageId = parseInt( pageId, 10 );
  7.             if ( pageId > 0 ) {
  8.             api.previewer.previewUrl.set( api.settings.url.home + '?page_id=' + pageId );
  9.             }
  10.         });
  11.     }
  12. );

同様のロジックを使用して、設定の値に基づいてactivateUIオブジェクトを操作できます。Twenty Seventeenテーマには、ユーザーエクスペリエンスを向上させるためにカスタマイズJS APIを活用するためのいくつかの便利な例が含まれています。コントロールペイン用のJSファイルは1つ、customize-controls.jsという名前で、カスタマイズプレビュー用のファイルは1つ、customize-preview.jsという名前です。明確にするために、すべてのテーマとプラグインは、この命名規則に従うことが推奨されます。たとえカスタマイズJSがコントロールまたはプレビューのいずれかにのみ提供されている場合でも、両方ではない場合でもです。

このページの残りは、WordPress 4.1で構築されたコントロール側のJS APIに主に捧げられています。

コントロール、セクション、およびパネルのモデル

PHPと同様に、各カスタマイザーオブジェクトタイプには、JavaScriptに対応するオブジェクトがあります。wp.customize.Control,``````````wp.customize.Panel,およびwp.customize.Sectionモデル、さらにwp.customize.panel,``````````wp.customize.section, and ``````````wp.customize.controlコレクション（はい、単数形です）があり、すべてのコントロールインスタンスを格納します。パネル、セクション、およびコントロールを次のように反復処理できます： 

  1. wp.customize.panel.each( function ( panel ) { /* ... */ } );
  2. wp.customize.section.each( function ( section ) { /* ... */ } );
  3. wp.customize.control.each( function ( control ) { /* ... */ } );

コントロール、セクション、およびパネルを関連付ける

PHPで新しいコントロールを登録する際には、親セクションIDを渡します： 

  1. <?php
  2. $wp_customize->add_control(
  3.     'blogname',
  4.     array(
  5.         'label'   => __( 'Site Title' ),
  6.         'section' => 'title_tagline',
  7.     )
  8. );
  9. ?>

JavaScript APIでは、コントロールのセクションを予測可能に取得できます： 

  1. id = wp.customize.control( 'blogname' ).section(); // returns title_tagline by default

IDからセクションオブジェクトを取得するには、通常通りIDでセクションを検索します：wp.customize.section( id )。

このsection状態を使用して、コントロールを別のセクションに移動できます。ここでは、ナビゲーションセクションに移動しています： 

  1. wp.customize.control( 'blogname' ).section( 'nav' );

同様に、セクションのパネルIDを同じ方法で取得できます： 

  1. id = wp.customize.section( 'sidebar-widgets-sidebar-1' ).panel(); // returns widgets by default

パネルとセクションの子を取得するために、逆の方法も使用できます： 

  1. sections = wp.customize.panel( 'widgets' ).sections();controls = wp.customize.section( 'title_tagline' ).controls();

これらを使用して、1つのセクションから別のセクションにすべてのコントロールを移動できます： 

  1. _.each( wp.customize.section( 'title_tagline' ).controls(), function ( control ) {
  2.    control.section( 'nav' );
  3. } );

コンテキストパネル、セクション、およびコントロール

  3. ``````bash
  4. wp.customize.section( 'nav' ).deactivate(); // slide up
  5. wp.customize.section( 'nav' ).activate({ duration: 1000 }); // slide down slowly
  6. wp.customize.section( 'colors' ).deactivate({ duration: 0 }); // hide immediately
  7. wp.customize.section( 'nav' ).deactivate({ completeCallback:
  8. function () {
  9.    wp.customize.section( 'colors' ).activate(); // show after nav hides completely
  10. } } );
  11. `

手動でactive状態を変更すると、プレビューが更新されるか別のURLが読み込まれるまでその状態が保持されることに注意してください。activate()/deactivate()メソッドは、新しいexpanded状態のパターンに従うように設計されています。

UIオブジェクトにフォーカスを当てる

  3. ``````bash
  4. wp.customize.control( 'page_on_front' ).focus()
  5. `

フォーカス機能は、カスタマイザー内のパネル、セクション、およびコントロールへのディープリンクを実装するために使用されます。これらのURLを考慮してください：

  • …/wp-admin/customize.php?autofocus[panel]=widgets
  • …/wp-admin/customize.php?autofocus[section]=colors
  • …/wp-admin/customize.php?autofocus[control]=blogname

これは、カスタマイザー内のウィジェットパネルに直接リンクするためにウィジェット管理ページにリンクを追加するためにWordPressコアで使用され、カスタマイズプレビュー内の可視編集ショートカットをカスタマイザーペイン内の関連コントロールに接続します。

優先順位

PHPでパネル、セクション、またはコントロールを登録する際に、priorityパラメータを指定できます。この値は、それぞれのPanel、Section、およびControlインスタンスのwp.customize.Valueインスタンスに保存されます。たとえば、ウィジェットパネルの優先順位を取得するには： 

  1. priority = wp.customize.panel( 'widgets' ).priority(); // returns 110 by default

その後、優先順位を動的に変更すると、カスタマイザーUIは新しい優先順位を反映するように自動的に再配置されます： 

  1. wp.customize.panel( 'widgets' ).priority( 1 ); // move Widgets to the top

カスタムコントロール、パネル、およびセクション

JSでカスタムカスタマイザーオブジェクトを扱う場合、コード構造を理解するためにWordPressコアのカスタムオブジェクトを調べるのが最も簡単です。wp-admin/js/customize-controls.jsを参照し、特にwp.customize.Panel|Section|Controlモデルを確認してください。特にメディアコントロールのコアコードにいくつかの例があり、オブジェクト階層を通じてお互いの機能を構築しています。