使用主題自定義 API 創建 WordPress 主題選項

已發表: 2014-11-27

使用主題自定義 API 創建 WordPress 主題選項很容易。本文向您展示了它是如何完成的。

WordPress 主題定制 API 早在 2012 年就與 WordPress 3.4 一起發布。它向開發人員承諾一種添加豐富選項主題的標準化方式，並為用戶提供一種以用戶友好的方式調整其網站的方式。

對於用戶來說，前端主題定制器可以讓你快速改變網站的外觀，甚至獲得實時預覽。

這個項目的成功是值得商榷的，但它正在被改進並且正在獲得牽引力。它建立在堅實的基礎之上，沒有理由不開始使用它。

因此，讓我們看看如何使用 API 輕鬆地將設置添加到主題中。

以下是我們今天要介紹的內容：

建立我們的基礎
主題設置的組成部分
使用設置值
實時預覽
封裝在一個類中
更多選項

建立我們的基礎

自定義 API 的關鍵是WP_Customize_Manager類，可以通過$wp_customize對象訪問該類。我們將使用此類中定義的各種方法在其中添加設置部分和控件。

創建主題設置的推薦方法是將它們封裝在一個類中。在我們最初的示例中，我不會遵循此建議以確保清楚什麼是自定義 API 的一部分，什麼不是。我將使用基於類的實現來完成這篇文章。

讓我們首先在主題的functions.php文件中創建一個函數，這將允許我們將添加的內容包含在定制器中。該函數需要與customize_register.

主題設置的組成部分

如示例中所述，您添加到定制器的每個項目都包含三個部分：

必須創建一個部分來放置它。這個部分當然可能是預先存在的部分之一
必須在數據庫中註冊設置，並且
需要創建一個控件，用於操作定義的設置

如果控件和設置之間的分離看起來令人困惑，可以這樣想：當你創建一個設置時，你告訴 WordPress 確實有一個字體顏色設置，默認值為 #444444。這本身就意味著可以使用此設置。

但是，主題定制器需要知道如何操作此設置。您可以為其創建一個文本字段，用戶在其中手動輸入新顏色為“#ff9900”，但您也可以指定一個顏色控件，該控件將輸出一個顏色選擇器。在數據庫級別上，它仍然會歸結為十六進制顏色，但面向用戶的一面是不同的。

創建一個部分

add_section()用於創建部分。它有兩個參數，一個部分 slug 和一個參數數組。這是我如何為主題中的頁腳選項設置部分的示例。

其中大部分是不言自明的。但是請注意優先級！這決定了屏幕上部分的順序。我喜歡以幾十個單位增加我的選擇。如果我需要在兩個現有部分之間插入一個部分，我不需要重新索引所有內容，我可以將新的部分分配為 95。

請注意，部分為空時不會顯示。在顯示之前，您必須向它們添加設置和控件。

添加設置

使用add_setting()方法創建設置。它們也將 slug 作為第一個參數，將一組參數作為第二個參數。看看下面的例子，為我們上面的部分添加背景顏色。

我們可以在這裡添加很多選項，但現在就可以了。請注意，設置與部分無關。正如我所提到的，設置只是在 WordPress 中註冊。這取決於控件，這些控件與部分相關聯來操作它們。

創建控件

控件是使用add_control()方法放置的。這個方法接受一個 slug 和一個參數數組，或者它也可以接收一個專用的控制對象。控件對像用於更複雜的控件，例如顏色選擇器或文件上傳器。

以下是我創建修改頁腳背景顏色的控件的方法：

加載要點 bae424ed134eae6cbf25

我已將控制對像傳遞給add_control()方法。該對象應該通過傳遞$wp_customize像作為第一個參數、控件的唯一 ID 作為第二個參數和一個參數數組作為第三個參數來構造。

請注意，控件是所有內容的結合處。 section設置為我們創建的部分的 id， settings為設置的 id。

一旦所有三個都設置好，您應該能夠重新加載定制器並查看您的工作。

使用設置值

默認情況下，設置保存在 theme_mod 中。 Theme_mods 是設置 API 的替代方案，它們提供了一種處理特定主題設置的簡單方法。檢索設置值所需要做的就是使用get_theme_mod()函數並將設置的 id 傳遞給它。

讓我們通過掛鉤wp_head並使用我們保存的設置向我們的網站添加一些動態 CSS：

實時預覽

默認情況下不啟用設置的實時預覽。要使用它們，您必須做三件事：

將處理預覽的 Javascript 文件排入隊列
為設置添加實時預覽支持，以及
創建 Javascript 代碼來處理每個設置

將實時預覽腳本加入隊列

這一步唯一不尋常的是我們需要使用customize_preview_init ，並且我們必須確保在我們的腳本之前加載'jquery'和'customize-preview'。除此之外，它是一個標準的隊列，指向我們主題中的一個 javascript 文件：

為設置添加實時預覽支持

這很容易。在我們設置的參數中，我們需要定義一個transport鍵並將其值設置為postMessage 。讓我們修改之前的代碼：

創建 Javascript 代碼來處理每個設置

我們需要在 Javascript 中使用wp.customize()函數。這個函數的第一個參數應該是設置的id，第二個是回調函數。在內部，我們將一個函數綁定到設置的更改並編寫我們的代碼來處理更改。

我們只需要寫一行，使用這個複制粘貼模板來提高實時預覽的寫作速度：

封裝在一個類中

封裝在一個類中是一個好主意，因為它允許您編寫更好的函數名稱並使您的代碼更符合跨主題，如果您有多個主題在工作中。這是我為上面的示例所做的。

請注意，一切都完全相同，只是一些函數的名稱發生了變化，我們指的是類內部的方法，而不是散佈在我們的functions.php文件中的函數。