云策 WordPress 开发者社区

函数文档

wp_sidebar_description()

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

概述

wp_sidebar_description() 函数用于检索已注册侧边栏的描述信息，该描述在注册侧边栏时通过 'description' 参数设置，并显示在小部件管理面板中。

关键要点

  • 函数接受一个必需的字符串参数 $id，表示侧边栏 ID。
  • 返回值为字符串或 void，如果侧边栏描述存在则返回经过 wp_kses() 过滤的描述文本。
  • 函数内部检查 $id 是否为标量，并访问全局变量 $wp_registered_sidebars 来获取描述。

代码示例

function wp_sidebar_description( $id ) {
    if ( ! is_scalar( $id ) ) {
        return;
    }

    global $wp_registered_sidebars;

    if ( isset( $wp_registered_sidebars[ $id ]['description'] ) ) {
        return wp_kses( $wp_registered_sidebars[ $id ]['description'], 'sidebar_description' );
    }
}

注意事项

  • 函数从 WordPress 2.9.0 版本开始引入。
  • 相关函数包括 wp_kses() 用于过滤 HTML，以及 WP_REST_Sidebars_Controller::prepare_item_for_response() 和 wp_list_widget_controls() 等。
📄 原文内容

Retrieves description for a sidebar.

Description

When registering sidebars a ‘description’ parameter can be included that describes the sidebar for display on the widget administration panel.

Parameters

$idstringrequired
sidebar ID.

Return

string|void Sidebar description, if available.

Source

function wp_sidebar_description( $id ) {
	if ( ! is_scalar( $id ) ) {
		return;
	}

	global $wp_registered_sidebars;

	if ( isset( $wp_registered_sidebars[ $id ]['description'] ) ) {
		return wp_kses( $wp_registered_sidebars[ $id ]['description'], 'sidebar_description' );
	}
}

View all references View on Trac View on GitHub

Uses Description
wp_kses()wp-includes/kses.php

Filters text content and strips out disallowed HTML.
Used by Description
WP_REST_Sidebars_Controller::prepare_item_for_response()wp-includes/rest-api/endpoints/class-wp-rest-sidebars-controller.php

Prepares a single sidebar output for response.
wp_list_widget_controls()wp-admin/includes/widgets.php

Show the widgets and their settings for a sidebar.

Changelog

Version Description
2.9.0 Introduced.