函数文档

get_theme_feature_list()

💡 云策文档标注

概述

get_theme_feature_list() 函数用于检索 WordPress 主题功能(即主题标签)列表。它支持从 WordPress.org API 获取数据,并返回按类别组织的数组,包含翻译后的标签名称。

关键要点

  • 函数返回一个数组,键为类别(如 Subject、Features、Layout),值为子数组,其中键为功能 slug,值为翻译后的标签名称。
  • 参数 $api 可选,默认为 true,控制是否尝试从 WordPress.org API 获取标签;若 API 不可用或无权限,则使用硬编码列表。
  • 函数内部使用站点瞬态缓存 API 数据以提高性能,缓存时间为 3 小时。
  • 相关函数包括 themes_api()、set_site_transient()、current_user_can() 等,用于 API 调用、缓存和权限检查。
  • 在版本更新中,功能列表有多次变更,如 6.2.0 添加了 'Style Variations',6.1.1 将 'Full Site Editing' 更名为 'Site Editor'。

代码示例

// 示例:获取主题功能列表
$features = get_theme_feature_list();
// 输出可能包括:
// array(
//     'Subject' => array('blog' => 'Blog', ...),
//     'Features' => array('accessibility-ready' => 'Accessibility Ready', ...),
//     'Layout' => array('grid-layout' => 'Grid Layout', ...)
// );

注意事项

  • 函数依赖于 current_user_can('install_themes') 权限检查,若无权限则直接返回硬编码列表。
  • 硬编码列表作为后备方案,确保在 API 失败时仍能提供基本功能数据。
  • 翻译通过 __() 函数处理,支持多语言环境。

📄 原文内容

Retrieves list of WordPress theme features (aka theme tags).

Parameters

$apibooloptional
Whether try to fetch tags from the WordPress.org API. Defaults to true.

Default:true

Return

array Array of features keyed by category with translations keyed by slug.

Source

function get_theme_feature_list( $api = true ) {
	// Hard-coded list is used if API is not accessible.
	$features = array(

		__( 'Subject' )  => array(
			'blog'           => __( 'Blog' ),
			'e-commerce'     => __( 'E-Commerce' ),
			'education'      => __( 'Education' ),
			'entertainment'  => __( 'Entertainment' ),
			'food-and-drink' => __( 'Food & Drink' ),
			'holiday'        => __( 'Holiday' ),
			'news'           => __( 'News' ),
			'photography'    => __( 'Photography' ),
			'portfolio'      => __( 'Portfolio' ),
		),

		__( 'Features' ) => array(
			'accessibility-ready'   => __( 'Accessibility Ready' ),
			'block-patterns'        => __( 'Block Editor Patterns' ),
			'block-styles'          => __( 'Block Editor Styles' ),
			'custom-background'     => __( 'Custom Background' ),
			'custom-colors'         => __( 'Custom Colors' ),
			'custom-header'         => __( 'Custom Header' ),
			'custom-logo'           => __( 'Custom Logo' ),
			'editor-style'          => __( 'Editor Style' ),
			'featured-image-header' => __( 'Featured Image Header' ),
			'featured-images'       => __( 'Featured Images' ),
			'footer-widgets'        => __( 'Footer Widgets' ),
			'full-site-editing'     => __( 'Site Editor' ),
			'full-width-template'   => __( 'Full Width Template' ),
			'post-formats'          => __( 'Post Formats' ),
			'sticky-post'           => __( 'Sticky Post' ),
			'style-variations'      => __( 'Style Variations' ),
			'template-editing'      => __( 'Template Editing' ),
			'theme-options'         => __( 'Theme Options' ),
		),

		__( 'Layout' )   => array(
			'grid-layout'   => __( 'Grid Layout' ),
			'one-column'    => __( 'One Column' ),
			'two-columns'   => __( 'Two Columns' ),
			'three-columns' => __( 'Three Columns' ),
			'four-columns'  => __( 'Four Columns' ),
			'left-sidebar'  => __( 'Left Sidebar' ),
			'right-sidebar' => __( 'Right Sidebar' ),
			'wide-blocks'   => __( 'Wide Blocks' ),
		),

	);

	if ( ! $api || ! current_user_can( 'install_themes' ) ) {
		return $features;
	}

	$feature_list = get_site_transient( 'wporg_theme_feature_list' );
	if ( ! $feature_list ) {
		set_site_transient( 'wporg_theme_feature_list', array(), 3 * HOUR_IN_SECONDS );
	}

	if ( ! $feature_list ) {
		$feature_list = themes_api( 'feature_list', array() );
		if ( is_wp_error( $feature_list ) ) {
			return $features;
		}
	}

	if ( ! $feature_list ) {
		return $features;
	}

	set_site_transient( 'wporg_theme_feature_list', $feature_list, 3 * HOUR_IN_SECONDS );

	$category_translations = array(
		'Layout'   => __( 'Layout' ),
		'Features' => __( 'Features' ),
		'Subject'  => __( 'Subject' ),
	);

	$wporg_features = array();

	// Loop over the wp.org canonical list and apply translations.
	foreach ( (array) $feature_list as $feature_category => $feature_items ) {
		if ( isset( $category_translations[ $feature_category ] ) ) {
			$feature_category = $category_translations[ $feature_category ];
		}

		$wporg_features[ $feature_category ] = array();

		foreach ( $feature_items as $feature ) {
			if ( isset( $features[ $feature_category ][ $feature ] ) ) {
				$wporg_features[ $feature_category ][ $feature ] = $features[ $feature_category ][ $feature ];
			} else {
				$wporg_features[ $feature_category ][ $feature ] = $feature;
			}
		}
	}

	return $wporg_features;
}

Changelog

Version Description
6.2.0 Added ‘Style Variations’ feature.
6.1.1 Replaced ‘Full Site Editing’ feature name with ‘Site Editor’.
5.8.1 Added ‘Template Editing’ feature.
5.5.0 Added ‘Wide Blocks’ layout option.
4.9.0 Removed 'BuddyPress', ‘Custom Menu’, ‘Flexible Header’, ‘Front Page Posting’, 'Microformats', ‘RTL Language Support’, ‘Threaded Comments’, and ‘Translation Ready’ features.
4.6.0 Added 'Blog', 'E-Commerce', 'Education', 'Entertainment', ‘Food & Drink’, 'Holiday', 'News', 'Photography', and 'Portfolio' subjects.
Removed 'Photoblogging' and 'Seasonal' subjects.
3.9.0 Combined 'Layout' and 'Columns' filters.
3.8.0 Added ‘Accessibility Ready’ feature and ‘Responsive Layout’ option.
3.5.0 Added ‘Flexible Header’ feature.
3.2.0 Added 'Gray' color and ‘Featured Image Header’, ‘Featured Images’, ‘Full Width Template’, and ‘Post Formats’ features.
3.1.0 Introduced.

Show 6 moreShow less