wp_get_document_title()
云策文档标注
概述
wp_get_document_title() 函数用于生成当前页面的文档标题，返回字符串格式的标题标签。它根据页面类型（如404、搜索、首页、文章等）动态生成标题，并支持通过多个过滤器进行自定义。
关键要点
- 函数返回当前页面的文档标题字符串，适用于在主题或插件中输出标题标签。
- 标题生成逻辑基于条件判断，如 is_404()、is_search()、is_front_page() 等，针对不同页面类型使用相应函数获取标题。
- 支持分页处理，当 $paged 或 $page 大于等于2时，自动添加页码信息。
- 提供多个过滤器：pre_get_document_title 用于短路径返回自定义标题，document_title_separator 用于修改标题分隔符，document_title_parts 用于过滤标题部分数组，document_title 用于最终标题过滤。
- 标题部分包括 title、page、tagline 和 site，通过分隔符连接并过滤空值后输出。
代码示例
// 基本用法示例：在主题中输出文档标题
echo wp_get_document_title();
// 使用过滤器自定义标题
add_filter( 'pre_get_document_title', function( $title ) {
if ( is_single() ) {
return '自定义文章标题';
}
return $title;
});注意事项
- 函数自 WordPress 4.4.0 版本引入，确保兼容性。
- 标题生成依赖于全局变量 $page 和 $paged，需在适当上下文中调用。
- 过滤器调用顺序：pre_get_document_title 优先，若返回非空值则直接返回，跳过后续逻辑。
- 相关函数如 get_search_query()、single_post_title() 等用于获取特定标题内容，需确保正确使用。
原文内容
Returns document title for the current page.
Source
function wp_get_document_title() {
/**
* Filters the document title before it is generated.
*
* Passing a non-empty value will short-circuit wp_get_document_title(),
* returning that value instead.
*
* @since 4.4.0
*
* @param string $title The document title. Default empty string.
*/
$title = apply_filters( 'pre_get_document_title', '' );
if ( ! empty( $title ) ) {
return $title;
}
global $page, $paged;
$title = array(
'title' => '',
);
// If it's a 404 page, use a "Page not found" title.
if ( is_404() ) {
$title['title'] = __( 'Page not found' );
// If it's a search, use a dynamic search results title.
} elseif ( is_search() ) {
/* translators: %s: Search query. */
$title['title'] = sprintf( __( 'Search Results for “%s”' ), get_search_query() );
// If on the front page, use the site title.
} elseif ( is_front_page() ) {
$title['title'] = get_bloginfo( 'name', 'display' );
// If on a post type archive, use the post type archive title.
} elseif ( is_post_type_archive() ) {
$title['title'] = post_type_archive_title( '', false );
// If on a taxonomy archive, use the term title.
} elseif ( is_tax() ) {
$title['title'] = single_term_title( '', false );
/*
* If we're on the blog page that is not the homepage
* or a single post of any post type, use the post title.
*/
} elseif ( is_home() || is_singular() ) {
$title['title'] = single_post_title( '', false );
// If on a category or tag archive, use the term title.
} elseif ( is_category() || is_tag() ) {
$title['title'] = single_term_title( '', false );
// If on an author archive, use the author's display name.
} elseif ( is_author() && get_queried_object() ) {
$author = get_queried_object();
$title['title'] = $author->display_name;
// If it's a date archive, use the date as the title.
} elseif ( is_year() ) {
$title['title'] = get_the_date( _x( 'Y', 'yearly archives date format' ) );
} elseif ( is_month() ) {
$title['title'] = get_the_date( _x( 'F Y', 'monthly archives date format' ) );
} elseif ( is_day() ) {
$title['title'] = get_the_date();
}
// Add a page number if necessary.
if ( ( $paged >= 2 || $page >= 2 ) && ! is_404() ) {
/* translators: %s: Page number. */
$title['page'] = sprintf( __( 'Page %s' ), max( $paged, $page ) );
}
// Append the description or site title to give context.
if ( is_front_page() ) {
$title['tagline'] = get_bloginfo( 'description', 'display' );
} else {
$title['site'] = get_bloginfo( 'name', 'display' );
}
/**
* Filters the separator for the document title.
*
* @since 4.4.0
*
* @param string $sep Document title separator. Default '-'.
*/
$sep = apply_filters( 'document_title_separator', '-' );
/**
* Filters the parts of the document title.
*
* @since 4.4.0
*
* @param array $title {
* The document title parts.
*
* @type string $title Title of the viewed page.
* @type string $page Optional. Page number if paginated.
* @type string $tagline Optional. Site description when on home page.
* @type string $site Optional. Site title when not on home page.
* }
*/
$title = apply_filters( 'document_title_parts', $title );
$title = implode( " $sep ", array_filter( $title ) );
/**
* Filters the document title.
*
* @since 5.8.0
*
* @param string $title Document title.
*/
$title = apply_filters( 'document_title', $title );
return $title;
}
Hooks
- apply_filters( ‘document_title’, string $title )
-
Filters the document title.
- apply_filters( ‘document_title_parts’, array $title )
-
Filters the parts of the document title.
- apply_filters( ‘document_title_separator’, string $sep )
-
Filters the separator for the document title.
- apply_filters( ‘pre_get_document_title’, string $title )
-
Filters the document title before it is generated.
Changelog
| Version | Description |
|---|---|
| 4.4.0 | Introduced. |
Skip to note 3 content
Rami Yushuvaev
Basic Usage:
<head> <meta charset="<?php bloginfo( 'charset' ); ?>"> <meta name="viewport" content="width=device-width" /> <title></title> </head>Skip to note 4 content
Khoi Pro
To use: add to header.php
<meta charset="">