首頁 >CMS教程 >＆＃＆按 >使用WordPress主題自定義器媒體控件

使用WordPress主題自定義器媒體控件

尊渡假赌尊渡假赌尊渡假赌原創: 2025-02-15 10:29:14328瀏覽

Using the WordPress Theme Customizer Media Controls

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

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

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

關鍵要點：

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

管理媒體控件的新基類

為什麼引入新類？

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

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

如何使用此媒體控件

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

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

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

基本用法

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

<code class="language-php">function add_my_media_controls($wp_customize) {
}
add_action('customize_register', 'add_my_media_controls');</code>

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

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

<code class="language-php">$wp_customize->add_section('sound', array(
    'title' => 'Sound',
    'description' => 'Add a sound to your website',
    'capability' => 'edit_theme_options'
));</code>

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

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

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

在創建控件之前，我們需要創建設置。

<code class="language-php">$wp_customize->add_setting('music', array(
    'type' => 'theme_mod',
    'capability' => 'edit_theme_options',
    'sanitize_callback' => 'absint'
));</code>

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

我們現在準備添加用戶可以看到的 UI 控件。

<code class="language-php">$wp_customize->add_control(new WP_Customize_Media_Control($wp_customize, 'music', array(
    'section' => 'sound',
    'label' => 'Music',
    'mime_type' => 'audio'
)));</code>

要構建 WP_Customize_Media_Control 對象，需要三個參數：當前主題定制器實例、相應設置的 ID（我們剛剛在上面創建的）和一個選項數組。

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

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

這就是創建控件的全部內容。現在您可以打開主題定制器：您應該會看到我們的部分和我們的控件。

檢索保存的設置

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

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

<code class="language-php">function add_my_media_controls($wp_customize) {
}
add_action('customize_register', 'add_my_media_controls');</code>

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

<code class="language-php">$wp_customize->add_section('sound', array(
    'title' => 'Sound',
    'description' => 'Add a sound to your website',
    'capability' => 'edit_theme_options'
));</code>

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

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

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

<code class="language-php">function add_my_media_controls($wp_customize) {
}
add_action('customize_register', 'add_my_media_controls');</code>

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

管理裁剪圖像

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

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

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

首先，我們創建我們的設置。由於我們將存儲媒體 ID，因此此設置與前面添加的音頻標籤基本相同。

<code class="language-php">$wp_customize->add_section('sound', array(
    'title' => 'Sound',
    'description' => 'Add a sound to your website',
    'capability' => 'edit_theme_options'
));</code>

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

<code class="language-php">$wp_customize->add_setting('music', array(
    'type' => 'theme_mod',
    'capability' => 'edit_theme_options',
    'sanitize_callback' => 'absint'
));</code>

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

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

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

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

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

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

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

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

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

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

<code class="language-php">function add_my_media_controls($wp_customize) {
}
add_action('customize_register', 'add_my_media_controls');</code>

結論

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

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

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

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

以上是使用WordPress主題自定義器媒體控件的詳細內容。更多資訊請關注PHP中文網其他相關文章！

php 封装构造函数回调函数字符串接口 using 对象数据库 ui WordPress

陳述：

本文內容由網友自願投稿，版權歸原作者所有。本站不承擔相應的法律責任。如發現涉嫌抄襲或侵權的內容，請聯絡admin@php.cn

上一篇：使用JetPack宣傳以簡化WordPress社交共享下一篇：使用JetPack宣傳以簡化WordPress社交共享

看更多

使用WordPress主題自定義器媒體控件

為什麼引入新類？

如何使用此媒體控件

基本用法

更多選項

檢索保存的設置

相關文章