在項目中使用 Kirki 框架更快地構建定制器設置

已發表: 2019-08-10

Kirki 是一個免費的開源（MIT 許可）框架，專為希望將定制器控件添加到其主題或插件的開發人員而構建。

Kirki 的首席開發人員 Aristeides Stathopoulos 自 2014 年以來一直致力於該框架。由於不斷的更新和改進，Kirki 在 Github 上建立了一個社區，其中包括 1000 多個 star 和 300 個分叉。

在 Kirki 之前，我從未接觸過定制器。 Kirki 幫助我了解了定制器並在更短的時間內完成了很多工作！
LebCit – WordPress 主題開發者

WordPress 核心定制器控件

默認情況下，WordPress Core 包含一些基本的定制器控件。例如：文本、文本區域、複選框、單選、選擇、下拉頁面、電子郵件、URL、數字、隱藏和日期控件。

Kirki 也支持 Core Controls，另外還有大約 20 個。一般來說，Kirki 控件涵蓋了更高級的用例。例如：

排版
調色板
TinyMCE 編輯器
可排序字段

Kirki 還提供了 Core WordPress 中沒有的功能，例如自動生成 CSS 輸出和 postMessage 腳本。我們將在本文後面介紹的這些功能可以輕鬆地將您的開發時間縮短一半。

柯基很慢

對 Kirki 的普遍批評之一是它的速度很慢。事實上，這種批評適用於大多數框架（包括 WordPress）。這是有道理的，對吧？您正在加載很多您可能永遠不會使用的代碼。

在這種情況下，現實情況恰恰相反。大多數情況下，使用 Kirki 構建的控制面板實際上會比使用 Core Controls 構建的相同面板更快。

這是因為 Kirki 添加了一個 WordPress 未內置的優化層。

當定制器被初始化時，WordPress 會立即嘗試加載所有控件，即使它們在一個部分或面板中並且用戶還不能與它們交互。相比之下，Kirki 將加載推遲到用戶與控件交互之前。

要查看實際效果，讓我們嘗試使用每種方法添加 50 個顏色控件。

核心方法：

 對於 ($i = 0; $i < 50; $i++){
	$wp_customize->add_setting( 'color_setting_hex_' . $i , array(
		'默認' => '#0088CC'
	));

	// 添加顏色選擇器控件
	$wp_customize->add_control（新 WP_Customize_Color_Control（$wp_customize，'color_setting_hex_'。$i，數組（
		'標籤' => '顏色控制',
		'section' => 'title_tagline',
		'設置' => 'color_setting_hex_' 。 $i,
	) ) );
}

與柯基：

 對於 ($i = 0; $i < 50; $i++) {
     Kirki::add_field('config_id', array(
         '類型' => '顏色',
         '設置' => 'color_setting_hex_' 。 $i,
         '標籤' => __( '顏色控制', 'kirki' ),
         'section' => 'title_tagline',
         '默認' => '#0088CC',
     ));
 }

結果：

如您所見，使用 Kirki 時初始加載速度要快得多。創建控件所需的代碼也更簡潔。

將 Kirki 集成到您的項目中

有多種方法可以將 Kirki 框架集成到您的項目中，官方文檔很好地解釋了不同的方法。

我建議開發人員指導用戶安裝 Kirki 的插件版本，而不是直接在項目代碼中包含框架。這可以使用 TGMPA 或提供的腳本來完成。

採用插件路線的原因是 Kirki 經常更新和改進。通過安裝插件版本，您的用戶將可以即時訪問錯誤修復和安全更新。

相反，當您將框架作為項目的一部分包含在內時，用戶只會在您更新主題或插件時收到更新，這可能比要求的頻率低。

無論您使用哪種方法，請務必在添加設置之前檢查 Kirki 是否已初始化：

 // 如果 Kirki 不存在，則提前退出。
如果（！class_exists（'Kirki'））{
    返回;
}

字段

在核心方法示例中，我們首先創建了一個設置，然後為它創建了一個控件。在大多數情況下，兩者是直接相關的。 Kirki 簡化了流程，並允許我們創建一個“字段”。創建字段時，它會在後台為我們構建設置和控件。

字段支持您期望的所有控制參數（標籤、描述、部分、默認），以及一些特定於 Kirki 的參數。

