如何在您自己的主题中利用主题定制器

一个比较老的教程了，但仍然具有参考性

来源于：

http://ottopress.com/2012/how-to-leverage-the-theme-customizer-in-your-own-themes/

注意：我在这里谈论的所有内容，包括代码，都处于测试模式。它可能会有所变化。我将在发布后更新此帖子，以修复从现在到现在之间可能发生的任何代码更改。我现在正在发布这篇文章，以便主题作者可以开始查看他们的主题并思考他们可能希望如何改变他们选择页面的方式。

因此，WordPress 3.4具有您在主题选择页面上可以找到的这个漂亮的新功能。它是标有“Customize”的每个主题旁边的链接。这是新的主题定制器，它很酷。

事实上，你无法看到它用简单的图片做什么，所以这是一个视频。如果你想全屏显示，它可以高清使用。

所以，现在你知道它做了什么，如果你是一个主题作者，你可能只是得到了一些好主意。以下是如何在主题中实现这些想法。

首先，请注意，如果您已经支持WordPress核心提供的内置自定义标题和自定义背景功能，那么这些功能将神奇地显示并在主题定制器中工作。您无需额外的代码。

现有选项

现在，您可能要做的第一件事就是记下主题中现有设置的工作方式。实际上，主题设置有三个主要选项。我会简要地回顾一下。

1.“主题模式”。这使用set_theme_mod和get_theme_mod函数。很少有主题实际使用这些，因为我写了关于Settings API，但它就在那里，如果你正常使用它们，那么主题定制器支持它（事实上它是默认值）。

2.个人设置。如果将主题的设置作为单独的行存储在选项表中，每个设置一个，则可以使用自定义程序。然而，这不是主题中的首选方式，而不是最常见的方式。不过，有些主题会这样做，所以如果你是其中之一，它也会得到支持。

3.序列化设置。这是我在我的设置API教程和主题评论指南推荐的方法中解释的方式，以及Chip在他自己的主题设置教程中描述的方式。实质上，您将设置存储在数组中，然后使用set_option或get_option将该数组存储为数据库中的一行。支持此方法，这是我在本文中主要介绍的方法。我会在适当的时候简要提及其他两种方法。

一旦您知道如何存储设置，您就会知道在代码中的某些位置填写什么。当我们到达它时，更多关于这一点。

面向对象

现在，主题定制器非常面向对象，虽然您不一定需要理解它来实现它的基础知识，但如果您打算完全自定义，则可能需要了解它。只是一个警告。

首先，我们将查看定制器屏幕的左侧。请注意，左侧分为几个部分。实际上，这就是他们的名字：WP_Customize_Section。在这些部分的每一部分中都有一个或多个控件; 或者更确切地说，WP_Customize_Control。最后，每个控件都控制页面上的一个或多个设置：aka WP_Customize_Setting。

部分组织控件。控件获取输入并将其传递给设置。“设置”界面与主题中的现有选项。

要在这里为自己的自定义选项创建新内容，您需要知道在哪里添加它。那个地方是customize_register动作钩子。

