跳到正文
原文
Make WordPress Core（核心开发）· Ashar Fuadi·· 11 小时前精选编辑评分77

WordPress 7.2 将后台栏与菜单图标改为内联 SVG

SVG icons in the admin bar and menu in WordPress 7.2

编辑导读

WordPress 7.2 Beta 将后台栏和菜单中的核心图标从 Dashicons 字体字形改为 @wordpress/icons 内联 SVG，大多数插件和主题无需调整，但修改图标颜色、隐藏或替换逻辑的 CSS 与 PHP 可能需要更新。

推荐理由

文章梳理了 WordPress 7.2 后台图标改为 SVG 后的兼容变化，并为颜色、隐藏、替换图标及兼容旧版本提供可迁移的代码方案。

你可能已经注意到 WordPress 7.2 Beta 管理界面中闪亮的新图标。正如之前在 Replacing Dashicons in the admin bar and menu 中宣布的那样，管理栏和菜单中的图标现在采用来自 @wordpress/icons 的内联 SVG。此前，它们是通过 CSS ::before 绘制的 Dashicons 字体字形。

大多数插件和主题无需更改。注册菜单页面和管理栏节点时，无论是否使用 Dashicons，均可照常工作。不过，诸如管理配色方案和管理主题之类的 CSS 可能需要稍作更新。如果你的插件修改了核心图标，也可能需要更新。

如果你的插件或主题未修改核心管理栏或菜单图标，可以直接跳到下方的 新 API 部分。

  1. 需要更新：配色方案
  2. 需要更新：核心图标修改
  3. 保持不变的功能
  4. 使用 SVG 图标的新 API
  5. 支持更早的 WordPress 版本
  6. 附录：HTML 标记变化

需要更新：配色方案

此前所有通过 ::before 设置核心图标样式的 CSS 规则，现在都无法再为这些图标设置样式，因为它们已成为内联 SVG 元素。

如果你的配色方案通过 ::before 为图标着色，为了向后兼容，WordPress 会使用以下尽力而为的规则，在更新之前保持这些颜色：

  • 侧边栏菜单：图标会使用你传递给 wp_admin_css_color() 的图标颜色，并以菜单文字颜色作为后备。
  • 管理栏：如果你使用 SASS 根据核心的 _admin.scss 生成样式表，那么它已经会为 .ab-icon 元素着色（幸运的是），因此图标能够保留预期颜色。

否则，图标会使用核心的默认颜色，而这些颜色可能并非你预期的颜色。要彻底修复你的配色方案，请在样式表中通过 ::before 为图标着色的地方，也同时为该元素着色。SVG 将继承该元素的颜色。对于为 .ab-item::before 设置颜色的规则，也请为 .ab-icon 设置颜色。

/* Before */
#adminmenu div.wp-menu-image::before { color: #c3c4c7; }
#wpadminbar li:hover .ab-icon::before { color: #72aee6; }
#wpadminbar #wp-admin-bar-site-name > .ab-item::before { color: #c3c4c7; }
/* After (works on 7.2 and earlier versions) */
#adminmenu div.wp-menu-image,
#adminmenu div.wp-menu-image::before { color: #c3c4c7; }
#wpadminbar li:hover .ab-icon,
#wpadminbar li:hover .ab-icon::before { color: #72aee6; }
#wpadminbar #wp-admin-bar-site-name > .ab-item .ab-icon,
#wpadminbar #wp-admin-bar-site-name > .ab-item::before { color: #c3c4c7; }

请对相应的悬停、聚焦、当前和展开状态，以及 .mobile 规则执行同样的操作。上面的规则仅供参考。

需要更新：核心图标修改

CSS：隐藏核心图标

通过 ::before 隐藏图标已不再起作用，因为图标现在是一个元素。请同时隐藏该元素。

/* Before */
#adminmenu #menu-comments div.wp-menu-image::before { display: none; }
#wpadminbar #wp-admin-bar-wp-logo > .ab-item .ab-icon::before { display: none; }
#wpadminbar #wp-admin-bar-edit > .ab-item::before { display: none; }
/* After (works on 7.2 and earlier versions) */
#adminmenu #menu-comments div.wp-menu-image::before,
#adminmenu #menu-comments div.wp-menu-image svg { display: none; }
#wpadminbar #wp-admin-bar-wp-logo > .ab-item .ab-icon { display: none; }
#wpadminbar #wp-admin-bar-edit > .ab-item::before,
#wpadminbar #wp-admin-bar-edit > .ab-item .ab-icon { display: none; }

CSS：使用图片替换核心图标

将背景图片设置到字形上并使字形透明的样式，过去依赖核心的 content 来创建该框。请自行设置 content 和尺寸。

