云策 WordPress 开发者社区

函数文档

get_sidebar()

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

概述

get_sidebar() 是 WordPress 中用于加载侧边栏模板文件的函数。它支持加载默认或指定名称的侧边栏模板，并可传递额外参数。

关键要点

  • 函数用于加载主题的侧边栏模板，可指定名称以加载专用侧边栏（如 sidebar-special.php）。
  • 参数包括可选的 $name（字符串或 null，默认 null）和 $args（数组，默认空数组）。
  • 返回值为 void（成功时）或 false（模板不存在时）。
  • 触发 get_sidebar 动作钩子，允许在加载前执行自定义代码。
  • 内部使用 locate_template() 查找模板文件，优先加载指定名称的模板。
  • 从 WordPress 5.5.0 版本开始支持 $args 参数，用于向模板传递额外数据。

代码示例

// 加载默认侧边栏
get_sidebar();

// 加载名为 'shop' 的侧边栏，并传递参数
$args = array('title' => 'Shop sidebar');
get_sidebar('shop', $args);

// 条件加载侧边栏示例
if (function_exists('register_sidebar')) {
    get_sidebar();
}

注意事项

  • 模板文件命名需遵循 sidebar-{$name}.php 格式，如 sidebar-right.php。
  • 使用前可检查侧边栏是否已注册或激活，以避免错误。
  • 参数 $args 可用于在模板中访问自定义变量，增强灵活性。
📄 原文内容

Loads sidebar template.

Description

Includes the sidebar template for a theme or if a name is specified then a specialized sidebar will be included.

For the parameter, if the file is called “sidebar-special.php” then specify “special”.

Parameters

$namestring|nulloptional
The name of the specialized sidebar.

Default:null

$argsarrayoptional
Additional arguments passed to the sidebar template.

Default:array()

Return

void|false Void on success, false if the template does not exist.

Source

function get_sidebar( $name = null, $args = array() ) {
	/**
	 * Fires before the sidebar template file is loaded.
	 *
	 * @since 2.2.0
	 * @since 2.8.0 The `$name` parameter was added.
	 * @since 5.5.0 The `$args` parameter was added.
	 *
	 * @param string|null $name Name of the specific sidebar file to use. Null for the default sidebar.
	 * @param array       $args Additional arguments passed to the sidebar template.
	 */
	do_action( 'get_sidebar', $name, $args );

	$templates = array();
	$name      = (string) $name;
	if ( '' !== $name ) {
		$templates[] = "sidebar-{$name}.php";
	}

	$templates[] = 'sidebar.php';

	if ( ! locate_template( $templates, true, true, $args ) ) {
		return false;
	}
}

View all references View on Trac View on GitHub

Hooks

do_action( ‘get_sidebar’, string|null $name, array $args )

Fires before the sidebar template file is loaded.

Uses Description
locate_template()wp-includes/template.php

Retrieves the name of the highest priority template file that exists.
do_action()wp-includes/plugin.php

Calls the callback functions that have been added to an action hook.

Changelog

Version Description
5.5.0 The $args parameter was added.
1.5.0 Introduced.

User Contributed Notes

  5. Skip to note 11 content


    Thirumani Guhan


    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

    Call sidebar with $args parameter (Since 5.5.0)
    Consider below is your sidebar call from anywhere inside your theme, 

     'Shop sidebar'
);

get_sidebar( 'shop', $args ); 

?>

    Your codes inside sidebar-shop.php file might look a like below.

    <div id="secondary" class="widget-area sidebar-shop" role="complementary">
	<h2><h2>
	
</div><!-- #secondary -->

  6. Skip to note 12 content


    tradesouthwest


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Conditional Statement for Any Sidebar
    In case you are making a plugin template where you do not know if there is a sidebar, for any given theme the plugin may be used with, you may check for register_sidebar function to see if any sidebar exists.

    if ( function_exists( 'register_sidebar' ) ) { 
	get_sidebar(); 
}

    Or, if you know the theme registered name for the sidebar in question try:

    //for twenty-sixteen theme
    if ( is_active_sidebar( 'content-bottom' ) ) : 
        get_sidebar( 'content-bottom' ); 
    endif;