云策 WordPress 开发者社区

主题开发文档

自定义文章类型模板文件

查看官方原文 ↗
💡 云策文档标注

概述

WordPress 主题系统支持为自定义文章类型创建自定义模板文件，包括单篇文章和归档页面。自 WordPress 3.0 起支持单篇文章模板，3.1 起支持归档模板。

关键要点

  • 自定义文章类型的单篇文章模板使用 single-{post_type}.php 文件，归档模板使用 archive-{post_type}.php 文件。
  • WordPress 遵循模板层级，优先使用特定模板文件，如 single-acme_product.php，若不存在则回退到 single.php、archive.php 或 index.php。
  • 可使用 is_post_type_archive() 函数检查是否为自定义文章类型归档页面，post_type_archive_title() 函数显示归档标题。

代码示例

// 注册自定义文章类型示例
register_post_type('acme_product', array(
    'public' => true,
    'label'  => 'Products'
));

// 在模板中检查归档页面
if (is_post_type_archive('acme_product')) {
    echo '这是产品归档页面';
}

// 显示归档标题
post_type_archive_title();

注意事项

  • 模板文件名中的 {post_type} 必须与 register_post_type() 函数中的 $post_type 参数一致。
  • 若无自定义归档页面，可通过 BLOG_URL?post_type={post_type} 访问归档。
📄 原文内容

The WordPress theme system supports custom templates for custom post types. Custom templates for the single display of posts belonging to custom post types have been supported since WordPress Version 3.0 and the support for custom templates for archive displays was added in Version 3.1.

Custom Post Type – Template Hierarchy

WordPress will work through the template hierarchy and use the template file it comes across first. So if you want to create a custom template for your acme_product custom post type, a good place to start is by copying the single.php file, saving it as single-acme_product.php and editing that.

However if you don’t want to create custom template files, WordPress will use the files already present in your theme, which would be archive.php and single.php and index.php files.

Single posts and their archives can be displayed using the single.php and archive.php template files respectively,

  • single posts of a custom post type will use single-{post_type}.php
  • and their archives will use archive-{post_type}.php
  • and if you don’t have this post type archive page you can pass BLOG_URL?post_type={post_type}

where {post_type} is the $post_type argument of the register_post_type() function.

So for the above example, you could create single-acme_product.php and archive-acme_product.php template files for single product posts and their archives.

Alternatively, you can use the is_post_type_archive() function in any template file to check if the query shows an archive page of a given post types(s), and the post_type_archive_title() to display the post type title.

Custom Post Type templates

  • single-{post-type}.php
    The single post template used when a visitor requests a single post from a custom post type. For example, single-acme_product.php would be used for displaying single posts from a custom post type named acme_product.
  • archive-{post-type}.php
    The archive post type template is used when visitors request a custom post type archive. For example, archive-acme_product.php would be used for displaying an archive of posts from the custom post type named acme_product. The archive.php template file is used if the archive-{post-type}.php is not present.
  • index.php
    The index.php is used if a specific query template (single-{post-type}.php, single.php, archive-{post-type}.php, archive.php, search.php) for the custom post type is not present.

Function Reference