/* Before */
#adminmenu #menu-posts div.wp-menu-image::before {
    background-image: url(logo.png);
    color: transparent;
}
#wpadminbar #wp-admin-bar-wp-logo > .ab-item .ab-icon::before {
    background-image: url(logo.png);
    color: transparent;
}
/* After (works on 7.2 and earlier versions) */
#adminmenu #menu-posts div.wp-menu-image::before {
    content: "";
    background: url(logo.png) center / 20px 20px no-repeat;
}
#wpadminbar #wp-admin-bar-wp-logo > .ab-item .ab-icon::before {
    content: "";
    display: inline-block;
    width: 20px;
    height: 20px;
    background: url(logo.png) center / contain no-repeat;
}

CSS：通过 .ab-item::before 替换核心管理栏图标

这适用于过去使用 .ab-item::before 绘制图标的管理栏节点：edit、customize、site-editor、my-sites、site-name 和 my-account。图标现在是一个独立的 .ab-icon 元素，因此设置在 .ab-item::before 上的 content 不再能够替换它。你的字形会被隐藏，取而代之的是显示核心图标。

要修复此问题，请在图标元素的 ::before 上也设置 content，该元素将取代核心图标。

/* Before */
#wpadminbar #wp-admin-bar-edit > .ab-item::before { content: "\f319"; }
/* After (works on 7.2 and earlier versions) */
#wpadminbar #wp-admin-bar-edit > .ab-item::before,
#wpadminbar #wp-admin-bar-edit > .ab-item .ab-icon::before { content: "\f319"; }

PHP：修改核心管理栏节点的标题或图标

某些核心节点的标题过去包含空的 <span class="ab-icon">，用于绘制图标。现在，这些节点以及其他核心管理栏节点都不再包含该空 span，而是使用新的 icon 参数设置图标。但 wp-logo 除外，其标题本身包含徽标图标。例如：

  • $wp_admin_bar->get_node( 'new-content' )->title:
    • 过去：<span class="ab-icon" aria-hidden="true"></span><span class="ab-label">New</span>
    • 现在：<span class="ab-label">New</span>
  • $wp_admin_bar->get_node( 'wp-logo' )->title:
    • 过去：<span class="ab-icon" aria-hidden="true"></span><span class="screen-reader-text">About WordPress</span>
      现在：<span class="ab-icon svg-icon" aria-hidden="true"><svg …>…</svg></span><span class="screen-reader-text">About WordPress</span>

在这些标题中查找空 span 的代码将无法再找到它，需要进行更新。另请参阅下方“支持更早的 WordPress 版本”部分，了解如何修改可跨版本使用的管理栏节点。另请参阅附录，了解完整的标记变化。

CSS：为前台搜索图标、默认的“我的站点”网站图标或“折叠菜单”图标设置样式

这些图标的伪元素样式不再对其生效。请改为定位新元素。

/* Before */
#wpadminbar #adminbarsearch::before { color: red; }
#wpadminbar .quicklinks li div.blavatar::before { color: red; }
#collapse-button .collapse-button-icon::after { color: red; }
/* After (works on 7.2 and earlier versions) */
#wpadminbar #adminbarsearch::before,
#wpadminbar #adminbarsearch .ab-icon { color: red; }
#wpadminbar .quicklinks li div.blavatar::before,
#wpadminbar .quicklinks li div.blavatar svg { color: red; }
#collapse-button .collapse-button-icon::after,
#collapse-button .collapse-button-icon svg { color: red; }

CSS：通过 Dashicon 类定位菜单项

现在请改用该项的 id 或其 menu-icon-* 类。

/* Before */
#adminmenu .dashicons-admin-post::before { content: "\f319"; }
/* After (works on 7.2 and earlier versions) */
#adminmenu .dashicons-admin-post::before { content: "\f319"; }
#adminmenu .menu-icon-post div.wp-menu-image::before { content: "\f319"; }

请注意，旧的 Dashicon 类会匹配所有使用该 Dashicon 的菜单项，而 id 或 menu-icon-* 类只会匹配一个项目。

仍然有效的内容

为实现向后兼容，WordPress 无需修改即可继续支持最常见的自定义设置。

侧边栏菜单

  • Existing core menu data is unchanged, including the dashicons-* icon values. For example:
    • get_post_type_object( 'post' )->menu_icon 仍然是 dashicons-admin-post。
    • 全局 $menu 和 REST API 仍然保留相同的 dashicons-* 值。
  • If a plugin uses Dashicon in menu_icon and it has a matching core-admin icon, that SVG icon will be rendered instead. This includes post types with no menu_icon, which default to dashicons-admin-post.
    • 有关 core-admin 集合的更多信息，请参阅下方的“新 API”部分。
  • 任何其他 Dashicon、图片 URL、base64 SVG 或 none 值都会像以前一样呈现。
  • 在 div.wp-menu-image 上带有 content 的 ::before 仍会替换图标，且不会显示 SVG。

