WordPress add_theme_support()函数详解

WordPress,

今天是在修改WordPress自带主题twentytwelve发现了这个函数----add_theme_support()，收集、整理如下：

1、函数描述

允许 WordPress 主题或插件 给当前正在使用的主题注册一些特色功能，如果在主题中使用，应该将该函数写入 function.php 文件中，如果是在插件中使用该函数，那它必须挂在钩子上（HOOK），如果是挂在钩子上，那他必须挂在”after_setup_theme”钩子上，如果是在init系列上将会太晚，以致部分特色功能将失效。
大概解释就是这样，神啊，原谅我那卑微的英文和卑劣的中文语法吧。

2、使用方法

<?php add_theme_support( $feature ); ?>

参数、变量

可供 $feature 变量使用的参数有以下几个。

  1. ‘post-thumbnails’ —– 增加缩略图支持
  2. automatic-feed-links’ 自动输出RSS
  3. ‘post-formats’—– 增加文章格式功能
  4. ‘custom-background’—– 增加自定义背景
  5. ‘custom-header’—– 增加自定义顶部图像
  6. 'menus'——激活自定义导航菜单
  7. 'html5'——能允许搜索形式，评论形式，评论列表，画廊和标题的HTML5标记的使用
  8. 'title-tag'——使插件和主题来管理文档标题标记。这应该是用在wp_title()功能的地方
  9. 'editor-style' (internal registrations not used directly by themes)
  10. 'widgets' (internal registrations not used directly by themes)

也就是说你可以像如下那样使用

add_theme_support( 'post-thumbnails' );
add_theme_support( 'automatic-feed-links' );
add_theme_support( 'post-formats', array( 'aside', 'gallery', 'chat', 'image', 'link', 'quote', 'status', 'video', 'audio' ) ); //如果是微博体的话，就选 status 好了
add_theme_support( 'custom-background' );
add_theme_support( 'custom-header' );
add_theme_support( 'html5', array( 'comment-list', 'comment-form', 'search-form', 'gallery', 'caption' ) );
add_theme_support( 'title-tag' );
add_theme_support( 'nav-menus' );

需注意 —– 个人总结

为什么我再主题中添加了 add_theme_support( ‘automatic-feed-links’ ); 却没有在头部发现自动生成的 RSS 地址呢？

很简单，只要你在头部位置放置了头部钩子，自动生成的rss地址就会出现了，如下：

<head>
...............codes........... 
wp_head();
...............codes...........
</head>

以上部分摘自http://pangbu.com/wordpress-add_theme_support/

以下摘自http://blog.wpjam.com/function_reference/add_theme_support/

3、实例

3.1、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.';
}

3.2、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();
}

3.3、Custom Background

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

add_theme_support( 'custom-background' );

设置默认背景的参数：

$defaults = array(
	'default-color'          => '000', //默认背景颜色
	'default-image'          => 'get_template_directory_uri() . '/images/background.jpg'', //默认背景图片
	'wp-head-callback'       => '_custom_background_cb', //回调函数
	'admin-head-callback'    => '',
	'admin-preview-callback' => ''
);
add_theme_support( 'custom-background', $defaults );

3.4、Custom Header

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

add_theme_support( 'custom-header' );

设置默认的头图参数

add_theme_support( 'custom-header', array(
	// Header image default
	'default-image'			=> get_template_directory_uri() . '/images/headers/default.jpg',
	// Header text display default
	'header-text'			=> false,
	// Header text color default
	'default-text-color'		=> '000',
	// Header image width (in pixels)
	'width'				=> 1000,
	// Header image height (in pixels)
	'height'			=> 198,
	// Header image random rotation default
	'random-default'		=> false,
	// Template header style callback
	'wp-head-callback'		=> $wphead_cb,
	// Admin header style callback
	'admin-head-callback'		=> $adminhead_cb,
	// Admin preview style callback
	'admin-preview-callback'	=> $adminpreview_cb
) );

3.5、Feed Links

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

add_theme_support( 'automatic-feed-links' );

3.6、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.

4、注解

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

  • sidebars: 使用 register_sidebar() 或者 register_sidebars()
  • menus: 使用 register_nav_menu() 或者 register_nav_menus()
  • editor-style: 使用 add_editor_style()

5、修改记录

  • 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'

6、源文件

wp-includes/theme.php