概述

wp_widget_description() 函数用于检索已注册小部件的描述信息，该描述通常在小部件管理面板或主题中显示。

关键要点

• 函数接受一个必需参数 $id，类型为 int 或 string，表示小部件 ID。
• 返回值为 string 或 void，如果小部件有描述则返回描述字符串，否则无返回值。
• 函数内部检查 $id 是否为标量，并查询全局变量 $wp_registered_widgets 来获取描述。
• 描述在注册小部件时通过 'description' 选项设置，返回前使用 esc_html() 进行转义以确保安全。

代码示例

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

    global $wp_registered_widgets;

    if ( isset( $wp_registered_widgets[ $id ]['description'] ) ) {
        return esc_html( $wp_registered_widgets[ $id ]['description'] );
    }
}

注意事项

• 确保 $id 参数是有效的标量类型，否则函数会提前返回。
• 描述字符串通过 esc_html() 转义，适合直接输出到 HTML 中，避免 XSS 攻击。
• 此函数自 WordPress 2.5.0 版本引入，相关函数包括 wp_widget_control()。