WordPress功能函数add_theme_support()

WordPress功能函数add_theme_support()，为给定的特性注册主题支持。

用法：

add_theme_support( string $feature, mixed $args )

描述

必须在主题的functions.php文件中调用才能工作。如果附加到一个钩子上，它必须是’ after_setup_theme ‘。init钩子对于某些特性来说可能太晚了。

使用示例:

add_theme_support( ‘title-tag’ );

add_theme_support( ‘custom-logo’, array(

‘height’ => 480,

‘width’ => 720,

) );

参数：

$feature

(string) (必需)要添加的特性。可能的核心价值包括:

‘admin-bar’

‘align-wide’

‘automatic-feed-links’

‘core-block-patterns’

‘custom-background’

‘custom-header’

‘custom-line-height’

‘custom-logo’

‘customize-selective-refresh-widgets’

‘custom-spacing’

‘custom-units’

‘dark-editor-style’

‘disable-custom-colors’

‘disable-custom-font-sizes’

‘editor-color-palette’

‘editor-gradient-presets’

‘editor-font-sizes’

‘editor-styles’

‘featured-content’

‘html5’

‘menus’

‘post-formats’

‘post-thumbnails’

‘responsive-embeds’

‘starter-content’

‘title-tag’

‘wp-block-styles’

‘widgets’

$args

(mixed) (可选) 与某些特性一起传递的额外参数。

返回

(void|false)成功时无效，失败时false。

更多信息

功能

帖子格式

这个特性支持主题的Post格式。使用子主题时，请注意

add_theme_support(“post-formats”)

将覆盖父主题定义的格式，而不是添加到它。

要启用特定的格式(参见Post格式支持的格式)，请使用:

add_theme_support( ‘post-formats’, array( ‘aside’, ‘gallery’ ) );

使用has_post_format()来检查是否有一个’ quote ‘格式分配给文章:

// In your theme single.php, page.php or custom post type

if ( has_post_format( ‘quote’ ) ) {

echo ‘This is a quote.’;

}

发布缩略图

这个特性使Post缩略图对主题的支持成为可能。注意，您可以选择传递第二个参数$args，它带有一个Post类型的数组，您希望为其启用该特性。

add_theme_support( ‘post-thumbnails’ );

add_theme_support( ‘post-thumbnails’, array( ‘post’ ) ); // Posts only

add_theme_support( ‘post-thumbnails’, array( ‘page’ ) ); // Pages only

add_theme_support( ‘post-thumbnails’, array( ‘post’, ‘movie’ ) ); // Posts and Movies

这个特性必须在’ init ‘钩子被触发之前被调用。这意味着它需要被直接放置在functions.php中或附加在’ after_setup_theme ‘钩子中的函数中。对于自定义文章类型，还可以使用register_post_type()函数添加文章缩略图。

要在themes .php或single.php或自定义模板中显示缩略图，请使用:

the_post_thumbnail();

要在显示之前检查是否有一个post缩略图分配给该post，使用:

if ( has_post_thumbnail() ) {

the_post_thumbnail();

}

自定义背景

这个特性启用了对主题的custom_background支持。

add_theme_support( ‘custom-background’ );

注意，你可以使用以下方式添加默认参数:

$defaults = array(

‘default-image’ => ”,

‘default-preset’ => ‘default’, // ‘default’, ‘fill’, ‘fit’, ‘repeat’, ‘custom’

‘default-position-x’ => ‘left’, // ‘left’, ‘center’, ‘right’

‘default-position-y’ => ‘top’, // ‘top’, ‘center’, ‘bottom’

‘default-size’ => ‘auto’, // ‘auto’, ‘contain’, ‘cover’

‘default-repeat’ => ‘repeat’, // ‘repeat-x’, ‘repeat-y’, ‘repeat’, ‘no-repeat’

‘default-attachment’ => ‘scroll’, // ‘scroll’, ‘fixed’

‘default-color’ => ”,

‘wp-head-callback’ => ‘_custom_background_cb’,

‘admin-head-callback’ => ”,

‘admin-preview-callback’ => ”,

);

add_theme_support( ‘custom-background’, $defaults );

自定义Header

这个特性启用了对主题的Custom_Headers支持。

add_theme_support( ‘custom-header’ );

注意，你可以使用以下方式添加默认参数:

$defaults = array(

‘default-image’ => ”,

‘random-default’ => false,

‘width’ => 0,

‘height’ => 0,

‘flex-height’ => false,

‘flex-width’ => false,

‘default-text-color’ => ”,

‘header-text’ => true,

‘uploads’ => true,

‘wp-head-callback’ => ”,

‘admin-head-callback’ => ”,

‘admin-preview-callback’ => ”,

‘video’ => false,

‘video-active-callback’ => ‘is_front_page’,

);

add_theme_support( ‘custom-header’, $defaults );

自定义Logo

这个特性是在Version_4.5中首次引入的，它支持主题的Theme_Logo。

add_theme_support( ‘custom-logo’ );

注意，你可以使用以下方式添加默认参数:

