WP Blocks 是一套面向 WordPress Gutenberg 区块开发、区块主题创建与 Interactivity API 的综合技能内容，目标版本为 WordPress 6.9+（PHP 7.2.24+）。
【用途】 该技能主要用于三类场景：构建 Gutenberg 自定义区块、创建区块主题，以及使用 Interactivity API 开发前端交互。
【主要能力】 第一部分为区块开发。涵盖 block.json 元数据：WordPress 6.9 强制使用 apiVersion 3，必填字段为 apiVersion、name、title，资产字段包括 editorScript、editorStyle、script、style、viewScript、viewScriptModule、viewStyle 与 render。提供脚手架命令：标准区块使用 npx @wordpress/create-block my-block，动态区块使用 --variant dynamic，交互式区块使用 --template @wordpress/create-block-interactive-template。区分静态与动态渲染：静态的 save() 返回完整标记，动态的 save() 返回 null（或最小回退）并通过 render.php 或 render_callback 渲染。包装函数在编辑器中用 useBlockProps()、静态保存用 useBlockProps.save()、PHP 动态渲染用 get_block_wrapper_attributes()，均需展开到最外层包装元素上。属性持久化通过注释分隔符 JSON、HTML source（source + selector）或 context 实现。InnerBlocks 用于容器区块，使用 useInnerBlocksProps()，每个区块仅允许一个 InnerBlocks，templateLock 取值 false、'all'、'insert'、'contentOnly'。修改 save() 输出或属性结构时必须添加弃用条目，顺序最新在前。PHP 侧通过 register_block_type_from_metadata() 在 init 钩子注册。
第二部分为区块主题。主题结构包含必需的 style.css 主题头与 theme.json，以及 templates/（至少需要 index.html）、parts/（扁平结构，不可有子目录）、patterns/、styles/。theme.json 版本 3 定义全局设置与样式，关键部分包括 settings.color.palette、settings.typography.、settings.spacing.、settings.layout 的 contentSize 与 wideSize、settings.border、styles.color、styles.typography、styles.elements.、styles.blocks.、customTemplates、templateParts。预设通过 var(--wp--preset--<type>--<slug>) 引用。样式层级为核心默认 -> theme.json -> 子主题 -> 用户自定义，数据库中存储的用户自定义可能覆盖 theme.json 的修改。模板使用区块标记的 HTML 文件，模板部件通过 <!-- wp:template-part ... /--> 引用。patterns/*.php 自动注册，使用 docblock 头（Title、Slug、Categories、Keywords、Block Types、Post Types、Viewport Width），可加 Inserter: no 隐藏。styles/ 下的 JSON 为样式变体。WordPress 6.9 新增：表单元素样式 styles.elements.input 与 styles.elements.select（边框、颜色、轮廓、阴影、间距，尚不支持焦点状态）、边框圆角预设 settings.border.radiusSizes、按钮伪类 :hover 与 :focus。
第三部分为 Interactivity API。指令包括 data-wp-interactive、data-wp-context、data-wp-on--{event}、data-wp-on-async--{event}（推荐）、data-wp-bind--{attr}、data-wp-text、data-wp-class--{name}、data-wp-style--{prop}、data-wp-each、data-wp-key、data-wp-watch、data-wp-init、data-wp-run。store 模式通过 store( namespace, { state, actions, callbacks } ) 定义，getContext() 获取每元素上下文，getElement() 获取当前 DOM 引用，异步动作使用生成器语法。state 为全局共享，context 为元素级作用域。服务端渲染为必需：在 block.json 中设置 "supports": { "interactivity": true }，用 wp_interactivity_state() 初始化状态，用 wp_interactivity_data_wp_context() 输出上下文，主题或插件无 block.json 时用 wp_interactivity_process_directives() 包裹 HTML。PHP 辅助函数还包括 wp_interactivity_get_context()、wp_interactivity_config()。水合规则要求客户端 JS 产出的标记与服务端一致，否则导致布局偏移。WordPress 6.9 变更：data-wp-ignore 已弃用，改用条件渲染或独立交互区域；同一元素多个同类型指令使用 --- 分隔符；getServerState()/getServerContext() 在客户端页面切换间重置；路由区域支持 attachTo 用于模态与弹窗等覆盖层；新增 TypeScript 类型 AsyncAction<ReturnType> 与 TypeYield<T>。
第四部分为工具链。@wordpress/scripts 命令包括 npx wp-scripts start、build、lint-js、lint-style、test-unit-js、test-e2e。wp-env 命令包括 npx wp-env start、stop、run cli wp plugin list。调试部分列出常见问题及排查方向，如“无效内容”多因未加弃用条目、区块不出现在插入器、属性未保存、编辑器样式未加载、apiVersion 警告、交互指令未触发、水合不匹配等。
第五部分为常见错误清单，包括改动 save() 未加弃用、重命名区块名、编辑端缺少 useBlockProps()、保存端缺少 useBlockProps.save()、PHP 渲染缺少 get_block_wrapper_attributes()、使用 innerHTML 保存、选择器过于脆弱、apiVersion 低于 3、派生状态仅存在于 JS、未在 block.json 声明样式、使用 data-wp-ignore、模板部件放入子目录、用户自定义覆盖 theme.json、一个区块内重复 InnerBlocks、无正当理由使用 templateLock: 'all' 等，并给出对应后果与修复方式。
【使用方式】 按需选用脚手架命令创建区块，依据 block.json 配置资产，区分静态与动态渲染实现，遵循包装函数与弃用规则；主题侧编写 theme.json 与模板文件；交互侧按 SSR 与水合规则定义 store 与指令。
【适用场景】 适合具备 WordPress 与前端开发经验、需要开发自定义 Gutenberg 区块、区块主题或使用 Interactivity API 构建交互功能的开发者。
【限制】 资料仅覆盖上述版本范围内的开发内容，未提供收费、价格、平台可用性或效果方面的信息。