the_content
云策文档标注
概述
the_content 是一个 WordPress 过滤器，用于在文章内容从数据库检索后、显示到屏幕前对其进行修改。开发者可以通过此 Hook 添加自定义内容或处理现有内容，但需注意条件检查以避免影响非主循环。
关键要点
- the_content 过滤器允许修改文章内容，参数为 $content 字符串。
- 使用时建议结合 is_main_query()、in_the_loop() 和 is_singular() 等条件函数，确保仅在主循环中应用过滤。
- 通过 add_filter 的优先级参数可控制过滤器执行顺序，影响短代码处理时机。
- 该过滤器不适用于 get_the_content() 函数调用。
代码示例
add_filter( 'the_content', 'filter_the_content_in_the_main_loop', 1 );
function filter_the_content_in_the_main_loop( $content ) {
if ( is_singular() && in_the_loop() && is_main_query() ) {
return $content . esc_html__( 'I’m filtering the content inside the main loop', 'wporg');
}
return $content;
}注意事项
- 避免在侧边栏、页脚等自定义循环中无意过滤内容，务必使用条件检查。
- 优先级设置影响过滤器执行顺序，默认优先级为 10，短代码在此之后处理；较高优先级（如 99）则短代码先处理。
- 文档中的“Used by”列表可能随 WordPress 版本变化，建议参考最新版本文档。
原文内容
Filters the post content.
Parameters
$contentstring-
Content of the current post.
Source
$content = apply_filters( 'the_content', $content );
Changelog
| Version | Description |
|---|---|
| 0.71 | Introduced. |
Skip to note 11 content
Benjamin Intal
Note that
the_contentfilter isn’t used whenget_the_content()function is called.Skip to note 12 content
jon
You can choose whether $content will have Shortcodes processed before or after your
the_contentfunction has executed by setting the Priority inadd_filter. The default (10) will process Shortcodes after you have returned $content at the end of your Filter function. A large figure, such as 99, will already have processed Shortcodes before your Filter function is passed $content.Skip to note 13 content
Barrett Golding
Example
/* Add a paragraph only to Pages. */ function my_added_page_content ( $content ) { if ( is_page() ) { return $content . '<p>Your content added to all pages (not posts).</p>'; } return $content; } add_filter( 'the_content', 'my_added_page_content');Skip to note 14 content
SeanM88
Consolidate multiple string replacement filters
String replacements are a common reason for filtering
the_contentand with PHP7 you can now consolidate multiple callback functions usingpreg_replace_callback_array();if it makes sense to.Example:
add_filter( 'the_content', 'multiple_string_replacements'); function multiple_string_replacements ( $content ) { if ( is_single() && in_the_loop() && is_main_query() ) { return preg_replace_callback_array([ // 1. Removes WordPress injected <p> tags surrounding images in post content. '/<p>s*(<a .*>)?s*(<img .* />)s*(</a>)?s*</p>/iU' => function ( &$matches ) { return $matches[1] . $matches[2] . $matches[3]; }, // 2. Adds custom data-attribute to <p> tags providing a paragraph id number. '|<p>|' => function ( &$matches ) { static $i = 1; return sprintf( '<p data-p-id="%d">', $i++ ); }, ], $content ); } return $content; }Skip to note 15 content
arena
the info at the bottom of the hook is wrong for most of the hooks :
Used by 7 functions | Uses 0 functions (At least it could be 0 function … ah ah ah !)
HERE is what i have for WP 5.1 :
* (7 is right, 0 is wrong)
* and i am not counting apply_filters_ref_array (happily there is no for “the_content” )
apply_filter
the_content comment.php 2656
the_content feed.php 191
the_content formatting.php 3692
the_content post-template.php 247
the_content class-wp-rest-attachments-controller.php 310
the_content class-wp-rest-posts-controller.php 1532
the_content class-wp-rest-revisions-controller.php 545
add_filter
the_content blocks.php 269
the_content blocks.php 296
the_content class-wp-embed.php 32
the_content class-wp-embed.php 39
the_content default-filters.php 142
the_content default-filters.php 172
the_content default-filters.php 173
the_content default-filters.php 174
the_content default-filters.php 175
the_content default-filters.php 176
the_content default-filters.php 177
the_content default-filters.php 178
the_content default-filters.php 519
There should be an indication of the WP version.
my doc (WP 5.1) is available here (https://blog.mailpress.org/hooks/wordpress-5-1/) !
Skip to note 16 content
dch2018
This is also a good hook to use if you want to display custom fields from a plugin (including ACF fields).
The following example is from Jeff Starr’s plugins course.
// display all custom fields for each post function wpdocs_display_all_custom_fields( $content ) { $custom_fields = 'Custom Fields'; $all_custom_fields = get_post_custom(); foreach ( $all_custom_fields as $key => $array ) { foreach ( $array as $value ) { if ( '_' !== substr( $key, 0, 1 ) ) { $custom_fields .= ''. $key .' => '. $value .''; } } } return $content . $custom_fields; } add_filter( 'the_content', 'wpdocs_display_all_custom_fields' );Skip to note 17 content
Muhammad Ayoub
Using the example to add classes to
ptag &h2tag.' => '<p class="text-danger">', '<h2>' => '<h2 class="h2">', ); $text_content = str_ireplace( array_keys( $text ), $text, $text_content ); } return $text_content; } add_filter( 'the_content', 'wpdocs_replace_content' ); ?>Skip to note 18 content
Chigozie Orunta
A useful hook to filter out vulgar words from your site and keep things nice and tidy for your site visitors.
add_filter( 'the_content', 'wpdocs_filter_vulgar_words' ); function wpdocs_filter_vulgar_words( $content ) { $vulgar_words = array( $vulgar_word1, $vulgar_word2, $vulgar_word3, $vulgar_word4 ); foreach ( $vulgar_words as $word ) { $hashed_word = substr( $word, 0, 1 ) . str_repeat( '*', strlen( $word ) - 1 ); $content = str_replace( $word, $hashed_word, $content ); } return $content; }Skip to note 19 content
trebitzki
The usage example is misleading. Unless you’re not interested in pages, it should be
You should also add a sufficiently high priority to the filter to hook on
the_contentbefore rendering happens:add_filter( 'the_content', 'filter_the_content_in_the_main_loop', -1 ); function filter_the_content_in_the_main_loop( $content ) { // Check if we're inside the main loop in a post or page. if ( ( is_single() || is_page() ) && in_the_loop() && is_main_query() ) { return $content . esc_html__("I'm filtering the content inside the main loop", "my-textdomain"); } return $content; }This should go in functions.php.
It took me half a day to figure out why my filter was doing nothing.
Skip to note 20 content
renanbessa
Using the example below verifies that if the ALT attribute of any image inserted in the content is empty, get the file name.
function wpdocs_replaceALT( $content ) { if ( is_single() && in_the_loop() && is_main_query() ) { libxml_use_internal_errors( true ); $post = new DOMDocument(); $post->loadHTML( $content ); $images = $post->getElementsByTagName( 'img' ); foreach ( $images as $image ) { if ( empty( $image->getAttribute( 'alt' ) ) ) { $src = $image->getAttribute( 'src' ); $alt = pathinfo( $src, PATHINFO_FILENAME ); $image->setAttribute( 'alt', $alt ); } } $content = $post->saveHTML(); return $content; } } add_filter( 'the_content', 'wpdocs_replaceALT' );$post->loadHTML( '' . $content );