add_theme_support( ‘custom-logo’, array(

‘height’ => 100,

‘width’ => 400,

‘flex-height’ => true,

‘flex-width’ => true,

‘header-text’ => array( ‘site-title’, ‘site-description’ ),

) );

Feed Links

这个功能可以在头部自动提供帖子和评论的链接。这应该用来代替已弃用的automatic_feed_links()函数。

add_theme_support( ‘automatic-feed-links’ );

HTML5

这个特性允许对搜索表单、评论表单、评论列表、图片库和标题使用HTML5标记。

add_theme_support( ‘html5’, array( ‘comment-list’, ‘comment-form’, ‘search-form’, ‘gallery’, ‘caption’, ‘style’, ‘script’ ) );

标题标签

这个特性使插件和主题能够管理文档标题标签。这应该用来代替wp_title()函数。

add_theme_support( ‘title-tag’ );

定制选择性刷新小部件

该特性支持对定制器中管理的小部件进行选择性刷新。这个功能在WordPress 4.5中就可以使用了。有关选择性刷新的原因和方式的更多信息，请阅读对小部件实现选择性刷新支持。

add_theme_support( ‘customize-selective-refresh-widgets’ );

多点

要在多站点安装中显示“特色图片”元框，请确保您更新了允许上传的文件类型，在网络管理，网络管理设置子面板#Upload_Settings，媒体上传按钮选项。默认为jpg jpeg png gif mp3 mov avi wmv midi mid pdf。

其他笔记

下面的参数是只读的，只能在current_theme_supports()的上下文中使用:

使用register_sidebar()或register_sidebars()代替。

菜单:使用register_nav_menu()或register_nav_menus()代替。

编辑器风格:使用add_editor_style()代替。

来源：

文件: wp-includes/theme.php

