get_calendar()

💡 云策文档标注

概述

get_calendar() 是 WordPress 中用于生成并显示日历的函数，该日历会将有文章的日期显示为链接。函数支持缓存机制以提高性能，并允许通过参数自定义输出行为。

关键要点

函数生成一个日历，其中包含文章的日期会以链接形式显示，无文章的月份则不显示日历。
支持参数配置，包括 $initial（是否使用日历名称缩写）、$display（是否直接输出或返回 HTML）和 $post_type（文章类型，默认为 'post'）。
使用缓存机制，基于参数和全局变量生成缓存键，避免重复计算，提升效率。
包含两个过滤器：get_calendar_args 用于在参数使用前修改，get_calendar 用于过滤最终的 HTML 输出。
函数返回类型取决于 $display 参数：若为 true 则直接输出并返回 void，若为 false 则返回日历的 HTML 字符串。

代码示例

// 直接显示日历，使用默认参数
get_calendar();

// 返回日历的 HTML 字符串，不直接显示
$calendar_html = get_calendar( array( 'display' => false ) );

// 自定义文章类型和初始设置
get_calendar( array( 'post_type' => 'event', 'initial' => false ) );

注意事项

函数依赖于全局变量如 $m、$monthnum、$year 等来确定当前月份和年份，需确保这些变量在调用前已正确设置。
缓存键排除 $display 参数，因为缓存内容相同，仅输出方式不同。
如果指定 $post_type 不存在，会自动回退到默认的 'post'。
从版本 6.8.0 开始，参数以数组形式传递，同时保持对旧版 $initial 和 $display 参数的向后兼容。

📄 原文内容

Displays calendar with days that have posts as links.

Description

The calendar is cached, which will be retrieved, if it exists. If there are no posts for the month, then it will not be displayed.

Parameters

$argsarrayoptional

Arguments for the get_calendar function.

initial bool
Whether to use initial calendar names. Default true.
display bool
Whether to display the calendar output. Default true.
post_type string
Optional. Post type. Default 'post'.

Default:array()

Return

void|string Void if $display argument is true, calendar HTML if $display is false.

Source