管理栏

  • 在所有核心节点上，在 .ab-icon 上带有 content 的 ::before 仍会替换图标。
  • 第三方节点的呈现效果与以前完全相同。

使用 SVG 图标的新 API

如果你想在自己的侧边栏菜单项和管理栏节点中使用 SVG 图标，而不是 Dashicons，现在可以在注册菜单页面、文章类型和管理栏节点时传入已注册图标的名称。

要使用哪些图标

你可以使用核心 core-admin 集合中的图标。图标添加到 core-admin 后，其名称不会更改，也不会被移除。你可以在 Storybook 的图标库中预览该集合。开发者插件的反馈将用于向 core-admin 添加更多图标。

请勿将 core 集合用于管理图标。它专为前端、内容和图标区块而设计。有些插件或主题可能需要注销 core 图标。

你也可以使用自己的图标。通过 wp_register_icon_collection() 和 wp_register_icon() 注册你自己的集合及其图标，然后以相同方式使用它们。

作为菜单图标的图标名称

除现有的 Dashicons、URL、base64 SVG 和 none 值之外，add_menu_page() 以及 register_post_type() 的 menu_icon 参数现在也接受已注册图标的命名空间名称。

add_menu_page(
    __( 'Notes', 'my-plugin' ),
    __( 'Notes', 'my-plugin' ),
    'manage_options',
    'my-plugin-notes',
    'my_plugin_render_notes',
    'core-admin/pin' // Now allowed: a registered icon name.
);

管理栏节点的 icon 参数

WP_Admin_Bar::add_node() 现在接受 icon 参数，即已注册图标的命名空间名称。图标会呈现在标题之前。

add_action(
    'admin_bar_menu',
    function ( WP_Admin_Bar $wp_admin_bar ) {
        $wp_admin_bar->add_node(
            array(
                'id'    => 'my-plugin-notes',
                'icon'  => 'core-admin/pin',
                'title' => __( 'Notes', 'my-plugin' ),
                'href'  => admin_url( 'admin.php?page=my-plugin-notes' ),
            )
        );
    },
    100
);

在这两种情况下，未注册的名称不会呈现任何图标。启用 WP_DEBUG 时，还会触发 _doing_it_wrong() 通知。

wp_is_valid_icon_name()

一个新增的辅助函数，用于返回某个值是否具有命名空间图标名称（collection/icon-name）的形式。它不会检查图标是否已注册。

支持更早的 WordPress 版本

如果你的插件过去在管理菜单或管理栏中显示 Dashicon，并且希望继续支持更早的版本，请遵循以下说明。

这取决于你的 Dashicon 是否已在 core-admin 集合中有官方替代图标。请在清单中的此处查看图标替代映射。在 'dashicons' 键中搜索你的 Dashicon。

如果你的 Dashicon 在 7.2 中没有官方 core-admin 图标替代项，或你想使用自己的 SVG 图标

你仍然可以使用任何备选的 core-admin 图标或自己的 SVG 图标，但需要明确传入图标名称。

对于管理菜单（add_menu_page() 和 register_post_type()），由于更早的版本不支持图标名称，请使用 function_exists( 'wp_is_valid_icon_name' ) 进行条件控制。相比之下，管理栏节点的新参数在更早的版本中会被忽略，而标题中的空 span 在 7.2 中会被隐藏，因此你可以同时传入旧的 Dashicon 和新的 SVG 图标，如下所示。

add_menu_page(
    ...,
    function_exists( 'wp_is_valid_icon_name' ) ? 'core-admin/receipt' : 'dashicons-text'
);
$wp_admin_bar->add_node(
    array(
        ...
        'title' => '<span class="ab-icon dashicons-text" aria-hidden="true"></span> My Node',
        'icon'  => 'core-admin/receipt',
    )
);

如果你的 Dashicon 在 7.2 中有官方 core-admin 图标替代项

从 7.2 开始，管理菜单图标将自动替换为 SVG 图标。不过，对于管理栏节点图标，你仍需明确传入映射后的图标名称。

add_menu_page(
    ...,
    'dashicons-cart'
);
$wp_admin_bar->add_node(
    array(
        ...
        'title' => '<span class="ab-icon dashicons-cart" aria-hidden="true"></span> My Node',
        'icon'  => 'core-admin/cart',
    )
);

如果你的 Dashicon 在晚于 7.2 的版本中有官方的 core-admin 图标替代品

在未来版本中，WordPress 可能会向 core-admin 集合添加更多图标，并映射到更多 Dashicon。将来，如果注册了新的 core-admin 图标并希望使用它，你还需要进一步使用注册检查来限制它，如下所示。

