body_class
云策文档标注
概述
body_class 是一个 WordPress 过滤器，用于修改当前文章或页面的 CSS body 类名数组。开发者可以通过此 Hook 动态添加、移除或调整 body 元素的类，以实现基于页面上下文、用户状态等的样式定制。
关键要点
- body_class 过滤器接收两个参数：$classes（现有类名数组）和 $css_class（额外添加的类名数组）。
- 过滤器函数必须返回处理后的类名数组，否则会清除所有类，可能严重影响网站视觉状态。
- 常用于添加基于页面类型（如 is_home、is_single）、用户角色、设备检测等的自定义类。
- 相关函数 get_body_class() 用于检索 body 元素的类名数组。
- 自 WordPress 2.8.0 版本引入。
代码示例
// 添加自定义类
add_filter( 'body_class', function( $classes ) {
return array_merge( $classes, array( 'class-name' ) );
} );
// 移除现有类
add_filter( 'body_class', function( $classes ) {
if ( isset( $classes['class-to-remove'] ) ) {
unset( $classes['class-to-remove'] );
}
return $classes;
} );
// 基于条件添加多个类
add_filter( 'body_class', 'custom_body_class', 10, 2 );
function custom_body_class( $classes, $css_class ) {
if ( is_home() ) {
$classes[] = 'home-page';
}
if ( is_single() ) {
$classes[] = 'single-post';
}
return $classes;
}注意事项
- 确保过滤器函数始终返回 $classes 数组，避免意外清除类。
- 使用条件函数（如 is_home、is_user_logged_in）时，需确保其正确性以添加合适的类。
- 在主题的 functions.php 文件中添加代码，或通过插件实现。
原文内容
Filters the list of CSS body class names for the current post or page.
Parameters
$classesstring[]-
An array of body class names.
$css_classstring[]-
An array of additional class names added to the body.
Source
$classes = apply_filters( 'body_class', $classes, $css_class );
Changelog
| Version | Description |
|---|---|
| 2.8.0 | Introduced. |
Skip to note 5 content
Drew Jaynes
Add New Classes
You can add additional body classes by filtering the ‘body_class’ hook.
To add the following to the WordPress Theme functions.php file, changing my_class_names and class-name to meet your needs:
// Add specific CSS class by filter. add_filter( 'body_class', function( $classes ) { return array_merge( $classes, array( 'class-name' ) ); } );Skip to note 6 content
Maarten Menten
Following function adds CSS classes that may be useful
function my_body_class( $classes ) { $include = array ( // browsers/devices (<a href="https://codex.wordpress.org/Global_Variables" rel="nofollow ugc">https://codex.wordpress.org/Global_Variables</a>) 'is-iphone' => $GLOBALS['is_iphone'], 'is-chrome' => $GLOBALS['is_chrome'], 'is-safari' => $GLOBALS['is_safari'], 'is-ns4' => $GLOBALS['is_NS4'], 'is-opera' => $GLOBALS['is_opera'], 'is-mac-ie' => $GLOBALS['is_macIE'], 'is-win-ie' => $GLOBALS['is_winIE'], 'is-gecko' => $GLOBALS['is_gecko'], 'is-lynx' => $GLOBALS['is_lynx'], 'is-ie' => $GLOBALS['is_IE'], 'is-edge' => $GLOBALS['is_edge'], // WP Query (already included by default, but nice to have same format) 'is-archive' => is_archive(), 'is-post_type_archive' => is_post_type_archive(), 'is-attachment' => is_attachment(), 'is-author' => is_author(), 'is-category' => is_category(), 'is-tag' => is_tag(), 'is-tax' => is_tax(), 'is-date' => is_date(), 'is-day' => is_day(), 'is-feed' => is_feed(), 'is-comment-feed' => is_comment_feed(), 'is-front-page' => is_front_page(), 'is-home' => is_home(), 'is-privacy-policy' => is_privacy_policy(), 'is-month' => is_month(), 'is-page' => is_page(), 'is-paged' => is_paged(), 'is-preview' => is_preview(), 'is-robots' => is_robots(), 'is-search' => is_search(), 'is-single' => is_single(), 'is-singular' => is_singular(), 'is-time' => is_time(), 'is-trackback' => is_trackback(), 'is-year' => is_year(), 'is-404' => is_404(), 'is-embed' => is_embed(), // Mobile 'is-mobile' => wp_is_mobile(), 'is-desktop' => ! wp_is_mobile(), // Common 'has-blocks' => function_exists( 'has_blocks' ) && has_blocks(), ); // Sidebars foreach ( $GLOBALS['wp_registered_sidebars'] as $sidebar ) { $include[ "is-sidebar-{$sidebar['id']}" ] = is_active_sidebar( $sidebar['id'] ); } // Add classes foreach ( $include as $class => $do_include ) { if ( $do_include ) $classes[ $class ] = $class; } // Return return $classes; } add_filter( 'body_class', 'my_body_class' );Skip to note 7 content
Drew Jaynes
Remove Classes
Remove an existing body class by un-setting the key from the
$classesarray.// Removes a class from the body_class array. add_filter( 'body_class', function( $classes ) { if ( isset( $classes['class-to-remove'] ) ) { unset( $classes['class-to-remove'] ); } return $classes; } );Skip to note 8 content
Noruzzaman
The body_class filter allows you to modify the array of classes applied to the tag. This can be useful for styling pages differently based on their context.
Open functions.php: Go to your theme directory and open functions.php. This file is where you add custom functions and hooks.
add_filter( 'body_class', 'custom_body_class', 10, 2 ); function custom_body_class( $classes, $css_class ) { // Example condition 1: Add class for home page if ( is_home() ) { $classes[] = 'home-page'; } // Example condition 2: Add class for single posts if ( is_single() ) { $classes[] = 'single-post'; } // Example condition 3: Add class for pages using a specific template if ( is_page_template( 'custom-template.php' ) ) { $classes[] = 'custom-template'; } // Example condition 4: Add class for logged-in users if ( is_user_logged_in() ) { $classes[] = 'logged-in'; } // Example condition 5: Add class based on user role if ( current_user_can( 'administrator' ) ) { $classes[] = 'admin-user'; } return $classes; }Understanding the Conditions
1. is_home() : Adds the home-page class if the current page is the home page.
2. is_single() : Adds the single-post class if the current page is a single post.
3. is_page_template() : Adds the custom-template class if the page is using a specific template.
4. is_user_logged_in() : Adds the logged-in class if the user is logged in.
5. current_user_can() : Adds the admin-user class if the current user has the ‘administrator’ role.