企业官网建设流程全解析

freeCodeCamp 实战：为图片添加 alt 文本替代，实现视觉障碍无障碍访问

【免费下载链接】freeCodeCampfreeCodeCamp.org's open-source codebase and curriculum. Learn math, programming, and computer science for free.项目地址: https://gitcode.com/GitHub_Trending/fr/freeCodeCamp

本篇技术指南以 freeCodeCamp 课程体系中「应用无障碍」（Applied Accessibility）模块的第一个实战挑战为核心，完整讲解 HTMLalt属性的作用、编写规范与验证机制。读完本文，你将掌握：如何为<img>标签撰写符合 HTML5 规范的替代文本（alt text）、无障碍挑战在 freeCodeCamp 仓库中的文档结构与自动断言验证方式，以及装饰性图片场景下 alt 属性留空的进阶规则。

挑战文档的坐标与结构

本文讨论的指定文档位于仓库课程目录中：

• 挑战文件：applied-accessibility 模块首个挑战
• 所属模块结构定义：applied-accessibility.json

从源码结构看，freeCodeCamp 的每个挑战都是一个 Markdown 文件，由 YAML frontmatter 加上若干约定小节组成。该挑战的 frontmatter 定义了挑战的全部元数据：

正文部分遵循统一的挑战文档骨架，由以下小节按序组成：

1. # --description--：知识点讲解，是本文主体内容的来源；
2. # --instructions--：给学员的具体任务指令；
3. # --hints--：提示，其中内嵌 Mochaassert断言代码，可帮助学员理解判题逻辑；
4. # --seed--下的## --seed-contents--：编辑器中初始的种子代码；
5. # --solutions--：标准答案。

在模块层面，applied-accessibility.json 通过challengeOrder数组声明了该模块 22 个挑战的先后顺序，本挑战（id 为587d774c367417b2b2512a9c）正是数组的第一项，即整个无障碍模块的入门任务。模块元数据同时声明了helpCategory: HTML-CSS与dashedName: applied-accessibility，用于帮助分类与 URL 路由。

核心概念：alt 属性为什么存在

挑战文档的--description--小节给出了三点技术理由，这也是 HTML 无障碍开发的基础知识：

1. 图片加载失败时的兜底。alt文本描述图片内容，充当其文本替代。当图片无法加载或用户无法看到图片时，alt属性保证信息通道不中断。文档给出的示例：

<img src="importantLogo.jpeg" alt="Company logo">

2. 屏幕阅读器的信息入口。视觉障碍用户依赖屏幕阅读器把网页内容转成语音界面——纯视觉呈现的信息对他们不可见。对于图片，屏幕阅读器可以读取img元素的alt属性内容并朗读出来，从而传达关键信息。因此「好的 alt 文本」要求：简洁地描述图片内容（brief description），而非堆砌关键词。

3. 搜索引擎的图像理解依据。搜索引擎会利用alt属性理解图片内容，以决定是否将其纳入图片搜索结果。因此 alt 文本同时服务于无障碍与 SEO 两个场景。

文档还强调了一个规范性结论：应始终为图片包含alt属性，按 HTML5 规范这已属于强制要求（mandatory）。这一表述与紧随其后的姊妹挑战 Know When Alt Text Should be Left Blank 相互衔接：属性必须有，但值可以是空字符串。

实战任务：种子代码、指令与解答

挑战的--instructions--设定了任务情境：Camper Cat 正在搭建个人网站，他的头像展示了他的技能，需要在img标签上添加alt属性，说明「Camper Cat 正在打空手道」。文档特别提示：图片的src并不指向真实文件，因此预览区会直接显示alt文本——这正是检验 alt 是否生效的直观方式。

编辑器中的初始种子代码（--seed-contents--）如下：

<img src="doingKarateWow.jpeg">

任务完成后，标准答案（--solutions--）为：

<img src="doingKarateWow.jpeg" alt="Someone doing karate">

对比两版代码，唯一的改动就是补充了alt="Someone doing karate"。alt 文本的措辞要点由此可以提炼：描述图片实际呈现的内容（有人在做空手道动作），而不是复述文件名或文件名语义（doingKarateWow）。

判题机制：基于 DOM 断言的提示

--hints--小节内嵌了判定该任务是否通过的测试断言代码：

assert.isNotEmpty(document.querySelector('img')?.getAttribute('alt'));

从源码结构看，freeCodeCamp 的challengeType: 0类挑战在学员提交代码后，会在沙箱环境中执行此类 Mochaassert风格的断言：通过document.querySelector('img')取到页面中的图片元素，再用getAttribute('alt')读取其 alt 属性值，最终用assert.isNotEmpty校验「alt 属性存在且非空」。断言使用了可选链?.，意味着如果页面中找不到img元素，取值会得到undefined而使断言失败——这从判题角度反向印证了文档中的要求：alt 属性不能省略，也不能留空（注意这与下一挑战「装饰图允许alt=""」形成对比，那里用的是assert.isEmpty）。

这条断言本身就是一份可运行的验证依据：任何前端工程中，都可以用同样的 DOM 查询方式编写无障碍审计脚本，批量检查页面中是否存在缺失 alt 的图片。

延伸：什么时候 alt 应该留空

本挑战确立了「alt 属性必须有」的规则，而模块中的下一个挑战 587d774c367417b2b2512a9d.md（Know When Alt Text Should be Left Blank）立即补全了规则的另一半：

• 当图片已有标题文字（caption）描述，或仅用于纯装饰时，img元素仍需要alt属性，但可以设为空字符串：

<img src="visualDecoration.jpeg" alt="">

• alt=""会告诉屏幕阅读器「跳过这张图」，避免朗读无意义的装饰内容；
• CSS 背景图（background-image）不属于标记层，屏幕阅读器本就不会处理，因此不需要 alt；
• 该挑战的判题断言为assert.isEmpty(document.querySelector('img')?.getAttribute('alt'))，与本挑战的isNotEmpty恰好互补。

这一「必须存在、可空值」的设计值得记入工程习惯：判断装饰性 vs 信息性图片是写 alt 文本前的第一步决策——信息图写描述，装饰图写空串，两者都保留属性本身。

本篇要点回顾

1. alt属性是 HTML5 规范下的强制性要求，服务于图片加载失败兜底、屏幕阅读器朗读、搜索引擎图像理解三个场景；
2. 优质 alt 文本应当简洁描述图片实际内容，如alt="Someone doing karate"，而非照抄文件名；
3. 装饰性或已有文字说明的图片使用alt=""，属性保留、值为空；
4. freeCodeCamp 仓库中，该知识点由 587d774c367417b2b2512a9c.md（写描述）与 587d774c367417b2b2512a9d.md（留空规则）两个挑战成对覆盖，并通过getAttribute('alt')上的 Mocha 断言在学员代码上自动验证；
5. 若想继续深入，可沿 applied-accessibility.json 中challengeOrder声明的 22 个挑战顺序，依次学习标题层级、main/article/地标元素、figure、表单label、对比度与tabindex等后续主题。

【免费下载链接】freeCodeCampfreeCodeCamp.org's open-source codebase and curriculum. Learn math, programming, and computer science for free.项目地址: https://gitcode.com/GitHub_Trending/fr/freeCodeCamp