WordPress 主題定制器媒體控件詳解：新增 WP_Customize_Media_Control 類

最近的 WordPress 更新改變了其 API。一些函數(shù)和類被添加，另一些則被棄用。本文將討論主題定制器媒體控件。在之前的版本中，這些控件是可用的，但僅限於 WP_Customize_Upload_Control 類?，F(xiàn)在我們發(fā)現(xiàn)了一個新的類來管理媒體，稱為 WP_Customize_Media_Control。

首先，我將介紹如何使用這個新類在主題定制器中管理媒體控件。然後，我們將介紹一個擴展 WP_Customize_Media_Control 的具體類示例，以允許控制裁剪圖像。

關(guān)鍵要點：

• WordPress 主題定制器媒體控件已更新，包含新的函數(shù)和類，包括新的 WP_Customize_Media_Control 類，它允許更好的媒體管理。
• WP_Customize_Media_Control 可用於允許用戶選擇一個音頻文件，該文件可在所有頁面上訪問。此控件可以添加到主題的 functions.php 文件或新的插件中。
• WP_Customize_Media_Control 可以擴展以添加更多功能，例如 WP_Customize_Cropped_Image_Control 類，它允許用戶在使用圖像之前選擇和裁剪圖像。
• 新的控件使主題定制器更加通用，允許開發(fā)者添加他們自己的媒體控件並檢索最有用的值：媒體 ID。此基類可以擴展為更具體的控件。

管理媒體控件的新基類

為什麼引入新類？

在 4.3 版本之前，WordPress 為我們提供了 WP_Customize_Upload_Control，這是一個在主題定制器中管理媒體文件上傳的類。但是，此類不保存上傳媒體的 ID，而只保存其 URL。由於 ID 是檢索有關(guān)媒體文件信息的更常用方法，因此決定提供一個新類 WP_Customize_Media_Control。

如果您習(xí)慣使用 WP_Customize_Upload_Control，您仍然可以使用它，沒有任何問題，因為它現(xiàn)在擴展了 WP_Customize_Media_Control 類，因此確保了兼容性。但是，更新您的代碼並使用 WP_Customize_Media_Control 肯定是一個更好的主意。

如何使用此媒體控件

此新的媒體控件的使用方式與其前身相同，除了保存的值。因為它不再是 URL，所以不能以相同的方式進行清理。

為了了解如何使用此控件，我們將回顧一個具體的示例。我們將看到如何讓用戶選擇一個音頻文件，訪問者可以在所有頁面上收聽。您可以將代碼寫入主題的 functions.php 文件或新的插件中。兩者都可以接受，並且這兩種選擇各有其自身的優(yōu)勢。

請注意，由於主題定制器 API 不是本文的主要重點，因此我不會在此處描述我們將調(diào)用的函數(shù)的所有可用選項。

基本用法

首先，我們從一個 WordPress 函數(shù)開始，當(dāng)用戶想要顯示主題定制器時，WordPress 將調(diào)用此函數(shù)。此函數(shù)會將我們的自定義元素添加到此定制器中。為了告知 WordPress 我們希望它在正確的時間調(diào)用我們的函數(shù)，我們使用 customize_register 動作。

function add_my_media_controls($wp_customize) {
}
add_action('customize_register', 'add_my_media_controls');

參數(shù)（此處命名為 $wp_customize）是一個表示主題定制器的對象。它包含添加設(shè)置所需的所有方法。

由於沒有默認部分真正適合添加我們的自定義聲音，我們將添加我們自己的部分，簡單地命名為“聲音”。

$wp_customize->add_section('sound', array(
    'title' => 'Sound',
    'description' => 'Add a sound to your website',
    'capability' => 'edit_theme_options'
));

如預(yù)期的那樣，此方法創(chuàng)建一個名為“聲音”的新部分。當(dāng)用戶打開它時，他們會在頂部看到說明。由於第三個選項，只有已經(jīng)可以編輯主題選項的用戶才能看到此部分。最後，請注意數(shù)組選項之前的第一個參數(shù)：它定義了部分的 ID，當(dāng)我們想要在此部分添加控件時必須重用它。

如果您現(xiàn)在打開主題定制器，您將看不到此部分。這是正常的：WordPress 不顯示空部分，因此要看到它，我們必須用至少一個控件填充它。

主題定制器 API 將控件分為兩部分：允許用戶選擇或鍵入正確數(shù)據(jù)的 UI 控件，以及檢索當(dāng)前值並保存新值的設(shè)置。將設(shè)置視為 UI 控件和數(shù)據(jù)庫之間的接口。

在創(chuàng)建控件之前，我們需要創(chuàng)建設(shè)置。

$wp_customize->add_setting('music', array(
    'type' => 'theme_mod',
    'capability' => 'edit_theme_options',
    'sanitize_callback' => 'absint'
));