add_action( 'customize_register', 'themename_customize_register' );
function themename_customize_register($wp_customize) {
    // ... do stuff ...

该函数获取主$ wp_customize对象的参数。这是接口点，您可以在其中执行所有操作，例如添加节和控件等。

第

所以，首先要做的是添加一个部分。这是一种方法：

$wp_customize->add_section( 'themename_color_scheme', array(
    'title'          => __( 'Color Scheme', 'themename' ),
    'priority'       => 35,
) );

第一个参数是稍后您需要的部分的唯一ID（当您将控件放入其中时）。第二个参数是该部分的选项数组。真的，章节没有很多选择。您可以给他们一个标题，如果您需要一些解释性文字，可以给他们一个“描述”。优先级设置确定其在列表中的顺序。

如果您有特殊情况，您还可以为章节提供“能力”。一般来说，大多数网站都需要“edit_theme_options”功能让用户编辑此类内容，这是这些部分使用的默认功能。但是，如果您有任何人可以编辑的选项，或者只应由管理员管理的选项，则更改此功能将阻止该部分显示给无论如何都无法更改这些设置的用户。

您可以添加到部分的最后一件事是“theme_supports”选项。除非主题支持，否则这将使菜单不显示。如果你把这个代码放在一个主题本身，那么你已经知道主题支持什么，所以它没有多大意义。如果主题不支持它，核心使用它来不显示标题和背景选项。

设置

接下来，让我们配置一些设置。是的，设置，而不是控件。请注意，控件需要知道它们正在更改的设置，因此我们必须首先附加设置。

要声明设置，您可以这样做：

五

$wp_customize->add_setting( 'themename_theme_options[color_scheme]', array(
    'default'        => 'some-default-value',
    'type'           => 'option',
    'capability'     => 'edit_theme_options',
) );

在这种情况下，我已经声明我感兴趣的设置在一个选项中，该选项在数据库中被命名为“themename_theme_options”，并且它被序列化，并且其中的实际数组键是“color_scheme”。还记得我们之前关于Settings API以及如何存储设置的演讲吗？这是方法3。

这是方法2（每个数据库条目一个选项）：

五

$wp_customize->add_setting( 'themename_color_scheme', array(
    'default'        => 'some-default-value',
    'type'           => 'option',
    'capability'     => 'edit_theme_options',
) );

这里的方法1（使用theme_mod）：

五

$wp_customize->add_setting( 'color_scheme', array(
    'default'        => 'some-default-value',
    'type'           => 'theme_mod',
    'capability'     => 'edit_theme_options',
) );

此设置基本上告诉主题自定义程序存储选项的位置，以及如何更改其值，以便使用更改的选项显示主题。

以下是关于此的好处：您告诉主题定制器选项的位置。您不必更改现有选项的工作方式。

你已经有了一个主题选项页面，对吗？所以，不知何故，你正在保存这些选项。在主题中，它使用get_theme_mod或get_option读取这些选项，对吧？主题定制器的工作方式是使用过滤器拦截该调用，仅更改预览器大小写的选项，然后将新选项传递给主题。因此，主题不知道它获得的值不在数据库中，而是用户刚刚选择的值。这是一个神奇的技巧，为什么主题不必大幅改变以支持这种事情。他们制作自定义部分所需要做的就是告诉主题自定义程序代码他们使用的选项和方式，并直接为预览器更改这些选项。

（注意这里的说明：上面的“默认”设置应该是默认值，而不是当前值。差异是一个微妙的，但重点是你实际上不需要从中获取选项的当前值数据库并将其放在这里.WP_Customize_Setting为您处理所有爵士乐。如果数据库中根本不存在该值，则应使用“默认”。）

add_setting调用还有一点，我将在稍后解释postMessage时再回来。

控制

最后，我们来控制。显然，控件可以看起来很多种方式之一。最简单的控件只是复选框或文本字段。但是，颜色会发生很大的变化，所以也有色轮控制。事实上，WordPress定义了许多可能的控件。我们来看几点：

收音机选择：

$wp_customize->add_control( 'themename_color_scheme', array(
    'label'      => __( 'Color Scheme', 'themename' ),
    'section'    => 'themename_color_scheme',
    'settings'   => 'themename_theme_options[color_scheme]',
    'type'       => 'radio',
    'choices'    => array(
        'value1' => 'Choice 1',
        'value2' => 'Choice 2',
        'value3' => 'Choice 3',
        ),
) );

很简单。它引用了它所在的部分，它将要改变的设置，然后它具有无线电类型和选择列表及其相关值。

如何改为复选框呢？这个直接来自核心：

$wp_customize->add_control( 'display_header_text', array(
    'settings' => 'header_textcolor',
    'label'    => __( 'Display Header Text' ),
    'section'  => 'header',
    'type'     => 'checkbox',
) );

复选框打开或关闭，true或false。它不需要真正的价值观。

选择下拉框怎么样？这是一个例子：

$wp_customize->add_control( 'example_select_box', array(
    'label'   => 'Select Something:',
    'section' => 'nav',
    'type'    => 'select',
    'choices'    => array(
        'value1' => 'Choice 1',
        'value2' => 'Choice 2',
        'value3' => 'Choice 3',
        ),
) );

默认的控件类型实际上是type ='text'，它会创建一个文本框控件。另一种类型的控件是“下拉页面”类型，它创建WordPress页面的下拉列表。

但这不是全部。实际上还有几个，但因为它们是如此习俗，它们被宣布不同。这是我们在ya上获得所有面向对象的地方......

$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'link_color', array(
    'label'   => __( 'Link Color', 'themename' ),
    'section' => 'themename_color_scheme',
    'settings'   => 'themename_theme_options[link_color]',
) ) );

