云策 WordPress 开发者社区

函数文档

dynamic_sidebar()

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

概述

dynamic_sidebar() 是 WordPress 中用于显示动态侧边栏的函数，默认显示 'sidebar-1'。它接受索引、名称或 ID 参数来指定要显示的侧边栏，并返回布尔值表示是否成功调用。

关键要点

  • 函数用于在主题模板中输出已注册的侧边栏，支持通过 $index 参数指定侧边栏的索引、名称或 ID。
  • 默认参数为 1，对应 'sidebar-1'，如果主题为侧边栏注册了 'id' 或 'name'，则可以使用这些标识符。
  • 返回 true 表示侧边栏找到并调用成功，false 表示未找到或未调用。
  • 内部处理包括参数转换、侧边栏验证、触发相关 Hook（如 dynamic_sidebar_before、dynamic_sidebar_after）和过滤参数。
  • 建议在使用前检查侧边栏是否激活且非空，以避免页面布局问题。

代码示例

if ( is_active_sidebar( 'sidebar-1' ) ) {
    dynamic_sidebar( 'sidebar-1' );
}

注意事项

  • 确保侧边栏已通过 register_sidebar() 注册，并在 Widgets 管理页面激活，否则函数可能返回 false。
  • 使用 is_active_sidebar() 进行条件检查可以避免输出空 HTML 元素，影响页面布局。
  • 函数在前后端均有效，包括 Inactive Widgets 侧边栏，注意相关 Hook 的触发条件。
📄 原文内容

Displays dynamic sidebar.

Description

By default this displays the default sidebar or ‘sidebar-1’. If your theme specifies the ‘id’ or ‘name’ parameter for its registered sidebars you can pass an ID or name as the $index parameter.
Otherwise, you can pass in a numerical index to display the sidebar at that index.

Parameters

$indexint|stringoptional
Index, name or ID of dynamic sidebar.

Default:1

Return

bool True, if widget sidebar was found and called. False if not found or not called.

Source

