深入解读 wordpress/edit-postWordPress 文章编辑器包的演进、架构与 API 迁移指南【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergwordpress/edit-post是 Gutenberg 项目中承载 WordPress 文章编辑界面Post Editor的核心包从 2018 年的 1.0.0 一路迭代到 8.55.0其 CHANGELOG.md 完整记录了编辑器初始化、core/edit-post数据 store、Meta Boxes 兼容层、插件扩展 UI 与无障碍体验的每一次关键变更。本文以该 CHANGELOG 为骨架结合仓库源码入口实现、store actions、store selectors梳理这个包做了什么、它如何演进、以及插件开发者面对旧 API 应如何迁移。读完你将掌握wordpress/edit-post的整体职责边界、Meta Boxes 的保存机制以及从core/edit-post迁往core/editor、core/preferences、core/interface的完整对照清单。包定位它负责什么又不负责什么根据 package.json 的描述wordpress/edit-post是 Edit Post module for WordPress即 WordPress 经典写文章/写页面后台界面区别于全站编辑的wordpress/edit-site的前端模块。README 明确提醒该包主要供 WordPress 核心使用虽然允许其他项目引用但可能永远不会被完整文档化。几个关键事实安装方式npm install wordpress/edit-post要求运行环境支持ES2015建议引入wordpress/babel-preset-default自带的 polyfill。环境要求见 package.jsonnode 18.12.0、npm 8.19.2peerDependencies为react ^18 || ^19。对外入口构建产物暴露为build/index.cjsCJS与build-module/index.mjsESM并额外声明wpScriptExtraDependencies: [media-models, media-views, postbox]表明它依赖 WordPress 后端的媒体库脚本与经典的 postboxesMeta Boxes 折叠/排序脚本。全局 API当把wp-edit-post声明为脚本依赖时扩展点挂在全局变量wp.editPost上包括initializeEditor、reinitializeEditor、store以及一系列Plugin*组件见 README.md。从依赖清单可以看出它的职责范围它依赖wordpress/editor编辑器核心、wordpress/block-editor、wordpress/block-library、wordpress/core-data、wordpress/data、wordpress/plugins、wordpress/preferences、wordpress/notices等本身更像一个编排层注册核心块、挂接数据预取、装配侧边栏与顶栏、托管 Meta Boxes并把大量纯编辑逻辑委托给更底层的wordpress/editor。编辑器初始化initializeEditor 到底做了什么initializeEditor( id, postType, postId, settings, initialEdits )是文章编辑器的启动入口从 src/index.jsx 可以看到一条完整、清晰的初始化流水线挂载容器通过document.getElementById( id )找到挂载点用wordpress/element的createRoot创建 React 根最终以StrictModeLayout ... //StrictMode渲染Layout组件在 src/components/layout/index.jsx。写入偏好默认值向wordpress/preferencesstore 写入core/edit-post命名空间下的默认值fullscreenMode: true、themeStyles: true、welcomeGuide: true、welcomeGuideTemplate: true以及core命名空间下的editorMode: visual、fixedToolbar: false、openPanels: [ post-status ]、showListViewByDefault: false等一大批默认偏好。注册块registerCoreBlocks()注册核心块registerCoreBlockBindingsSources()注册 block bindings 源registerLegacyWidgetBlock( { inserter: false } )与registerWidgetGroupBlock注册旧版小工具块但不进插入器。当运行在 Gutenberg 插件环境globalThis.IS_GUTENBERG_PLUGIN为真时还会按需注册实验性核心块。环境健康检查检测浏览器是否为 Standards 渲染模式若处于 Quirks 模式则打印 console 警告提示 PHP 错误或!DOCTYPE html之前的 HTML 可能造成块覆盖 Meta Boxes。数据预取preload调用enablePreloadMultiUse()启用预取数据的多路复用再通过preloadResolutions( postType, postId )分三阶段踢动 core-data 的 resolver用户信息、实体配置、taxonomy、当前主题、全局样式、权限检查、post 记录、autosave、默认模板等使首帧渲染不再依赖异步setTimeout(0)兜底预取结束后clearPreloadedData()清理未被消费的缓存条目。装配编辑数据取到 post 实体记录后dispatch( editorStore ).setupEditor( post, initialEdits, settings.template )完成编辑器数据初始化。注意 CHANGELOG 8.0.0 的破坏性变更原先依赖process.env.IS_GUTENBERG_PLUGIN的构建变量改成了globalThis.IS_GUTENBERG_PLUGIN更早的 6.0.0 把GUTENBERG_PHASE环境变量重命名为IS_GUTENBERG_PLUGIN且改为布尔值。使用该变量做条件编译的构建系统需要对应更新。另外reinitializeEditor()在 6.2 起被标记为废弃、6.3 起成为空操作noop若你的代码在错误恢复场景调用过它请移除。数据中枢core/edit-post store 的演进store 由createReduxStore( core/edit-post, { reducer, actions, selectors } )注册见 src/store/index.js命名空间常量在 src/store/constants.js 定义为core/edit-post并额外定义了管理栏查看/预览链接的 CSS 选择器#wp-admin-bar-view a、#wp-admin-bar-preview a。侧边栏与面板控制早期版本2.x–3.x由本 store 直接管理侧边栏与面板openGeneralSidebar( name )/closeGeneralSidebar()委托给core/interface的enableComplementaryArea/disableComplementaryArea侧边栏名称如edit-post/document、edit-post/block或插件自定的my-plugin/insert-image-sidebar。对应的 selectorsisEditorSidebarOpened/isPluginSidebarOpened/getActiveGeneralSidebarName也是基于interfaceStore.getActiveComplementaryArea( core )的薄封装。3.0.0 的破坏性变更宣告了面板 API 的第一次改名删除isEditorSidebarPanelOpened改用isEditorPanelEnabled与toggleGeneralSidebarEditorPanel改用toggleEditorPanelOpened。到 7.26.0面板显隐/开关相关动作与 selector 整体迁往wordpress/editor包toggleEditorPanelEnabled、toggleEditorPanelOpened、removeEditorPanel、isEditorPanelRemoved、isEditorPanelOpened、isEditorPanelEnabled均被废弃替代品是core/editor中同名动作/选择器见 actions.js 与 selectors.js 的deprecated调用与alternative提示。发布侧边栏、编辑器模式等向 core/editor 迁移6.6 起发布侧边栏与编辑模式相关 API 迁往core/editoropenPublishSidebar/closePublishSidebar/togglePublishSidebar→dispatch( core/editor ).openPublishSidebar / closePublishSidebar / togglePublishSidebar。switchEditorMode→dispatch( core/editor ).switchEditorMode。toggleDistractionFree→dispatch( core/editor ).toggleDistractionFree。选择器isPublishSidebarOpened→select( core/editor ).isPublishSidebarOpened。6.5 起更多 UI 状态迁往core/editorsetIsInserterOpened( value )→dispatch( core/editor ).setIsInserterOpenedsetIsListViewOpened( isOpen )→dispatch( core/editor ).setIsListViewOpened。__experimentalSetPreviewDeviceType→dispatch( core/editor ).setDeviceType6.7 移除。__experimentalGetPreviewDeviceType/__experimentalGetInsertionPoint→select( core/editor ).getDeviceType等6.7 移除。setIsEditingTemplate被废弃替代为core/editor的setRenderingMode__unstableCreateTemplate一并废弃。updatePreferredStyleVariations废弃Preferred Style Variations are not supported anymore返回{ type: NOTHING }。偏好系统迁移6.0 起getPreferences/getPreference被废弃改用select( core/preferences ).get。源码中保留了向后兼容的转换逻辑convertPanelsToOldFormat把新版偏好 store 中的inactivePanels、openPanels数组还原成旧版{ panelName: { enabled, opened } }对象结构避免破坏依赖旧格式的插件。新版数据结构为inactivePanels: [ panel-a ] // 停用面板 openPanels: [ post-status ] // 默认展开的面板模态框迁移openModal( name )/closeModal()与isModalActive( name )自 WP 6.3 起废弃改用core/interface中同名动作与选择器。Meta Boxes经典编辑器兼容机制文章编辑器必须兼容大量依赖 Meta Boxes经典设置区块的插件这是wordpress/edit-post独有的复杂职责也占据 CHANGELOG 中相当篇幅。数据模型与选择器reducer 维护state.metaBoxes.locations每个位置对应的 meta box 列表与state.metaBoxes.isSaving、state.metaBoxes.initialized。核心选择器selectors.jsgetActiveMetaBoxLocations()有 meta box 激活的位置列表。isMetaBoxLocationActive( location )某位置是否存在 meta box。getMetaBoxesPerLocation( location )/getAllMetaBoxes()按位置或全量列出 meta box。isMetaBoxLocationVisible( location )位置可见性还受对应面板meta-box-${ id }是否启用影响。hasMetaBoxes()/isSavingMetaBoxes()/areMetaBoxesInitialized()。2.0.0 的元数据框 API 重构2.0.0 是 Meta Boxes 相关的最大破坏性版本删除setActiveMetaBoxLocations、initializeMetaBoxState、setMetaBoxSavedData三个动作initializeEditor不再返回对象原对象上的initializeMetaBoxes改为独立动作setActiveMetaBoxLocations。删除getMetaBoxes改用getActiveMetaBoxLocations与getMetaBox改用isMetaBoxLocationActive。保存流程与经典编辑器兼容initializeMetaBoxes动作actions.js只在编辑器就绪后执行一次为当前 post type 调用window.postboxes.add_postbox_toggles启用经典折叠/排序并挂接editor.savePost钩子——每次正式保存非 autosave且存在 meta box 时触发requestMetaBoxUpdates。requestMetaBoxUpdatesactions.js实现了一套严谨的合并保存流程window.tinyMCE.triggerSave()先同步经典编辑器的内容。收集.metabox-base-form的基础表单数据post_ID、post_type 等并补上comment_status、ping_status、sticky、post_author等兼容字段——注释明确警告若不提供这些数据post 会被默认值覆盖。遍历所有激活位置的 meta box 容器把每个容器的FormData合并进同一请求体。apiFetchPOST 到window._wpMetaBoxUrlparse: false成功后派发metaBoxUpdatesSuccess失败则派发metaBoxUpdatesFailure。8.55.0 修复了一个关键回归经典TinyMCE编辑器在 meta box 中变得不可用的问题通过在其可用时用moveBefore移动 meta box 标记解决#82243。早年间 3.1.5 也曾修复保存 WYSIWYG Meta Boxes的问题可见这是长期维护的兼容性焦点。插件扩展wp.editPost 下的组件 APIwp.editPost全局对象暴露的组件README.md多数是wordpress/editor中同名组件的再导出PluginBlockSettingsMenuItem、PluginDocumentSettingPanel、PluginMoreMenuItem、PluginPostPublishPanel、PluginPostStatusInfo、PluginPrePublishPanel、PluginSidebar、PluginSidebarMoreMenuItem。使用方式统一为registerPlugin( plugin-name, { render, icon } )后在这些组件内声明 UI。几个有据可查的演进细节3.27.0渲染可固定pinnable的PluginSidebar时默认自动生成对应的PluginSidebarMenuItem同时尊重插件已注册的匹配菜单项完全向后兼容。3.2.0PluginSidebar增加className属性支持自定义样式。3.0.0AdminNotices组件会把页面上的.notice元素透明升级为wordpress/notices通知状态。3.4.0MediaUpload钩子新增addToGallery选项可让媒体弹窗默认停留在gallery-library而非gallery-edit状态。固定/取消固定插件项由togglePinnedPluginItem( pluginName )动作与isPluginItemPinned( pluginName )选择器提供底层委托core/interface的pinItem/unpinItem/isItemPinned。近期8.x增强与内部重构速览无障碍与 UIUnreleasedOptions 菜单中的 Welcome Guide 项标记aria-haspopupdialog因为它打开的是一个模态对话框。8.55.0WelcomeGuide的模态关闭图标在改为 stroke 风格后保持白色#78812。8.53.0文章编辑器布局用ThemeProvider包裹并以当前后台配色方案的主色作为种子。8.45.0交互式光标样式改用--wpds-cursor-control变量。8.36.0welcome-guide样式把关闭按钮的 hover 态改为在共享Guide组件内部定义。依赖与构建8.55.0移除未使用的依赖wordpress/a11y、wordpress/dom、wordpress/viewport等#82103含 JSX 的源文件统一使用.jsx扩展名#80990。8.54.0不再自行渲染EditorKeyboardShortcutsRegister——现在由 editor provider 负责说明快捷键注册责任上移到了wordpress/editor。8.51.0React peer 依赖放宽为^18 || ^19可同时支持 React 18 与 React 19 环境。8.1.0补回wordpress/html-entities依赖#62313。7.35.0用更快更小的clsx替换classnames。7.0.0依赖升级要求 React 18。5.0.0组件升级适配 React 17无新特性。状态与初始化治理8.55.0停止注册editorTool偏好默认值其消费方 Write/Design 工具已在 #72193 移除initializeEditor不再处理showListViewByDefault改由wordpress/editor包自行应用该偏好。这两项都体现了状态归 editor 包统一管理的长期收敛趋势。8.26.0–8.35.0多个版本为空迭代无行为变化CHANGELOG 仅保留版本时间戳属于 monorepo 常规发布节奏。6.19.0BlockTypesChecklist把BlockIcon移出CheckboxControl的 label改善可点击区域与无障碍。3.13.0内部EditorRegions组件迁至wordpress/block-editor并更名为EditorSkeletonclass 名由edit-post-editor-regions改为block-editor-editor-skeleton。3.6.0引入EditorInitializer组件替换早期__unstableInitialize方案统一处理编辑器加载过程中的初始化工作。3.2.0修复 Code Editor 下保存快捷键失效、以及 Safari 中ClipboardButton误复制序列化块字符串的问题。API 迁移速查表来自 CHANGELOG 与源码废弃的 APIcore/edit-post版本替代 APIgetPreferences/getPreference6.0select( core/preferences ).getopenModal/closeModal/isModalActive6.3core/interface同名 APItoggleEditorPanelEnabled等面板动作与选择器6.5core/editor同名 APIsetIsInserterOpened/isInserterOpened6.5core/editor同名 APIsetIsListViewOpened/isListViewOpened6.5core/editor同名 APIsetIsEditingTemplate/isEditingTemplate6.5core/editor.setRenderingMode/getRenderingMode__experimentalSetPreviewDeviceType等6.56.7 移除core/editor.setDeviceType/getDeviceTypeopenPublishSidebar系列6.6core/editor同名 APIswitchEditorMode6.6core/editor.switchEditorModetoggleDistractionFree6.6core/editor.toggleDistractionFreereinitializeEditor6.26.3 起 noop移除调用updatePreferredStyleVariations6.6不再支持isEditorSidebarPanelOpened/toggleGeneralSidebarEditorPanel3.0.0isEditorPanelEnabled/toggleEditorPanelOpenedsetActiveMetaBoxLocations等 Meta Boxes 旧动作2.0.0新版 Meta Boxes store 动作/选择器工程层面的破坏性变更8.0.0 要求 Node v18.12.0LTS、构建变量改为globalThis.IS_GUTENBERG_PLUGIN4.0.0 移除 IE11 支持并要求 Node v127.0.0 要求 React 18。给插件开发者的实践建议优先使用core/editor凡涉及面板、侧边栏、发布流程、编辑器模式、插入器/列表视图等状态直接走wordpress/editor的公开 store APIcore/edit-post中的旧入口均已进入废弃通道其中相当一部分如预览设备类型相关已按计划移除。偏好一律走core/preferences读写用户偏好用select( core/preferences ).get/dispatch( core/preferences ).set命名空间建议沿用core/edit-post或core。Meta Boxes 场景请回归测试凡使用经典 TinyMCE 或依赖 meta box 表单的插件务必在保存流程editor.savePost钩子 _wpMetaBoxUrl请求验证表单字段合并、comment_status/sticky等兼容字段不被覆盖。关注条件编译变量若代码使用process.env.IS_GUTENBERG_PLUGIN或旧变量名请迁移到globalThis.IS_GUTENBERG_PLUGIN并确认构建环境满足 Node 18.12 与 React 18/19 的要求。维护视角该 CHANGELOG 遵循 packages 目录的 changelog 维护约定每个行为变更都标注了对应的 Gutenberg PR 编号如 #82395 与 CHANGELOG。总体而言wordpress/edit-post正沿着编辑逻辑下沉到wordpress/editor、偏好归core/preferences、界面容器归core/interface的方向持续瘦身CHANGELOG 中每一次 Breaking Changes 与 Deprecations 都是这条演进路线的路标。理解这张迁移图谱你就能在升级 Gutenberg 与 WordPress 核心版本时从容评估插件受影响面。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考