云策 WordPress 开发者社区

函数文档

get_term_parents_list()

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

概述

get_term_parents_list() 函数用于检索指定分类术语的父级术语列表，并以分隔符连接返回。它支持自定义格式、链接和包含当前术语等选项，适用于构建面包屑导航或显示术语层级结构。

关键要点

  • 参数：$term_id（术语ID，必填）、$taxonomy（分类法名称，必填）、$args（可选参数数组，包括format、separator、link、inclusive等）。
  • 返回值：成功时返回父级术语列表字符串，失败时返回WP_Error或空字符串。
  • 核心功能：通过get_ancestors()获取祖先术语ID，根据参数格式化输出，支持链接和名称/别名显示。
  • 相关函数：涉及wp_validate_boolean()、get_ancestors()、get_term_link()等辅助函数。

代码示例

// 在分类存档页面显示术语父级列表
if ( is_category() ) {
    $term_id = get_queried_object()->term_id;
    echo get_term_parents_list( $term_id, 'category' );
}
// 输出示例：Parent Category/Child Category/Grandchild Category

注意事项

  • 确保$term_id和$taxonomy参数有效，否则可能返回错误或空值。
  • 参数$args中的布尔值（如link和inclusive）会被wp_validate_boolean()处理，确保正确转换。
  • 函数自WordPress 4.8.0版本引入，兼容性需考虑。
📄 原文内容

Retrieves term parents with separator.

Parameters

$term_idintrequired
Term ID.
$taxonomystringrequired
Taxonomy name.
$argsstring|arrayoptional
Array of optional arguments.

  • format string
    Use term names or slugs for display. Accepts 'name' or 'slug'.
    Default 'name'.
  • separator string
    Separator for between the terms. Default '/'.
  • link bool
    Whether to format as a link. Default true.
  • inclusive bool
    Include the term to get the parents for. Default true.

Default:array()

Return

string|WP_Error A list of term parents on success, WP_Error or empty string on failure.

Source

function get_term_parents_list( $term_id, $taxonomy, $args = array() ) {
	$list = '';
	$term = get_term( $term_id, $taxonomy );

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

	if ( ! $term ) {
		return $list;
	}

	$term_id = $term->term_id;

	$defaults = array(
		'format'    => 'name',
		'separator' => '/',
		'link'      => true,
		'inclusive' => true,
	);

	$args = wp_parse_args( $args, $defaults );

	foreach ( array( 'link', 'inclusive' ) as $bool ) {
		$args[ $bool ] = wp_validate_boolean( $args[ $bool ] );
	}

	$parents = get_ancestors( $term_id, $taxonomy, 'taxonomy' );

	if ( $args['inclusive'] ) {
		array_unshift( $parents, $term_id );
	}

	foreach ( array_reverse( $parents ) as $term_id ) {
		$parent = get_term( $term_id, $taxonomy );
		$name   = ( 'slug' === $args['format'] ) ? $parent->slug : $parent->name;

		if ( $args['link'] ) {
			$list .= '<a href="' . esc_url( get_term_link( $parent->term_id, $taxonomy ) ) . '">' . $name . '</a>' . $args['separator'];
		} else {
			$list .= $name . $args['separator'];
		}
	}

	return $list;
}

View all references View on Trac View on GitHub

Uses Description
wp_validate_boolean()wp-includes/functions.php

Filters/validates a variable as a boolean.
get_ancestors()wp-includes/taxonomy.php

Gets an array of ancestor IDs for a given object.
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.
wp_parse_args()wp-includes/functions.php

Merges user defined arguments into defaults array.
get_term()wp-includes/taxonomy.php

Gets all term data from database by term ID.
is_wp_error()wp-includes/load.php

Checks whether the given variable is a WordPress Error.

Show 4 moreShow less

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

Retrieves category parents with separator.

Changelog

Version Description
4.8.0 Introduced.

User Contributed Notes

  1. Skip to note 3 content


    keesiemeijer


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

    Example to display term parents in category archive pages. Use this in your category archive theme templates.

    term_id;

	echo get_term_parents_list( $term_id, 'category' );
}
?>

    This is an example of what it would print on a “Grandchild Category” term page.

    Parent Category/Child Category/Grandchild Category

  2. Skip to note 4 content


    keesiemeijer


    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

    Example of a breadcrumb trail for taxonomy pages. Use it in your theme’s taxonomy templates

    Home</a>';
	$query_obj = get_queried_object();
	$term_id   = $query_obj->term_id;
	$taxonomy  = get_taxonomy( $query_obj->taxonomy );

	if ( $term_id && $taxonomy ) {
		// Add taxonomy label name to the trail.
		$trail .=  '/' . $taxonomy->labels->menu_name;
		// Add term parents to the trail.
		$trail .= '/' . get_term_parents_list( $term_id, $taxonomy->name, array( 'inclusive' => false ) );
	}

	// Print trail and add current term name at the end.
	echo '<p class="breadcrumb-trail">' . $home . $trail . $query_obj->name . '</p>';
}
?>