Gutenberg区块根组件类名修改的Deprecation功能实现问题求助

嘿，Niko，我看了你遇到的问题——修改Gutenberg区块根类名后，区块验证失败，虽然配置了deprecated但没生效对吧？我来帮你梳理下问题出在哪，以及怎么解决。

核心问题分析 #

你现在遇到的验证错误，本质是WordPress没有触发旧版本区块的迁移逻辑：它直接用新版本save函数生成的内容（根类为SOME_OTHER_CLASSNAME），和数据库里的旧内容（根类为abc_defbox）做对比，自然不匹配。而导致deprecated没生效的最关键原因，是你没有更新block.json里的版本号——Gutenberg是通过版本号来区分新旧区块的，如果新旧版本用同一个version，WordPress不会认为这是一次版本迭代，也就不会去检查deprecated数组。

具体解决步骤 #

步骤1：更新block.json的版本号

打开你的block.json文件，添加或更新version字段，把旧版本号（比如1）改成新的版本号（比如2）：

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "abc/defbox",
  "title": "ABC Defbox",
  "version": "2", // 旧版本如果是1，这里改成2
  // 其他属性（比如attributes、description等）保持不变
}

这一步是触发deprecated逻辑的核心，告诉WordPress这是区块的2.0版本，需要兼容旧的1.0版本。

步骤2：完善deprecated.js配置

你的v1配置已经有了旧版本的save函数，但可以补充migrate函数（虽然属性没变化，但能明确触发迁移流程），同时去掉不必要的console.log：

import { RichText, InnerBlocks } from '@wordpress/block-editor';
import { Icon } from '@wordpress/components';
import { abcIcons } from '../../assets/icons';

const v1 = {
    // 如果旧版本的attributes和新版本完全一致，可以省略这个字段；如果有差异，要写旧版本的attributes定义
    // attributes: { ... },
    migrate( attributes ) {
        // 我们只是修改了根类名，属性结构没变化，直接返回原属性即可
        return attributes;
    },
    save(props) {
        const { attributes } = props;
        return (
            <div className={"abc_defbox"}>
                <div className={'abc_defbox-definition'}>
                    <div
                        className={'abc_defbox-icon-wrapper'}
                        style={{ fill: attributes.color }}
                    >
                        <Icon icon={abcIcons[attributes.icon]} />
                    </div>
                    <RichText.Content
                        tagName={'span'}
                        className={'abc_defbox-header'}
                        value={attributes.header}
                        style={{ color: attributes.color }}
                    />
                </div>
                <InnerBlocks.Content />
            </div>
        );
    }
};

export default [v1];

步骤3：优化新版本的save函数（可选但推荐）

尽量使用Gutenberg官方推荐的useBlockProps来处理根元素属性，这样能更好地兼容区块的核心功能（比如自定义类名、对齐设置等）：

import { RichText, InnerBlocks, useBlockProps } from '@wordpress/block-editor';
import { Icon } from '@wordpress/components';
import { abcIcons } from '../../assets/icons';
import './style.scss';

export default function save(props) {
    const { attributes } = props;
    // 使用useBlockProps.save合并默认属性和自定义类名
    const blockProps = useBlockProps.save( { className: 'SOME_OTHER_CLASSNAME' } );
    
    return (
        <div { ...blockProps }>
            <div className={'abc_defbox-definition'}>
                <div
                    className={'abc_defbox-icon-wrapper'}
                    style={{ fill: attributes.color }}
                >
                    <Icon icon={abcIcons[attributes.icon]} />
                </div>
                <RichText.Content
                    tagName={'span'}
                    className={'abc_defbox-header'}
                    value={attributes.header}
                    style={{ color: attributes.color }}
                />
            </div>
            <InnerBlocks.Content />
        </div>
    );
}

验证修复效果 #

做完以上修改后，重新构建你的区块代码并刷新编辑器：

1. 旧区块会被识别为v1版本，通过deprecated里的save函数验证匹配
2. WordPress会自动用新版本的save函数重新保存区块内容，根类名会更新为SOME_OTHER_CLASSNAME
3. 之前的区块验证错误会完全消失

备注：内容来源于stack exchange，提问作者SoneFall