the_excerpt()
云策文档标注
概述
the_excerpt() 是 WordPress 模板函数，用于显示当前文章的摘要。它会自动处理摘要的生成和格式化，包括应用过滤器、自动段落转换等。开发者可以通过多种方式自定义摘要长度、结尾符号和链接行为。
关键要点
- the_excerpt() 调用 get_the_excerpt() 生成摘要，若无显式摘要则从文章内容自动截取。
- 自动生成的摘要默认长度为 55 个单词，会移除短代码和标签，并在结尾添加 […] 符号。
- 用户提供的摘要默认不添加 […] 符号，可通过修改 $post->post_excerpt 或添加过滤器实现。
- 摘要与 the_content() 和 快速标签不同，模板开发者可基于页面类型等因素选择显示全文或摘要。
- 支持通过 excerpt_length 和 excerpt_more 过滤器自定义摘要长度和“阅读更多”文本。
- 对于附件类型文章，the_excerpt() 会显示附件说明，且不包含 […] 文本。
代码示例
// 修改摘要长度为 20 个单词
add_filter( 'excerpt_length', function( $length ) {
return 20;
}, 999 );
// 修改摘要结尾为自定义链接
add_filter( 'excerpt_more', function( $more ) {
if ( ! is_single() ) {
return sprintf( '<a href="%s">%s</a>', get_permalink(), __( 'Read More', 'textdomain' ) );
}
return $more;
} );注意事项
- 在模板中使用 the_excerpt() 时，需确保位于 The Loop 内，通常用于首页、分类、标签等索引页面。
- 自定义过滤器时，注意优先级设置，避免与其他插件或主题冲突。
- 对于东亚语言，摘要截断基于字符而非单词边界，需特别处理长度控制。
原文内容
Displays the post excerpt.
Source
function the_excerpt() {
/**
* Filters the displayed post excerpt.
*
* @since 0.71
*
* @see get_the_excerpt()
*
* @param string $post_excerpt The post excerpt.
*/
echo apply_filters( 'the_excerpt', get_the_excerpt() );
}
Hooks
- apply_filters( ‘the_excerpt’, string $post_excerpt )
-
Filters the displayed post excerpt.
Changelog
| Version | Description |
|---|---|
| 0.71 | Introduced. |
Skip to note 13 content
Codex
Control Excerpt Length using Filters
By default, excerpt length is set to 55 words. To change excerpt length to 20 words using the
excerpt_lengthfilter,add the following code to the
functions.php/** * Filter the except length to 20 words. * * @param int $length Excerpt length. * @return int (Maybe) modified excerpt length. */ function wpdocs_custom_excerpt_length( $length ) { return 20; } add_filter( 'excerpt_length', 'wpdocs_custom_excerpt_length', 999 );Skip to note 14 content
Codex
Make the “read more” string link to the post:
Place this in a theme’s
functions.phpto make the “read more” link to the post/** * Filter the "read more" excerpt string link to the post. * * @param string $more "Read more" excerpt string. * @return string (Maybe) modified "read more" excerpt string. */ function wpdocs_excerpt_more( $more ) { if ( ! is_single() ) { $more = sprintf( '<a class="read-more" href="%1$s">%2$s</a>', get_permalink( get_the_ID() ), __( 'Read More', 'textdomain' ) ); } return $more; } add_filter( 'excerpt_more', 'wpdocs_excerpt_more' );Note: This link will not appear on a new line. To achieve this, modify the CSS for the
.read-moreclass.Skip to note 15 content
Codex
Modify the
[...]string using filtersFor versions 2.9 and higher of WordPress
By default, the excerpt “read more” string at the end is set to ‘[…]’. To change the excerpt “read more” string using the
<a href="https://developer.wordpress.org/reference/hooks/excerpt_more/" rel="nofollow">excerpt_more</a>filter add the following code to thefunctions.phpfile in your theme:/** * Filter the excerpt "read more" string. * * @param string $more "Read more" excerpt string. * @return string (Maybe) modified "read more" excerpt string. */ function wpdocs_excerpt_more( $more ) { return '[.....]'; } add_filter( 'excerpt_more', 'wpdocs_excerpt_more' );Skip to note 16 content
Jacob Schwartz
The phpdoc in the excerpt_length example says “characters” where it should say “words”. FYI!
Skip to note 17 content
ekodek
Simple function that changes the output of the “[…..]” text:
function wpdocs_excerpt_more( $more ) { return '<a href="'.get_the_permalink().'" rel="nofollow">Read More...</a>'; } add_filter( 'excerpt_more', 'wpdocs_excerpt_more' );You can change the CSS of “my-class” , to everything you want….like a button or whatever.
Skip to note 18 content
Codex
Use with Conditional Tags
Replaces
<a href="https://developer.wordpress.org/reference/functions/the_content/" rel="nofollow">the_content()</a>tag withthe_excerpt()when on archive or category pages.Both the examples below work for versions 1.5 and above.
This example implies that there is only one template file being used for both categories and archives, e.g. simply
archive.php.But also that the template shows even other things, so this could simply be
index.php.Skip to note 19 content
Jonm511
How to manually add an excerpt and limit the length:
$excerpt = get_the_excerpt(); $excerpt = substr( $excerpt, 0, 260 ); // Only display first 260 characters of excerpt $result = substr( $excerpt, 0, strrpos( $excerpt, ' ' ) ); echo $result;Skip to note 20 content
Anasite
Easy Way To limit by word
/* already using in Anasite themes */
Note : 15 = 15 Word limit to showing .
Skip to note 21 content
Sachyya
The safest way to use this filter is checking for
is_admintoo as it may alter in the admin area like the following:/** * Filter the excerpt "read more" string. * * @param string $more "Read more" excerpt string. * @return string (Maybe) modified "read more" excerpt string. */ function wpdocs_excerpt_more( $more ) { if ( is_admin() ) { return $more; } return '[.....]'; } add_filter( 'excerpt_more', 'wpdocs_excerpt_more' );Skip to note 22 content
Codex
Default Usage
Displays the post excerpt. Used in templates that provide a form of index, ie. for home, category, tag, archive pages. Not used for single post views. Not meaningful for static pages.
Used as a replacement for
<a href="https://developer.wordpress.org/reference/functions/the_content/" rel="nofollow">the_content()</a>to force excerpts to show within The Loop.Skip to note 23 content
Fox Coders
I added
function wporg_fcs_excerpt_more( $more ) { return ''; } add_filter( 'excerpt_more', 'wporg_fcs_excerpt_more' );To remove default […]
Skip to note 24 content
Jonm511
Classic Editor: Add a word counter to the bottom of the ‘Excerpt’ field
This will add a word counter under the ‘Excerpt’ field when creating a new post. Helpful if you would like to limit how long your manually entered excerpt is.
Add this into your
functions.phpfile:/** * Use jQuery to add a word counter to the excerpt box * * Should attach to all post screens and indicate the number of words just below the #excerpt textarea */ function gv_excerpt_word_count_js() { echo ' <script>jQuery(document).ready(function(){ jQuery("#postexcerpt #excerpt").after("Word Count: <strong><span id='excerpt-word-count'></span></strong>"); jQuery("#excerpt-word-count").html(jQuery("#excerpt").val().split(/S+b[s,.'-:;]*/).length - 1); jQuery("#excerpt").keyup( function() { jQuery("#excerpt-word-count").html(jQuery("#excerpt").val().split(/S+b[s,.'-:;]*/).length - 1); }); });</script> '; } add_action( 'admin_head-post.php', 'gv_excerpt_word_count_js'); add_action( 'admin_head-post-new.php', 'gv_excerpt_word_count_js');