哇，新课程怎么样？WP_Customize_Color_Control是一个扩展内置WP_Customize_Control类的类。它将色轮爵士乐添加到需要选择颜色的地方。请注意，这里的类是使用new创建的，因此它必须直接传递给它的$ wp_customize，因此它知道在哪里挂钩。（注意：这可能会在最终的3.4版本之前发生变化。）

其他控制措施：

WP_Customize_Upload_Control - 这为您提供了一个允许文件上传的上传框。但是，您可能不会直接使用它，您可以将其扩展为其他内容...例如：
WP_Customize_Image_Control - 这给出了图像选择器和上传器框。它扩展了上传控制器。您可以在自定义背景片上看到它，用户可以将新文件上传为背景图像。
WP_Customize_Header_Image_Control - 由于头文件的大小调整操作，它需要一些特殊处理和显示，因此WP_Customize_Header_Image_Control扩展了WP_Customize_Image_Control以添加该功能。您可以在自定义标题片上看到它，用户可以将新文件上传为标题图像。

因此，创建自定义控制器以执行任何操作的方法是创建自己的新类，它扩展了WP_Customize_Control并添加了您想要的位。如何做到这一点有点复杂，所以我将保存为另一个教程。目前，您已经拥有图像处理，色轮，文本框，收音机，下拉菜单和复选框。我认为应该足够开始。

教程结束？

不完全的。我上面所做的一切都足以向定制器中添加新的部分，将控件放入其中，然后在页面刷新后稍微延迟后让预览显示您的更改。您所要做的就是在适当的位置使用适当的参数调用这些函数，它将起作用。

但请注意，我说“当页面刷新时”......来吧......这是2012年。我们没有飞行汽车，我们还要等一两秒钟？

不。

输入postMessage

回到我提到$ wp_customize-> add_setting函数调用时，我提到“再多一点”。再多一点是称为“运输”的选项。

传输定义设置更改从您将其更改为预览窗格的位置。默认设置为“刷新”。另一种设置名为“postMessage”。

postMessage传输使得设置立即发送到另一帧，javascript可以使用这些新信息即时调整页面。

一个例子：

假设我们有一个设置来改变标题的颜色。页面上的所有标题都在某些标签中，或许有一类字幕。该选项通常只保存所选的HTML颜色，然后在header.php中输出一些内联CSS基本上这样做：

.posttitle {
    color: #abcdef;
}

或者无论该颜色实际上是什么选项。

我们已经将我们的设置挂钩到该选项，并将我们的WP_Customize_Color_Control挂钩到它，现在当我们更改它时，它可以工作，我们可以看到颜色变化。请注意，这对于已经正常工作的自定义程序选项来说是最容易的，因此最好的方法是首先使其正常工作，然后再添加下一位。

现在，我们在自定义程序中有工作选项，因此为了消除刷新延迟，我们将这个新选项添加到add_setting调用：

'transport'         => 'postMessage',