我們將“music”指定為我們設(shè)置的 ID。它是一個主題修改，如第一個選項所示。 capability 選項與 add_section() 方法相同。最後，我們將 absint() 指定為清理回調(diào)函數(shù)。此 WordPress 函數(shù)是 abs(intval()) 的快捷方式，用於確保該值為正整數(shù)。正如我們上面看到的，WP_Customize_Media_Control 將存儲一個 ID，因此它正是我們想要用於清理值的函數(shù)。

我們現(xiàn)在準(zhǔn)備添加用戶可以看到的 UI 控件。

$wp_customize->add_control(new WP_Customize_Media_Control($wp_customize, 'music', array(
    'section' => 'sound',
    'label' => 'Music',
    'mime_type' => 'audio'
)));

要構(gòu)建 WP_Customize_Media_Control 對象，需要三個參數(shù)：當(dāng)前主題定制器實例、相應(yīng)設(shè)置的 ID（我們剛剛在上面創(chuàng)建的）和一個選項數(shù)組。

section 選項用於指示我們要放置控件的部分。我們在這裡使用我們專門為此用途創(chuàng)建的部分。然後我們指示字段的標(biāo)籤。您可以在這裡放置任何您想要的值。

最後，在這裡我們將為用戶提供一種選擇媒體文件的方法。因為我們希望他們只能選擇音頻文件，所以我們將音頻指定為所需的 MIME 類型。這樣，WordPress 將不允許選擇其他類型的文件。

這就是創(chuàng)建控件的全部內(nèi)容?，F(xiàn)在您可以打開主題定制器：您應(yīng)該會看到我們的部分和我們的控件。

更多選項

請注意，我們作為 WP_Customize_Media_Control 構(gòu)造函數(shù)的第三個參數(shù)提供的選項數(shù)組可以接受更多選項。

除了其標(biāo)籤外，您還可以通過 description 選項顯示有關(guān)控件的更多信息。實際上，通過為 description 選項提供非空字符串，您可以在標(biāo)籤下方顯示說明，例如，描述它將在哪裡顯示。

您可以通過 priority 選項設(shè)置其優(yōu)先級。此數(shù)字定義必須顯示對象的順序。默認情況下，優(yōu)先級設(shè)置為 10，並且對象按創(chuàng)建順序顯示。但是您可以更改它。例如，如果您創(chuàng)建兩個對象，您可以將第一個對象的優(yōu)先級設(shè)置為 10，將第二個對象的優(yōu)先級設(shè)置為 0：這樣，第二個對象將首先顯示。如果您插件或主題提供必須按特定順序顯示的多個控件，此選項可能很有用。

檢索保存的設(shè)置

為了檢索用戶保存的設(shè)置，我們將創(chuàng)建一個名為 echo_theme_sound() 的新函數(shù)。此函數(shù)將在您希望在主題中顯示的位置調(diào)用，以顯示對應(yīng)於所選媒體的音頻標(biāo)籤。

首先，請記住我們的設(shè)置是一個主題修改，因此要檢索其值，我們必須使用 get_theme_mod() 函數(shù)。

function add_my_media_controls($wp_customize) {
}
add_action('customize_register', 'add_my_media_controls');

如果用戶已經(jīng)做出選擇，則此變量將包含所選媒體的 ID。換句話說，要檢查是否已做出選擇，我們只需要檢查此 ID 是否不同於零。

$wp_customize->add_section('sound', array(
    'title' => 'Sound',
    'description' => 'Add a sound to your website',
    'capability' => 'edit_theme_options'
));

要構(gòu)建音頻標(biāo)籤，我們將使用 wp_audio_shortcode()，它需要一個參數(shù)：一個選項數(shù)組，實際上將是標(biāo)籤的屬性。

此數(shù)組必須包含一個名為 src 的選項，它是音頻文件的 URL。要檢索此 URL，我們可以使用 wp_get_attachment_url() 和前面檢索到的 ID。如果您想使用其他屬性，您可以，但不是強制性的。有關(guān)可用屬性的更多信息，請參閱 WordPress Codex。

我們現(xiàn)在準(zhǔn)備顯示我們的音頻標(biāo)籤。我在這裡選擇將其封裝到一個 div 中，但您可以選擇另一個標(biāo)籤和另一種樣式。您甚至可以，例如，為您的 echo_theme_sound() 函數(shù)定義兩個參數(shù) $before 和 $after，以允許用戶提供在音頻標(biāo)籤之前和之後顯示的文本。

function add_my_media_controls($wp_customize) {
}
add_action('customize_register', 'add_my_media_controls');

現(xiàn)在，只需在任何您想要的地方調(diào)用 echo_theme_sound() 函數(shù)，然後享受結(jié)果！請注意，一旦您在一個主題文件中使用了此函數(shù)，您就可以在進行更改後直接看到您在主題定制器中所做的更改，而無需刷新頁面。

管理裁剪圖像

可以擴展 WP_Customize_Media_Control 以添加更多功能。如果您需要一個關(guān)於可以這樣添加哪些功能的具體示例，您可以在 WordPress Core 本身中找到一個，使用 WP_Customize_Cropped_Image_Control 類。

正如您從其名稱中猜測的那樣，當(dāng)您想要為用戶提供一種在使用圖像之前選擇和裁剪圖像的方法時，此類很有用。