function get_calendar( $args = array() ) {
	global $wpdb, $m, $monthnum, $year, $wp_locale, $posts;

	$defaults = array(
		'initial'   => true,
		'display'   => true,
		'post_type' => 'post',
	);

	$original_args = func_get_args();
	$args          = array();

	if ( ! empty( $original_args ) ) {
		if ( ! is_array( $original_args[0] ) ) {
			if ( isset( $original_args[0] ) && is_bool( $original_args[0] ) ) {
				$defaults['initial'] = $original_args[0];
			}
			if ( isset( $original_args[1] ) && is_bool( $original_args[1] ) ) {
				$defaults['display'] = $original_args[1];
			}
		} else {
			$args = $original_args[0];
		}
	}

	/**
	 * Filter the `get_calendar` function arguments before they are used.
	 *
	 * @since 6.8.0
	 *
	 * @param array $args {
	 *     Optional. Arguments for the `get_calendar` function.
	 *
	 *     @type bool   $initial   Whether to use initial calendar names. Default true.
	 *     @type bool   $display   Whether to display the calendar output. Default true.
	 *     @type string $post_type Optional. Post type. Default 'post'.
	 * }
	 */
	$args = apply_filters( 'get_calendar_args', wp_parse_args( $args, $defaults ) );

	if ( ! post_type_exists( $args['post_type'] ) ) {
		$args['post_type'] = 'post';
	}

	$w = 0;
	if ( isset( $_GET['w'] ) ) {
		$w = (int) $_GET['w'];
	}

	/*
	 * Normalize the cache key.
	 *
	 * The following ensures the same cache key is used for the same parameter
	 * and parameter equivalents. This prevents `post_type > post, initial > true`
	 * from generating a different key from the same values in the reverse order.
	 *
	 * `display` is excluded from the cache key as the cache contains the same
	 * HTML regardless of this function's need to echo or return the output.
	 *
	 * The global values contain data generated by the URL query string variables.
	 */
	$cache_args = $args;
	unset( $cache_args['display'] );

	$cache_args['globals'] = array(
		'm'        => $m,
		'monthnum' => $monthnum,
		'year'     => $year,
		'week'     => $w,
	);

	wp_recursive_ksort( $cache_args );
	$key   = md5( serialize( $cache_args ) );
	$cache = wp_cache_get( 'get_calendar', 'calendar' );

	if ( $cache && is_array( $cache ) && isset( $cache[ $key ] ) ) {
		/** This filter is documented in wp-includes/general-template.php */
		$output = apply_filters( 'get_calendar', $cache[ $key ], $args );

		if ( $args['display'] ) {
			echo $output;
			return;
		}

		return $output;
	}

	if ( ! is_array( $cache ) ) {
		$cache = array();
	}

	$post_type = $args['post_type'];

	// Quick check. If we have no posts at all, abort!
	if ( ! $posts ) {
		$gotsome = $wpdb->get_var(
			$wpdb->prepare(
				"SELECT 1 as test
				FROM $wpdb->posts
				WHERE post_type = %s
				AND post_status = 'publish'
				LIMIT 1",
				$post_type
			)
		);

		if ( ! $gotsome ) {
			$cache[ $key ] = '';
			wp_cache_set( 'get_calendar', $cache, 'calendar' );
			return;
		}
	}

	// week_begins = 0 stands for Sunday.
	$week_begins = (int) get_option( 'start_of_week' );

	// Let's figure out when we are.
	if ( ! empty( $monthnum ) && ! empty( $year ) ) {
		$thismonth = (int) $monthnum;
		$thisyear  = (int) $year;
	} elseif ( ! empty( $w ) ) {
		// We need to get the month from MySQL.
		$thisyear = (int) substr( $m, 0, 4 );
		// It seems MySQL's weeks disagree with PHP's.
		$d         = ( ( $w - 1 ) * 7 ) + 6;
		$thismonth = (int) $wpdb->get_var(
			$wpdb->prepare(
				"SELECT DATE_FORMAT((DATE_ADD('%d0101', INTERVAL %d DAY) ), '%%m')",
				$thisyear,
				$d
			)
		);
	} elseif ( ! empty( $m ) ) {
		$thisyear = (int) substr( $m, 0, 4 );
		if ( strlen( $m ) < 6 ) {
			$thismonth = 1;
		} else {
			$thismonth = (int) substr( $m, 4, 2 );
		}
	} else {
		$thisyear  = (int) current_time( 'Y' );
		$thismonth = (int) current_time( 'm' );
	}

	$unixmonth = mktime( 0, 0, 0, $thismonth, 1, $thisyear );
	$last_day  = gmdate( 't', $unixmonth );

	// Get the next and previous month and year with at least one post.
	$previous = $wpdb->get_row(
		$wpdb->prepare(
			"SELECT MONTH(post_date) AS month, YEAR(post_date) AS year
			FROM $wpdb->posts
			WHERE post_date < '%d-%d-01'
			AND post_type = %s AND post_status = 'publish'
			ORDER BY post_date DESC
			LIMIT 1",
			$thisyear,
			zeroise( $thismonth, 2 ),
			$post_type
		)
	);

	$next = $wpdb->get_row(
		$wpdb->prepare(
			"SELECT MONTH(post_date) AS month, YEAR(post_date) AS year
			FROM $wpdb->posts
			WHERE post_date > '%d-%d-%d 23:59:59'
			AND post_type = %s AND post_status = 'publish'
			ORDER BY post_date ASC
			LIMIT 1",
			$thisyear,
			zeroise( $thismonth, 2 ),
			$last_day,
			$post_type
		)
	);

	/* translators: Calendar caption: 1: Month name, 2: 4-digit year. */
	$calendar_caption = _x( '%1$s %2$s', 'calendar caption' );
	$calendar_output  = '<table id="wp-calendar" class="wp-calendar-table">
	<caption>' . sprintf(
		$calendar_caption,
		$wp_locale->get_month( $thismonth ),
		gmdate( 'Y', $unixmonth )
	) . '</caption>
	<thead>
	<tr>';

	$myweek = array();

	for ( $wdcount = 0; $wdcount <= 6; $wdcount++ ) {
		$myweek[] = $wp_locale->get_weekday( ( $wdcount + $week_begins ) % 7 );
	}

	foreach ( $myweek as $wd ) {
		$day_name         = $args['initial'] ? $wp_locale->get_weekday_initial( $wd ) : $wp_locale->get_weekday_abbrev( $wd );
		$wd               = esc_attr( $wd );
		$calendar_output .= "ntt<th scope="col" aria-label="$wd">$day_name</th>";
	}

	$calendar_output .= '
	</tr>
	</thead>
	<tbody>
	<tr>';

	$daywithpost = array();

	// Get days with posts.
	$dayswithposts = $wpdb->get_results(
		$wpdb->prepare(
			"SELECT DISTINCT DAYOFMONTH(post_date)
			FROM $wpdb->posts WHERE post_date >= '%d-%d-01 00:00:00'
			AND post_type = %s AND post_status = 'publish'
			AND post_date <= '%d-%d-%d 23:59:59'",
			$thisyear,
			zeroise( $thismonth, 2 ),
			$post_type,
			$thisyear,
			zeroise( $thismonth, 2 ),
			$last_day
		),
		ARRAY_N
	);

	if ( $dayswithposts ) {
		foreach ( (array) $dayswithposts as $daywith ) {
			$daywithpost[] = (int) $daywith[0];
		}
	}

	// See how much we should pad in the beginning.
	$pad = calendar_week_mod( (int) gmdate( 'w', $unixmonth ) - $week_begins );
	if ( $pad > 0 ) {
		$calendar_output .= "ntt" . '<td colspan="' . esc_attr( $pad ) . '" class="pad"> </td>';
	}

	$newrow      = false;
	$daysinmonth = (int) gmdate( 't', $unixmonth );

	for ( $day = 1; $day <= $daysinmonth; ++$day ) {
		if ( $newrow ) {
			$calendar_output .= "nt</tr>nt<tr>ntt";
		}

		$newrow = false;

		if ( (int) current_time( 'j' ) === $day
			&& (int) current_time( 'm' ) === $thismonth
			&& (int) current_time( 'Y' ) === $thisyear
		) {
			$calendar_output .= '<td id="today">';
		} else {
			$calendar_output .= '<td>';
		}

		if ( in_array( $day, $daywithpost, true ) ) {
			// Any posts today?
			$date_format = gmdate( _x( 'F j, Y', 'daily archives date format' ), strtotime( "{$thisyear}-{$thismonth}-{$day}" ) );
			/* translators: Post calendar label. %s: Date. */
			$label            = sprintf( __( 'Posts published on %s' ), $date_format );
			$calendar_output .= sprintf(
				'<a href="%s" aria-label="%s">%s</a>',
				get_day_link( $thisyear, $thismonth, $day ),
				esc_attr( $label ),
				$day
			);
		} else {
			$calendar_output .= $day;
		}

		$calendar_output .= '</td>';

		if ( 6 === (int) calendar_week_mod( (int) gmdate( 'w', mktime( 0, 0, 0, $thismonth, $day, $thisyear ) ) - $week_begins ) ) {
			$newrow = true;
		}
	}

	$pad = 7 - calendar_week_mod( (int) gmdate( 'w', mktime( 0, 0, 0, $thismonth, $day, $thisyear ) ) - $week_begins );
	if ( 0 < $pad && $pad < 7 ) {
		$calendar_output .= "ntt" . '<td class="pad" colspan="' . esc_attr( $pad ) . '"> </td>';
	}

	$calendar_output .= "nt</tr>nt</tbody>";

	$calendar_output .= "nt</table>";

	$calendar_output .= '<nav aria-label="' . __( 'Previous and next months' ) . '" class="wp-calendar-nav">';

	if ( $previous ) {
		$calendar_output .= "ntt" . sprintf(
			'<span class="wp-calendar-nav-prev"><a href="%1$s">« %2$s</a></span>',
			get_month_link( $previous->year, $previous->month ),
			$wp_locale->get_month_abbrev( $wp_locale->get_month( $previous->month ) )
		);
	} else {
		$calendar_output .= "ntt" . '<span class="wp-calendar-nav-prev"> </span>';
	}

	$calendar_output .= "ntt" . '<span class="pad"> </span>';

	if ( $next ) {
		$calendar_output .= "ntt" . sprintf(
			'<span class="wp-calendar-nav-next"><a href="%1$s">%2$s »</a></span>',
			get_month_link( $next->year, $next->month ),
			$wp_locale->get_month_abbrev( $wp_locale->get_month( $next->month ) )
		);
	} else {
		$calendar_output .= "ntt" . '<span class="wp-calendar-nav-next"> </span>';
	}

	$calendar_output .= '
	</nav>';

	$cache[ $key ] = $calendar_output;
	wp_cache_set( 'get_calendar', $cache, 'calendar' );

	/**
	 * Filters the HTML calendar output.
	 *
	 * @since 3.0.0
	 * @since 6.8.0 Added the `$args` parameter.
	 *
	 * @param string $calendar_output HTML output of the calendar.
	 * @param array  $args {
	 *     Optional. Array of display arguments.
	 *
	 *     @type bool   $initial   Whether to use initial calendar names. Default true.
	 *     @type bool   $display   Whether to display the calendar output. Default true.
	 *     @type string $post_type Optional. Post type. Default 'post'.
	 * }
	 */
	$calendar_output = apply_filters( 'get_calendar', $calendar_output, $args );

	if ( $args['display'] ) {
		echo $calendar_output;
		return;
	}

	return $calendar_output;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘get_calendar’, string $calendar_output, array $args ): Filters the HTML calendar output.