function add_theme_support( $feature, …$args ) {

global $_wp_theme_features;

if ( ! $args ) {

$args = true;

}

switch ( $feature ) {

case ‘post-thumbnails’:

// All post types are already supported.

if ( true === get_theme_support( ‘post-thumbnails’ ) ) {

return;

}

/*

* Merge post types with any that already declared their support

* for post thumbnails.

*/

if ( isset( $args[0] ) && is_array( $args[0] ) && isset( $_wp_theme_features[‘post-thumbnails’] ) ) {

$args[0] = array_unique( array_merge( $_wp_theme_features[‘post-thumbnails’][0], $args[0] ) );

}

break;

case ‘post-formats’:

if ( isset( $args[0] ) && is_array( $args[0] ) ) {

$post_formats = get_post_format_slugs();

unset( $post_formats[‘standard’] );

$args[0] = array_intersect( $args[0], array_keys( $post_formats ) );

} else {

_doing_it_wrong( “add_theme_support( ‘post-formats’ )”, __( ‘You need to pass an array of post formats.’ ), ‘5.6.0’ );

return false;

}

break;

case ‘html5’:

// You can’t just pass ‘html5’, you need to pass an array of types.

if ( empty( $args[0] ) ) {

// Build an array of types for back-compat.

$args = array( 0 => array( ‘comment-list’, ‘comment-form’, ‘search-form’ ) );

} elseif ( ! isset( $args[0] ) || ! is_array( $args[0] ) ) {

_doing_it_wrong( “add_theme_support( ‘html5’ )”, __( ‘You need to pass an array of types.’ ), ‘3.6.1’ );

return false;

}

// Calling ‘html5’ again merges, rather than overwrites.

if ( isset( $_wp_theme_features[‘html5’] ) ) {

$args[0] = array_merge( $_wp_theme_features[‘html5’][0], $args[0] );

}

break;

case ‘custom-logo’:

if ( true === $args ) {

$args = array( 0 => array() );

}

$defaults = array(

‘width’ => null,

‘height’ => null,

‘flex-width’ => false,

‘flex-height’ => false,

‘header-text’ => ”,

‘unlink-homepage-logo’ => false,

);

$args[0] = wp_parse_args( array_intersect_key( $args[0], $defaults ), $defaults );

// Allow full flexibility if no size is specified.

if ( is_null( $args[0][‘width’] ) && is_null( $args[0][‘height’] ) ) {

$args[0][‘flex-width’] = true;

$args[0][‘flex-height’] = true;

}

break;

case ‘custom-header-uploads’:

return add_theme_support( ‘custom-header’, array( ‘uploads’ => true ) );

case ‘custom-header’:

if ( true === $args ) {

$args = array( 0 => array() );

}

$defaults = array(

‘default-image’ => ”,

‘random-default’ => false,

‘width’ => 0,

‘height’ => 0,

‘flex-height’ => false,

‘flex-width’ => false,

‘default-text-color’ => ”,

‘header-text’ => true,

‘uploads’ => true,

‘wp-head-callback’ => ”,

‘admin-head-callback’ => ”,

‘admin-preview-callback’ => ”,

‘video’ => false,

‘video-active-callback’ => ‘is_front_page’,

);

$jit = isset( $args[0][‘__jit’] );

unset( $args[0][‘__jit’] );

// Merge in data from previous add_theme_support() calls.

// The first value registered wins. (A child theme is set up first.)

if ( isset( $_wp_theme_features[‘custom-header’] ) ) {

$args[0] = wp_parse_args( $_wp_theme_features[‘custom-header’][0], $args[0] );

}

// Load in the defaults at the end, as we need to insure first one wins.

// This will cause all constants to be defined, as each arg will then be set to the default.

if ( $jit ) {

$args[0] = wp_parse_args( $args[0], $defaults );

}

/*

* If a constant was defined, use that value. Otherwise, define the constant to ensure

* the constant is always accurate (and is not defined later, overriding our value).

* As stated above, the first value wins.

* Once we get to wp_loaded (just-in-time), define any constants we haven’t already.

* Constants are lame. Don’t reference them. This is just for backward compatibility.

*/

if ( defined( ‘NO_HEADER_TEXT’ ) ) {

$args[0][‘header-text’] = ! NO_HEADER_TEXT;

} elseif ( isset( $args[0][‘header-text’] ) ) {

define( ‘NO_HEADER_TEXT’, empty( $args[0][‘header-text’] ) );

}

if ( defined( ‘HEADER_IMAGE_WIDTH’ ) ) {

$args[0][‘width’] = (int) HEADER_IMAGE_WIDTH;

} elseif ( isset( $args[0][‘width’] ) ) {

define( ‘HEADER_IMAGE_WIDTH’, (int) $args[0][‘width’] );

}

if ( defined( ‘HEADER_IMAGE_HEIGHT’ ) ) {

$args[0][‘height’] = (int) HEADER_IMAGE_HEIGHT;

} elseif ( isset( $args[0][‘height’] ) ) {

define( ‘HEADER_IMAGE_HEIGHT’, (int) $args[0][‘height’] );

}

if ( defined( ‘HEADER_TEXTCOLOR’ ) ) {

$args[0][‘default-text-color’] = HEADER_TEXTCOLOR;

} elseif ( isset( $args[0][‘default-text-color’] ) ) {

define( ‘HEADER_TEXTCOLOR’, $args[0][‘default-text-color’] );

}

if ( defined( ‘HEADER_IMAGE’ ) ) {

$args[0][‘default-image’] = HEADER_IMAGE;

} elseif ( isset( $args[0][‘default-image’] ) ) {

define( ‘HEADER_IMAGE’, $args[0][‘default-image’] );

}

if ( $jit && ! empty( $args[0][‘default-image’] ) ) {

$args[0][‘random-default’] = false;

}

// If headers are supported, and we still don’t have a defined width or height,

// we have implicit flex sizes.

if ( $jit ) {

if ( empty( $args[0][‘width’] ) && empty( $args[0][‘flex-width’] ) ) {

$args[0][‘flex-width’] = true;

}

if ( empty( $args[0][‘height’] ) && empty( $args[0][‘flex-height’] ) ) {

$args[0][‘flex-height’] = true;

}

}

break;

case ‘custom-background’:

if ( true === $args ) {

$args = array( 0 => array() );

}

$defaults = array(

‘default-image’ => ”,

‘default-preset’ => ‘default’,

‘default-position-x’ => ‘left’,

‘default-position-y’ => ‘top’,

‘default-size’ => ‘auto’,

‘default-repeat’ => ‘repeat’,

‘default-attachment’ => ‘scroll’,

‘default-color’ => ”,

‘wp-head-callback’ => ‘_custom_background_cb’,

‘admin-head-callback’ => ”,

‘admin-preview-callback’ => ”,

);

$jit = isset( $args[0][‘__jit’] );

unset( $args[0][‘__jit’] );

// Merge in data from previous add_theme_support() calls. The first value registered wins.

if ( isset( $_wp_theme_features[‘custom-background’] ) ) {

$args[0] = wp_parse_args( $_wp_theme_features[‘custom-background’][0], $args[0] );

}

if ( $jit ) {

$args[0] = wp_parse_args( $args[0], $defaults );

}

if ( defined( ‘BACKGROUND_COLOR’ ) ) {

$args[0][‘default-color’] = BACKGROUND_COLOR;

} elseif ( isset( $args[0][‘default-color’] ) || $jit ) {

define( ‘BACKGROUND_COLOR’, $args[0][‘default-color’] );

}

if ( defined( ‘BACKGROUND_IMAGE’ ) ) {

$args[0][‘default-image’] = BACKGROUND_IMAGE;

} elseif ( isset( $args[0][‘default-image’] ) || $jit ) {

define( ‘BACKGROUND_IMAGE’, $args[0][‘default-image’] );

}

break;

// Ensure that ‘title-tag’ is accessible in the admin.

case ‘title-tag’:

// Can be called in functions.php but must happen before wp_loaded, i.e. not in header.php.

if ( did_action( ‘wp_loaded’ ) ) {

_doing_it_wrong(

“add_theme_support( ‘title-tag’ )”,

sprintf(

/* translators: 1: title-tag, 2: wp_loaded */

__( ‘Theme support for %1$s should be registered before the %2$s hook.’ ),

‘<code>title-tag</code>’,

‘<code>wp_loaded</code>’

),

‘4.1.0’

);

return false;

}

}

$_wp_theme_features[ $feature ] = $args;

}