WordPress短代码生成表单报错及规范疑问

问题根源 #

你遇到的「更新失败。响应不是有效的JSON响应」错误，核心原因是你的短代码函数直接输出了HTML内容，违反了WordPress短代码的核心规范：短代码函数不能直接输出内容，必须将内容以返回值（return）的形式交给WordPress处理。

当你在块编辑器中保存文章时，系统会通过AJAX请求处理更新，期望返回标准的JSON格式响应。但你的代码通过require_once直接输出了form.php里的HTML，导致响应内容被HTML打乱，无法解析为合法JSON，因此触发报错。

关于官方文档的误解 #

WordPress官方文档中「shortcode should never produce an output of any kind」的表述，并不是禁止短代码输出内容，而是禁止直接输出。那些知名插件的短代码都是合规的——它们的短代码函数都是将内容通过return返回，而非直接echo或输出。

修正你的短代码 #

只需修改短代码函数，利用输出缓冲捕获form.php的内容并返回：

add_shortcode( 'form', 'create_form' );
function create_form () {
    ob_start(); // 开启输出缓冲
    require_once __DIR__ . '/form.php';
    return ob_get_clean(); // 获取缓冲的HTML内容并返回
}

这样处理后，HTML内容会被WordPress正确接管，不会破坏AJAX的JSON响应，保存文章时就不会报错了。

其他复用表单的方案 #

如果不想用短代码，还可以选择这些方式：

• 自定义Gutenberg区块：开发专属的表单区块，在编辑器中可直接插入，更适配现代WordPress编辑流程。
• 自定义小工具：若表单需放置在侧边栏等小工具区域，可创建自定义小工具实现复用。
• 模板标签函数：编写一个返回表单HTML的函数，在主题模板文件中直接调用，适合固定位置的表单需求。

内容的提问来源于stack exchange，提问作者dejitay836