apply_filters( ‘get_calendar_args’, array $args ): Filter the get_calendar function arguments before they are used.

Uses	Description
wp_recursive_ksort()`wp-includes/functions.php`	Sorts the keys of an array alphabetically.
wp_cache_set()`wp-includes/cache.php`	Saves the data to the cache.
zeroise()`wp-includes/formatting.php`	Add leading zeros when necessary.
calendar_week_mod()`wp-includes/general-template.php`	Gets number of days since the start of the week.
current_time()`wp-includes/functions.php`	Retrieves the current time based on specified type.
WP_Locale::get_month()`wp-includes/class-wp-locale.php`	Retrieves the full translated month by month number.
WP_Locale::get_month_abbrev()`wp-includes/class-wp-locale.php`	Retrieves translated version of month abbreviation string.
WP_Locale::get_weekday()`wp-includes/class-wp-locale.php`	Retrieves the full translated weekday word.
WP_Locale::get_weekday_initial()`wp-includes/class-wp-locale.php`	Retrieves the translated weekday initial.
WP_Locale::get_weekday_abbrev()`wp-includes/class-wp-locale.php`	Retrieves the translated weekday abbreviation.
get_day_link()`wp-includes/link-template.php`	Retrieves the permalink for the day archives with year and month.
get_month_link()`wp-includes/link-template.php`	Retrieves the permalink for the month archives with year.
post_type_exists()`wp-includes/post.php`	Determines whether a post type is registered.
wpdb::get_row()`wp-includes/class-wpdb.php`	Retrieves one row from the database.
wp_cache_get()`wp-includes/cache.php`	Retrieves the cache contents from the cache by key and group.
_x()`wp-includes/l10n.php`	Retrieves translated string with gettext context.
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
esc_attr()`wp-includes/formatting.php`	Escaping for HTML attributes.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.
get_option()`wp-includes/option.php`	Retrieves an option value based on an option name.
wpdb::get_var()`wp-includes/class-wpdb.php`	Retrieves one value from the database.
wpdb::get_results()`wp-includes/class-wpdb.php`	Retrieves an entire SQL result set from the database (i.e., many rows).
wpdb::prepare()`wp-includes/class-wpdb.php`	Prepares a SQL query for safe execution.

Show 19 more Show less

Used by	Description
WP_Widget_Calendar::widget()`wp-includes/widgets/class-wp-widget-calendar.php`	Outputs the content for the current Calendar widget instance.

Changelog

Version	Description
6.8.0	Added the `$args` parameter, with backward compatibility for the replaced `$initial` and `$display` parameters.
1.0.0	Introduced.

云策 WordPress 开发者社区

函数文档

get_calendar()

概述

关键要点

代码示例

注意事项

Description

Parameters

Return

Source

Hooks

Changelog

函数文档

概述

关键要点

代码示例

注意事项

Description

Parameters

Return

Source

Hooks

Related

Changelog