WordPress 7.2 后台菜单与管理栏图标改用内联 SVG：开发者适配清单

WordPress 7.2 Beta 的后台管理界面里，一个不易察觉却会影响所有插件与主题的改动正在发生：后台管理栏（admin bar）和侧边菜单（menu）中的图标，已经从通过 CSS ::before 绘制的 Dashicons 字体字形，换成了来自 @wordpress/icons 的内联 SVG（inline SVG）。这是官方「逐步替换 Dashicons 」计划的一部分。对绝大多数站点来说它是透明的，但如果你写过自定义管理界面样式、或直接修改过核心图标，就需要留意下文要点。想了解 7.2 的整体进度，可看 WordPress 7.2 Beta 4 发布 与 WordPress 7.2 Beta 1 首发功能。

这次到底改了什么

• 字体图标 → 内联 SVG：颜色通过 currentColor 继承，不再依赖单独的字体文件，渲染更可控、也更容易随主题着色。
• 注册方式不变：注册菜单页面、管理栏节点的写法本身没有变化，变化的只是图标「画出来」的方式。

哪些情况才需要改

大多数插件和主题无需任何改动。只有两种情形需要更新：

• 你自定义了管理颜色方案（admin color schemes）或管理主题（admin themes）里针对图标的 CSS；
• 你直接替换过核心图标的插件。

其余情况（图片 URL 、 base64 SVG 、none）的渲染方式完全不变。

新增的图标 API

WordPress 7.2 引入了一套图标注册机制：

• wp_register_icon_collection()：注册一个图标集合；
• wp_register_icon()：在集合内注册具体图标；
• wp_is_valid_icon_name()：判断名字是否符合 collection/icon-name 命名空间形式（不检查是否已注册）；
• WP_Icons_Registry::get_instance()->is_registered('collection/icon-name')：检查某个图标是否已注册。

同时，多个既有函数的图标参数现在接受「已注册图标的命名空间名称」，例如 core-admin/pin：

• add_menu_page() 第 6 个参数（图标）；
• register_post_type() 的 menu_icon；
• WP_Admin_Bar::add_node() 新增的 icon 参数（图标渲染在标题之前）。

用 add_menu_page() 传入 SVG 图标名：

add_menu_page(
    __( 'Notes', 'my-plugin' ),
    __( 'Notes', 'my-plugin' ),
    'manage_options',
    'my-plugin-notes',
    'my_plugin_render_notes',
    'core-admin/pin' // 现在支持已注册的图标名
);

用 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
);

开发者如何适配自定义图标

• 优先用核心 core-admin 集合：名称稳定，不会变更或移除（预览见 Storybook 图标库）。不要把前台/内容用的 core 集合用于管理界面图标，它可能被主题或插件注销。
• 要用自己的图标：通过 wp_register_icon_collection() + wp_register_icon() 注册集合，再按上述方式引用，格式统一为 collection/icon-name。
• 跨版本兼容：如需同时支持 7.2 之前版本，用 function_exists('wp_is_valid_icon_name') 判断，存在则传命名空间名称，否则回退到 Dashicon（官方给出了三种兼容写法 A/B/C）。

向后兼容要点（别踩坑）

• 侧边栏菜单：现有核心菜单数据不变，仍包含 dashicons-* 值；你用 Dashicon 且在 core-admin 有对应项时，会自动渲染成 SVG 。其余 Dashicon / 图片 URL / base64 / none 渲染完全不变。
• 管理栏：核心节点上 .ab-icon 带 content 的 ::before 仍会替换图标；第三方节点渲染不变。
• PHP 层面：过去一些核心节点标题里嵌了空 <span class="ab-icon"> 来画图标，现在除 wp-logo 外都已改用 icon 参数。例如 new-content 节点的 title 从 <span class="ab-icon">…</span><span class="ab-label">New</span> 变为 <span class="ab-label">New</span>。依赖查找空 span 的代码要更新。

CSS 怎么改（关键）

因为图标变成了真实 SVG 元素，所有针对 ::before 伪元素的着色/隐藏样式都不再生效，必须同时作用于真实元素。以颜色方案为例：

/* 旧：只针对伪元素 */
#adminmenu div.wp-menu-image::before { color: #c3c4c7; }
#wpadminbar li:hover .ab-icon::before { color: #72aee6; }

/* 新：7.2 与早期版本都兼容 */
#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; }

隐藏核心图标、用图片替换图标、通过 .ab-item::before 替换管理栏图标等场景，都要做同样的「元素 + 伪元素」双写。官方说明对 hover / focus / current / open 以及 .mobile 规则都列出了对应写法。

快速适配清单

常见问题