カスタマイザーのペンマークと設定メニューを連携させる方法

はじめに
完成イメージ
実装手順
- 解説
まとめ

はじめに

WordPress のカスタマイザーには、プレビュー画面上にペンマークが表示され、クリックすると対応する設定項目が自動的に開く仕組みがあります。
この機能を正しく利用すると、「この部分の色を変えたい」「ここはどの設定で制御されているのか」を直感的に操作できるようになります。

しかし、カスタマイザーに設定を追加しただけでは、ペンマークは表示されません。
設定メニューとプレビュー画面を連携させるためには、Selective Refreshの設定が必要になります。

そこで、Cocoonを前提に、フッター背景色のカスタマイザー設定を例として、ペンマークとカスタマイザーのメニューを連携さます。

この記事では、この方法について説明します。

完成イメージ

実装手順

以下のコードをfunctions.phpに追加します。

add_action('customize_register', function ($wp_customize) {
  // フッター色設定用セクションを追加
  $wp_customize->add_section('cocoon_footer_color', [
    'title'    => 'フッター色設定',
    'priority' => 300,
  ]);

  // フッター背景色の設定
  $wp_customize->add_setting('footer_background_color', [
    'default' => '',
  ]);

  // カラーピッカーコントロールを追加
  $wp_customize->add_control(
    new WP_Customize_Color_Control(
      $wp_customize,
      'footer_background_color',
      [
        'label'    => 'フッター背景色',
        'section'  => 'cocoon_footer_color',
        'settings' => 'footer_background_color',
      ]
    )
  );

  // #footer要素にペンマークを表示
  $wp_customize->selective_refresh->add_partial(
    'footer_background_color',
    [
      'selector' => '#footer',                  // ペンが表示されるDOM
      'settings' => 'footer_background_color',  // 紐付くsetting
    ]
  );
}, 20);

解説

Selective Refreshによるペンマークの表示

フッターにペンマークを表示するためには、selective_refresh->add_partial()を使用します。
このとき重要なのは、ペンマークはselectorに直接付与されるのではなく、settingに対して付与されるという点です。

例えば、footer_background_colorというsettingに対してpartialを登録し、そのselectorとして #footerを指定することで、「この settingは#footer要素に影響する」という情報がカスタマイザーに伝わります。
その結果、プレビュー画面のフッター部分にペンマークが表示されるようになります。

ペンマークをクリックすると

該当するフッター背景色のカラーピッカーにフォーカスが当たる
カスタマイザーの左メニューが自動的に開く

ペンマークと設定が結びつく仕組み

プレビュー画面に表示されるペンマークには、内部的にcustomize-partial-edit-shortcut-footer_background_colorのようなクラスが付与されています。
このクラス名に含まれる footer_background_colorがsetting IDと一致しているため、WordPressは「どの設定を開くべきか」を認識できます。

まとめ

カスタマイザーのペンマークは、単に要素に付く装飾ではなく、settingを中心とした仕組みで動作しています。
setting、control、そして Selective Refreshを正しく組み合わせることで、プレビュー画面とカスタマイザーメニューを直感的に連携させることができます。
Cocoonをカスタマイズする際の参考として、ぜひ活用してみてください。