云策 WordPress 开发者社区

函数文档

show_admin_bar()

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

概述

show_admin_bar() 函数用于设置管理工具栏的显示状态，适用于插件或主题开发中控制前端和后端工具栏的可见性。它可以直接在插件加载时或主题的 functions.php 文件中调用，无需依赖 'init' 钩子。

关键要点

  • 函数接受一个布尔参数 $show，决定是否显示管理工具栏。
  • 调用时机灵活，可在插件加载时或主题 functions.php 中直接使用，无需等待 'init' 动作。
  • 影响 WordPress 3.3 版本之前的仪表板工具栏显示。
  • 提供了多种实现方式，包括直接调用、条件控制（如基于用户角色或页面类型）和使用过滤器。
  • 注意在共享插件中避免使用 add_filter( 'show_admin_bar', '__return_false' )，以免与其他插件冲突。

代码示例

// 基本示例：在主题 functions.php 中禁用前端工具栏
show_admin_bar( false );

// 条件显示：仅对管理员显示工具栏
if ( ! current_user_can( 'manage_options' ) ) {
    show_admin_bar( false );
}

// 使用过滤器隐藏前端工具栏（适用于私有主题或插件）
add_filter( 'show_admin_bar', '__return_false' );

// 基于自定义文章类型隐藏工具栏
add_action( "wp", function wp(){
  if (is_singular("course"))
    add_filter( "show_admin_bar", "__return_false" );
});

注意事项

  • 在共享插件中，推荐使用 show_admin_bar() 函数而非过滤器，以减少冲突风险。
  • 条件隐藏工具栏时，前端可使用 'wp' 动作，后端可使用 'admin_init' 动作（优先级 9）。
  • 用户个人资料中的“查看站点时显示工具栏”选项可能影响显示逻辑，需通过 get_user_option() 处理。
📄 原文内容

Sets the display status of the admin bar.

Description

This can be called immediately upon plugin load. It does not need to be called from a function hooked to the ‘init’ action.

Parameters

$showboolrequired
Whether to allow the admin bar to show.

More Information

This function should be called immediately upon plugin load or placed in the theme’s functions.php file.

This function will also affect the display of the Toolbar in the dashboard for WordPress versions prior to Version 3.3.

Source

function show_admin_bar( $show ) {
	global $show_admin_bar;
	$show_admin_bar = (bool) $show;
}

View all references View on Trac View on GitHub

Used by Description
iframe_header()wp-admin/includes/template.php

Generic Iframe header for use with Thickbox.
WP_Customize_Manager::setup_theme()wp-includes/class-wp-customize-manager.php

Starts preview and customize theme.

Changelog

Version Description
3.1.0 Introduced.

User Contributed Notes

  4. Skip to note 10 content


    Philipp Stracker


    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

    This function can be called immediately from the functions.php or the main plugin file to disable the admin-bar for all users.

    If you want to conditionally hide the admin-bar based on the current page or user role, then you can do it in/before the following actions:

    Front-End

    // To disable admin-bar on front-end, the last
// possibility is action "wp" at any Prio.
add_action( 'wp', 'prefix_maybe_hide_admin_bar' );

    wp-admin

    // To disable admin-bar inside wp-admin. the last
// possibility is action "admin_init" at Prio 9
add_action( 'admin_init', 'prefix_maybe_hide_admin_bar', 9 );

    Full sample

    add_action( 'wp', 'wpdocs_maybe_hide_admin_bar' );
add_action( 'admin_init', 'wpdocs_maybe_hide_admin_bar', 9 );

function wpdocs_maybe_hide_admin_bar() {
    if ( ! current_user_can( 'manage_options' ) ) {
        show_admin_bar( false );
    }
}

    Note:

    The init action is fired before wp and admin_init. It’s possible to use show_admin_bar() inside the init action, but other plugins might overwrite your decision at a later point.

    I do NOT recommend using the filter add_filter( 'show_admin_bar', '__return_false' ); in shared plugins! It will create conflicts with other plugins. Only use the filter in your private (child) theme or internal plugins, and stick with the show_admin_bar() function in public or shared plugins.

  6. Skip to note 12 content


    Matt Taylor


    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

    With this example we can hide the admin bar for all users, but for users with “edit posts” permissions, they can opt-in to showing the bar via the “Show Toolbar when viewing site” option on their profile.

    You can flip the logic so those users can opt-out of showing the bar as well.

    // Display the admin bar for editors and above
add_filter( 'show_admin_bar', function ( $bool ) {
	if ( empty( $bool ) ) {
		return false;
	}

	if ( current_user_can( 'edit_posts' ) ) {
		// Note: get_user_option() will return a string (ie. 'false'/'true'/'') and not a bool or null
	        $show_bar_setting = get_user_option( 'show_admin_bar_front' );

        	// Default for these users is to hide the bar but allow them to turn it on
	        return ( 'true' === $show_bar_setting ? true : false );
	}

	return false;
} );