Gutenberg create-block-interactive-template 使用与演进：从 CHANGELOG 解读交互块模板的完整技术图谱

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 的全部架构变化：

这条演进链说明：该模板始终是 Interactivity API 官方最佳实践的“活教材”，每次 API 变更都会优先落进模板再推广到社区。

二、快速上手：安装命令与运行前提

该模板由npx @wordpress/create-block消费，使用方式极其简单（来自 README.md）：

npx @wordpress/create-block --template @wordpress/create-block-interactive-template

运行前提（必须满足）

• WordPress ≥ 6.5，或 Gutenberg ≥ 17.7：交互块依赖 Interactivity API 的运行时支持，低于此版本无法工作。
• Node.js ≥ 18.12.0，npm ≥ 8.19.2：这一限制自 2.0.0 起生效（见 package.json 的engines字段），与@wordpress/scripts的构建链要求一致。

模板默认值一览

打开 index.js 的defaultValues可以看到生成块的完整默认骨架：

其中--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-templates）：

• index.js— 通过registerBlockType注册块，并引入style.scss与editor.scss；
• edit.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 输出 context（1.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.ts（view.ts.mustache），由index.js中viewScriptModule: 'file:./view.ts'指定。其亮点在于全类型化的 state 与 context：

type 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.0（2024-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--click="actions.navigateTo"与data-wp-on--mouseenter="actions.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.0，2026-09-10）：CHANGELOG 显示 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