Gutenberg Interactivity API 快速上手用官方模板搭建你的第一个交互式块【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg本指南基于 Gutenberg 仓库中的 iapi-quick-start-guide.md 编写讲解如何借助wordpress/create-block与wordpress/create-block-interactive-template官方模板在几分钟内脚手架出一个可直接运行的交互式块插件。读完本文你将掌握交互式块的完整创建流程脚手架、开发、构建、本地运行并理解模板产出的指令Directives与 Store 背后的源码级原理为深入开发复杂交互计数器、弹窗、即时搜索、购物车等打下基础。前置条件Prerequisites在开始之前需要准备一套标准的 WordPress 块开发环境。这些要求与普通块开发完全一致并不会因为使用 Interactivity API 而增加额外门槛Node.js 与 npm脚手架与构建流程依赖它们可参考仓库文档 docs/getting-started/devenv 下的 Node.js 开发环境说明。代码编辑器任何支持 JavaScript/JSX 与 PHP 的编辑器均可。本地 WordPress 环境用于安装、激活并预览最终生成的插件。版本要求Interactivity API 自 WordPress 6.5 起随 Core 内置发布低于 6.5 的版本需要安装并激活 Gutenberg 17.5 及以上版本。而本指南使用的交互式模板要求至少 WordPress 6.5 或 Gutenberg 17.7见 create-block-interactive-template/README.md。脚手架一个交互式块在选定的目标文件夹中打开终端执行以下命令npx wordpress/create-blocklatest my-first-interactive-block --template wordpress/create-block-interactive-template命令解析wordpress/create-blockGutenberg 官方块脚手架工具其实现与文档位于 packages/create-block。--template wordpress/create-block-interactive-template指定使用交互式块模板该模板位于 packages/create-block-interactive-template。my-first-interactive-blockslug块别名。它同时决定了插件的文件夹名、内部块名block name以及模板渲染时的命名空间namespace。模板的三个变体Variantscreate-block-interactive-template模板支持通过--variant参数选择三种形态若不指定则默认使用default变体命令说明defaultnpx wordpress/create-block --template wordpress/create-block-interactive-template --variant default标准交互式块演示响应式 state、context 与 DOM 事件处理typescriptnpx wordpress/create-block --template wordpress/create-block-interactive-template --variant typescript与default相同但视图脚本view.ts用 TypeScript 编写state 与 context 均有完整类型标注client-side-navigationnpx wordpress/create-block --template wordpress/create-block-interactive-template --variant client-side-navigation演示基于wordpress/interactivity-router的客户端导航额外增加该 npm 依赖基本用法开发与构建脚手架完成后进入插件目录并启动开发进程cd my-first-interactive-block npm startcreate-block在生成插件时会自动安装wp-scripts并把最常用的脚本写入插件的package.json。npm start会启动开发服务器并监视代码变化任何修改都会触发增量重建。wp-scripts的详细介绍可参考仓库中的 packages/scripts/README.md。完成修改后执行构建命令产出生产就绪代码npm run build该命令会对块代码做压缩与优化构建结果输出到build目录供 WordPress 在运行时加载。注意--experimental-modules 标志Interactivity API 的视图代码以 Script Module 形式加载viewScriptModule因此build与start脚本需要附带--experimental-modules标志才能正确打包。若使用本模板脚手架该标志已预置在package.json中无需手动配置如果手动接入需要在package.json中写入{ scripts: { build: wp-scripts build --experimental-modules, start: wp-scripts start --experimental-modules } }在浏览器中查看块的实际效果如果你已有正在运行的本地 WordPress将上面命令在安装目录的plugins文件夹内执行即可。否则推荐使用wp-playground/cli一键启动一个预装该插件的 WordPress 站点在插件目录my-first-interactive-block内执行npx wp-playground/cli server --auto-mount--auto-mount会把当前插件目录自动挂载到 Playground 站点的插件目录。站点启动后在任意文章/页面中插入 “My First Interactive Block” 块发布后即可在前端看到它的交互行为——这也是验证 Interactivity API “无需整页刷新即响应”这一特性最直观的方式。深入源码模板到底生成了什么为了真正理解脚手架产物直接阅读模板源文件是最佳途径。模板渲染 PHP 与前端脚本的源码位于 packages/create-block-interactive-template/block-templates。服务端渲染render.php中的指令与全局状态交互式块的标记Markup在 render.php.mustache 中定义。它以服务端渲染方式输出 DOM并通过指令把行为“挂”到元素上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}} ), ) );wp_interactivity_state()在服务端声明该块的全局状态state前端 Store 中的state与之一一对应。接着是块根元素div >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可包含普通值与 getter。themeText是派生状态读取时依据state.isDark动态计算按钮文案体现了 Interactivity API 响应式、声明式的编程心智模型详见 core-concepts/the-reactive-and-declarative-mindset.md。actionstoggleOpen通过getContext()读写当前元素局部上下文toggleTheme直接翻转全局 state。任何 state/context 变化都会触发相关指令自动更新 DOM无需手动操作 DOM。callbackslogIsOpen在isOpen每次变化后执行副作用此处为控制台日志对应data-wp-watch指令。其他脚手架文件index.js用registerBlockType()注册块引入样式与edit组件。edit.js编辑器中的渲染占位文案 “hello from the editor!”。style.scss前后台共用的样式其中.dark-theme深色主题样式与state.isDark开关呼应。插件主文件$slug.php.mustache通过wp_register_block_types_from_metadata_collection()从build目录注册块元数据与资源见 plugin-templates/$slug.php.mustache。进阶TypeScript 与客户端导航变体TypeScript 变体选择--variant typescript后前端脚本变为 view.ts.mustache。它与 JS 版逻辑一致但额外定义了ServerState与Context类型并通过store Store ( {{namespace}}, storeDef )让 state、context、getter 全部获得静态类型检查type ServerState { state: { isDark: boolean; darkText: string; lightText: string; }; }; type Context { isOpen: boolean; };类型化的getContext Context ()让局部上下文的读写更加安全。TypeScript 使用细节可参考 core-concepts/using-typescript.md。客户端导航变体--variant client-side-navigation演示了基于wordpress/interactivity-router的客户端导航块的 render.php.mustache 中内容区域被标记为data-wp-router-region{{namespace}}/quotePrev/Next 链接在点击时调用 view.js.mustache 中的navigateToactionnavigateTo: withSyncEvent( function* ( event ) { event.preventDefault(); 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; } ),要点路由器只替换router-region内的内容不做整页刷新同时callbacks.startTimer启动的秒表位于 router 区域之外导航前后持续走动正好证明页面没有发生完整重载。withSyncEvent、getElement与动态import()的用法也展示了在 action 中编写异步流程的标准姿势。手动接入 Interactivity API非模板方式如果不使用模板也可以按以下四步在现有块中手动启用 Interactivity API安装依赖npm install wordpress/interactivity --save并在view.js中import { store } from wordpress/interactivity;。声明支持在块的block.json中添加supports: { interactivity: true }。加载前端脚本在block.json中声明viewScriptModule: file:./view.js并确保wp-scripts build/start带--experimental-modules标志。激活交互区在render.php或save.js中为目标 DOM 元素添加data-wp-interactivemyPlugin该元素及其子元素即可使用指令与 Store。以上各步骤的详细依据可分别查看 interactivity-api/README.md 与 directives-and-store.md。延伸阅读Interactivity API 文档首页需求、版本说明与全部子文档索引。Directives and Store 参考全部指令的规范与 Store 工作机制。核心概念响应式与声明式心智模型、服务端渲染、全局状态与局部上下文、客户端导航等。交互式模板源码模板变体说明与源码结构。wp-scripts 包start/build等脚本命令的完整选项。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考