云策 WordPress 开发者社区

函数文档

the_date()

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

概述

the_date() 是 WordPress 模板标签，用于在循环中显示或检索文章的发布日期，但每个日期仅输出一次。它通过比较当前文章与前一文章的日期，确保同一天的文章只显示一个日期。

关键要点

  • 功能：显示或检索文章日期，但每个日期在循环中仅输出一次，基于 is_new_day() 判断。
  • 参数：$format（PHP 日期格式，默认 'date_format' 选项）、$before（日期前输出）、$after（日期后输出）、$display（是否回显，默认 true）。
  • 返回值：当 $display 为 false 时返回日期字符串，否则无返回值。
  • 过滤器：HTML 输出可通过 'the_date' 过滤，日期字符串可通过 'get_the_date' 过滤。
  • 相关函数：get_the_date() 用于检索日期，the_time() 可用于同一天多篇文章显示日期。

代码示例

// 默认用法：显示日期，格式基于 'date_format' 选项
the_date();

// 自定义格式：显示为 '2007-07-23' 格式，并包装在 <h3> 标签中
the_date('Y-m-d', '<h3>', '</h3>');

// 返回日期字符串：不直接输出，赋值给变量
$my_date = the_date('', '', '', false);
echo $my_date;

注意事项

  • 同一天多篇文章：the_date() 只显示一次日期，如需每篇文章都显示日期，应使用 the_time() 或 get_the_date()。
  • 日期格式：遵循 PHP date() 函数格式，如 'Y-m-d' 表示年-月-日。
  • 过滤器应用：可通过 apply_filters('the_date', ...) 自定义输出。
📄 原文内容

Displays or retrieves the date of the post (once per date).

Description

Will only output the date if the current post’s date is different from the previous one output.

i.e. Only one date listing will show per day worth of posts shown in the loop, even if the function is called several times for each post.

HTML output can be filtered with ‘the_date’.
Date string output can be filtered with ‘get_the_date’.

Parameters

$formatstringoptional
PHP date format. Defaults to the 'date_format' option.
$beforestringoptional
Output before the date. Default empty.
$afterstringoptional
Output after the date. Default empty.
$displaybooloptional
Whether to echo the date or return it.

Default:true

Return

string|void String if retrieving.

Source

function the_date( $format = '', $before = '', $after = '', $display = true ) {
	global $currentday, $previousday;

	$the_date = '';

	if ( is_new_day() ) {
		$the_date    = $before . get_the_date( $format ) . $after;
		$previousday = $currentday;
	}

	/**
	 * Filters the date of the post, for display.
	 *
	 * @since 0.71
	 *
	 * @param string $the_date The formatted date string.
	 * @param string $format   PHP date format.
	 * @param string $before   HTML output before the date.
	 * @param string $after    HTML output after the date.
	 */
	$the_date = apply_filters( 'the_date', $the_date, $format, $before, $after );

	if ( $display ) {
		echo $the_date;
	} else {
		return $the_date;
	}
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘the_date’, string $the_date, string $format, string $before, string $after )

Filters the date of the post, for display.

Uses Description
get_the_date()wp-includes/general-template.php

Retrieves the date of the post.
is_new_day()wp-includes/functions.php

Determines whether the publish date of the current post in the loop is different from the publish date of the previous post in the loop.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.

Show 1 moreShow less

Changelog

Version Description
0.71 Introduced.

User Contributed Notes

  4. Skip to note 9 content


    Ruhul Amin


    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

    As stated in the documentation if there are multiple posts from the same day, it will only show once.
    To show the date for posts published under same day, we should use the template tag the_time() or get_the_date() with a date-specific format string.

     
// get_the_date() return the date doesn't echo the date, so have to echo to show it

// or use the_time() with date-specific format

    Both functions takes an optional parameter which follows the PHP Date Format