主题函数 - 主题开发手册

Functions.php可以被经典主题、区块主题和子主题使用。

functions.php文件是您向WordPress主题添加特定功能的地方。它可以用来连接WordPress的核心功能，使主题更加模块化、可扩展和功能化。

什么是`functions.php`？

functions.php文件的行为类似于WordPress插件，为WordPress站点添加特性和功能。您可以使用它调用WordPress函数并定义自己的函数。

使用插件或functions.php可以产生相同的结果。如果您正在创建无论网站外观如何都应该可用的新功能，那么最好将其放入插件中。

无论是使用WordPress插件还是使用functions.php，都有其利弊。

WordPress插件：

需要特定、唯一的标题文本；
储存在wp-content/plugins中，通常位于子目录中。
仅在激活时在页面加载时执行；
适用于所有主题；
应具有单一用途–例如，提供搜索引擎优化功能或帮助备份。

functions.php文件：

不需要唯一的标题文本；
储存在wp-content/themes的主题子目录中；
仅在启用的主题中执行；
仅适用于该主题（如果主题已更改，则无法再使用功能）；
可以有许多代码块用于许多不同的目的。

每个主题都有自己的函数文件，但只有启用的主题 functions.php 中的代码才会真正运行。如果你的主题已经有一个函数文件，你可以向它添加代码。如果没有，你可以创建一个名为 functions.php 的纯文本文件，添加到你的主题目录中，如下所述。

一个子主题可以有自己的 functions.php 文件。在子函数文件中添加一个函数是一种无风险的修改父主题的方式。这样，当父主题被更新时，你就不必担心你新添加的函数会消失。

尽管子主题的functions.php会在父主题的functions.php之前被WordPress加载，但它并没有覆盖父主题的functions.php。子主题的functions.php可以用来增加或替换父主题的功能。同样的，functions.php也是在任何插件文件加载完毕后加载的。

通过functions.php你可以：

使用WordPress钩子，例如，使用excerpt_length过滤器，您可以更改文章的摘录长度（默认为55个单词）。
用add_theme_support()启用WordPress功能。例如，开启文章缩略图、文章格式和导航菜单。
定义要在多个主题模板文件中重用的函数。

如果一个WordPress插件调用了与你在functions.php中相同的函数，或过滤器，结果可能会出乎意料，甚至导致您的网站被禁用。

示例

下面是一些例子，你可以在你的function.php文件中使用，以支持各种功能。如果你选择提交给WordPress.org主题目录，这些例子中的每一个都允许在你的主题中使用。

主题设置

一些主题功能应该被包含在一个 "设置 "函数中，当你的主题被激活时，这个函数会在最初运行。如下所示，这些功能中的每一个都可以被添加到你的functions.php文件中，以激活推荐的WordPress功能。

用你的主题名称来命名你的函数是很重要的。下面所有的例子都使用myfirsttheme_作为它们的命名空间，这应该根据你的主题名称来定制。

要创建这个初始函数，请创建一个名为myfirsttheme_setup()的新函数，像这样：

