Gutenberg create-block-interactive-template 使用与演进从 CHANGELOG 解读交互块模板的完整技术图谱【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg本指南以wordpress/create-block-interactive-template的 CHANGELOG.md 为主线骨架结合该包在 Gutenberg 仓库中的完整模板源码index.js、block-templates/与block-templates-client-side-navigation/下的.mustache模板系统讲解如何基于官方交互块模板快速搭建基于 Interactivity API 的 WordPress 交互块并深入剖析其版本演进背后隐含的架构变迁从经典脚本到 ES Module、从手动 context 到wp_interactivity_data_wp_context、再到store()新 API 与viewModule。读者读完后将掌握模板安装、三种 variant 的选择、模板生成结果的结构、关键源码位点以及为何该模板是理解 Gutenberg 交互块最佳实践的最短路径。一、CHANGELOG 里隐藏的技术演化史与普通变更日志不同create-block-interactive-template的 CHANGELOG.md 记录的不只是版本号而是一条完整的交互块开发范式演进链。把关键条目按时间轴串联即可还原该模板从 1.2.0 到 2.55.0 的全部架构变化版本关键变化技术含义1.2.0 (2023-08-10)将example属性移入 block.json配合 create-block 对example的新支持模板生成块的示例定义集中到块元数据1.10.0 (2023-11-29)view.js与render.php改用新的store()API交互逻辑从旧的data-wp-*直接挂载方式迁移到显式store()注册是 Interactivity API 的正式形态1.10.1 (2023-12-07)模板改用 modules 而非 scripts前端资源从经典脚本切换为 ES Module为viewModule铺路1.11.0 (2023-12-13)所有文件加入生成的插件 zipGutenberg 插件未安装时不再崩溃提升产物完整性与降级健壮性1.12.0 (2024-01-10)模板改用viewModule字段block.json 的view声明从viewScript演进为模块化的viewModule1.17.0 (2024-03-21)context 属性改用wp_interactivity_data_wp_context服务端渲染 context 数据不再手写 JSON而是由 PHP 函数安全输出2.0.0 (2024-05-31)最低 Node.js 版本提升到 v18.12.0LTS与工具链现代对齐同步wordpress/scripts的要求2.7.0 (2024-09-05)最低 WordPress 版本提升到 6.6与最新wordpress/scripts无缝协作2.8.0 (2024-09-19)新增 TypeScript variant在默认模板之外提供强类型视图脚本见下文“三种变体”2.50.0 ~ 2.55.0 (2026-07~09)连续常规发布维持与 Gutenberg 主版本同步的版本节奏这条演进链说明该模板始终是 Interactivity API 官方最佳实践的“活教材”每次 API 变更都会优先落进模板再推广到社区。二、快速上手安装命令与运行前提该模板由npx wordpress/create-block消费使用方式极其简单来自 README.mdnpx wordpress/create-block --template wordpress/create-block-interactive-template运行前提必须满足WordPress ≥ 6.5或 Gutenberg ≥ 17.7交互块依赖 Interactivity API 的运行时支持低于此版本无法工作。Node.js ≥ 18.12.0npm ≥ 8.19.2这一限制自 2.0.0 起生效见 package.json 的engines字段与wordpress/scripts的构建链要求一致。模板默认值一览打开 index.js 的defaultValues可以看到生成块的完整默认骨架配置项默认值说明slugexample-interactive生成块的目录/命名titleExample Interactive编辑器中的块标题descriptionAn interactive block with the Interactivity API.块描述dashiconmedia-interactive编辑器图标npmDependencies[wordpress/interactivity]视图脚本依赖的运行时supports.interactivitytrue显式声明块支持交互viewScriptnull不再使用经典脚本方式viewScriptModulefile:./view.js视图脚本以 ES Module 形式加载renderfile:./render.php服务端渲染模板example{}块预览示例构建脚本wp-scripts build --experimental-modules --blocks-manifest支持模块化构建其中--experimental-modules --blocks-manifest两个构建参数正是为了让viewModule的模块化产物被 WordPress 正确识别与加载是 1.10.1/1.12.0 演进的结果。三、三种变体variant按需选择脚手架README 与index.js的variants字段共同定义了三种可复用变体通过--variant参数选择不传该参数时默认使用default。1.default— 标准交互块脚手架npx wordpress/create-block --template wordpress/create-block-interactive-template --variant default生成一个演示响应式 state、context 与 DOM 事件处理的完整交互块。生成结果包含来自 block-templatesindex.js— 通过registerBlockType注册块并引入style.scss与editor.scssedit.js— 编辑器内渲染{{title}} – hello from the editor!render.php— 服务端渲染模板view.js— 前端交互逻辑block.json、style.scss、editor.scss、README.md。服务端渲染render.php.mustache展示了三个核心要点// 1. 注入全局状态 wp_interactivity_state( {{namespace}}, array( isDark false, darkText esc_html__( Switch to Light, {{textdomain}} ), lightText esc_html__( Switch to Dark, {{textdomain}} ), themeText esc_html__( Switch to Dark, {{textdomain}} ), ) ); // 2. 使用 wp_interactivity_data_wp_context 输出 context1.17.0 起 ?php echo wp_interactivity_data_wp_context( array( isOpen false ) ); ? // 3. 通过>import { store, getContext } from wordpress/interactivity; const { state } store( {{namespace}}, { state: { get themeText() { return state.isDark ? state.darkText : state.lightText; } }, actions: { toggleOpen() { const context getContext(); context.isOpen ! context.isOpen; }, toggleTheme() { state.isDark ! state.isDark; } }, callbacks: { logIsOpen: () { const { isOpen } getContext(); console.log( Is open: ${ isOpen } ); }, }, } );这里的state响应式共享状态、actions事件处理器、callbacks副作用/watch 回调正是 1.10.0 引入store()API 后的标准结构。2.typescript— 强类型视图脚本npx wordpress/create-block --template wordpress/create-block-interactive-template --variant typescript与default唯一区别是视图脚本为view.tsview.ts.mustache由index.js中viewScriptModule: file:./view.ts指定。其亮点在于全类型化的 state 与 contexttype ServerState { state: { isDark: boolean; darkText: string; lightText: string; }; }; type Context { isOpen: boolean; }; type Store ServerState typeof storeDef; const { state } store Store ( {{namespace}}, storeDef );注意ServerState typeof storeDef的组合类型它将PHP 端注入的初始 state 形状与JS 端定义的状态派生逻辑合并为完整 Store 类型getContext Context ()让 context 读取也获得编译期检查。这是 2.8.02024-09-19加入的类型安全增强。3.client-side-navigation— 无刷新导航演示npx wordpress/create-block --template wordpress/create-block-interactive-template --variant client-side-navigation该变体演示由wordpress/interactivity-router驱动的客户端导航并额外将wordpress/interactivity-router加入 npm 依赖见 index.js 的 variants 配置。生成内容来自独立的 block-templates-client-side-navigation 目录。工作机制模板 README.md.mustache 明确列出服务端渲染内容render.php读取?quote查询参数从硬编码引语数组中挑选一条渲染在 router region 内客户端导航Prev/Next 链接改变查询参数并经由wordpress/interactivity-router触发导航而非整页刷新状态保持证明router region 之外运行一个客户端秒表跨导航持续跳动证明没有发生整页重载加载指示器导航过程中显示 “Loading…” 提示。其关键实现render.php.mustache中导航 region 用data-wp-router-region{{namespace}}/quote划定Prev/Next 链接用data-wp-on--clickactions.navigateTo与data-wp-on--mouseenteractions.prefetchTo绑定对应的视图逻辑view.js.mustache则示范了 Generator 函数 withSyncEvent 动态import()的异步导航模式navigateTo: withSyncEvent( function* ( event ) { event.preventDefault(); // getElement() 必须在任何 yield 之前同步调用 const { attributes } getElement(); state.isNavigating true; if ( state.artificialDelay ) { yield new Promise( ( resolve ) setTimeout( resolve, 1000 ) ); } const { actions } yield import( wordpress/interactivity-router ); yield actions.navigate( attributes.href ); state.isNavigating false; } ),同时startTimercallback 通过data-wp-init在 DOM 初始化时启动 setInterval 秒表其清理函数在组件卸载时清除定时器——这个“region 外状态跨导航存活”的秒表正是验证无整页刷新的可视证据。四、模板生成的完整块结构与源码对照综合以上分析无论选择哪种 variant生成块的目录结构都遵循 Gutenberg 标准块布局以default为例src/$slug/ ├── block.json # 块元数据含 viewModule / render / example ├── edit.js # 编辑器编辑界面 ├── editor.scss # 编辑器专属样式 ├── index.js # 块注册入口 ├── render.php # 服务端渲染模板前端输出 ├── style.scss # 前台与编辑器共用样式 └── view.js # 前端交互模块ES Module这些.mustache源模板由 create-block 在生成时替换{{slug}}、{{title}}、{{namespace}}、{{textdomain}}等占位符。因此本仓库中block-templates/与block-templates-client-side-navigation/目录下的每一份.mustache文件就是你在执行npx wordpress/create-block后得到的最终文件是学习与二次定制交互块最直接的源码参照。五、版本选择与升级建议使用最新稳定版2.55.02026-09-10CHANGELOG 显示 2.50.0 ~ 2.55.0 期间为常规同步发布持续跟随 Gutenberg 主版本新项目应直接使用最新版以获得最新的 Interactivity API 特性。升级到 2.7.0 需注意最低 WordPress 6.6 的限制意味着老站点需先升级 WordPress 再使用该模板。升级到 2.0.0 需注意Node.js 18.12.0 的开发环境需要先升级运行时否则npm install与wp-scripts构建会失败。从旧版模板迁移若你手头的块还在用viewScript或旧式 context 写法请参照 1.10.1、1.12.0、1.17.0 的演进点分别迁移到viewModule、store()API 与wp_interactivity_data_wp_context。六、总结wordpress/create-block-interactive-template是通往 Gutenberg Interactivity API 的官方脚手架default变体演示响应式 state/context/事件的核心范式typescript变体叠加编译期类型安全client-side-navigation变体展示 router 驱动的无刷新导航。而它的 CHANGELOG 本身就是一份可读性极高的架构演进编年史——从脚本到模块、从viewScript到viewModule、从手工 context 到wp_interactivity_data_wp_context、从旧式绑定到store()API。若想进一步深挖 Interactivity API 的运行时实现可继续阅读 packages/interactivity 与 packages/interactivity-router 的源码若想了解 create-block 本体如何消费这些模板参见 packages/create-block。通过对照模板源码与 CHANGELOG 逐版本阅读你将能完整复现 Gutenberg 对“交互块应该如何编写”这一问题的官方答案。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考