'type' 參數允許您選擇 Kirki 的 30 種控件類型之一：https://kirki.org/docs/controls/

部分

定制器部分允許您將控件組合在一起。 WordPress 有六個內置部分，您也可以添加控件：

title_tagline – 網站標識
顏色 – 顏色
header_image - 標題圖像
background_image - 背景圖像
static_front_page – 主頁設置
custom_css – 附加 CSS

Kirki 中的部分與 Core 中的工作方式完全相同，Kirki::add_section() 方法只是 $wp_customize->add_section() 的包裝器，並接受相同的參數和參數。

 Kirki::add_section('section_id', array(
     'title' => esc_html__('我的部分', 'kirki' ),
     'description' => esc_html__('我的部分描述', 'kirki' ),
 ));

面板

面板允許您通過將部分組合在一起來創建另一個層次結構。 WordPress Core 有一個內置面板，即“菜單”。

同樣，Kirki 實現只是核心功能的包裝器。

 Kirki::add_panel('panel_id', array(
     '優先級' => 10,
     'title' => esc_html__('我的面板', 'kirki' ),
     'description' => esc_html__('我的面板描述', 'kirki' ),
 ));

'運輸' => '汽車'

傳統上，在創建定制器控件時，傳輸參數有兩個選項：

刷新– 每次用戶進行更改時，預覽窗格都會刷新以顯示更改。這可能需要幾秒鐘。
postMessage – 每次用戶進行更改時，預覽窗格都會使用 Javascript 進行更新，該 Javascript 不需要刷新並且幾乎是即時的。

postMessage 無疑是更新預覽器的最佳方法，應盡可能使用。但是，有一個缺點，使用 postMessage 意味著您需要為每個控件創建編寫自定義 JS 代碼。一個簡單的實現如下所示：

 // 實時更新站點標題...
wp.customize（'博客名稱'，函數（值）{
    value.bind(函數(newval){
        $( '#site-title a' ).html( newval );
    });
});

當您有很多設置時，這很快就會變得重複。

這就是 Kirki 的亮點，它增加了第三個選項：'transport' => 'auto'。

'transport' => 'auto' 與 Kirki 添加的另一個名為 'output' 的參數一起使用。定義這兩個值後，Kirki 將為您自動生成 postMessage 腳本。這意味著您無需編寫任何 Javascript 代碼即可獲得使用 postMessage 的所有好處。

使用 transport => 'auto' 的字段如下所示：

 Kirki::add_field('config_id', array(
     '類型' => '顏色',
     '設置' => 'color_setting_hex',
     '標籤' => __( '顏色控制', 'kirki' ),
     '部分' => '顏色',
     '默認' => '#0088CC',
     '運輸' => '汽車',
     '輸出' => 數組（
         大批（
             '元素' => '身體',
             '屬性' => '背景色',
         ),
     ),
 ));

Kirki 的這一省時特性意味著大多數時候您將不再需要編寫或將您自己的 postMessage 腳本排入隊列。

前端 CSS 輸出

創建定制器設置的另一部分是在前端生成 CSS 輸出。一個簡單的示例可能如下所示：

 /**
 * 將定制器 CSS 輸出到 wp_head
 */
功能 wptavern_customizer_css() {
	$bg_color = get_theme_mod('color_setting_hex');
	?>
	<風格>
		身體 {
			背景顏色：<?php echo sanitize_hex_color( $bg_color ); ?>;
		}
	</style>
	<?php
}
add_action('wp_head', wptavern_customizer_css);

與 postMessage 示例一樣，如果您有很多設置，編寫此代碼很快就會變得重複。

幸運的是，'transport' => 'auto' 也為您處理前端輸出。即使在我們的簡化示例中，'transport' => 'auto' 也將我們需要編寫的代碼減少了約 50%。

結論

在本文中，我們只了解了 Kirki 框架的基礎知識及其兩個論點，我們已經可以看到它如何讓我們更快地創建自定義控件而不影響性能。

當您深入了解 Kirki 時，您會很快發現它在自定義 API 之上添加的豐富功能。毫不奇怪，它已在超過 300,000 個網站上使用，並且是市場上一些最大的 WordPress 主題的核心部分。