函数文档

wp_admin_bar_my_sites_menu()

💡 云策文档标注

概述

wp_admin_bar_my_sites_menu() 函数用于在 WordPress 管理工具栏中添加“我的站点/[站点名称]”菜单及其所有子菜单,适用于多站点环境。该函数根据用户权限和站点配置动态生成菜单项,包括网络管理员选项和各个站点的链接。

关键要点

  • 函数仅在用户已登录且启用多站点模式时执行,否则直接返回。
  • 菜单显示条件:用户至少拥有一个站点或为超级管理员。
  • 主菜单项“My Sites”链接到 my-sites.php 页面,URL 根据用户活动站点动态生成。
  • 超级管理员(manage_network 权限)会看到网络管理员子菜单,包含仪表板、站点、用户、主题、插件和设置等子项。
  • 为每个用户站点添加链接组,显示站点图标(可通过 wp_admin_bar_show_site_icons 过滤器控制)、名称和子菜单(如仪表板、新建文章、管理评论、访问站点)。
  • 使用 WP_Admin_Bar::add_node() 和 WP_Admin_Bar::add_group() 构建菜单结构,涉及 switch_to_blog() 和 restore_current_blog() 切换站点上下文。

代码示例

function wp_admin_bar_my_sites_menu( $wp_admin_bar ) {
    // Don't show for logged out users or single site mode.
    if ( ! is_user_logged_in() || ! is_multisite() ) {
        return;
    }

    // Show only when the user has at least one site, or they're a super admin.
    if ( count( $wp_admin_bar->user->blogs ) < 1 && ! current_user_can( 'manage_network' ) ) {
        return;
    }

    // 主菜单节点添加示例
    $wp_admin_bar->add_node(
        array(
            'id'    => 'my-sites',
            'title' => __( 'My Sites' ),
            'href'  => $my_sites_url,
        )
    );
}

注意事项

  • 站点图标显示默认启用,但可通过 apply_filters( 'wp_admin_bar_show_site_icons', true ) 过滤器调整,关闭以提升大型多站点性能。
  • 函数内部依赖多个 WordPress 核心函数和类,如 current_user_can() 检查权限、get_site_icon_url() 获取图标 URL,确保环境兼容。
  • 菜单项 ID 和结构需遵循 WordPress 工具栏规范,避免冲突。

📄 原文内容

Adds the “My Sites/[Site Name]” menu and all submenus.

Parameters

$wp_admin_barWP_Admin_Barrequired
The WP_Admin_Bar instance.

Source

