WordPress Gutenberg自定义块icon属性未保存及块报错问题

问题背景 #

开发Gutenberg自定义块时，需要根据单选组选中项渲染对应SVG图标，出现两个核心异常：

• 重新进入编辑会话时单选组选中状态丢失
• 块验证报错，提示save输出标记与存储内容不匹配，icon属性读取为空，同属配置的color属性可正常读写

根因定位 #

核心问题出在icon属性配置错误、Save组件输出不符合规则，以及冗余状态冲突：

1. 属性类型与source配置不匹配：原配置给icon设置type: "object"搭配source: "html"，但html类型source提取的是DOM节点的innerHTML字符串，和object类型完全不兼容，导致属性无法被正确序列化存储，重新加载时也无法从已保存内容中提取值
2. Save输出与属性选择器不匹配：原配置给icon指定了提取选择器.jig_defbox-icon，但Save函数输出的DOM结构里没有带这个class的节点，Gutenberg加载块时找不到对应节点，自然无法读取icon值
3. 冗余本地状态冲突：Edit组件里额外用useState存储toggled状态属于多余逻辑，很容易和块属性的真值不同步

修复步骤 #

1. 修正块属性注册配置 #

icon存储的是单选选项的字符串标识，这类简单配置值不需要从HTML提取，直接去掉source配置即可（属性会直接序列化到块的注释标记里，是Gutenberg最稳定的属性存储方式），修正后配置：

"icon": {
  "type": "string",
  "default": ""
},
"color": {
  "type": "string",
  "default": "#919191"
}

如果你确实需要从DOM节点提取icon值，必须保证type和source匹配，且Save输出对应选择器的节点：比如将type设为string，Save里把icon值输出到带.jig_defbox-icon类的节点中（例如<div class="jig_defbox-icon" data-icon={attributes.icon}>），但对于选项标识这类简单值，直接存储到块属性是更简单可靠的方案。

2. 简化Edit组件逻辑，删除冗余本地状态 #

不需要额外用useState存储选中状态，直接绑定块属性即可，同时补全编辑区预览结构，修正后的核心代码：

return(
    <InspectorControls>
        <ColorPalette
            colors={[
                {name: 'lightgray', color: '#d8d8d8'},
                {name: 'darkgray', color: '#919191'},
                {name: 'red', color: '#dc1a22'}
            ]}
            disableCustomColors={true}
            onChange={(value) => {props.setAttributes({color: value});}}
            value={props.attributes.color}
            clearable={false}
        />
        <RadioGroup
            onChange={ (value) => {
                props.setAttributes({icon: value});
            } }
            checked={props.attributes.icon}     
        >
            {
            str_array.map( 
                item => ( <Radio value={item} key={item}><Icon icon={icon_getter(item)}/></Radio> )
            )
            }
        </RadioGroup>
    </InspectorControls>
    <div style={{"fill": props.attributes.color}}>
        <Icon icon={icon_getter(props.attributes.icon)}/>
    </div>
)

注意：循环渲染Radio时必须加唯一key属性，避免React渲染异常

3. 修正Save组件输出，保证结构稳定 #

Save组件不要输出动态随机属性，保证和Edit预览结构一致，修正后代码：

const {attributes} = props;
return (
    <div style={{"fill": attributes.color}}>
        <Icon icon={icon_getter(attributes.icon)}/>
    </div>
)

验证步骤 #

修改完成后需要在块编辑页点击右上角「更多选项」->「尝试重新匹配块」，或者直接新建块测试：

1. 选择图标、设置颜色后保存更新文章
2. 刷新页面重新进入编辑，检查单选组选中状态是否保留
3. 查看控制台是否还有块验证报错
4. 检查前台页面SVG图标和颜色是否正常渲染

内容的提问来源于stack exchange，提问作者HoffErik-JohnerInst