这告诉定制器该设置将通过javascript直接发送到帧。但是，要使该设置生效，我们需要在框架中使用javascript来接收它。

所以，回到我们的主要功能......还记得吗？它开始是这样的：

add_action( 'customize_register', 'themename_customize_register' );
function themename_customize_register($wp_customize) {
    // ... do stuff ...

在该函数结束时，我们将添加以下代码：

if ( $wp_customize->is_preview() && ! is_admin() )
    add_action( 'wp_footer', 'themename_customize_preview', 21);

这将为我们的预览框架的页脚添加一个新的函数调用。它只会添加预览框，因此实时网站和其他人不会看到它，因为他们不需要看到它。这是我们将输出我们的javascript以实现实时发生的地方。

这是我们的功能：

function themename_customize_preview() {
    ?>
    <script type="text/javascript">
    ( function( $ ){
    wp.customize('setting_name',function( value ) {
        value.bind(function(to) {
            $('.posttitle').css('color', to ? to : '' );
        });
    });
    } )( jQuery )
    </script>
    <?php 
}

如你所见，它只输出一些javascript。这段代码不会有太大变化，所以让我们重点介绍两件事：

'setting_name'是设置的名称，由$ wp_customize-> add_setting调用添加。
以jQuery（'.posttitle'）开头的整行是我们的自定义代码。它获取“to”变量，它将是用户选择的颜色，并使用jquery的css修改功能将页面上的字幕设置为具有该颜色。

那些是你需要改变的唯一两个，真的。剩下的就是漂亮的意大利面。对于每个实时设置，您可以在脚本中填写这段代码。

这是另一回事：您可以将预先存在的刷新设置更改为postMessage。例如，在“标题”部分中获取“站点标题”和“标语”元素。这些是刷新设置，原因是每个主题以不同方式实现它们。核心无法知道任何特定主题所需的javascript代码。

但如果你是一个主题作者，那么你就不是在写一个通用主题。你是为你的特定主题而写的。您知道如何显示网站标题和标语。没有理由你不能实时进行这些更新。当你在它的时候，header_textcolor设置也可以是实时的，因为你知道主题代码。

在您的main函数中，添加以下三行代码：

$wp_customize->get_setting('blogname')->transport='postMessage';
$wp_customize->get_setting('blogdescription')->transport='postMessage';
$wp_customize->get_setting('header_textcolor')->transport='postMessage';

这会将这些核心设置上的传输更改为postMessage。现在您需要添加javascript代码以实际在主题中进行刷新。这是TwentyEleven这样做的一个例子（我为它写的补丁）：

function twentyeleven_customize_preview() {
    ?>
    <script type="text/javascript">
    ( function( $ ){
    wp.customize('blogname',function( value ) {
        value.bind(function(to) {
            $('#site-title a').html(to);
        });
    });
    wp.customize('blogdescription',function( value ) {
        value.bind(function(to) {
            $('#site-description').html(to);
        });
    });
    wp.customize( 'header_textcolor', function( value ) {
        value.bind( function( to ) {
            $('#site-title a, #site-description').css('color', to ? to : '' );
        });
    });
    } )( jQuery )
    </script>
    <?php
}

对于blogname，它会更改“＃site-title a”链接中的HTML。对于描述，它使用#sitedescription更改标记。对于那些颜色，它只是针对它们并改变它们的CSS。

Core必须尝试在所有主题中都是通用的。但是主题更多地了解它们的工作方式，并且能够以更好的方式改变目标。添加控件的主题知道这些控件会发生什么变化，所以如果它像CSS一样简单，甚至像HTML这样复杂的东西，如果你可以编写javascript代码来实时修改，那么你可以使用postMessage并消除刷新延迟。

希望这能解释一些主题定制器。它像泥一样清澈吗？看看我对Twenty Eleven的补丁，将现有选项屏幕中的一些主题选项添加到定制器中。您可以在此门票上找到它：http：//core.trac.wordpress.org/ticket/20448。