function dynamic_sidebar( $index = 1 ) {
	global $wp_registered_sidebars, $wp_registered_widgets;

	if ( is_int( $index ) ) {
		$index = "sidebar-$index";
	} else {
		$index = sanitize_title( $index );
		foreach ( (array) $wp_registered_sidebars as $key => $value ) {
			if ( sanitize_title( $value['name'] ) === $index ) {
				$index = $key;
				break;
			}
		}
	}

	$sidebars_widgets = wp_get_sidebars_widgets();
	if ( empty( $wp_registered_sidebars[ $index ] ) || empty( $sidebars_widgets[ $index ] ) || ! is_array( $sidebars_widgets[ $index ] ) ) {
		/** This action is documented in wp-includes/widget.php */
		do_action( 'dynamic_sidebar_before', $index, false );
		/** This action is documented in wp-includes/widget.php */
		do_action( 'dynamic_sidebar_after', $index, false );
		/** This filter is documented in wp-includes/widget.php */
		return apply_filters( 'dynamic_sidebar_has_widgets', false, $index );
	}

	$sidebar = $wp_registered_sidebars[ $index ];

	$sidebar['before_sidebar'] = sprintf( $sidebar['before_sidebar'], $sidebar['id'], $sidebar['class'] );

	/**
	 * Fires before widgets are rendered in a dynamic sidebar.
	 *
	 * Note: The action also fires for empty sidebars, and on both the front end
	 * and back end, including the Inactive Widgets sidebar on the Widgets screen.
	 *
	 * @since 3.9.0
	 *
	 * @param int|string $index       Index, name, or ID of the dynamic sidebar.
	 * @param bool       $has_widgets Whether the sidebar is populated with widgets.
	 *                                Default true.
	 */
	do_action( 'dynamic_sidebar_before', $index, true );

	if ( ! is_admin() && ! empty( $sidebar['before_sidebar'] ) ) {
		echo $sidebar['before_sidebar'];
	}

	$did_one = false;
	foreach ( (array) $sidebars_widgets[ $index ] as $id ) {

		if ( ! isset( $wp_registered_widgets[ $id ] ) ) {
			continue;
		}

		$params = array_merge(
			array(
				array_merge(
					$sidebar,
					array(
						'widget_id'   => $id,
						'widget_name' => $wp_registered_widgets[ $id ]['name'],
					)
				),
			),
			(array) $wp_registered_widgets[ $id ]['params']
		);

		// Substitute HTML `id` and `class` attributes into `before_widget`.
		$classname_ = '';
		foreach ( (array) $wp_registered_widgets[ $id ]['classname'] as $cn ) {
			if ( is_string( $cn ) ) {
				$classname_ .= '_' . $cn;
			} elseif ( is_object( $cn ) ) {
				$classname_ .= '_' . get_class( $cn );
			}
		}
		$classname_ = ltrim( $classname_, '_' );

		$params[0]['before_widget'] = sprintf(
			$params[0]['before_widget'],
			str_replace( '\', '_', $id ),
			$classname_
		);

		/**
		 * Filters the parameters passed to a widget's display callback.
		 *
		 * Note: The filter is evaluated on both the front end and back end,
		 * including for the Inactive Widgets sidebar on the Widgets screen.
		 *
		 * @since 2.5.0
		 *
		 * @see register_sidebar()
		 *
		 * @param array $params {
		 *     @type array $args  {
		 *         An array of widget display arguments.
		 *
		 *         @type string $name          Name of the sidebar the widget is assigned to.
		 *         @type string $id            ID of the sidebar the widget is assigned to.
		 *         @type string $description   The sidebar description.
		 *         @type string $class         CSS class applied to the sidebar container.
		 *         @type string $before_widget HTML markup to prepend to each widget in the sidebar.
		 *         @type string $after_widget  HTML markup to append to each widget in the sidebar.
		 *         @type string $before_title  HTML markup to prepend to the widget title when displayed.
		 *         @type string $after_title   HTML markup to append to the widget title when displayed.
		 *         @type string $widget_id     ID of the widget.
		 *         @type string $widget_name   Name of the widget.
		 *     }
		 *     @type array $widget_args {
		 *         An array of multi-widget arguments.
		 *
		 *         @type int $number Number increment used for multiples of the same widget.
		 *     }
		 * }
		 */
		$params = apply_filters( 'dynamic_sidebar_params', $params );

		$callback = $wp_registered_widgets[ $id ]['callback'];

		/**
		 * Fires before a widget's display callback is called.
		 *
		 * Note: The action fires on both the front end and back end, including
		 * for widgets in the Inactive Widgets sidebar on the Widgets screen.
		 *
		 * The action is not fired for empty sidebars.
		 *
		 * @since 3.0.0
		 *
		 * @param array $widget {
		 *     An associative array of widget arguments.
		 *
		 *     @type string   $name        Name of the widget.
		 *     @type string   $id          Widget ID.
		 *     @type callable $callback    When the hook is fired on the front end, `$callback` is an array
		 *                                 containing the widget object. Fired on the back end, `$callback`
		 *                                 is 'wp_widget_control', see `$_callback`.
		 *     @type array    $params      An associative array of multi-widget arguments.
		 *     @type string   $classname   CSS class applied to the widget container.
		 *     @type string   $description The widget description.
		 *     @type array    $_callback   When the hook is fired on the back end, `$_callback` is populated
		 *                                 with an array containing the widget object, see `$callback`.
		 * }
		 */
		do_action( 'dynamic_sidebar', $wp_registered_widgets[ $id ] );

		if ( is_callable( $callback ) ) {
			call_user_func_array( $callback, $params );
			$did_one = true;
		}
	}

	if ( ! is_admin() && ! empty( $sidebar['after_sidebar'] ) ) {
		echo $sidebar['after_sidebar'];
	}

	/**
	 * Fires after widgets are rendered in a dynamic sidebar.
	 *
	 * Note: The action also fires for empty sidebars, and on both the front end
	 * and back end, including the Inactive Widgets sidebar on the Widgets screen.
	 *
	 * @since 3.9.0
	 *
	 * @param int|string $index       Index, name, or ID of the dynamic sidebar.
	 * @param bool       $has_widgets Whether the sidebar is populated with widgets.
	 *                                Default true.
	 */
	do_action( 'dynamic_sidebar_after', $index, true );

	/**
	 * Filters whether a sidebar has widgets.
	 *
	 * Note: The filter is also evaluated for empty sidebars, and on both the front end
	 * and back end, including the Inactive Widgets sidebar on the Widgets screen.
	 *
	 * @since 3.9.0
	 *
	 * @param bool       $did_one Whether at least one widget was rendered in the sidebar.
	 *                            Default false.
	 * @param int|string $index   Index, name, or ID of the dynamic sidebar.
	 */
	return apply_filters( 'dynamic_sidebar_has_widgets', $did_one, $index );
}

View all references View on Trac View on GitHub

Hooks

do_action( ‘dynamic_sidebar’, array $widget )

Fires before a widget’s display callback is called.

do_action( ‘dynamic_sidebar_after’, int|string $index, bool $has_widgets )

Fires after widgets are rendered in a dynamic sidebar.

do_action( ‘dynamic_sidebar_before’, int|string $index, bool $has_widgets )

Fires before widgets are rendered in a dynamic sidebar.

apply_filters( ‘dynamic_sidebar_has_widgets’, bool $did_one, int|string $index )

Filters whether a sidebar has widgets.

apply_filters( ‘dynamic_sidebar_params’, array $params )

Filters the parameters passed to a widget’s display callback.

Uses Description
sanitize_title()wp-includes/formatting.php

Sanitizes a string into a slug, which can be used in URLs or HTML attributes.
wp_get_sidebars_widgets()wp-includes/widgets.php

Retrieves the full list of sidebars and their widget instance IDs.
is_admin()wp-includes/load.php

Determines whether the current request is for an administrative interface page.
do_action()wp-includes/plugin.php

Calls the callback functions that have been added to an action hook.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.

Show 3 moreShow less

Used by Description
WP_Customize_Widgets::render_widget_partial()wp-includes/class-wp-customize-widgets.php

Renders a specific widget using the supplied sidebar arguments.
wp_list_widget_controls()wp-admin/includes/widgets.php

Show the widgets and their settings for a sidebar.

Changelog

Version Description
2.2.0 Introduced.

User Contributed Notes

  2. Skip to note 5 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

    dynamic_sidebar() callback is useful for, if you have no sidebar.php file to query and; for using sidebars that may not have a template. Hence the term “dynamic.” By dynamic this means the sidebar may have been generated in the themes register_sidebar(array($arguments)) function.

    As @Codex demonstrates, it is always good to verify the sidebar is ACTIVE (set in the Widgets admin page) and not empty. This prevents an empty div section on the page which might create empty space or broken alignment of page view. Using PHP conditional statements like else, if or case switch; in your template is the safest way to render a dynamic sidebar. It also give your theme context if the admin has not found the time to put a sidebar into a widget.

    <section id="sidebar">

    
    
    <br>
    
        
    
        <div class="meta-default">

            
                

					<nav class="sidebar-login">
                        <ul></ul>
					</nav>
        </div>

    

</section>

  3. Skip to note 6 content


    benoitadam


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

    I just got into hell with the famous

    Your theme has 3 widget areas, but this particular page doesn’t display them.

    You can navigate to other pages on your site while using the Customiser to view and edit the widgets displayed on those pages.

    Turns out activating jquery from a CDN for me leads to that error.

    Not sure at that point if it is a specific version error or CDN. THus, I heard WordPress has jQuery integrated now