WordPress常用模板函数参考文档

2020-12-24 · Ryan · 发表评论

基本模板文件

一个标准的 WordPress 主题通常包含以下核心模板文件，它们共同构成了网站的前端结构。

文件名	描述
`style.css`	主题样式表，也是主题信息声明文件。
`index.php`	主模板文件，当其他模板文件不存在时作为后备。
`header.php`	头部模板，通常包含 `<head>` 部分和网站页眉。
`footer.php`	底部模板，通常包含页脚内容和脚本。
`sidebar.php`	侧边栏模板。
`single.php`	用于显示单篇文章。
`page.php`	用于显示静态页面。
`archive.php`	用于显示分类、标签、作者、日期等存档页。
`category.php`	分类存档模板（优先级高于 archive.php）。
`tag.php`	标签存档模板（优先级高于 archive.php）。
`search.php`	搜索结果页面模板。
`searchform.php`	搜索表单模板，通常被 `get_search_form()` 调用。
`404.php`	404 错误页面模板。
`comments.php`	评论列表和评论表单模板。
`front-page.php`	当设置为静态首页时，此模板优先于 index.php。

头部常用函数

这些函数常用于 header.php 文件中，用于输出站点信息和资源链接。

函数调用	描述
`<?php bloginfo('name'); ?>`	输出在“设置”>“常规”中定义的站点标题。
`<?php bloginfo('description'); ?>`	输出站点副标题（标语）。
`<?php bloginfo('url'); ?>`	输出站点地址（URL）。
`<?php bloginfo('stylesheet_url'); ?>`	输出主题主样式表 style.css 的 URL。
`<?php bloginfo('charset'); ?>`	输出在“设置”>“阅读”中定义的博客字符集。
`<?php wp_title(); ?>`	输出当前页面的标题。从 WordPress 4.4 开始，建议使用 `wp_get_document_title()`。
`<?php wp_head(); ?>`	关键函数：必须位于 `</head>` 标签前，用于让插件和主题添加脚本、样式等。

导航菜单

WordPress 提供了强大的菜单管理系统，以下是几种常用的导航输出方式。

使用导航菜单系统

这是最推荐的方式，允许用户在后台“外观”>“菜单”中管理菜单项。

<?php
wp_nav_menu( array(
    'theme_location' => 'primary', // 在 functions.php 中注册的菜单位置
    'menu_class'     => 'main-menu', // 菜单容器的 CSS 类
    'fallback_cb'    => 'wp_page_menu', // 后备函数，如果菜单未设置则显示页面列表
) );
?>

基于分类的导航（传统方法）

直接列出所有分类，适合简单的博客结构。

<ul id="menu">
    <li <?php if ( is_home() ) echo 'class="current-cat"'; ?>>
        <a href="<?php echo esc_url( home_url( '/' ) ); ?>">首页</a>
    </li>
    <?php wp_list_categories( 'title_li=&orderby=name' ); ?>
</ul>

基于页面的导航（传统方法）

直接列出所有页面，适合简单的网站结构。

<ul id="menu">
    <li <?php if ( is_front_page() ) echo 'class="current-page-item"'; ?>>
        <a href="<?php echo esc_url( home_url( '/' ) ); ?>">首页</a>
    </li>
    <?php wp_list_pages( 'sort_column=menu_order&depth=1&title_li=' ); ?>
</ul>

模板核心函数

这些函数是构建 WordPress 主题循环和内容显示的基础。

函数调用	描述
`<?php get_header(); ?>`	引入 header.php 模板文件。
`<?php get_sidebar(); ?>`	引入 sidebar.php 模板文件。
`<?php get_footer(); ?>`	引入 footer.php 模板文件。必须在模板末尾调用。
`<?php if ( have_posts() ) : ?>`	检查主查询是否有文章。
`<?php while ( have_posts() ) : the_post(); ?>`	开启主循环，并设置当前文章数据。
`<?php the_title(); ?>`	输出当前文章的标题。
`<?php the_permalink(); ?>`	输出当前文章的永久链接。通常与标题搭配：`<a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>`。
`<?php the_content(); ?>`	输出当前文章的全部内容（支持分页）。
`<?php the_excerpt(); ?>`	输出当前文章的摘要。
`<?php the_time( 'Y-m-d' ); ?>`	输出文章发布时间。参数为 PHP 日期格式，如 'Y-m-d' 输出 '2023-10-27'。
`<?php the_category( ', ' ); ?>`	输出文章所属分类，以逗号分隔。
`<?php the_author(); ?>`	输出文章作者名称。
`<?php comments_template(); ?>`	引入 comments.php 模板来显示评论。
`<?php endwhile; ?>`	结束 while 循环。
`<?php endif; ?>`	结束 if 判断。
`<?php next_posts_link( '更早的文章' ); ?>`	在存档页输出指向更早文章的链接（分页）。
`<?php previous_posts_link( '较新的文章' ); ?>`	在存档页输出指向较新文章的链接（分页）。
`<?php edit_post_link( '编辑' ); ?>`	为有权限的用户输出文章编辑链接。

主循环结构

这是 WordPress 主题中用于输出文章列表的标准循环结构。

<?php if ( have_posts() ) : ?>
    <?php while ( have_posts() ) : the_post(); ?>
        <!-- 在这里输出每篇文章的内容 -->
        <article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
            <h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
            <div class="entry-meta">
                发布于 <?php the_time( 'Y年m月d日' ); ?> | 分类：<?php the_category( ', ' ); ?>
            </div>
            <div class="entry-content">
                <?php the_excerpt(); ?>
            </div>
        </article>
    <?php endwhile; ?>
    <!-- 分页导航 -->
    <div class="pagination">
        <?php next_posts_link( '&laquo; 更早的文章' ); ?>
        <?php previous_posts_link( '较新的文章 &raquo;' ); ?>
    </div>
<?php else : ?>
    <p>抱歉，没有找到任何内容。</p>
<?php endif; ?>

其他实用函数与标签

函数/标签	描述
`<?php body_class(); ?>`	输出 `<body>` 标签的 CSS 类，用于基于页面类型进行样式控制。
`<?php wp_footer(); ?>`	关键函数：必须位于 `</body>` 标签前，用于让插件和主题添加页脚脚本。
`<?php dynamic_sidebar( 'sidebar-1' ); ?>`	输出一个已注册的小工具区域。
`<?php echo esc_url( home_url( '/' ) ); ?>`	安全地输出网站首页链接。推荐替代 `bloginfo('url')`。
`<?php the_post_thumbnail( 'medium' ); ?>`	输出文章的特色图像（缩略图）。
`<!--more-->`	在文章编辑器中插入，用于手动定义“阅读更多”标签的截断点。
`<?php _e( '文本', 'textdomain' ); ?>`	翻译函数，输出已翻译的文本。用于使主题支持多语言。