FSWP 区块开发者
基础（始终应用）： fswp-developer/references/lean-coding.md（少写、优先复用）、fswp-developer/references/coding-standards.md（编码标准、文档、国际化、可访问性），以及 fswp-security-engineer（输入、输出、授权）。
优先使用核心区块；仅在核心区块和模式无法满足需求时编写自定义区块。官方参考：Block Editor Handbook 链接位于 fswp-developer/references/official-docs.md。对照项目声明的WordPress最低版本，检查每个API所需的WordPress版本。
区块结构
blocks/my-block/
block.json 名称、标题、分类、属性、支持、渲染、editorScript、viewScriptModule、style
edit.js 编辑器UI（使用 useBlockProps）
save.js 静态标记，动态区块可省略
render.php 动态区块的服务器端渲染
view.js 前端行为（模块）
style.scss / editor.scss
通过元数据注册：register_block_type( __DIR__ . '/build/my-block' ) 在 init 钩子上（为 init 回调使用具名函数）。设置 "apiVersion": 3（自WordPress 6.3起）并添加 "$schema": "https://schemas.wp.org/trunk/block.json"。字段参考（已对照Block Editor Handbook验证）：references/block-json.md。
决策指南
| 问题 | 选择 |
|---|---|
| 输出仅依赖于保存的属性 | 静态区块（save.js） |
| 输出依赖于实时数据、必须在不重新保存的情况下更改，或包含逻辑 | 动态区块（render.php）；save 返回 null 或仅返回 InnerBlocks |
| 嵌套内容 | InnerBlocks 配合 allowedBlocks 和 template |
| 将属性绑定到数据（文章元数据、自定义来源） | Block Bindings API（register_block_bindings_source），需WordPress最低版本允许 |
| 已有区块的替代预设 | 区块变体或样式，而非新建区块 |
| 可复用的布局 | 模式，而非区块 |
规则
- 属性：为每个属性指定
type和default；一致地从标记或注释中获取来源；在render.php中进行验证。 - 使用
supports（颜色、间距、排版、对齐、锚点）而非编写控件。 - 编辑器标记必须使用
useBlockProps()；动态PHP使用get_block_wrapper_attributes()。 render.php（block.json 中的render，WordPress 6.1+）接收$attributes、$content和$block（WP_Block对象）。它会在页面中每个区块实例加载一次，因此切勿在其中声明函数或类；应调用另一个文件中的共享代码。- 脚本 vs 模块：
viewScript用于传统脚本（以及依赖WordPress脚本的任何内容）；viewScriptModule（6.5+）用于脚本模块，例如Interactivity API。两者不可互换，因此不要混合依赖。 - 在
render.php中转义所有内容（fswp-security-engineer）；属性是用户输入。 - 更改已发布静态区块的已保存标记会破坏现有内容。添加包含旧
save、属性和migrate函数的deprecated条目，然后更改区块。 - 在JS和PHP中翻译字符串（使用文本域的
__()）；使用wp_set_script_translations或 block.json 中的textdomain。 - 仅在区块渲染的位置加载前端脚本（block.json 中的
viewScriptModule/script会自动处理）。
模式
关于模式、变体、区块钩子和绑定的更多细节：references/patterns-variations.md。Interactivity API深度内容（服务器端渲染、异步操作、data-wp-each、观察器、性能）：references/interactivity.md。
在PHP中使用 register_block_pattern()（及 register_block_pattern_category()）注册，或作为主题 patterns/ 目录下的文件注册。模式使用预设和翻译文本；不使用远程图片；为它们提供清晰的标题、分类和关键词。
Interactivity API
服务器端渲染标记加上小型响应式行为，无需框架。
- 启用方式：
"supports": { "interactivity": true }和"viewScriptModule": "file:./view.js"。 - 标记指令：
data-wp-interactive="namespace"、data-wp-context='{"open":false}'、data-wp-on--click="actions.toggle"、data-wp-bind--hidden="!context.open"、data-wp-class--is-open="context.open"、data-wp-text="state.label"。 - 存储（
view.js）：import { store, getContext } from '@wordpress/interactivity'; store( 'namespace', { state: {...}, actions: { toggle() { const c = getContext(); c.open = ! c.open; } } } ); - 使用
wp_interactivity_state( 'namespace', array(...) )注入服务器端状态，以确保首次渲染正确且无闪烁。保持状态可序列化。 - 所有内容添加命名空间以避免冲突；切勿将机密信息放入状态或上下文中（两者都会打印到页面中）。
- 对于可访问性，将
aria-expanded和焦点处理与状态绑定，并测试键盘操作。
构建与测试
使用 npx @wordpress/create-block 创建起点；使用 @wordpress/scripts 进行 build、start、lint-js、lint-style、test-unit-js。将构建后的文件与 src/、package.json 和锁定文件一起交付（编译代码的目录规则）。在编辑器中测试（插入、编辑、保存、重新加载、切换到代码视图）以及前端测试。交予 fswp-qa-engineer。