wp_dashboard_recent_posts()
云策文档标注
概述
wp_dashboard_recent_posts() 函数用于在 WordPress 仪表板中生成“即将发布”和“最近发布”的帖子列表。它基于传入的参数构建 WP_Query 查询，并输出格式化的 HTML 内容。
关键要点
- 函数接受一个数组参数 $args，用于控制查询和显示设置，包括最大帖子数、状态、排序、标题和容器 ID。
- 内部使用 WP_Query 执行查询，支持通过 dashboard_recent_posts_query_args 过滤器修改查询参数。
- 根据帖子发布日期动态显示相对时间（如“今天”、“明天”或格式化日期），并为可编辑用户提供编辑链接。
- 返回布尔值：如果找到帖子则返回 true，否则返回 false。
代码示例
function wp_dashboard_recent_posts( $args ) {
$query_args = array(
'post_type' => 'post',
'post_status' => $args['status'],
'orderby' => 'date',
'order' => $args['order'],
'posts_per_page' => (int) $args['max'],
'no_found_rows' => true,
'cache_results' => true,
'perm' => ( 'future' === $args['status'] ) ? 'editable' : 'readable',
);
$query_args = apply_filters( 'dashboard_recent_posts_query_args', $query_args );
$posts = new WP_Query( $query_args );
if ( $posts->have_posts() ) {
// 输出 HTML 内容
while ( $posts->have_posts() ) {
$posts->the_post();
// 处理时间和链接
}
wp_reset_postdata();
return true;
} else {
return false;
}
}注意事项
- 函数默认查询 post 类型的帖子，状态和排序由 $args 参数控制。
- 使用 wp_reset_postdata() 重置全局 $post 数据，确保主查询不受影响。
- 输出内容包含国际化字符串，支持多语言环境。
原文内容
Generates Publishing Soon and Recently Published sections.
Parameters
$argsarrayrequired-
An array of query and display arguments.
maxintNumber of posts to display.statusstringPost status.orderstringDesignates ascending ('ASC') or descending ('DESC') order.titlestringSection title.idstringThe container id.
Source
function wp_dashboard_recent_posts( $args ) {
$query_args = array(
'post_type' => 'post',
'post_status' => $args['status'],
'orderby' => 'date',
'order' => $args['order'],
'posts_per_page' => (int) $args['max'],
'no_found_rows' => true,
'cache_results' => true,
'perm' => ( 'future' === $args['status'] ) ? 'editable' : 'readable',
);
/**
* Filters the query arguments used for the Recent Posts widget.
*
* @since 4.2.0
*
* @param array $query_args The arguments passed to WP_Query to produce the list of posts.
*/
$query_args = apply_filters( 'dashboard_recent_posts_query_args', $query_args );
$posts = new WP_Query( $query_args );
if ( $posts->have_posts() ) {
echo '<div id="' . $args['id'] . '" class="activity-block">';
echo '<h3>' . $args['title'] . '</h3>';
echo '<ul>';
$today = current_time( 'Y-m-d' );
$tomorrow = current_datetime()->modify( '+1 day' )->format( 'Y-m-d' );
$year = current_time( 'Y' );
while ( $posts->have_posts() ) {
$posts->the_post();
$time = get_the_time( 'U' );
if ( gmdate( 'Y-m-d', $time ) === $today ) {
$relative = __( 'Today' );
} elseif ( gmdate( 'Y-m-d', $time ) === $tomorrow ) {
$relative = __( 'Tomorrow' );
} elseif ( gmdate( 'Y', $time ) !== $year ) {
/* translators: Date and time format for recent posts on the dashboard, from a different calendar year, see https://www.php.net/manual/datetime.format.php */
$relative = date_i18n( __( 'M jS Y' ), $time );
} else {
/* translators: Date and time format for recent posts on the dashboard, see https://www.php.net/manual/datetime.format.php */
$relative = date_i18n( __( 'M jS' ), $time );
}
// Use the post edit link for those who can edit, the permalink otherwise.
$recent_post_link = current_user_can( 'edit_post', get_the_ID() ) ? get_edit_post_link() : get_permalink();
$draft_or_post_title = _draft_or_post_title();
printf(
'<li><span>%1$s</span> <a href="%2$s" aria-label="%3$s">%4$s</a></li>',
/* translators: 1: Relative date, 2: Time. */
sprintf( _x( '%1$s, %2$s', 'dashboard' ), $relative, get_the_time() ),
$recent_post_link,
/* translators: %s: Post title. */
esc_attr( sprintf( __( 'Edit “%s”' ), $draft_or_post_title ) ),
$draft_or_post_title
);
}
echo '</ul>';
echo '</div>';
} else {
return false;
}
wp_reset_postdata();
return true;
}
Hooks
- apply_filters( ‘dashboard_recent_posts_query_args’, array $query_args )
-
Filters the query arguments used for the Recent Posts widget.
Changelog
| Version | Description |
|---|---|
| 3.8.0 | Introduced. |