WordPress 模板层级
什么是模板层级？
WordPress 使用模板层级系统来决定为每个页面显示哪个模板文件。了解这个系统对于创建灵活的主题至关重要。
模板层级图
┌─────────────────────────────────────────────────────────────┐
│ 请求类型 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────┐
│ 首页 (front-page.php) │
│ 或 │
│ (home.php + is_front_page) │
└───────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ singular │
│ (单个文章、页面或附件) │
└─────────────────────────────────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ single │ │ page │ │attachment│
│-{slug}.php│ │-{slug}.php│ │.php │
└──────────┘ └──────────┘ └──────────┘
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ single │ │ page │ │single │
│-{id}.php │ │-{id}.php │ │attachment │
└──────────┘ └──────────┘ └──────────┘
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│single.php│ │ page.php │ │ default │
└──────────┘ └──────────┘ └──────────┘
│ │ │
└───────────────────┼────────────────────┘
▼
┌──────────────────┐
│ singular.php │
└──────────────────┘
│
▼
┌──────────────────┐
│ index.php │
└──────────────────┘详细层级列表
首页模板
1. front-page.php - 首页模板
2. home.php - 博客文章列表
3. index.php - 回退模板文章模板
1. single-{post-type}.php - 自定义文章类型
2. single-{slug}.php - 按别名
3. single-{id}.php - 按 ID
4. single.php - 单文章模板
5. singular.php - 所有单内容
6. index.php - 回退模板页面模板
1. 自定义模板 - 页面属性中选择的模板
2. page-{slug}.php - 按别名
3. page-{id}.php - 按 ID
4. page.php - 页面模板
5. singular.php - 所有单内容
6. index.php - 回退模板分类模板
1. category-{slug}.php - 按别名
2. category-{id}.php - 按 ID
3. category.php - 分类模板
4. archive.php - 存档模板
5. index.php - 回退模板标签模板
1. tag-{slug}.php - 按别名
2. tag-{id}.php - 按 ID
3. tag.php - 标签模板
4. archive.php - 存档模板
5. index.php - 回退模板自定义分类法模板
1. taxonomy-{taxonomy}-{term}.php
2. taxonomy-{taxonomy}.php
3. taxonomy.php
4. archive.php
5. index.php作者模板
1. author-{nicename}.php - 按用户名
2. author-{id}.php - 按 ID
3. author.php - 作者模板
4. archive.php - 存档模板
5. index.php - 回退模板日期模板
1. date.php - 日期存档
2. archive.php - 存档模板
3. index.php - 回退模板搜索结果模板
1. search.php - 搜索结果
2. index.php - 回退模板404 模板
1. 404.php - 404 错误页面
2. index.php - 回退模板附件模板
1. {mime-type}.php - 按 MIME 类型
2. attachment.php - 附件模板
3. single-attachment.php - 单附件
4. singular.php - 所有单内容
5. index.php - 回退模板实际应用示例
创建自定义文章模板
假设有一个"作品集"自定义文章类型：
php
// 注册自定义文章类型
function create_portfolio_cpt() {
register_post_type('portfolio', array(
'labels' => array(
'name' => '作品集',
'singular_name' => '作品',
),
'public' => true,
'has_archive' => true,
'rewrite' => array('slug' => 'portfolio'),
'supports' => array('title', 'editor', 'thumbnail'),
));
}
add_action('init', 'create_portfolio_cpt');创建模板文件：
themes/my-theme/
├── single-portfolio.php # 作品集单页模板 ← 新建
├── archive-portfolio.php # 作品集存档页 ← 新建
├── taxonomy-portfolio_category.php # 作品分类 ← 新建
└── ...single-portfolio.php 示例
php
<?php get_header(); ?>
<main class="portfolio-single">
<?php while (have_posts()): the_post(); ?>
<article id="portfolio-<?php the_ID(); ?>">
<?php if (has_post_thumbnail()): ?>
<div class="portfolio-featured">
<?php the_post_thumbnail('large'); ?>
</div>
<?php endif; ?>
<h1><?php the_title(); ?></h1>
<div class="portfolio-meta">
<span>客户: <?php echo get_post_meta(get_the_ID(), 'client', true); ?></span>
<span>年份: <?php echo get_post_meta(get_the_ID(), 'year', true); ?></span>
</div>
<div class="portfolio-content">
<?php the_content(); ?>
</div>
<!-- 画廊 -->
<?php
$gallery = get_post_meta(get_the_ID(), 'project_gallery', true);
if ($gallery): ?>
<div class="portfolio-gallery">
<?php foreach ($gallery as $image): ?>
<img src="<?php echo wp_get_attachment_url($image); ?>" alt="">
<?php endforeach; ?>
</div>
<?php endif; ?>
</article>
<nav class="portfolio-nav">
<?php previous_post_link(); ?> |
<?php next_post_link(); ?>
</nav>
<?php endwhile; ?>
</main>
<?php get_footer(); ?>archive-portfolio.php 示例
php
<?php get_header(); ?>
<main class="portfolio-archive">
<header class="archive-header">
<h1>作品集</h1>
<?php the_archive_description(); ?>
</header>
<div class="portfolio-grid">
<?php if (have_posts()): while (have_posts()): the_post(); ?>
<article class="portfolio-item">
<a href="<?php the_permalink(); ?>">
<?php if (has_post_thumbnail()): ?>
<?php the_post_thumbnail('medium'); ?>
<?php endif; ?>
<h2><?php the_title(); ?></h2>
</a>
</article>
<?php endwhile; endif; ?>
</div>
<?php the_posts_pagination(); ?>
</main>
<?php get_footer(); ?>自定义页面模板
创建页面模板
php
<?php
/**
* Template Name: 全宽页面
* Template Post Type: page
*/
get_header(); ?>
<div class="full-width-template">
<?php while (have_posts()): the_post(); ?>
<h1><?php the_title(); ?></h1>
<div class="entry-content">
<?php the_content(); ?>
</div>
<?php endwhile; ?>
</div>
<?php get_footer(); ?>模板选择器
在页面编辑器的"页面属性"元数据框中可以看到所有可用的页面模板。
使用 singular.php
singular.php 是所有单内容类型的通用模板：
php
<?php
// singular.php - 所有单内容类型共用
get_header();
while (have_posts()): the_post();
// 获取当前内容类型
$post_type = get_post_type();
?>
<article id="<?php echo $post_type; ?>-<?php the_ID(); ?>"
class="<?php echo $post_type; ?>-single">
<header>
<?php
// 根据类型显示不同标题
if ($post_type === 'post'): ?>
<span class="post-type">文章</span>
<?php elseif ($post_type === 'page'): ?>
<span class="post-type">页面</span>
<?php endif; ?>
<h1><?php the_title(); ?></h1>
<time><?php the_date(); ?></time>
</header>
<div class="content">
<?php the_content(); ?>
</div>
</article>
<?php endwhile; ?>
<?php get_footer(); ?>模板包含函数
get_template_part()
php
<?php
// 包含 content.php
get_template_part('content');
// 包含 content-page.php（带参数）
get_template_part('content', 'page');
// 使用变量作为 slug
get_template_part('template-parts/content', get_post_type());
?>get_header() / get_footer()
php
<?php
// 包含 header.php
get_header();
// 包含 header-custom.php（带参数）
get_header('custom');
// 包含 footer.php
get_footer();
// 包含 footer-minimal.php
get_footer('minimal');
?>条件标签组合
php
<?php
// 首页显示侧边栏，其他页面不显示
if (is_home() || is_front_page()) {
get_sidebar();
}
// 存档页显示过滤器
if (is_archive()) {
get_template_part('template-parts/archive', 'filters');
}
// 自定义文章类型存档页
if (is_post_type_archive('portfolio')) {
// 自定义存档页内容
}
?>最佳实践
- 始终创建 index.php - 作为最后的回退
- 使用 get_template_part() - 代码复用
- 遵循层级顺序 - 创建最具体的模板
- 保持模板简洁 - 复杂逻辑放在 functions.php
- 使用子主题 - 避免直接修改主题