WordPress 常用函数 / add_theme_support

简介

允许主题去支持特定的主题功能。

这个函数必须在主题的 functions.php 文件中去调用,如果想通过 hook 调用,则必须使用 after_setup_theme 这个 hook,因为 init hook 对于一些功能来说,已经太迟了。

用法

<?php add_theme_support( $feature ); ?>

参数

$feature
(string) (required) 要添加的主题功能的名称。
目前主题支持的功能列表:

  • 'post-formats'
  • 'post-thumbnails'
  • 'custom-background'
  • 'custom-header'
  • 'automatic-feed-links'
  • 'menus'

Default: None

返回值

实例

Post Formats

这个功能让主题支持 Post Formats 功能,这个功能是 3.1 版本引进的,当使用子主题(Child Themes)的时候,注意 add_theme_support( 'post-formats' ) 会覆盖父主题(Parent Themes)定义的 Formats,而不是额外增加。

让主题支持特定的 Post Formats,使用:

add_theme_support( 'post-formats', array( 'aside', 'gallery' ) );

检查一个主题是否给 post 指定了 'quote' 这类 post format:

if ( has_post_format( 'quote' ) ) {
	echo 'This is a quote.';
}

Post Thumbnails

这个功能让主题支持特色图片(Post Thumbnails),这个功能是 2.9 版本引进的,我们可以将日志类型(Post Type)数组作为第二个参数,来指定哪些日志类型要启用这个功能。

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 hook 之前调用,所以必须在主题的 functions.php 文件或者在 'after_setup_theme' hook 中调用。

对于自定义日志类型(custom post types),我们可以在使用 register_post_type() 注册新的日志类型的时候,添加 post thumbnails 的支持。

显示日志缩略图:

the_post_thumbnail();

使用之前检查是否已经设置日志缩略图:

if ( has_post_thumbnail() ) {
	the_post_thumbnail();
}

Custom Background

3.4 版本引进的功能,让主题支持定义背景。

add_theme_support( 'custom-background' );

设置默认背景的参数:

$defaults = array(
	'default-color'          => '',
	'default-image'          => '',
	'wp-head-callback'       => '_custom_background_cb',
	'admin-head-callback'    => '',
	'admin-preview-callback' => ''
);
add_theme_support( 'custom-background', $defaults );

Custom Header

也是 3.4 版本引进的,让主图支持自定义头图。

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' => '',
);
add_theme_support( 'custom-header', $defaults );

Feed Links

这个功能让 WordPress 自动在主题 head 添加 日志和留言的 RSS feed links。这个功能是在 3.0 版本引进的。

add_theme_support( 'automatic-feed-links' );

Multisite

To show the "Featured Image" meta box in multisite installation, make sure you update the allowed upload file types, in Network Admin, Network Admin Settings SubPanel#Upload_Settings, Media upload buttons options. Default is jpg jpeg png gif mp3 mov avi wmv midi mid pdf.

注解

下面这几个参数只是可读,主要用于 current_theme_supports() 中的判断,具体添加主题的功能请使用下面的方法代替:

修改记录

  • 3.4: 开始支持 'custom-background' 并废弃函数 add_custom_background().
  • 3.4: 开始支持 'custom-header' 并废弃函数 add_custom_image_header().
  • 3.1: 开始支持 'post-formats'.
  • 3.0: 开始支持 'automatic-feed-links' 并废弃函数 automatic_feed_links().
  • 2.9: 引入,并支持第一个功能:'post-thumbnails'

源文件

wp-includes/theme.php