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