WordPress中文开发手册

WordPress主题开发 — Sidebars

什么是Sidebars

侧边栏是您的主题的任何小部件区域。 小部件区域是您主题中的地方,用户可以添加自己的小部件。 您不需要在主题中包含侧边栏,但包括侧栏意味着用户可以通过定制程序或窗口小部件管理面板向窗口小部件区域添加内容。

小部件可以用于各种目的,从列出最近的帖子到进行实时聊天。

提示:名称“sidebars”来自于小部件区域通常在漫长的条带中创建到博客的左侧或右侧的时间。 今天,边栏已经超越了原来的名字。 它们可以包含在您网站的任何地方。 将边栏视为包含小部件的任何区域。

注册Sidebar

要使用侧边栏,您必须在functions.php中注册它们。

要开始,register_sidebar()有几个参数应该始终被定义,不管它们是否被标记为可选。这些包括x,y和z。

  • name - 您的侧边栏的名称。这是用户将在“小部件”面板中看到的名称。
  • id - 必须是小写。您将使用dynamic_sidebar函数将其称为主题。
  • description - 侧边栏的说明。这也将显示在管理窗口小部件面板中。
  • class - 要分配给窗口小部件的HTML的CSS类名称。
  • before_widget - 在每个窗口小部件之前放置的HTML。
  • after_widget - 每个窗口小部件后面放置的HTML。应该用于从before_widget关闭标签。
  • before_title - 放置在每个窗口小部件的标题之前的HTML,例如标题标签。
  • after_title - 每个标题后放置的HTML。应该用于从before_title关闭标签。

要注册边栏,我们使用register_sidebar和widgets_init函数。

function themename_widgets_init() {
    register_sidebar( array(
        'name'          => __( 'Primary Sidebar', 'theme_name' ),
        'id'            => 'sidebar-1',
        'before_widget' => '<aside id="%1$s" class="widget %2$s">',
        'after_widget'  => '</aside>',
        'before_title'  => '<h1 class="widget-title">',
        'after_title'   => '</h1>',
    ) );
 
    register_sidebar( array(
        'name'          => __( 'Secondary Sidebar', 'theme_name' ),
        'id'            => 'sidebar-2',
        'before_widget' => '<ul><li id="%1$s" class="widget %2$s">',
        'after_widget'  => '</li></ul>',
        'before_title'  => '<h3 class="widget-title">',
        'after_title'   => '</h3>',
    ) );
}
add_action( 'widgets_init', 'themename_widgets_init' );

注册边栏告诉WordPress,您将在Appearance> Widgets中创建一个新的小部件区域,用户可以将其小部件拖动到其中。 注册侧边栏有两种功能:

  • register_sidebar()
  • register_sidebars()

第一个可以让您注册一个侧边栏,第二个可以让您注册多个侧边栏。

提示:建议您单独注册侧边栏,因为它可以为每个侧边栏提供唯一和描述性的名称。

示例

对于页眉和页脚中的小部件区域,将其标题为“标题小部件区域”和“页脚小部件区域”,而不是“边栏1”和“边栏2”(这是默认值)。 这提供了侧边栏所在位置的有用描述。

以下代码,添加到functions.php注册一个侧边栏:

<?php
add_action( 'widgets_init', 'my_register_sidebars' );
function my_register_sidebars() {
    /* Register the 'primary' sidebar. */
    register_sidebar(
        array(
            'id'            => 'primary',
            'name'          => __( 'Primary Sidebar' ),
            'description'   => __( 'A short description of the sidebar.' ),
            'before_widget' => '<div id="%1$s" class="widget %2$s">',
            'after_widget'  => '</div>',
            'before_title'  => '<h3 class="widget-title">',
            'after_title'   => '</h3>',
        )
    );
    /* Repeat register_sidebar() code for additional sidebars. */
}
?>

代码执行以下操作:

  • register_sidebar – 告诉WordPress你正在注册边栏
  • 'name' => __( 'Primary Widget Area', 'mytheme' ), – 是将出现在外观>小部件中的小部件区域的名称
  • 'id' => 'sidebar-1' – 在侧边栏分配一个ID。 WordPress使用“id”将小部件分配给特定的侧边栏。
  • before_widget/after_widget – 分配给侧边栏的小部件的包装元素。 “%1 $ s”和“%2 $ s”应该分别保留在id和class中,以便插件可以使用它们。 默认情况下,WordPress将其设置为列表项,但在上述示例中,它们已被更改为div。
  • before_title/after_title – 小部件标题的包装元素。 默认情况下,WordPress将其设置为h2,但使用h3使其更具语义。

一旦您的侧栏被注册,您可以在主题中显示。

在主题中显示侧边栏

现在您的侧边栏已注册,您将要在主题中显示。 为此,有两个步骤:

  • 创建sidebar.php模板文件,并使用dynamic_sidebar函数显示边栏
  • 使用get_sidebar函数加载主题

创建侧栏模板文件

侧边栏模板包含您的侧边栏的代码。 WordPress识别文件sidebar.php和名称为sidebar-{name} .php的任何模板文件。 这意味着您可以在自己的模板文件中的每个侧边栏中组织文件。

示例:

  1. 创建 sidebar-primary.php
  2. 添加以下代码:
<div id="sidebar-primary" class="sidebar">
    <?php dynamic_sidebar( 'primary' ); ?>
</div>

请注意,dynamic_sidebar采用$index的单个参数,可以是边栏的名称或ID。

加载你的侧栏

要在您的主题中加载您的侧边栏,请使用get_sidebar函数。 这应该被插入到你想要侧栏显示的模板文件中。 要加载默认的sidebar.php,请使用以下命令:

<?php get_sidebar(); ?>

要显示主侧边栏,请将$name参数传递给函数:

<?php get_sidebar( 'primary' ); ?>

自定义您的侧栏

有很多方法可以自定义您的侧边栏。 这里有些例子:

显示默认侧栏内容

如果用户尚未向边栏添加任何小部件,则可能希望显示内容。 为此,您可以使用is_sidebar_active()函数检查边栏是否有任何小部件。 这接受$index参数,该参数应该是要检查的边栏的ID。

此代码检查边栏是否处于活动状态,如果不显示某些内容:

<div id="sidebar-primary" class="sidebar">
    <?php if ( is_active_sidebar( 'primary' ) ) : ?>
        <?php dynamic_sidebar( 'primary' ); ?>
    <?php else : ?>
        <!-- Time to add some widgets! -->
    <?php endif; ?>
</div>

显示默认窗口小部件

您可能希望您的侧边栏默认填充一些小部件。 例如,显示搜索,存档和元小部件。 为此,您将使用:

<div id="primary" class="sidebar">
    <?php do_action( 'before_sidebar' ); ?>
    <?php if ( ! dynamic_sidebar( 'sidebar-primary' ) ) : ?>
        <aside id="search" class="widget widget_search">
           <?php get_search_form(); ?>
        </aside>
        <aside id="archives" class"widget">
            <h1 class="widget-title"><?php _e( 'Archives', 'shape' ); ?></h1>
            <ul>
                <?php wp_get_archives( array( 'type' => 'monthly' ) ); ?>
            </ul>
        </aside>
        <aside id="meta" class="widget">
            <h1 class="widget-title"><?php _e( 'Meta', 'shape' ); ?></h1>
            <ul>
                <?php wp_register(); ?>
                <li><?php wp_loginout(); ?></li>
                <?php wp_meta(); ?>
            </ul>
        </aside>
   <?php endif; ?>
</div>