Gutenbergwordpress/core-commands深度解析可复用的 WordPress 管理后台命令调色板【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg导读wordpress/core-commands是 GutenbergWordPress 块编辑器monorepo 中的一个核心包负责把命令调色板Command Palette这一功能固化为一套可在多个 WP Admin 页面复用的内置命令集合从跳转到指定后台菜单到在站点编辑器中搜索并打开页面、文章、模板、模板部件再到一键直达 Styles、Navigation、Patterns 等区域。本文以 packages/core-commands/README.md 为骨架结合仓库源码逐层剖析其公开 API、settings 数据结构、命令注册机制与底层实现帮助你理解如何在自己的项目中初始化命令调色板以及 WordPress 内置命令是如何被组织与加载的。包定位它解决什么问题Gutenberg 的命令调色板按cmdk/CtrlK唤出本身由更底层的wordpress/commands包提供通用能力注册静态命令、注册动态命令加载器command loader、按上下文context与类别category组织命令。而wordpress/core-commands的职责是把这些能力沉淀为WordPress 核心可复用的命令——即那些在任何后台页面都通用、与具体编辑器无关的管理命令。从 package.json 中的描述可以确认该包的定位是 WordPress core reusable commands。它依赖了wordpress/commands、wordpress/core-data、wordpress/data、wordpress/router、wordpress/url、wordpress/icons、wordpress/i18n等一系列包并通过wordpress/private-apis来隔离内部私有 API。安装与环境要求README 给出的安装方式非常简单npm install wordpress/core-commands --save环境要求README 原文明确说明该包假定你的代码运行在ES2015环境中如果你的运行环境对这类语言特性与 API 支持有限或完全不支持应引入wordpress/babel-preset-default内置的 polyfill。从 package.json 还能看到更精确的工程约束Node 版本要求18.12.0npm 版本要求8.19.2React 的 peer 依赖范围为^18 || ^19也就是说同时支持 React 18 与 React 19对应 CHANGELOG.md 中 1.51.0 版本 Widen React peer dependency ranges 的记录包同时提供 CommonJSbuild/index.cjs与 ES Modulebuild-module/index.mjs两种构建产物。公开 APIinitializeCommandPalette( settings )README 的 API 章节由自动生成文档标注START/END TOKEN(Autogenerated API docs)给出两个导出项API说明initializeCommandPalette( settings )初始化命令调色板settings为Object类型privateApis未文档化的私有 API 声明供 Gutenberg 核心模块内部使用实现细节入口如何工作initializeCommandPalette的实现在 packages/core-commands/src/index.jsx 中核心流程如下export function initializeCommandPalette( settings ) { const root document.createElement( div ); document.body.appendChild( root ); createRoot( root ).render( StrictMode CommandPalette settings{ settings } / /StrictMode ); }关键点手动挂载到document.body它动态创建一个div并 append 到 body再用wordpress/element的createRoot渲染CommandPalette组件。这意味着该函数是命令调色板在某个后台页面中的启动入口由宿主页面如 WP Admin 页面在合适的时机调用。渲染在StrictMode下便于在开发阶段暴露潜在副作用。CommandPalette内部拆解 settings源码第 12-22 行function CommandPalette( { settings } ) { const { menu_commands: menuCommands, is_network_admin: isNetworkAdmin } settings; useAdminNavigationCommands( menuCommands ); useSiteEditorNavigationCommands( isNetworkAdmin ); return ( RouterProvider pathArgp CommandMenu / /RouterProvider ); }由此可以确认settings对象支持两个字段字段名沿用 PHP 序列化风格的 snake_case可以推断该 settings 来自服务端通过wp_localize_script一类机制注入的配置数据menu_commands后台菜单项列表。每个元素至少包含name菜单项唯一名与label菜单显示文本源码中还用到了url字段进行跳转。is_network_admin布尔值标记当前是否为多站点网络管理后台Network Admin。该值用于禁用站点编辑器相关命令——在 packages/core-commands/src/site-editor-navigation-commands.js 中所有useCommandLoader调用都传入了disabled: isNetworkAdmin。RouterProvider pathArgp来自wordpress/router的私有 API通过unlock()解锁。pathArgp表示路由状态通过 URL 查询参数p传递——这正是站点编辑器命令通过 URL 参数p/templates/...导航的实现基础。核心实现一管理后台导航命令useAdminNavigationCommands源码位于 packages/core-commands/src/admin-navigation-commands.js。静态命令把菜单项变成命令useAdminNavigationCommands( menuCommands )把传入的menu_commands数组映射为静态命令并注册const commands useMemo( () { return ( menuCommands ?? [] ).map( ( menuCommand ) { const label sprintf( /* translators: %s: menu label */ __( Go to: %s ), menuCommand.label ); return { name: menuCommand.name, label, searchLabel: label, category: view, callback: ( { close } ) { document.location menuCommand.url; close(); }, }; } ); }, [ menuCommands ] ); useCommands( commands );可以总结出这条内置命令的完整结构name直接复用菜单项的唯一名menuCommand.namelabel/searchLabel统一格式化为Go to: 菜单标签前往xxx并通过wordpress/i18n的sprintf__保证可翻译category: view属于导航/查看类别详见后文命令类别说明调色板会为该类别显示统一的跳转箭头图标callback执行document.location menuCommand.url跳转到目标 URL同时调用close()关闭调色板。动态命令查看站点同一文件还通过useCommandLoader注册了一个动态命令加载器core/view-site它从core-data获取站点根记录__unstableBase实体的home字段当站点 URL 可用时提供一个View site命令点击后在新标签页打开站点首页window.open( homeUrl, _blank )useCommandLoader( { name: core/view-site, hook: getViewSiteCommand(), } );由于使用useSelect从数据层读取站点首页地址这个命令天然是异步就绪的homeUrl尚未加载完成时加载器直接返回空命令数组[]不会渲染出不完整的命令。核心实现二站点编辑器导航命令useSiteEditorNavigationCommands源码位于 packages/core-commands/src/site-editor-navigation-commands.js这是整个包中逻辑最丰富的部分。它在非网络管理后台环境下disabled: isNetworkAdmin一次性注册了 6 个动态命令加载器加载器名称加载器 Hook作用core/edit-site/navigate-pagesgetNavigationCommandLoaderPerPostType( page )按搜索词查找并打开页面core/edit-site/navigate-postsgetNavigationCommandLoaderPerPostType( post )按搜索词查找并打开文章core/edit-site/navigate-templatesgetNavigationCommandLoaderPerTemplate( wp_template )打开模板core/edit-site/navigate-template-partsgetNavigationCommandLoaderPerTemplate( wp_template_part )打开模板部件core/edit-site/basic-navigationgetSiteEditorBasicNavigationCommands()站点编辑器基础导航Styles、Navigation、Templates、Patterns带context: site-editorcore/edit-site/global-styles-cssgetGlobalStylesOpenCssCommands()打开自定义 CSS 编辑文章/页面搜索型加载器getNavigationCommandLoaderPerPostType( postType )的搜索流程非常值得借鉴输入防抖使用useDebounce( setDebouncedValue, 250 )对用户输入做 250ms 防抖避免每次按键都触发 REST 请求源码中的useDebouncedValue条件查询只有输入非空才发起查询查询参数固定为search: delayedSearch防抖后的搜索词per_page: 10最多返回 10 条orderby: relevance按相关性排序status: [ publish, future, draft, pending, private ]覆盖发布、定时、草稿、待审核、私密等多种状态加载状态通过hasFinishedResolution( getEntityRecords, ... )判断数据是否解析完成作为加载器的isLoading返回值让调色板显示加载态命令构造每个记录生成一条category: edit编辑类命令label取标题标题为空时显示(no title)并调用decodeEntities反转义 HTML 实体图标按类型映射——文章用post图标、页面用page图标跳转分支无法创建模板、或对象为文章postType post、或对象为页面但主题非块主题时回退到传统后台document.location addQueryArgs( post.php, { post: id, action: edit } )否则走站点编辑器若当前已在站点编辑器中则通过history.navigate( \/${postType}/${id}?canvasedit )进行 SPA 内导航否则跳转到site-editor.php或实验性的admin.php?pagesite-editor-v2由window.__experimentalExtensibleSiteEditor决定并携带p与canvasedit 查询参数。模板/模板部件加载器getNavigationCommandLoaderPerTemplate( templateType )与前者不同因为注释明确指出wp_template与wp_template_part的 REST 端点不支持per_page与orderby参数。因此实现改为一次性拉取全部记录per_page: -1用本地排序工具orderEntityRecordsBySearch对结果按搜索词相关性排序后再.slice( 0, 10 )截断。orderEntityRecordsBySearch的实现位于 packages/core-commands/src/utils/order-entity-records-by-search.js逻辑是把标题title.raw包含搜索词忽略大小写的记录排在前priority其余排在后nonPriority保持原有相对顺序export function orderEntityRecordsBySearch( records [], search ) { if ( ! Array.isArray( records ) || ! records.length ) { return []; } if ( ! search ) { return records; } const priority []; const nonPriority []; for ( let i 0; i records.length; i ) { const record records[ i ]; if ( record?.title?.raw?.toLowerCase()?.includes( search?.toLowerCase() ) ) { priority.push( record ); } else { nonPriority.push( record ); } } return priority.concat( nonPriority ); }此外模板部件加载器在存在匹配记录时还会追加一条core/edit-site/open-template-parts的Go to: Template parts命令直接导航到模板部件列表/pattern?postTypewp_template_partcategoryIdall-parts方便在搜索结果之外一键进入管理入口。基础导航命令带上下文getSiteEditorBasicNavigationCommands()注册的命令全部带context: site-editor加载器定义于useSiteEditorNavigationCommands中的core/edit-site/basic-navigation。这意味着在站点编辑器的上下文中这些命令会获得更高优先级并显示在其他命令之上。注册的前提是基于权限与主题能力仅当canCreateTemplate isBlockBasedTheme可创建模板且为块主题时才注册core/edit-site/open-styles→ Go to: Styles/stylescore/edit-site/open-navigation→ Go to: Navigation/navigationcore/edit-site/open-templates→ Go to: Templates/template实验性站点编辑器下映射为/templates仅当canCreatePatterns可创建模式即wp_block权限时注册core/edit-site/open-patterns→ Go to: Patterns若用户无权限进入站点编辑器则回退到传统后台edit.php?post_typewp_block。自定义 CSS 命令getGlobalStylesOpenCssCommands()会检查全局样式实体是否暴露了wp:action-edit-css链接canEditCSS且当前主题为块主题只有两者都满足时才提供core/open-styles-css→ Open custom CSS导航到/styles?section/css。支撑机制一命令的类别与上下文wordpress/core-commands大量使用category与context其语义在 packages/commands/README.md 中有明确定义静态命令Static commands通过registerCommandaction 或useCommandhook 注册用于执行确定动作动态命令Dynamic commands通过useCommandLoader命令加载器注册适用于命令列表取决于用户搜索词或仅在某些条件下可用的场景——本文上述搜索型加载器就是典型例子上下文Context目前实现了site-editor、entity-edit、block-selection-edit三种。带上下文的命令会在对应场景打开调色板时优先显示。core/edit-site/basic-navigation使用site-editor上下文正是这一特性的运用类别Category包括command执行代码/切换动作、view导航到后台某区域或打开面板如 Go to: Templates、edit导航去编辑文档如编辑模板/页面、action通用兜底。未指定category时默认为action若传了非法值开发模式下会发出警告。view类别还有统一的回退箭头图标。支撑机制二私有 API 与 lock/unlockREADME 中标注为 Undocumented declaration 的privateApis在 packages/core-commands/src/private-apis.js 中实现function useCommands() { useAdminNavigationCommands(); useSiteEditorNavigationCommands(); } export const privateApis {}; lock( privateApis, { useCommands, } );而 packages/core-commands/src/lock-unlock.js 通过wordpress/private-apis的__dangerousOptInToUnstableAPIsOnlyForCoreModules声明承认私有特性不用于主题和插件否则会在下个版本中失效的准入协议export const { lock, unlock } __dangerousOptInToUnstableAPIsOnlyForCoreModules( I acknowledge private features are not for use in themes or plugins and doing so will break in the next version of WordPress., wordpress/core-commands );这解释了源码中两处关键用法index.jsx用unlock( routerPrivateApis )获取RouterProvidersite-editor-navigation-commands.js用unlock( routerPrivateApis )获取useHistory——核心模块之间通过私有 API 交换能力而第三方主题/插件则不被允许依赖这些接口。组合起来一个页面如何接入命令调色板综合以上源码分析一个 WP Admin 页面要启用核心命令调色板需要完成三步引入依赖通过 npm 安装wordpress/core-commands同时它自身依赖wordpress/commands等包会在构建时一并打包。提供 settings准备menu_commands后台菜单项数组含name/label/url与is_network_admin是否网络后台两个字段。调用入口在页面脚本中执行initializeCommandPalette( settings )它会自动创建容器节点并渲染出完整的命令菜单wordpress/commands包负责提供cmdkmacOS 为⌘K呼出调色板的交互wordpress/core-commands则负责把菜单跳转、文章/页面/模板/模板部件搜索、Styles/Navigation/Patterns 等核心命令注册进去。在 Gutenberg 的 monorepo 语境中initializeCommandPalette设计成多页面可复用正呼应了 README 开篇的定位These commands can be used in multiple WP Admin pages.扩展阅读命令调色板通用机制与注册 APIpackages/commands/README.md入口与 settings 解析packages/core-commands/src/index.jsx管理后台导航命令实现packages/core-commands/src/admin-navigation-commands.js站点编辑器导航命令实现packages/core-commands/src/site-editor-navigation-commands.js本地搜索结果排序工具packages/core-commands/src/utils/order-entity-records-by-search.js私有 API 打包与解锁packages/core-commands/src/private-apis.js、packages/core-commands/src/lock-unlock.js包元数据与版本演进packages/core-commands/package.json、packages/core-commands/CHANGELOG.md【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
