wp_get_post_terms()
云策文档标注
概述
wp_get_post_terms() 函数用于检索文章(或自定义文章类型)的术语(terms),支持指定文章ID、分类法(taxonomy)和查询参数。它返回一个 WP_Term 对象数组或错误对象,常用于获取文章的分类、标签等关联数据。
关键要点
- 参数:$post_id(文章ID,默认0,不默认使用全局 $post)、$taxonomy(分类法slug或数组,默认'post_tag')、$args(查询参数数组,支持 WP_Term_Query 参数,默认 fields 为 'all')。
- 返回值:成功时返回 WP_Term 对象数组,无术语时返回空数组;若 $taxonomy 不存在则返回 WP_Error 对象。
- 与 get_the_terms() 的区别:wp_get_post_terms() 结果不缓存(每次调用都会查询数据库),且允许第三个参数 $args。
- 内部实现:调用 wp_get_object_terms() 并处理参数,确保字段默认值为 'all'。
代码示例
// 返回 'my_taxonomy' 的所有术语项
$term_list = wp_get_post_terms( $post->ID, 'my_taxonomy', array( 'fields' => 'all' ) );
print_r( $term_list );
// 返回 'my_taxonomy' 的术语名称数组
$term_list = wp_get_post_terms( $post->ID, 'my_taxonomy', array( 'fields' => 'names' ) );
print_r( $term_list );
// 返回 'my_taxonomy' 的术语ID数组
$term_list = wp_get_post_terms( $post->ID, 'my_taxonomy', array( 'fields' => 'ids' ) );
print_r( $term_list );注意事项
- 函数自 WordPress 2.8.0 引入,无缓存机制,频繁调用可能影响性能。
- 相关函数:wp_get_object_terms()(底层实现)、wp_get_post_tags()(获取文章标签的便捷函数)。
- 用户贡献笔记提供了实际应用示例,如根据术语条件输出内容或生成HTML列表。
原文内容
Retrieves the terms for a post.
Parameters
$post_idintoptional-
The Post ID. Does not default to the ID of the global $post. Default 0.
$taxonomystring|string[]optional-
The taxonomy slug or array of slugs for which to retrieve terms. Default
'post_tag'. $argsarrayoptional-
Term query parameters. See WP_Term_Query::__construct() for supported arguments.
fieldsstringTerm fields to retrieve. Default'all'.
Default:
array()
Source
function wp_get_post_terms( $post_id = 0, $taxonomy = 'post_tag', $args = array() ) {
$post_id = (int) $post_id;
$defaults = array( 'fields' => 'all' );
$args = wp_parse_args( $args, $defaults );
$tags = wp_get_object_terms( $post_id, $taxonomy, $args );
return $tags;
}
Changelog
| Version | Description |
|---|---|
| 2.8.0 | Introduced. |
Skip to note 6 content
Dustin Falgout
The difference between this function and
get_the_terms()is that this function’s results are not cached (thus, it’ll hit the database every time its called).get_the_terms()does not allow the third parameter:$args.Skip to note 7 content
Codex
Examples
//Returns All Term Items for "my_taxonomy". $term_list = wp_get_post_terms( $post->ID, 'my_taxonomy', array( 'fields' => 'all' ) ); print_r( $term_list ); // Returns Array of Term Names for "my_taxonomy". $term_list = wp_get_post_terms( $post->ID, 'my_taxonomy', array( 'fields' => 'names' ) ); print_r( $term_list ); // Returns Array of Term ID's for "my_taxonomy". $term_list = wp_get_post_terms( $post->ID, 'my_taxonomy', array( 'fields' => 'ids' ) ); print_r( $term_list );Skip to note 8 content
tradesouthwest
Get term category to only run function if the post (CPT) has that category:
/** * Get category and add text to that page, only. * * @param string $terms Get post terms * @return string Text */ function wpdocs_additional_measurements() { global $post; $innertext = "Hemmed tarps have seatbelt material woven into the hems."; $terms = wp_get_post_terms( $post->ID, 'product_cat' ); foreach ( $terms as $term ) { $categories[] = $term->slug; } // Look for term/category by slug if ( in_array( 'custom-tarps', $categories ) ) { printf( '<p>%s</p>', esc_html__( $innertext, 'woocommerce' ) ); } } add_action( 'woocommerce_before_add_to_cart_button', 'wpdocs_additional_measurements', 9 );Use curly brackets recommended but not needed on one expression of foreach
Skip to note 9 content
Mehedi Foysal
Get all taxonomy slug of a post
function post_taxonomy_slug_array( $tax_name = 'category' ) { $terms = wp_get_post_terms( get_the_ID(), $tax_name, array( "fields" => "slugs" ) ); if ( ! empty( $terms ) && ! is_wp_error( $terms ) ) { $term_array = array(); foreach ( $terms as $term ) { $term_array[] = $term; } return $term_array; } return ''; }Skip to note 10 content
awaismushtaq
You can get the taxonomy terms HTML using this function am_get_post_term
function am_get_post_terms( $post_id = 0, $taxonomy = 'category', $custom_html = ['ul','li','a'] ) { $post_terms = wp_get_post_terms( $post_id, $taxonomy ); $custom_html[0] = isset($custom_html[0]) ? $custom_html[0] : 'ul'; $custom_html[1] = isset($custom_html[1]) ? $custom_html[1] : 'li'; $custom_html[2] = isset($custom_html[2]) ? $custom_html[2] : 'a'; $post_term_html = ''; $post_term_html .= '<' . $custom_html[0] . '>'; foreach( $post_terms as $p_term ) { $post_term_html .= '<' . $custom_html[1] . '><' . $custom_html[2] . ' href="'. get_term_link( $p_term->term_id, $taxonomy ) .'">'. $p_term->name .'<!--' . $custom_html[2] . '--><!--' . $custom_html[1] . '-->'; } $post_term_html .= '<!--' . $custom_html[0] . '-->'; return $post_term_html; } Call the function in single.php file work for all CPT: <pre class="wp-block-code"><code lang="php" class="language-php ">echo am_get_post_terms( get_the_ID(), 'category',['div','span','a'] );