云策 WordPress 开发者社区

函数文档

previous_post_link()

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

概述

previous_post_link() 是一个 WordPress 模板标签，用于在单篇文章页面显示指向按时间顺序排列的前一篇文章的链接。该函数必须在 The Loop 中使用，并支持多种参数来自定义链接格式和筛选条件。

关键要点

  • 函数用于显示当前文章的前一篇文章链接，基于时间顺序（如发布日期）。
  • 必须在 The Loop 内使用，适用于单篇文章页面。
  • 参数包括 $format（链接锚点格式，默认 '« %link'）、$link（链接永久链接格式，默认 '%title'）、$in_same_term（是否在同一分类法术语内，默认 false）、$excluded_terms（排除的术语 ID 数组或列表，默认空）和 $taxonomy（分类法名称，默认 'category'）。
  • 通过 $in_same_term 和 $taxonomy 参数可以限制链接在同一分类法术语内，例如同一分类或自定义分类。
  • $excluded_terms 参数用于排除特定术语 ID，从 WordPress 3.3 起不再支持用 'and' 分隔的列表。
  • 函数内部调用 get_previous_post_link() 来获取链接并直接输出。

代码示例

// 默认用法：显示左尖括号和文章标题
previous_post_link();

// 在同一自定义分类法术语内显示链接，例如自定义文章类型 Buildings 和分类法 Neighborhood
previous_post_link( '%link', '%title', true, '', 'neighborhood' );

// 使用 strong 标签加粗标题
previous_post_link( '%link', '<strong>%title</strong>' );

// 在同一分类内显示自定义文本链接，不包含文章标题
previous_post_link( '%link', 'Previous in category', true );

// 在同一分类内排除特定分类 ID（例如 ID 13）
previous_post_link( '%link', '%title', true, array( 13 ) );

注意事项

  • 确保在 The Loop 中调用此函数，否则可能无法正确获取文章上下文。
  • 使用 $excluded_terms 时，注意从 WordPress 3.3 起已弃用 'and' 分隔符，应使用数组或逗号分隔列表。
  • 参数 $taxonomy 仅在 $in_same_term 为 true 时生效，用于指定分类法类型。
  • 函数直接输出链接，若需获取链接字符串而不输出，应使用 get_previous_post_link()。
📄 原文内容

Displays the previous post link that is adjacent to the current post.

Description

See also

Parameters

$formatstringoptional
Link anchor format. Default ‘« %link’.
$linkstringoptional
Link permalink format. Default '%title'.
$in_same_termbooloptional
Whether link should be in the same taxonomy term.

Default:false

$excluded_termsint[]|stringoptional
Array or comma-separated list of excluded term IDs.
Default empty.
$taxonomystringoptional
Taxonomy, if $in_same_term is true. Default 'category'.

More Information

Used on single post permalink pages, this template tag displays a link to the previous post which exists in chronological order from the current post. This tag must be used in The Loop.

$format is the format string for the link. This is where to control what comes before and after the link. '%link' in string will be replaced with whatever is declared as 'link' (see next parameter). 'Go to %link' will generate “Go to <a href=…” Put HTML tags here to style the final results.

$in_same_term indicates whether previous post must be within the same taxonomy term as the current post. If set to 'true', only posts from the current taxonomy term will be displayed. If the post is in both the parent and subcategory, or more than one term, the previous post link will lead to the previous post in any of those terms.
$excluded_terms is an array or a comma-separated list of numeric terms IDs from which the next post should not be listed. For example array(1, 5) or '1,5'. This argument used to accept a list of IDs separated by 'and', this was deprecated in WordPress 3.3.

Source

function previous_post_link( $format = '« %link', $link = '%title', $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' ) {
	echo get_previous_post_link( $format, $link, $in_same_term, $excluded_terms, $taxonomy );
}

View all references View on Trac View on GitHub

Uses Description
get_previous_post_link()wp-includes/link-template.php

Retrieves the previous post link that is adjacent to the current post.

Changelog

Version Description
1.5.0 Introduced.

User Contributed Notes

  4. Skip to note 10 content


    Codex


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

    Text As Link, Without Post Title, Within Same Category

    Displays custom text as link to the previous post within the same category as the current post. Post title is not included here. “Previous in category” is the custom text, which can be changed to fit your requirements.

    Previous in category

  5. Skip to note 11 content


    Codex


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

    Within Same Category, Excluding One

    Displays link to previous post in the same category, as long as it is not in category 13 (the category ID #). You can change the number to any category you wish to exclude. Array or comma-separated list of category ID(s) from which the previous post should not be listed. For example array( 1, 5) or ‘1,5’.

    Previous in category