get_post_class()
云策文档标注
概述
get_post_class() 函数用于检索文章容器元素的 CSS 类名数组,自动根据文章属性(如缩略图、置顶状态、分类等)生成类名,并支持通过参数和过滤器进行自定义。
关键要点
- 函数返回一个字符串数组,包含基于文章 ID、类型、状态、格式、缩略图、置顶状态、分类等自动生成的类名。
- 参数 $css_class 可选,用于添加额外的类名,可以是空格分隔的字符串或数组;$post 可选,指定文章 ID 或对象,默认为当前文章。
- 内置类名包括 'post-{ID}'、'type-{post_type}'、'status-{post_status}'、'hentry'(用于 hAtom 合规性),以及根据分类生成的类名(如 'category-foo' 或 'tag-bar')。
- 支持过滤器 'post_class' 和 'post_class_taxonomies',允许开发者修改类名列表或分类生成逻辑。
- 在循环中使用时,建议显式传递 $css_class 参数以避免类名重复问题。
代码示例
// 默认用法(在循环中)
$classes = get_post_class();
echo implode(' ', $classes);
// 传递自定义类名
$post_class = get_post_class(array('my-class'), $post_id);
var_dump($post_class);注意事项
- 函数内部使用 esc_attr() 对类名进行转义,确保安全性。
- 对于 'post_tag' 分类,类名前缀为 'tag-' 而非 'post_tag-',以保持向后兼容性。
- 在管理界面(is_admin() 为 true)时,不会添加文章类型类名,但会添加 'status-sticky' 类名。
原文内容
Retrieves an array of the class names for the post container element.
Description
The class names are many:
- If the post has a post thumbnail,
has-post-thumbnailis added as a class. - If the post is sticky, then the
stickyclass name is added. - The class
hentryis always added to each post. - For each taxonomy that the post belongs to, a class will be added of the format
{$taxonomy}-{$slug}, e.g.category-fooormy_custom_taxonomy-bar.
Thepost_tagtaxonomy is a special case; the class has thetag-prefix instead ofpost_tag-.
All class names are passed through the filter, ‘post_class’, followed by $css_class parameter value, with the post ID as the last parameter.
Parameters
$css_classstring|string[]optional-
Space-separated string or array of class names to add to the class list. Default empty.
$postint|WP_Postoptional-
Post ID or post object.
Default:
null
Source
function get_post_class( $css_class = '', $post = null ) {
$post = get_post( $post );
$classes = array();
if ( $css_class ) {
if ( ! is_array( $css_class ) ) {
$css_class = preg_split( '#s+#', $css_class );
}
$classes = array_map( 'esc_attr', $css_class );
} else {
// Ensure that we always coerce class to being an array.
$css_class = array();
}
if ( ! $post ) {
return $classes;
}
$classes[] = 'post-' . $post->ID;
if ( ! is_admin() ) {
$classes[] = $post->post_type;
}
$classes[] = 'type-' . $post->post_type;
$classes[] = 'status-' . $post->post_status;
// Post Format.
if ( post_type_supports( $post->post_type, 'post-formats' ) ) {
$post_format = get_post_format( $post->ID );
if ( $post_format && ! is_wp_error( $post_format ) ) {
$classes[] = 'format-' . sanitize_html_class( $post_format );
} else {
$classes[] = 'format-standard';
}
}
$post_password_required = post_password_required( $post->ID );
// Post requires password.
if ( $post_password_required ) {
$classes[] = 'post-password-required';
} elseif ( ! empty( $post->post_password ) ) {
$classes[] = 'post-password-protected';
}
// Post thumbnails.
if ( current_theme_supports( 'post-thumbnails' ) && has_post_thumbnail( $post->ID ) && ! is_attachment( $post ) && ! $post_password_required ) {
$classes[] = 'has-post-thumbnail';
}
// Sticky for Sticky Posts.
if ( is_sticky( $post->ID ) ) {
if ( is_home() && ! is_paged() ) {
$classes[] = 'sticky';
} elseif ( is_admin() ) {
$classes[] = 'status-sticky';
}
}
// hentry for hAtom compliance.
$classes[] = 'hentry';
// All public taxonomies.
$taxonomies = get_taxonomies( array( 'public' => true ) );
/**
* Filters the taxonomies to generate classes for each individual term.
*
* Default is all public taxonomies registered to the post type.
*
* @since 6.1.0
*
* @param string[] $taxonomies List of all taxonomy names to generate classes for.
* @param int $post_id The post ID.
* @param string[] $classes An array of post class names.
* @param string[] $css_class An array of additional class names added to the post.
*/
$taxonomies = apply_filters( 'post_class_taxonomies', $taxonomies, $post->ID, $classes, $css_class );
foreach ( (array) $taxonomies as $taxonomy ) {
if ( is_object_in_taxonomy( $post->post_type, $taxonomy ) ) {
foreach ( (array) get_the_terms( $post->ID, $taxonomy ) as $term ) {
if ( empty( $term->slug ) ) {
continue;
}
$term_class = sanitize_html_class( $term->slug, $term->term_id );
if ( is_numeric( $term_class ) || ! trim( $term_class, '-' ) ) {
$term_class = $term->term_id;
}
// 'post_tag' uses the 'tag' prefix for backward compatibility.
if ( 'post_tag' === $taxonomy ) {
$classes[] = 'tag-' . $term_class;
} else {
$classes[] = sanitize_html_class( $taxonomy . '-' . $term_class, $taxonomy . '-' . $term->term_id );
}
}
}
}
$classes = array_map( 'esc_attr', $classes );
/**
* Filters the list of CSS class names for the current post.
*
* @since 2.7.0
*
* @param string[] $classes An array of post class names.
* @param string[] $css_class An array of additional class names added to the post.
* @param int $post_id The post ID.
*/
$classes = apply_filters( 'post_class', $classes, $css_class, $post->ID );
return array_unique( $classes );
}
Hooks
- apply_filters( ‘post_class’, string[] $classes, string[] $css_class, int $post_id )
-
Filters the list of CSS class names for the current post.
- apply_filters( ‘post_class_taxonomies’, string[] $taxonomies, int $post_id, string[] $classes, string[] $css_class )
-
Filters the taxonomies to generate classes for each individual term.
Skip to note 4 content
flomei
If you are writing custom themes and are using this function, make sure to pass the first parameter, although it might be empty.
$classes = get_post_class( '', $post->ID ); # later... echo '<article class="' . esc_attr( implode( ' ', $classes ) ) . '" itemscope="" itemtype="<a href="http://schema.org/Article">" rel="nofollow ugc">http://schema.org/Article"></a>;';If you omit this parameter (in a loop), all posts of your listing will have the same classes.
Skip to note 5 content
Codex
Default Usage
Default example without params and global
$postobject available (or in the loop).var_dump( get_post_class() ); /*Output:*/ array() { 0 => string 'post-[ID]' (length=7) 1 => string '[post_type]' (length=4) 2 => string 'type-[post_type]' (length=9) 3 => string 'status-[post_status]' (length=14) 4 => string 'format-[post_format]' (length=15) 5 => string 'hentry' (length=6) 6 => string 'category-[...]' X => string 'tag-[...]' }Skip to note 6 content
Codex
With Params
Passing an array of your own classes.
/* Optional: global $post; $postID = $post->ID; OR $postID = get_the_ID(); $postClass = get_post_class(array('my-class')); OR $postClass = get_post_class(array('my-class'), (int) $postID); */ $post_class = get_post_class( array( 'my-class' ) ); var_dump( $post_class ); /* Output: array 0 => string 'post-[ID]' (length=7) 1 => string '[post_type]' (length=4) 2 => string 'type-[post_type]' (length=9) 3 => string 'status-[post_status]' (length=14) 4 => string 'format-[post_format]' (length=15) 5 => string 'hentry' (length=6) 6 => string 'category-[...]' ... X => string 'tag-[...]' ... X+1 => string 'my-class' (length=8) ... */