在這裡，我們將使用它向當(dāng)前默認 WordPress 主題（Twenty Fifteen）添加一個小標(biāo)題圖像。我選擇將此圖像顯示在標(biāo)題頂部，網(wǎng)站標(biāo)題正上方，但是，再一次，您可以隨意放置它：本文的目標(biāo)只是展示新 API 的具體示例。

首先，我們創(chuàng)建我們的設(shè)置。由於我們將存儲媒體 ID，因此此設(shè)置與前面添加的音頻標(biāo)籤基本相同。

$wp_customize->add_section('sound', array(
    'title' => 'Sound',
    'description' => 'Add a sound to your website',
    'capability' => 'edit_theme_options'
));

然後，有趣的部分：控件本身。與 WP_Customize_Media_Control 的一個一樣，WP_Customize_Cropped_Image_Control 的構(gòu)造函數(shù)需要三個參數(shù)，這些參數(shù)完全相同：主題定制器實例、設(shè)置的 ID 和一個選項數(shù)組。

$wp_customize->add_setting('music', array(
    'type' => 'theme_mod',
    'capability' => 'edit_theme_options',
    'sanitize_callback' => 'absint'
));

在這裡，我沒有創(chuàng)建一個新的部分：我們重用了 WordPress 已經(jīng)用來提供控件的部分，允許用戶選擇背景圖像標(biāo)題。 label 選項是一個已經(jīng)知道的選項，您會對另外兩個選項更感興趣：width 和 height。

這些選項用於控制最終圖像的大小。用戶選擇他們想要的圖像，然後，一個圖形工具允許他們裁剪他們想要的圖像。 WordPress 將根據(jù)此選擇裁剪圖像並將裁剪後的圖像調(diào)整為您使用這些選項選擇的大小。

當(dāng)用戶裁剪圖像時，圖像比例的約束在這裡，他們不能選擇具有其他比例的圖像的一部分。但這可以改變。

實際上，此類提供了另外兩個選項：flex_width 和 flex_height。默認情況下，這兩個選項都設(shè)置為 false，並且您指示的尺寸給出的縱橫比是一個約束：用戶必須選擇具有相同比例的區(qū)域。

但是，如果您將其中一個選項設(shè)置為 true，則此約束將被刪除，並且用戶將能夠選擇具有任何比例的圖像的一部分。請注意，WordPress 仍然會將結(jié)果調(diào)整為您要求的大小，因此可能會發(fā)生變形。

使用 flex_width 和 flex_height 時，比例很重要。實際上，在一開始，WordPress 為用戶提供了一個默認的裁剪區(qū)域。此區(qū)域?qū)?yīng)於圖像中具有所需比例的最大可用區(qū)域（例如矩形中的最大可能正方形）。這將給我們在這裡所說的默認寬度和高度。

如果 flex_width 設(shè)置為 false，則用戶將無法選擇大於默認寬度的區(qū)域。如果您將此選項設(shè)置為 true，則此約束將被取消。對於 flex_height 也可以這樣說。

最後，如果 flex_width 和 flex_height 設(shè)置為 false（它們的默認值），並且如果用戶選擇與您在 width 和 height 選項中指示的尺寸完全相同的圖像，則將跳過裁剪步驟。

請注意，裁剪圖像不會改變原始圖像：將創(chuàng)建一個新的子媒體，其中包含裁剪後的圖像，並且原始文件保持不變。這樣，如果您的用戶需要在多個地方使用同一張圖像，他們就不必多次上傳同一張圖像。

檢索裁剪圖像的方法與我們之前用於檢索聲音的方法類似：我們使用 get_theme_mod() 獲取圖像 ID，使用 wp_get_attachment_url() 獲取其 URL。然後我們以我們想要的方式顯示它。在這裡，我選擇了最簡單的方法，通過回顯圖像。

function add_my_media_controls($wp_customize) {
}
add_action('customize_register', 'add_my_media_controls');

結(jié)論

通過這些新的控件，主題定制器變得越來越有趣，因為它允許開發(fā)者更容易地做更多的事情。現(xiàn)在，如果您在此定制器中需要媒體控件，您可以添加您自己的控件並檢索最有用的值：媒體 ID。

本文中看到的基類可以在您需要更具體的控件時進行擴展。這在 WordPress 核心中的多個地方都已完成：裁剪圖像控件擴展了 WP_Customize_Media_Control，而此類本身又被新的站點圖標(biāo) API 使用的控件擴展。這些只是您可以使用此 API 執(zhí)行的操作示例。

您可以使用主題或插件來使用主題定制器。但是，由於為我提供一個小插件更實用，您可以通過此鏈接找到一個。它結(jié)合了本文中看到的示例。

(此處應(yīng)插入常見問題解答部分，內(nèi)容與輸入文本中的FAQ部分一致)

以上是使用WordPress主題自定義器媒體控件的詳細內(nèi)容。更多資訊請關(guān)注PHP中文網(wǎng)其他相關(guān)文章！