$icon = 'dashicons-text';              // for < 7.2
if ( function_exists( 'wp_is_valid_icon_name' ) ) {
    $registry = WP_Icons_Registry::get_instance();
    if ( $registry->is_registered( 'core-admin/invoice' ) ) {
        $icon = 'core-admin/invoice';  // for > 7.2 (as an example)
    } elseif ( $registry->is_registered( 'core-admin/receipt' )  ) {
        $icon = 'core-admin/receipt';  // for 7.2
    }
}
add_menu_page(
    ...,
    $icon
);
$wp_admin_bar->add_node(
    array(
        ...
        'title' => '<span class="ab-icon dashicons-text" aria-hidden="true"></span> My Node',
        'icon'  => $icon,
    )
);

附录：HTML 标记变更

本附录展示了每个图标的标记和 CSS 是如何变化的，适用于直接针对这些图标编写的代码。

显示标记变更

侧边栏菜单项

核心顶级菜单项所用的十二个 Dashicon 现在以内联 SVG 形式绘制：Dashboard、Posts、Media、Links、Pages、Comments、Appearance、Plugins、Users、Tools、Settings，以及（在网络管理中）Sites。折叠菜单按钮的箭头也是如此。

使用这十二个 Dashicon 之一的菜单项，例如 Posts：

<!-- Before 7.2 -->
<div class='wp-menu-image dashicons-before dashicons-admin-post' aria-hidden='true'><br /></div>

.dashicons-admin-post::before { content: "\f109"; }
<!-- In 7.2 -->
<div class='wp-menu-image dashicons-before svg-icon' aria-hidden='true'><svg …>…</svg></div>

图标颜色现在设置在 div.wp-menu-image 上，并通过 currentColor 继承到 SVG。

折叠菜单按钮：

<!-- Before 7.2 -->
<span class="collapse-button-icon" aria-hidden="true"></span>

#collapse-button .collapse-button-icon::after { content: "\f148"; }
<!-- In 7.2 -->
<span class="collapse-button-icon" aria-hidden="true"><svg …>…</svg></span>

管理栏节点

在 7.2 之前，大多数核心节点的图标会绘制在 .ab-item::before 或 .ab-icon::before 上。搜索图标和默认站点图标各有自己的规则。现在，它们全部以内联 SVG 形式绘制。

.ab-item::before 上的图标： edit、customize、site-editor、my-sites、site-name，以及没有头像时的 my-account。

<!-- Before 7.2 -->
<a class='ab-item' href='…'>Edit Post</a>

#wpadminbar #wp-admin-bar-edit > .ab-item::before { content: "\f464"; }
<!-- In 7.2 -->
<a class='ab-item' href='…'><span class="ab-icon svg-icon" aria-hidden="true"><svg …>…</svg></span>Edit Post</a>

.ab-icon::before 上的图标，其中在 7.2 之前，span 是节点标题的一部分：wp-logo、menu-toggle、command-palette、new-content、comments 和 updates。在 7.2 中，除了 wp-logo 之外，该 span 不再位于标题中，图标会根据 icon 参数呈现。

<!-- Before 7.2 -->
<a class='ab-item' href='…'><span class="ab-icon" aria-hidden="true"></span><span class="ab-label">New</span></a>

#wpadminbar #wp-admin-bar-new-content .ab-icon::before { content: "\f132"; }
<!-- In 7.2 -->
<a class='ab-item' href='…'><span class="ab-icon svg-icon" aria-hidden="true"><svg …>…</svg></span><span class="ab-label">New</span></a>

搜索，在前端：

<!-- Before 7.2 -->
<form id="adminbarsearch" …><input …>…</form>

#wpadminbar #adminbarsearch::before { content: "\f179"; }
<!-- In 7.2 -->
<form id="adminbarsearch" …><span class="ab-icon svg-icon" aria-hidden="true"><svg …>…</svg></span><input …>…</form>

“我的站点”列表中的默认站点图标：

<!-- Before 7.2 -->
<div class="blavatar"></div>

#wpadminbar .quicklinks li div.blavatar::before { content: "\f120"; }
<!-- In 7.2 -->
<div class="blavatar"><svg …>…</svg></div>

图标颜色现在设置在 .ab-icon 上，默认站点图标则设置在 div.blavatar 上，并通过 currentColor 继承到 SVG。

感谢 @audrasjb、@peterwilsoncc、@mcsf 和 @wildworks 审阅此开发说明。

#7-2、#dev-notes、#dev-notes-7-2

来源：Make WordPress Core（核心开发） · https://make.wordpress.org/core/2026/11/05/svg-icons-in-the-admin-bar-and-menu-in-wordpress-7-2/

部分链接为推广/关联链接。

#核心更新#区块编辑器#插件开发#主题开发