function wp_admin_bar_my_sites_menu( $wp_admin_bar ) {
	// Don't show for logged out users or single site mode.
	if ( ! is_user_logged_in() || ! is_multisite() ) {
		return;
	}

	// Show only when the user has at least one site, or they're a super admin.
	if ( count( $wp_admin_bar->user->blogs ) < 1 && ! current_user_can( 'manage_network' ) ) {
		return;
	}

	if ( $wp_admin_bar->user->active_blog ) {
		$my_sites_url = get_admin_url( $wp_admin_bar->user->active_blog->blog_id, 'my-sites.php' );
	} else {
		$my_sites_url = admin_url( 'my-sites.php' );
	}

	$wp_admin_bar->add_node(
		array(
			'id'    => 'my-sites',
			'title' => __( 'My Sites' ),
			'href'  => $my_sites_url,
		)
	);

	if ( current_user_can( 'manage_network' ) ) {
		$wp_admin_bar->add_group(
			array(
				'parent' => 'my-sites',
				'id'     => 'my-sites-super-admin',
			)
		);

		$wp_admin_bar->add_node(
			array(
				'parent' => 'my-sites-super-admin',
				'id'     => 'network-admin',
				'title'  => __( 'Network Admin' ),
				'href'   => network_admin_url(),
			)
		);

		$wp_admin_bar->add_node(
			array(
				'parent' => 'network-admin',
				'id'     => 'network-admin-d',
				'title'  => __( 'Dashboard' ),
				'href'   => network_admin_url(),
			)
		);

		if ( current_user_can( 'manage_sites' ) ) {
			$wp_admin_bar->add_node(
				array(
					'parent' => 'network-admin',
					'id'     => 'network-admin-s',
					'title'  => __( 'Sites' ),
					'href'   => network_admin_url( 'sites.php' ),
				)
			);
		}

		if ( current_user_can( 'manage_network_users' ) ) {
			$wp_admin_bar->add_node(
				array(
					'parent' => 'network-admin',
					'id'     => 'network-admin-u',
					'title'  => __( 'Users' ),
					'href'   => network_admin_url( 'users.php' ),
				)
			);
		}

		if ( current_user_can( 'manage_network_themes' ) ) {
			$wp_admin_bar->add_node(
				array(
					'parent' => 'network-admin',
					'id'     => 'network-admin-t',
					'title'  => __( 'Themes' ),
					'href'   => network_admin_url( 'themes.php' ),
				)
			);
		}

		if ( current_user_can( 'manage_network_plugins' ) ) {
			$wp_admin_bar->add_node(
				array(
					'parent' => 'network-admin',
					'id'     => 'network-admin-p',
					'title'  => __( 'Plugins' ),
					'href'   => network_admin_url( 'plugins.php' ),
				)
			);
		}

		if ( current_user_can( 'manage_network_options' ) ) {
			$wp_admin_bar->add_node(
				array(
					'parent' => 'network-admin',
					'id'     => 'network-admin-o',
					'title'  => __( 'Settings' ),
					'href'   => network_admin_url( 'settings.php' ),
				)
			);
		}
	}

	// Add site links.
	$wp_admin_bar->add_group(
		array(
			'parent' => 'my-sites',
			'id'     => 'my-sites-list',
			'meta'   => array(
				'class' => current_user_can( 'manage_network' ) ? 'ab-sub-secondary' : '',
			),
		)
	);

	/**
	 * Filters whether to show the site icons in toolbar.
	 *
	 * Returning false to this hook is the recommended way to hide site icons in the toolbar.
	 * A truthy return may have negative performance impact on large multisites.
	 *
	 * @since 6.0.0
	 *
	 * @param bool $show_site_icons Whether site icons should be shown in the toolbar. Default true.
	 */
	$show_site_icons = apply_filters( 'wp_admin_bar_show_site_icons', true );

	foreach ( (array) $wp_admin_bar->user->blogs as $blog ) {
		switch_to_blog( $blog->userblog_id );

		if ( true === $show_site_icons && has_site_icon() ) {
			$blavatar = sprintf(
				'<img class="blavatar" src="%s" srcset="%s 2x" alt="" width="16" height="16"%s />',
				esc_url( get_site_icon_url( 16 ) ),
				esc_url( get_site_icon_url( 32 ) ),
				( wp_lazy_loading_enabled( 'img', 'site_icon_in_toolbar' ) ? ' loading="lazy"' : '' )
			);
		} else {
			$blavatar = '<div class="blavatar"></div>';
		}

		$blogname = $blog->blogname;

		if ( ! $blogname ) {
			$blogname = preg_replace( '#^(https?://)?(www.)?#', '', get_home_url() );
		}

		$menu_id = 'blog-' . $blog->userblog_id;

		if ( current_user_can( 'read' ) ) {
			$wp_admin_bar->add_node(
				array(
					'parent' => 'my-sites-list',
					'id'     => $menu_id,
					'title'  => $blavatar . $blogname,
					'href'   => admin_url(),
				)
			);

			$wp_admin_bar->add_node(
				array(
					'parent' => $menu_id,
					'id'     => $menu_id . '-d',
					'title'  => __( 'Dashboard' ),
					'href'   => admin_url(),
				)
			);
		} else {
			$wp_admin_bar->add_node(
				array(
					'parent' => 'my-sites-list',
					'id'     => $menu_id,
					'title'  => $blavatar . $blogname,
					'href'   => home_url(),
				)
			);
		}

		if ( current_user_can( get_post_type_object( 'post' )->cap->create_posts ) ) {
			$wp_admin_bar->add_node(
				array(
					'parent' => $menu_id,
					'id'     => $menu_id . '-n',
					'title'  => get_post_type_object( 'post' )->labels->new_item,
					'href'   => admin_url( 'post-new.php' ),
				)
			);
		}

		if ( current_user_can( 'edit_posts' ) ) {
			$wp_admin_bar->add_node(
				array(
					'parent' => $menu_id,
					'id'     => $menu_id . '-c',
					'title'  => __( 'Manage Comments' ),
					'href'   => admin_url( 'edit-comments.php' ),
				)
			);
		}

		$wp_admin_bar->add_node(
			array(
				'parent' => $menu_id,
				'id'     => $menu_id . '-v',
				'title'  => __( 'Visit Site' ),
				'href'   => home_url( '/' ),
			)
		);

		restore_current_blog();
	}
}

Hooks

apply_filters( ‘wp_admin_bar_show_site_icons’, bool $show_site_icons )

Filters whether to show the site icons in toolbar.

Changelog

Version Description
3.1.0 Introduced.