云策 WordPress 开发者社区

函数文档

get_the_term_list()

查看官方原文 ↗
💡 云策文档标注

概述

get_the_term_list() 函数用于获取文章的分类法术语列表，并以指定格式返回链接列表。它基于 get_the_terms() 获取术语，并通过 get_term_link() 生成链接，支持自定义前后缀和分隔符。

关键要点

  • 函数返回文章指定分类法的术语链接列表，格式可自定义。
  • 参数包括 $post_id（文章ID）、$taxonomy（分类法名称）、$before（前缀）、$sep（分隔符）和 $after（后缀）。
  • 返回值：成功时返回术语列表字符串，无术语时返回 false，失败时返回 WP_Error。
  • 内部使用 get_the_terms() 获取术语，get_term_link() 生成链接，并应用 term_links-{$taxonomy} 过滤器。
  • 相关函数包括 the_terms() 和 get_the_tag_list()，用于显示或获取术语列表。

代码示例

// 基本示例：输出 people 分类法的术语列表，带前缀和逗号分隔
echo get_the_term_list( $post->ID, 'people', 'People: ', ', ' );
// 输出类似：People: Person 1, Person 2, ...

// 返回 HTML 列表：输出 styles 分类法的术语作为列表项
echo get_the_term_list( $post->ID, 'styles', '<ul><li>', '</li><li>', '</li></ul>' );
// 输出类似：<ul><li>Style 1</li><li>Style 2</li></ul>

// 使用 strip_tags 或 wp_strip_all_tags 获取无链接的纯文本术语列表
echo strip_tags( get_the_term_list( $post->ID, 'job_titles', '', ', ' ) );
// 输出类似：Designer, Front-end Developer, Developer

注意事项

  • 函数内部处理错误：如果 get_the_terms() 或 get_term_link() 返回 WP_Error，则直接返回该错误。
  • 过滤器 term_links-{$taxonomy} 允许自定义术语链接数组，动态部分为分类法 slug。
  • 建议使用 wp_strip_all_tags() 而非 strip_tags() 来去除 HTML 标签，以符合 WordPress 编码标准。
  • 函数自 WordPress 2.5.0 引入，适用于在循环内或指定文章ID获取术语列表。
📄 原文内容

Retrieves a post’s terms as a list with specified format.

Description

Terms are linked to their respective term listing pages.

Parameters

$post_idintrequired
Post ID.
$taxonomystringrequired
Taxonomy name.
$beforestringoptional
String to use before the terms. Default empty.
$sepstringoptional
String to use between the terms. Default empty.
$afterstringoptional
String to use after the terms. Default empty.

Return

string|false|WP_Error A list of terms on success, false if there are no terms, WP_Error on failure.

Source

function get_the_term_list( $post_id, $taxonomy, $before = '', $sep = '', $after = '' ) {
	$terms = get_the_terms( $post_id, $taxonomy );

	if ( is_wp_error( $terms ) ) {
		return $terms;
	}

	if ( empty( $terms ) ) {
		return false;
	}

	$links = array();

	foreach ( $terms as $term ) {
		$link = get_term_link( $term, $taxonomy );
		if ( is_wp_error( $link ) ) {
			return $link;
		}
		$links[] = '<a href="' . esc_url( $link ) . '" rel="tag">' . $term->name . '</a>';
	}

	/**
	 * Filters the term links for a given taxonomy.
	 *
	 * The dynamic portion of the hook name, `$taxonomy`, refers
	 * to the taxonomy slug.
	 *
	 * Possible hook names include:
	 *
	 *  - `term_links-category`
	 *  - `term_links-post_tag`
	 *  - `term_links-post_format`
	 *
	 * @since 2.5.0
	 *
	 * @param string[] $links An array of term links.
	 */
	$term_links = apply_filters( "term_links-{$taxonomy}", $links );  // phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores

	return $before . implode( $sep, $term_links ) . $after;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( “term_links-{$taxonomy}”, string[] $links )

Filters the term links for a given taxonomy.

Uses Description
get_the_terms()wp-includes/category-template.php

Retrieves the terms of the taxonomy that are attached to the post.
get_term_link()wp-includes/taxonomy.php

Generates a permalink for a taxonomy term archive.
esc_url()wp-includes/formatting.php

Checks and cleans a URL.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.
is_wp_error()wp-includes/load.php

Checks whether the given variable is a WordPress Error.

Show 3 moreShow less

Used by Description
the_terms()wp-includes/category-template.php

Displays the terms for a post in a list.
get_the_tag_list()wp-includes/category-template.php

Retrieves the tags for a post formatted as a string.

Changelog

Version Description
2.5.0 Introduced.

User Contributed Notes

  1. Skip to note 4 content


    Ömür Yanıkoğlu


    You must log in to vote on the helpfulness of this noteVote results for this note: 7You must log in to vote on the helpfulness of this note

    You can use this function with strip_tags function to print not linked term list:

    echo strip_tags( get_the_term_list( $post->ID, 'job_titles', '', ', ') )

    This prints something like this:

    Designer, Front-end Developer, Developer

  3. Skip to note 6 content


    Codex


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    Returning an HTML List

    Used inside the loop this outputs the terms from the styles taxonomy for a specific post as an (x)html list.

    echo get_the_term_list( $post->ID, 'styles', '<ul class="styles"><li>', ',</li><li>', '</li></ul>' );

    This would return something like.

    <ul class="styles">
    <li><a href="person1">Style 1</a>,</li> 
    <li><a href="person2">Style 2</a></li>
</ul>