使用WordPress主题自定义器媒体控件

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 动作。

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

参数（此处命名为 $wp_customize）是一个表示主题定制器的对象。它包含添加设置所需的所有方法。

由于没有默认部分真正适合添加我们的自定义声音，我们将添加我们自己的部分，简单地命名为“声音”。

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

如预期的那样，此方法创建一个名为“声音”的新部分。当用户打开它时，他们会在顶部看到说明。由于第三个选项，只有已经可以编辑主题选项的用户才能看到此部分。最后，请注意数组选项之前的第一个参数：它定义了部分的 ID，当我们想要在此部分添加控件时必须重用它。

如果您现在打开主题定制器，您将看不到此部分。这是正常的：WordPress 不显示空部分，因此要看到它，我们必须用至少一个控件填充它。

主题定制器 API 将控件分为两部分：允许用户选择或键入正确数据的 UI 控件，以及检索当前值并保存新值的设置。将设置视为 UI 控件和数据库之间的接口。

在创建控件之前，我们需要创建设置。

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

我们将“music”指定为我们设置的 ID。它是一个主题修改，如第一个选项所示。capability 选项与 add_section() 方法相同。最后，我们将 absint() 指定为清理回调函数。此 WordPress 函数是 abs(intval()) 的快捷方式，用于确保该值为正整数。正如我们上面看到的，WP_Customize_Media_Control 将存储一个 ID，因此它正是我们想要用于清理值的函数。

我们现在准备添加用户可以看到的 UI 控件。

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

要构建 WP_Customize_Media_Control 对象，需要三个参数：当前主题定制器实例、相应设置的 ID（我们刚刚在上面创建的）和一个选项数组。

section 选项用于指示我们要放置控件的部分。我们在这里使用我们专门为此用途创建的部分。然后我们指示字段的标签。您可以在这里放置任何您想要的值。

最后，在这里我们将为用户提供一种选择媒体文件的方法。因为我们希望他们只能选择音频文件，所以我们将音频指定为所需的 MIME 类型。这样，WordPress 将不允许选择其他类型的文件。

这就是创建控件的全部内容。现在您可以打开主题定制器：您应该会看到我们的部分和我们的控件。

更多选项

请注意，我们作为 WP_Customize_Media_Control 构造函数的第三个参数提供的选项数组可以接受更多选项。

除了其标签外，您还可以通过 description 选项显示有关控件的更多信息。实际上，通过为 description 选项提供非空字符串，您可以在标签下方显示说明，例如，描述它将在哪里显示。

您可以通过 priority 选项设置其优先级。此数字定义必须显示对象的顺序。默认情况下，优先级设置为 10，并且对象按创建顺序显示。但是您可以更改它。例如，如果您创建两个对象，您可以将第一个对象的优先级设置为 10，将第二个对象的优先级设置为 0：这样，第二个对象将首先显示。如果您插件或主题提供必须按特定顺序显示的多个控件，此选项可能很有用。

检索保存的设置

为了检索用户保存的设置，我们将创建一个名为 echo_theme_sound() 的新函数。此函数将在您希望在主题中显示的位置调用，以显示对应于所选媒体的音频标签。

首先，请记住我们的设置是一个主题修改，因此要检索其值，我们必须使用 get_theme_mod() 函数。

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

如果用户已经做出选择，则此变量将包含所选媒体的 ID。换句话说，要检查是否已做出选择，我们只需要检查此 ID 是否不同于零。

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

要构建音频标签，我们将使用 wp_audio_shortcode()，它需要一个参数：一个选项数组，实际上将是标签的属性。

此数组必须包含一个名为 src 的选项，它是音频文件的 URL。要检索此 URL，我们可以使用 wp_get_attachment_url() 和前面检索到的 ID。如果您想使用其他属性，您可以，但不是强制性的。有关可用属性的更多信息，请参阅 WordPress Codex。

我们现在准备显示我们的音频标签。我在这里选择将其封装到一个 div 中，但您可以选择另一个标签和另一种样式。您甚至可以，例如，为您的 echo_theme_sound() 函数定义两个参数 $before 和 $after，以允许用户提供在音频标签之前和之后显示的文本。

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

现在，只需在任何您想要的地方调用 echo_theme_sound() 函数，然后享受结果！请注意，一旦您在一个主题文件中使用了此函数，您就可以在进行更改后直接看到您在主题定制器中所做的更改，而无需刷新页面。

管理裁剪图像

可以扩展 WP_Customize_Media_Control 以添加更多功能。如果您需要一个关于可以这样添加哪些功能的具体示例，您可以在 WordPress Core 本身中找到一个，使用 WP_Customize_Cropped_Image_Control 类。

正如您从其名称中猜测的那样，当您想要为用户提供一种在使用图像之前选择和裁剪图像的方法时，此类很有用。

在这里，我们将使用它向当前默认 WordPress 主题（Twenty Fifteen）添加一个小标题图像。我选择将此图像显示在标题顶部，网站标题正上方，但是，再一次，您可以随意放置它：本文的目标只是展示新 API 的具体示例。

首先，我们创建我们的设置。由于我们将存储媒体 ID，因此此设置与前面添加的音频标签基本相同。

$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 的构造函数需要三个参数，这些参数完全相同：主题定制器实例、设置的 ID 和一个选项数组。

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

在这里，我没有创建一个新的部分：我们重用了 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。然后我们以我们想要的方式显示它。在这里，我选择了最简单的方法，通过回显图像。

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

结论

通过这些新的控件，主题定制器变得越来越有趣，因为它允许开发者更容易地做更多的事情。现在，如果您在此定制器中需要媒体控件，您可以添加您自己的控件并检索最有用的值：媒体 ID。

本文中看到的基类可以在您需要更具体的控件时进行扩展。这在 WordPress 核心中的多个地方都已完成：裁剪图像控件扩展了 WP_Customize_Media_Control，而此类本身又被新的站点图标 API 使用的控件扩展。这些只是您可以使用此 API 执行的操作示例。

您可以使用主题或插件来使用主题定制器。但是，由于为我提供一个小插件更实用，您可以通过此链接找到一个。它结合了本文中看到的示例。

(此处应插入常见问题解答部分，内容与输入文本中的FAQ部分一致)

以上是使用WordPress主题自定义器媒体控件的详细内容。更多信息请关注PHP中文网其他相关文章！