模板层级
理解 WordPress 模板层级是主题开发的核心。本文档详细介绍 WordPress 如何选择和加载模板文件。
📊 模板层级图
mermaid
graph TD
A[请求开始] --> B{是首页?}
B -->|是| C[front-page.php]
B -->|否| D{有静态首页?}
D -->|是| E[front-page.php 或 home.php]
D -->|否| F[home.php]
F --> G[index.php]
C -->|不存在| G
E -->|不存在| G
H[单一文章] --> I[single-{post_type}.php]
I -->|不存在| J[single.php]
J -->|不存在| K[singular.php]
K --> G
L[页面] --> M[custom-page-template.php]
M -->|不存在| N[page-{slug}.php]
N -->|不存在| O[page-{id}.php]
O -->|不存在| P[page.php]
P -->|不存在| K
Q[分类] --> R[category-{slug}.php]
R -->|不存在| S[category-{id}.php]
S -->|不存在| T[category.php]
T -->|不存在| U[archive.php]
U -->|不存在| G
V[标签] --> W[tag-{slug}.php]
W -->|不存在| X[tag-{id}.php]
X -->|不存在| Y[tag.php]
Y --> U
Z[自定义分类] --> AA[taxonomy-{taxonomy}.php]
AA -->|不存在| U
AB[自定义文章类型] --> AC[archive-{post_type}.php]
AC -->|不存在| U
AD[作者] --> AE[author-{nicename}.php]
AE -->|不存在| AF[author-{id}.php]
AF -->|不存在| AG[author.php]
AG -->|不存在| U
AH[日期] --> AI[date.php]
AI -->|不存在| U
AJ[搜索结果] --> AK[search.php]
AK -->|不存在| G
AL[404] --> AM[404.php]
AM -->|不存在| G
AN[附件] --> AO[attachment.php]
AO -->|不存在| P
AP[嵌入内容] --> AQ[singular.php]1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
📋 模板加载顺序
首页模板
| 优先级 | 模板文件 | 条件 |
|---|---|---|
| 1 | front-page.php | 设置 → 阅读 → 前端页面设置为静态页面 |
| 2 | home.php | 设置 → 阅读 → 最新文章 |
| 3 | index.php | 回退 |
文章模板
| 优先级 | 模板文件 | 条件 |
|---|---|---|
| 1 | single-{post_type}.php | 自定义文章类型 |
| 2 | single.php | 默认文章 |
| 3 | singular.php | 回退 |
| 4 | index.php | 最终回退 |
页面模板
| 优先级 | 模板文件 | 条件 |
|---|---|---|
| 1 | 自定义页面模板 | page-{slug}.php |
| 2 | page-{id}.php | 页面ID |
| 3 | page.php | 默认页面 |
| 4 | singular.php | 回退 |
| 5 | index.php | 最终回退 |
分类模板
| 优先级 | 模板文件 | 条件 |
|---|---|---|
| 1 | category-{slug}.php | 分类别名 |
| 2 | category-{id}.php | 分类ID |
| 3 | category.php | 默认 |
| 4 | archive.php | 归档页 |
| 5 | index.php | 最终回退 |
💡 模板选择示例
示例 1: 分类页面
访问 example.com/category/news/：
- 先查找
category-news.php - 再查找
category-1.php(news 的 ID) - 再查找
category.php - 再查找
archive.php - 最后使用
index.php
示例 2: 单篇文章
访问 example.com/hello-world/：
- 先查找
single-post-hello-world.php - 再查找
single-post.php - 再查找
single.php - 再查找
singular.php - 最后使用
index.php
示例 3: 自定义页面模板
创建自定义页面模板：
php
<?php
/**
* Template Name: 关于我们页面
* Template Post Type: page
*/
get_header();
?>
<main class="about-page">
<h1><?php the_title(); ?></h1>
<div class="about-content">
<?php the_content(); ?>
</div>
</main>
<?php get_footer(); ?>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
🔧 条件标签
在模板中使用条件标签：
php
<?php if (is_home()) : ?>
<!-- 首页内容 -->
<?php endif; ?>
<?php if (is_single()) : ?>
<!-- 文章页内容 -->
<?php elseif (is_page()) : ?>
<!-- 页面内容 -->
<?php elseif (is_archive()) : ?>
<!-- 归档页内容 -->
<?php endif; ?>
<?php if (have_posts()) : ?>
<?php while (have_posts()) : the_post(); ?>
<h2><?php the_title(); ?></h2>
<?php the_content(); ?>
<?php endwhile; ?>
<?php endif; ?>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
常用条件标签
| 标签 | 说明 |
|---|---|
is_home() | 首页 |
is_front_page() | 前端页面 |
is_single() | 单一文章 |
is_page() | 页面 |
is_archive() | 任何归档页 |
is_category() | 分类归档 |
is_tag() | 标签归档 |
is_tax() | 自定义分类法 |
is_search() | 搜索结果 |
is_404() | 404 页面 |
is_author() | 作者归档 |
is_date() | 日期归档 |
is_preview() | 预览模式 |
is_singular() | 任何单一内容 |
📝 自定义模板查询
WP_Query 示例
php
<?php
// 创建一个新的查询
$args = array(
'post_type' => 'post',
'posts_per_page' => 5,
'category_name' => 'featured',
'orderby' => 'date',
'order' => 'DESC',
);
$featured_posts = new WP_Query($args);
if ($featured_posts->have_posts()) : ?>
<section class="featured-posts">
<?php while ($featured_posts->have_posts()) : $featured_posts->the_post(); ?>
<article>
<h3><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h3>
<?php if (has_post_thumbnail()) : ?>
<a href="<?php the_permalink(); ?>">
<?php the_post_thumbnail('medium'); ?>
</a>
<?php endif; ?>
<p><?php the_excerpt(); ?></p>
</article>
<?php endwhile; ?>
</section>
<?php wp_reset_postdata(); ?>
<?php endif; ?>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
预加载查询
使用 get_template_part() 组织模板：
php
<?php
// 头部
get_header();
// 循环
if (have_posts()) :
while (have_posts()) :
the_post();
// 获取对应的内容模板
get_template_part('template-parts/content', get_post_type());
endwhile;
// 分页
the_posts_pagination();
else :
// 无内容模板
get_template_part('template-parts/content', 'none');
endif;
// 侧边栏
get_sidebar();
// 页脚
get_footer();1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
🎯 最佳实践
最佳实践
- 不要重复代码 - 使用
get_header(),get_footer()等 - 模块化模板 - 使用
get_template_part()复用模板部件 - 使用条件标签 - 根据页面类型加载不同内容
- 保持简洁 - 每个模板文件专注于单一职责
- 遵循层级 - 充分利用模板层级减少代码冗余