Gutenberg自定义图片块预览不显示alt文本求助

问题核心 #

编辑器中能看到Alt文本，但预览/前端页面不显示，本质是save组件未正确输出alt属性，或block.json未完成alt属性的存储规则注册——毕竟edit组件负责编辑器内渲染，而save组件才是生成前端页面HTML的关键。

分步修复方案 #

1. 确保block.json正确注册alt属性 #

在block.json的attributes字段中添加alt属性的定义，明确其存储规则：

{
  "apiVersion": 3,
  "name": "custom/image-block",
  "title": "自定义图片块",
  "category": "media",
  "icon": "format-image",
  "attributes": {
    "imageUrl": {
      "type": "string",
      "source": "attribute",
      "selector": "img",
      "attribute": "src"
    },
    "altText": {
      "type": "string",
      "source": "attribute",
      "selector": "img",
      "attribute": "alt",
      "default": ""
    }
  },
  "editorScript": "file:./edit.js",
  "saveScript": "file:./save.js"
}

这里要保证altText的source和selector与save组件中的img标签对应，确保WordPress能正确从存储的HTML中解析该属性。

2. 修改save.js，显式输出alt属性 #

save函数必须将存储的altText绑定到img标签的alt属性上，即使为空也要显式输出（符合无障碍规范）：

import { useBlockProps } from '@wordpress/block-editor';

export default function save({ attributes }) {
  const blockProps = useBlockProps.save();
  const { imageUrl, altText } = attributes;

  return (
    <div {...blockProps}>
      {imageUrl && (
        <img
          src={imageUrl}
          alt={altText || ''}
        />
      )}
    </div>
  );
}

关键是alt={altText || ''}这一行，省略alt属性会导致前端完全不渲染该字段，即使编辑器中已设置。

3. 验证edit组件的属性绑定（确保编辑器修改能被保存） #

确保edit组件中，alt文本的输入操作能同步更新altText属性，示例代码：

import { useBlockProps, MediaUpload, MediaUploadCheck } from '@wordpress/block-editor';
import { Button } from '@wordpress/components';

export default function Edit({ attributes, setAttributes }) {
  const blockProps = useBlockProps();
  const { imageUrl, altText } = attributes;

  const onSelectImage = (media) => {
    setAttributes({
      imageUrl: media.url,
      altText: media.alt || '' // 选中图片时同步自带的alt文本
    });
  };

  return (
    <div {...blockProps}>
      <MediaUploadCheck>
        <MediaUpload
          onSelect={onSelectImage}
          allowedTypes={['image']}
          value={imageUrl}
          render={({ open }) => (
            <Button onClick={open} variant="secondary">
              {imageUrl ? '更换图片' : '选择图片'}
            </Button>
          )}
        />
      </MediaUploadCheck>
      {imageUrl && (
        <>
          <img src={imageUrl} alt={altText} />
          <input
            type="text"
            value={altText}
            onChange={(e) => setAttributes({ altText: e.target.value })}
            placeholder="输入图片Alt文本"
          />
        </>
      )}
    </div>
  );
}

这里要保证用户修改输入框时，setAttributes能实时更新altText，让save组件拿到最新值。

验证修复 #

1. 重新构建并激活块插件
2. 在编辑器中插入自定义图片块，设置图片和Alt文本
3. 点击预览或发布后查看前端页面，检查img标签的alt属性是否正确渲染
4. 查看页面源代码，确认alt字段已存在

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