if ( ! function_exists( 'myfirsttheme_setup' ) ) :
/**
* Sets up theme defaults and registers support for various WordPress features
*
*  It is important to set up these functions before the init hook so that none of these
*  features are lost.
*
*  @since MyFirstTheme 1.0
*/
function myfirsttheme_setup() {

注意：在上面的例子中，函数myfirsttheme_setup被启动，但没有关闭。请确保关闭你的函数。

自动Feed链接

自动feed链接默认启用文章和评论的RSS feeds。这些feeds将自动显示在<head>中。它们可以用add_theme_support()来调用。

add_theme_support( 'automatic-feed-links' );

在经典主题中，自定义导航菜单允许用户在菜单管理面板中编辑和定制菜单，给用户一个拖放界面来编辑他们主题中的各种菜单。

你可以在function.php中设置多个菜单。它们可以用register_nav_menus()来添加，用wp_nav_menu()插入到主题中，这一点在本手册后面有讨论。如果你的主题将允许一个以上的菜单，你应该使用一个数组。虽然有些主题不会有自定义的导航菜单，但建议你允许这个功能，以方便定制。

register_nav_menus( array(
	'primary'   => __( 'Primary Menu', 'myfirsttheme' ),
	'secondary' => __( 'Secondary Menu', 'myfirsttheme' )
) );

你定义的每个菜单都可以在以后使用wp_nav_menu()并使用指定的名称（即primary）作为theme_location参数来调用。

在区块主题中，你使用导航块来代替。

加载文本域

通过使主题中的字符串可用于翻译，可以将主题翻译为多种语言。要做到这一点，你必须使用load_theme_textdomain()。有关主题翻译的更多信息，请阅读国际化部分。

load_theme_textdomain( 'myfirsttheme', get_template_directory() . '/languages' );

文章缩略图

文章缩略图和特色图片允许你的用户选择一张图片来代表他们的文章。你的主题可以根据其设计来决定如何显示它们。例如，你可以选择在档案视图中的每篇文章中显示一张文章缩略图。或者，你可能想在你的主页上使用一张大的特色图片。虽然不是每个主题都需要特色图片，但建议你支持文章缩略图和特色图片。

add_theme_support( 'post-thumbnails' );

文章格式

文章格式允许用户以不同的方式格式化他们的文章。这对允许博主根据文章的内容选择不同的格式和模板很有用。 add_theme_support()也用于文章格式。这一点是值得推荐的。

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

学习更多关于文章格式

区块主题中的主题支持

在区块主题中，下列主题支持被自动启用。

add_theme_support( 'post-thumbnails' );
add_theme_support( 'responsive-embeds' );
add_theme_support( 'editor-styles' );
add_theme_support( 'html5', array('style','script', ) );
add_theme_support( 'automatic-feed-links' );

初始设置示例

包括上述所有的功能，将给你一个像下面这样的functions.php文件。为了今后更加清晰，已经添加了代码注释。

如本例底部所示，你必须添加必要的add_action()语句以确保myfirsttheme_setup函数被加载。

if ( ! function_exists( 'myfirsttheme_setup' ) ) :
/**
 * Sets up theme defaults and registers support for various WordPress features.
 *
 * Note that this function is hooked into the after_setup_theme hook, which runs
 * before the init hook. The init hook is too late for some features, such as indicating
 * support post thumbnails.
 */
function myfirsttheme_setup() {

	/**
	 * Make theme available for translation.
	 * Translations can be placed in the /languages/ directory.
	 */
	load_theme_textdomain( 'myfirsttheme', get_template_directory() . '/languages' );

	/**
	 * Add default posts and comments RSS feed links to &lt;head>.
	 */
	add_theme_support( 'automatic-feed-links' );

	/**
	 * Enable support for post thumbnails and featured images.
	 */
	add_theme_support( 'post-thumbnails' );

	/**
	 * Add support for two custom navigation menus.
	 */
	register_nav_menus( array(
		'primary'   => __( 'Primary Menu', 'myfirsttheme' ),
		'secondary' => __('Secondary Menu', 'myfirsttheme' )
	) );

	/**
	 * Enable support for the following post formats:
	 * aside, gallery, quote, image, and video
	 */
	add_theme_support( 'post-formats', array ( 'aside', 'gallery', 'quote', 'image', 'video' ) );
}
endif; // myfirsttheme_setup
add_action( 'after_setup_theme', 'myfirsttheme_setup' );

内容宽度

内容宽度被添加到你的 functions.php 文件中，以确保没有内容或资源破坏网站的容器。内容宽度为添加到网站的任何内容设定最大允许宽度，包括上传的图片。在下面的例子中，内容区的最大宽度为800像素。任何内容都不会大于这个宽度。

if ( ! isset ( $content_width) )
    $content_width = 800;

其他功能

在 functions.php 中还可以包含其他一些常见的功能。下面列出的是一些最常见的功能。点击查看，了解更多关于这些功能的信息。

自定义页眉 -经典主题
侧边栏 (widget区域) -经典主题
自定义背景 -经典主题
标题标签 -经典主题
添加编辑器样式
HTML5

你的functions.php文件

如果你选择包含上面列出的所有函数，你的 functions.php 可能会是这个样子。它已经被注释了，并引用了上面的内容。

/**
 * MyFirstTheme's functions and definitions
 *
 * @package MyFirstTheme
 * @since MyFirstTheme 1.0
 */

/**
 * First, let's set the maximum content width based on the theme's design and stylesheet.
 * This will limit the width of all uploaded images and embeds.
 */
if ( ! isset( $content_width ) )
	$content_width = 800; /* pixels */

if ( ! function_exists( 'myfirsttheme_setup' ) ) :
/**
 * Sets up theme defaults and registers support for various WordPress features.
 *
 * Note that this function is hooked into the after_setup_theme hook, which runs
 * before the init hook. The init hook is too late for some features, such as indicating
 * support post thumbnails.
 */
function myfirsttheme_setup() {

	/**
	 * Make theme available for translation.
	 * Translations can be placed in the /languages/ directory.
	 */
	load_theme_textdomain( 'myfirsttheme', get_template_directory() . '/languages' );

	/**
	 * Add default posts and comments RSS feed links to &lt;head>.
	 */
	add_theme_support( 'automatic-feed-links' );

	/**
	 * Enable support for post thumbnails and featured images.
	 */
	add_theme_support( 'post-thumbnails' );

	/**
	 * Add support for two custom navigation menus.
	 */
	register_nav_menus( array(
		'primary'   => __( 'Primary Menu', 'myfirsttheme' ),
		'secondary' => __('Secondary Menu', 'myfirsttheme' )
	) );

	/**
	 * Enable support for the following post formats:
	 * aside, gallery, quote, image, and video
	 */
	add_theme_support( 'post-formats', array ( 'aside', 'gallery', 'quote', 'image', 'video' ) );
}
endif; // myfirsttheme_setup
add_action( 'after_setup_theme', 'myfirsttheme_setup' );