工具页案例图如何编写 alt让图片说明与处理场景对应

给案例图补上 alt 并不难难的是让说明始终对应图片原图和结果图说的是不是同一件商品描述的是处理目标还是实际画面图片加载失败后换了备用素材文字有没有一起换这些问题比“每张图都有 alt”更接近工具页的真实维护成本。本文以我维护的图片猫PicCat为例项目入口为www.piccat.cn。我沿商品换色工具页的案例配置和公共组件检查了一遍用仓库中的运动鞋、沙发素材说明 alt 的写法以及实现中仍需处理的边界。本文讨论网页 img 元素的替代文本。示例图片来自项目已有案例素材仅重新并排排版它们不是本次调用模型生成的结果也不能代表工具对任意输入的处理效果。1 先问图片在当前页面承担什么作用商品换色页的主案例图承载具体信息换的是哪个对象、原来是什么颜色、结果变成什么样。仅写“处理前”“处理后”读者仍然不知道画面内容。写成一串“AI 换色、免费在线换色、商品图处理”也无法补足这些信息。我会先看图片所在的位置。主对比图需要表达画面状态用于切换案例的缩略图可能只是旁边案例标题的视觉补充只有图标、没有文字的按钮则需要说明操作目的。W3C WAI 的图片教程也按图片用途区分替代文本不能只按文件类型决定写法。[1][2]所在位置优先表达的信息需要避免处理前后主图主体、当前状态、与本次操作相关的变化两张图都只写“效果图”带文字的案例切换按钮由按钮文字说明案例图片若无额外信息可用空 alt图片说明与可见标题重复朗读只有图片的操作入口操作或目的例如“放大查看运动鞋换色结果”只有“运动鞋”却不说明入口作用纯装饰图片明确写 alt省略属性后让文件名承担说明空 alt 与缺少 alt 不是同一件事。是否允许空值要结合周围文本和交互名称判断。主案例图如果承担独立的对比信息通常应保留有效说明缩略图是否冗余则要检查它所在的整个按钮。2 把场景说明放进案例数据当前商品换色页 EcommerceProductRecolor.vue 在上传区的 showcase-sections 插槽中把 ecommerceProductRecolorFixedCases 传给 FixedShowcaseStorySections。后者再把 beforeAlt、afterAlt 原样传入 BeforeAfterSlider由滑块绑定到两张 img 上。这条链路把“知道画面内容的配置”和“负责显示的组件”分开。通用滑块不需要猜运动鞋是什么颜色也不需要根据文件名生成商品说明。ShowcaseCase 类型已经提供 beforeAlt、afterAlt、thumbnailAlt不过它们都是可选字段类型本身并不保证每个案例都写了有效说明。项目代码摘录运动鞋案例的说明字段beforeLabel: 纯白运动鞋,afterLabel: 亮橙色鞋面,beforeAlt: AI 商品换色案例白色运动鞋商品图,afterAlt: AI 商品换色案例运动鞋改为亮橙色后保留网面和鞋带细节,片段来自 ecommerceProductRecolorFixedCases.ts省略了案例 ID、图片路径、标题和 caption。beforeLabel、afterLabel 用作图片上的短标签alt 提供图片的文字替代caption 则放在图片附近解释整个案例。三个字段用途不同不必机械地复制同一段内容。项目代码摘录FixedShowcaseStorySections.vue 中的属性传递BeforeAfterSlider:before-srcitem.before:after-srcitem.after:before-labelitem.beforeLabel:after-labelitem.afterLabel:before-altitem.beforeAlt:after-altitem.afterAlt:aspect-ratioitem.previewAspectRatio:tool-nametoolName:image-loadingindex 0 ? eager : lazy/这是循环内部的真实片段省略了外层 article 和文字区域不能独立运行。新增案例时维护一条完整的数据记录即可复用这条传递链替换图片时也应把同条记录中的标签、alt 和 caption 一起复核。3 从实际画面写出处理前后的差异运动鞋案例很适合说明“主体状态”的写法。原图可以写“白色运动鞋侧面展示鞋面为网布与拼接结构”结果图可以写“运动鞋由白色改为橙色网面和鞋带仍可见”。这些是建议文案不是当前配置的逐字摘录。如果页面标题已经写清“AI 商品换色”alt 可以直接从运动鞋说起不必每张都重复工具名。颜色变化是这组图的重点背景墙的细节就不必逐项描述。另一方面画面里能看见网面不等于已经证明处理“无损”所以我倾向于用“仍可见”而不是“完美保留”。这套写法可以按处理类型调整抠图说明主体及背景变化消除说明被移除的对象和留下的区域改字说明与任务有关的原文字和新文字。不要把整段提示词直接塞进 alt也不要补写图片没有展示的处理步骤或质量结论。沙发案例暴露出另一类问题。当前 afterAlt 写的是“AI 商品换色案例沙发改为森林绿后客厅背景与光影保持不变”。但直接对照仓库中的前后图片可以看到左侧边几上的花瓶与枝叶状摆件也变成了绿色。仅凭这组素材无法支持“背景与光影保持不变”的断言。更贴近画面的建议写法是“客厅中的单人沙发改为绿色左侧摆件也出现绿色变化。”如果产品希望展示的是只修改沙发的案例应先更换合适的素材再同步修订说明。靠 alt 把副作用写没了读者实际看到的矛盾仍然存在。当前仓库的这一处文案尚未在本文中修改。这里的判断只针对这对本地素材不推断线上模型的普遍表现。实际图片优先于处理要求提示词写了“其他区域不变”并不能成为结果说明里的事实依据。4 默认文案只能兜底 空值必须有语义BeforeAfterSlider 当前优先使用显式 alt未提供时拼接工具名和前后标签。这个默认值可以避免完全没有说明但不包含具体主体无法替代逐案例文案。项目代码摘录BeforeAfterSlider.vue 的前图 alt 计算调整换行const computedBeforeAlt computed(() (props.beforeAlt || (props.toolName? ${props.toolName} - ${props.beforeLabel}: props.beforeLabel)));后图采用相同逻辑。这里使用 ||会把空字符串也视为“未填写”调用方传 beforeAlt得到的仍是“AI 商品换色 - 处理前”。反过来只有空格的字符串属于真值会绕过默认值。是否有 alt 属性与是否有有效描述需要分开检查。对承载信息的主图最简单的做法是在案例数据校验中拒绝空白说明。若公共组件确实需要支持“明确不提供替代文本”的用途才考虑把未提供与显式空值区分开。下面是后者的建议局部实现尚未接入项目。建议改进代码仅示意前图的空值策略依赖现有 props 与 computedconst computedBeforeAlt computed(() {const fallback props.toolName? ${props.toolName} - ${props.beforeLabel}: props.beforeLabel;if (props.beforeAlt undefined) return fallback;return props.beforeAlt.trim();});这段逻辑约定 undefined 表示使用默认值显式传入的空白文本会规范为 。它不会替你决定图片是否属于装饰内容主案例配置仍需要禁止误传空值。如果数据来自接口还应先校验类型不把 TypeScript 的 string 声明当成运行时保证。5 切换图片和加载回退也要切换说明另一条案例展示路径 FeatureShowcaseGallery.vue 使用 activeCase 同时提供主图地址和 alt。发生主图加载错误且有备用案例时组件会切换到 fallbackCases主图资源和说明因而取自同一条备用记录。这与商品换色页的固定长图文案例入口不同不应混为同一条渲染路径。但缩略图回退是单独处理的。getMatchingFallbackCase 优先按 ID 匹配找不到时使用相同下标的备用案例getThumbnailSrc 切换图片来源模板中的 alt 仍读取原来的 item。下面只摘录与问题相关的两处绑定。项目代码摘录FeatureShowcaseGallery.vue 的缩略图绑定省略其他属性img:srcgetThumbnailSrc(item, index):altitem.thumbnailAlt || ${item.title}处理效果/当两套案例恰好同序、内容一致时这种写法未必出错如果某个缩略图失效而同下标备用项对应另一件商品就可能出现“图片是沙发说明仍是运动鞋”。这是现有逻辑在特定数据条件下的风险不是已经确认的线上故障。建议先确定备用关系再统一解析当前缩略图的资源和元数据。无法确认是同一案例时保留原案例标题并显示中性占位通常比换成另一件商品更准确。仅把备用 alt 换过来也不够因为点击后打开的仍可能是原案例图片、说明和操作目标必须一起对应。缩略图按钮里还已有可见的 item.title。如果缩略图只是这段标题的视觉补充可以让图片使用 alt由按钮文字提供名称如果图片传递了标题没有的信息再保留简短补充。当前模板使用 ||同样不能直接通过 thumbnailAlt 表达前一种意图。WAI 的功能图片示例说明了有文字的链接如何避免重复而只有图片的入口则必须有可用名称。[2]6 验证文本之外 还要验证实际语义本次做了源码局部执行和素材核对5 条固定换色案例都有非空的前后 alt对应的 10 个本地图片文件均存在从滑块源码提取计算逻辑后确认显式文本被保留、空字符串触发默认文案、纯空格不会触发默认文案。另外用“原案例是运动鞋、同下标备用案例是沙发”的构造数据执行缩略图来源函数确认它可返回沙发图片地址而原模板表达式仍返回运动鞋说明。这个验证只证明局部逻辑可以产生错配不代表实际接口正在返回这组数据也没有覆盖完整页面、网络和读屏软件。还有一个容易被 alt 检查遗漏的结构问题当前 BeforeAfterSlider 把 roleslider 放在包住两张图片的根元素上并设置固定 aria-label“处理前后对比滑块”。MDN 说明slider 的后代元素语义会被呈现性处理。因此即使 DOM 中两张图都有 alt也不能据此认定辅助技术会把它们作为两个独立图片读出。[3]建议把对比内容与滑块控制分开组织或在控件外提供明确关联的案例说明并结合实际无障碍树核验。这里不能只把根节点的 aria-label 改长就宣布完成控制名称、当前数值的含义、前后画面的说明和键盘操作都需要一起验证。本文没有对该结构实施改造或完成读屏验收。建议验收项应检查的结果逐案例看图读文主体、颜色、前后状态准确副作用没有被质量承诺掩盖切换案例与接口更新src、alt、caption 和点击目标属于同一案例模拟图片加载失败备用素材语义一致无法匹配时不使用另一案例冒充空值与重复信息区分省略、空字符串和空白文本按钮名称不过度重复辅助技术与键盘检查无障碍树及读屏输出滑块名称、数值、说明可理解这些是建议执行的验收项不是本次已全部通过的测试。自动检查适合发现属性缺失、空白文本和资源路径问题“森林绿”“背景不变”是否符合图像仍需要人工对照素材。也不要用一个固定字符数上限代替信息质量判断。7 让 alt 随案例一起维护对工具页而言好的 alt 来自可复核的案例记录描述谁、呈现什么状态、这次变化是什么图片更新后同步检查说明和交互。通用组件保留合理兜底但不替业务猜场景备用图也必须遵守同一套对应关系。Google 的图片指南建议让 alt 与页面上下文相关、提供有用信息并避免关键词堆砌。[4] 这支持我们把场景写清楚但不意味着补完 alt 就能保证收录或排名。本文没有进行流量对照实验也不把文案修订当成 SEO 效果证明。对我来说这次核对最有价值的发现是沙发案例字段存在、组件传值正确文字依然可能与画面不符。真正需要持续维护的是图片与说明的对应关系。源码位置与参考资料项目代码均位于 webClientVue/srccomponents/ecommerce/EcommerceProductRecolor.vue 为页面接入config/ecommerceProductRecolorFixedCases.ts 为本文两组案例的数据来源config/showcasePairs.ts 定义案例类型components/common 下的 FixedShowcaseStorySections.vue、BeforeAfterSlider.vue 和 FeatureShowcaseGallery.vue 分别承担传值、对比显示与画廊回退。两组图片来自 webClientVue/public/showcase/cases/ecommerce-product-recolor 下的 sneaker-color-before/after.webp 与 sofa-color-before/after.webp。源码结论针对本次检查的本地版本建议代码与当前实现已分别标明。[1] W3C WAI · Images Tutorial[2] W3C WAI · Functional Images[3] MDN · ARIA slider role[4] Google Search Central · Google image SEO best practices