语义化列表元素实战指南:用 ul、ol、dl 构建屏幕阅读器可感知的内容结构
【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址https://gitcode.com/gh_mirrors/fr/Front-End-Checklist点击查看免费下载本文是 Front-End-Checklist 仓库中semantic-lists无障碍/文档结构规则的技术解读。核心文档位于 skills/semantic-lists/references/rule.md配套技能定义见 skills/semantic-lists/SKILL.md。读完本文你将掌握为什么长得像列表的 div 堆叠对辅助技术毫无意义、三种语义列表元素的正确选型与写法、如何在 React 与 CSS 中保留语义地实现列表以及如何用自动化与人工手段验证屏幕阅读器的实际播报结果。规则速览优先级 medium · 难度 beginner · 预计耗时 10 分钟。核心结论一句话成组的相关条目应使用ul、ol或dl元素以便屏幕阅读器播报列表上下文与条目数量。一、规则是什么语义列表元素成组的相关条目应使用ul、ol或dl元素以便屏幕阅读器播报列表上下文与条目数量。这条规则属于**文档结构document-structure**子类别是 Front-End-Checklist「无障碍基础Accessibility Essentials」检查清单中 12 项核心检查之一见 packages/content/checklists/en/accessibility-essentials.mdx该清单聚焦 WCAG Level A 与 AA 要求。它的本质是HTML 语义元素是屏幕阅读器理解页面结构的信息载体视觉上看起来像列表的div在无障碍树中只是无意义的容器。典型反例与正解!-- ❌ Bad: Styled divs with no semantics -- div classfeature-list div classfeatureFast performance/div div classfeatureEasy setup/div div classfeature24/7 support/div /div !-- ✅ Good: Semantic unordered list -- ul classfeature-list liFast performance/li liEasy setup/li li24/7 support/li /ul从仓库源码结构看该规则对应的完整元数据优先级、难度、检查/修复/解释提示词、AI 上下文都定义在 packages/content/rules/en/accessibility/semantic-lists.mdx 中其中的aiContext明确建议审查渲染后的 HTML、交互组件或设计系统模式时先检查原生语义再检查键盘行为、焦点流、可访问名称与屏幕阅读器输出。二、为什么它重要屏幕阅读器的播报机制屏幕阅读器如 NVDA、JAWS、VoiceOver进入一个语义列表时会播报列表共 X 项list with 5 items帮助用户理解内容的组织方式、总条目数以及当前位置。而纯样式化的div不会提供任何列表上下文——用户听到的只是一串孤立的文本节点无法判断这些内容在结构上是并列的一组功能点还是有顺序的操作步骤。配套规则 listitem.mdx 对这一点给出了更细的佐证当li存在于合法列表容器之外时NVDA 与 JAWS 不会播报共 5 项或第 2 项共 5 项VoiceOver 则可能把孤立的li当作纯文本播报用户彻底失去这个列表有多长、我在哪里的结构信息。这正是语义结构规则背后统一的无障碍原理。三、三种列表类型怎么选元素用途屏幕阅读器播报ul无序条目导航、功能点、项目符号列表共 X 项ol有序序列步骤、排名、操作指引列表共 X 项 当前位置/序号dl术语-定义对术语表、FAQ定义列表选型原则来自 skills/semantic-lists/SKILL.md 的 Quick Referenceul用于无序列表导航菜单、产品功能点、普通项目符号ol用于有序序列分步指引、排名、操作步骤dl用于术语-定义对术语表、FAQ、元数据说明。有序列表别手动编号手动把序号写进div是常见错误——一旦内容增删序号就需要手工维护而且屏幕阅读器无法播报当前位置。!-- ❌ Bad: Manual numbering -- div classsteps div1. Sign up for an account/div div2. Complete your profile/div div3. Start using the app/div /div !-- ✅ Good: Semantic ordered list -- ol classsteps liSign up for an account/li liComplete your profile/li liStart using the app/li /ol使用ol后序号由浏览器自动生成用户可以用屏幕阅读器的列表导航快捷键在不同步骤间跳转并始终获知当前位置。四、定义列表术语与定义的配对dldescription list由dt术语与dd描述配对组成适合术语表与 FAQ!-- ✅ Good: Term-definition pairs -- dl classglossary dtAPI/dt ddApplication Programming Interface/dd dtREST/dt ddRepresentational State Transfer/dd dtJSON/dt ddJavaScript Object Notation/dd /dl !-- FAQ using definition list -- dl classfaq dtHow do I reset my password?/dt ddClick the Forgot Password link on the login page./dd dtWhat payment methods do you accept?/dt ddWe accept Visa, Mastercard, and PayPal./dd /dl结构要点来自 definition-list.mdx 与 dlitem.mdx 的 Best Practicesdt、dd只能作为dl的子元素存在孤立的dt/dd会失去语义关联若出于 Grid/Flexbox 布局需要给条目加容器HTML5 允许在dl内使用div包裹dt/dd对一个dt后跟多个dd是合法的同一术语的多个描述标题h3与段落p不应直接放在dl内部确保每个dt至少关联一个dd。五、导航列表nav ul li 的标准嵌套导航菜单是语义列表最典型的应用场景之一!-- ✅ Good: Navigation as list -- nav aria-labelMain navigation ul lia href/Home/a/li lia href/productsProducts/a/li lia href/aboutAbout/a/li lia href/contactContact/a/li /ul /nav注意三点nav用aria-label提供可访问名称li必须是ul/ol的直接子元素嵌套列表必须放在li内部见 list-structure.mdxul与ol的直接子元素只能是li或script/template把div直接塞进ul会破坏列表的父-子关系导致条目被漏计甚至被整体忽略。一个浏览器兼容性陷阱listitem.mdx 记录了一个值得注意的边界情况对ul应用list-style: none后部分浏览器Safari/VoiceOver会剥离列表语义。如果移除项目符号是有意为之如导航菜单应显式加上rolelist恢复语义!-- ⚠️ Note: list-style: none may remove list semantics in Safari/VoiceOver -- ul stylelist-style: none; rolelist lia href/homeHome/a/li /ul六、React 中的语义列表组件框架层最容易犯的错误是为了方便直接输出div容器。下面的组件用ordered布尔属性在ol与ul之间切换保证输出的始终是语义元素interface ListProps { items: string[] ordered?: boolean } function List({ items, ordered false }: ListProps) { const Tag ordered ? ol : ul return ( Tag {items.map((item, index) ( li key{index}{item}/li ))} /Tag ) }仓库的设计系统为这个实践提供了真实源码例证packages/design-system/src/custom/navigation/breadcrumb.tsx 中的BreadcrumbList组件渲染的是原生ol面包屑是有序路径天然应该用ol其子项BreadcrumbItem渲染原生li分隔符则用rolepresentationaria-hiddentrue从无障碍树中隐藏。这正是选择正确语义元素 用 ARIA 修饰非语义装饰的完整组合。七、CSS 样式去视觉、保语义用 CSS 去掉默认项目符号不影响语义这是既要美观、又要无障碍的标准手法/* Remove default bullets while keeping semantics */ ul.clean-list { list-style: none; padding: 0; margin: 0; } /* Custom bullets with accessibility preserved */ ul.custom-bullets li::before { content: ✓; margin-right: 0.5em; color: green; }list-style: none只影响视觉呈现ul的语义在大多数浏览器中保持不变但结合上文提到的 Safari/VoiceOver 边界情况在关键导航区域建议保留或恢复rolelist。用::before伪元素生成自定义符号则是不改 DOM、不丢语义的推荐做法。八、例外情况什么时候不该机械套用规则文档Exceptions 部分强调先评估渲染后的实际体验再决定是否把静态代码味道视为阻断问题交互时机、浏览器行为与辅助技术输出往往决定严重程度并非每个次要无障碍问题都同等重要应优先处理最直接阻碍感知、操作或理解的问题不要为了满足规则而添加冗余标记或 ARIA——如果更简单的语义实现能彻底消除问题就用它例如在 listitem.mdx 中提到的如果li纯粹是为了视觉项目符号而存在正确的修复可能是换成div或p并完全移除列表语义而不是硬凑一个ul。九、验证自动化检查与人工核验自动化检查使用浏览器无障碍工具、axe、Lighthouse 或等效工具对代表性渲染状态进行检测在浏览器无障碍树/无障碍面板Accessibility Pane中检查相关元素、角色与可访问名称配套规则 list-structure.mdx 与 listitem.mdx 建议同时运行 axe 或 Lighthouse 等自动化检查器axe 的对应规则名为definition-list-item见 dlitem.mdx。人工检查清单使用屏幕阅读器在列表中导航NVDA / JAWS / VoiceOver 均可核验列表共 X 项的播报是否存在检查播报的条目数量与可见条目数量是否一致对受规则影响的关键交互用纯键盘重测一遍代表性用户流程。仓库内的规则元数据还提供了两套可直接复用的提示词模板见 semantic-lists.mdx 的 frontmattercheck如何定位问题、fix如何修复、explain如何向开发者解释原理、codeReview代码审查时应标记的具体元素既适合人工审查也适合作为 AI 编码助手审查提示词。十、与相邻规则的配合语义列表规则不是孤立的仓库在accessibility/document-structure区域维护了一组互相关联的规则每个规则的 frontmatter 中都通过relatedRules声明了关联关系list-structure.mdxul/ol内只能有li嵌套列表必须包在li内listitem.mdxli必须位于ul/ol/menu容器内rolelistitem必须由rolelist拥有definition-list.mdxdl内只能有合法的dt/dd/div包装dlitem.mdxdt/dd必须包裹在dl内。最佳审查路径先看semantic-lists确认该不该用列表、用哪种列表再看list-structure确认列表结构是否合法最后用listitem/dlitem兜底检查孤儿条目——四者一起构成完整的列表语义审查闭环。至此从为什么 div 堆叠不够格到如何用ul/ol/dl写出屏幕阅读器可感知的列表再到 React/CSS 实现与自动化/人工双重验证这条语义化列表的完整链路已经打通。将这条规则与仓库中其余无障碍检查键盘导航、跳转链接、焦点样式、对比度、表单标签等见 accessibility-essentials.mdx配合使用即可在不做全量 WCAG 审计的情况下快速建立可靠的页面结构语义基线。赞分享【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址https://gitcode.com/gh_mirrors/fr/Front-End-Checklist点击查看免费下载相关推荐Front-End-Checklist 无障碍清单正确使用列表结构ul/ol/li——从 HTML 语义规则到源码级校验实践Front End Checklist 无障碍清单正确使用列表结构ul/ol/li——从 HTML 语义规则到源码级校验实践 本篇文章以开源仓库 Fronreact-beautiful-dnd 无障碍指南为列表拖拽构建完整的屏幕阅读器体验react beautiful dnd 无障碍指南为列表拖拽构建完整的屏幕阅读器体验 优秀的功能应当对每个人都可访问。 react beautiful dndSpinKit屏幕阅读器测试确保加载状态可感知SpinKit屏幕阅读器测试确保加载状态可感知 你是否遇到过这样的情况页面加载时进度条转个不停视力障碍用户却完全不知道系统正在忙碌根据WebAIM 20UI组件上一篇终极指南如何使用Kyverno策略测试框架确保Kubernetes规则有效性下一篇SyncTrayzor文件夹排除规则终极指南配置不需要同步的文件类型创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

相关新闻

AI陪伴机器人提醒域建模-t_reminder字段与五种提醒类型

AI陪伴机器人提醒域建模-t_reminder字段与五种提醒类型

01-提醒域建模-t_reminder字段与五种提醒类型 聊陪伴机器人,大家第一反应都是"能聊天吗"“会不会讲故事”。但真把一台机器人放进有老人的家里,最先被用起来、也最离不开的功能,往往不是聊天,而是提醒。 道理很简单&…

2026/9/20 5:15:27 阅读更多 →
DeepSeek 零代码生成 3D 游戏,Roo Code 的 Base URL 填 TaoToken

DeepSeek 零代码生成 3D 游戏,Roo Code 的 Base URL 填 TaoToken

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/9/20 5:15:27 阅读更多 →
LibreChat:面向生产落地的开源Agent对话平台

LibreChat:面向生产落地的开源Agent对话平台

1. LibreChat 是什么?一个真正能落地的开源对话平台LibreChat 不是另一个“玩具级”聊天界面,也不是套着 Web UI 外壳的 API 转发器。它是一个从第一天起就为**真实工作流、多模型协同、可扩展代理架构(Agents)和协议标准化&#…

2026/9/20 5:15:27 阅读更多 →

最新新闻

郑州seo顾问热狗hotdoger拆解3个实战案例教你搞定网站UI

郑州seo顾问热狗hotdoger拆解3个实战案例教你搞定网站UI

郑州seo顾问热狗hotdoger拆解3个实战案例教你搞定网站UI 不会写代码却想做个像样的官网?这种焦虑我懂。 很多老板或运营负责人,手里攥着预算,脑子里有画面,但对着设计师提的需求,心里直打鼓:这到底合不合理?怎么验收?怎么让网站既能留住人,又能被搜索引擎抓到?…

2026/9/21 6:44:12 阅读更多 →
2026最新wordpress调用字段避坑指南

2026最新wordpress调用字段避坑指南

2026最新wordpress调用字段避坑指南 找建站公司怕被坑高价?这是很多老板和运营新人的心头大患。很多公司报价动辄几万,说得天花乱坠,其实底层技术也就那样。2026最新的数据显示,超过60%的中小企业网站其实可以用更透明的开源方案搞定,比如WordPress。今天咱们不聊虚的,直接拆解Word…

2026/9/21 6:29:22 阅读更多 →
实战案例揭秘:wordpress删除rss的3个关键坑

实战案例揭秘:wordpress删除rss的3个关键坑

实战案例揭秘:wordpress删除rss的3个关键坑 域名解析改错,服务器配置没跟上,导致后台能改前台打不开?这种“域名服务器搞不懂”的噩梦,我在给客户做运维时见过太多次。上个月刚处理的一个 实战案例…

2026/9/21 6:15:47 阅读更多 →
3个实战案例拆解i网站建设报价,拒绝被坑

3个实战案例拆解i网站建设报价,拒绝被坑

3个实战案例拆解i网站建设报价,拒绝被坑 网站做好了没人访问?这不仅是流量焦虑,更是建站前的预算盲区。很多老板拿着“i网站建设”这个模糊的概念去询价,结果被报出从几千到几十万不等的天价,心里直打鼓。…

2026/9/21 6:03:14 阅读更多 →
网站建设的探讨与研究速查手册

网站建设的探讨与研究速查手册

网站建设探讨与研究:5大费用陷阱与选型注意事项 网站做好了没人访问,这是无数甲方老板和运营负责人深夜里最真实的焦虑。钱花出去了,服务器租了,域名买了,甚至SEO优化都上了,结果后台流量曲线平得像心电图停搏。很多人以为技术决定成败,但在我看来, 注意事项 往往比技术本身更决定生死。…

2026/9/21 5:46:06 阅读更多 →
Simulink与FlightGear联合仿真:飞行器控制算法三维可视化验证平台搭建

Simulink与FlightGear联合仿真:飞行器控制算法三维可视化验证平台搭建

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/9/21 5:38:52 阅读更多 →

日新闻

agents-generator 决策矩阵全解析:从项目检测到 AGENTS.md 规则生成的 16 步判定流程

agents-generator 决策矩阵全解析:从项目检测到 AGENTS.md 规则生成的 16 步判定流程

agents-generator 决策矩阵全解析:从项目检测到 AGENTS.md 规则生成的 16 步判定流程 【免费下载链接】agentic-awesome-skills AAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and …

2026/9/21 0:00:01 阅读更多 →
gin-vue-admin 前端工具函数全景指南:src/utils 复用规范与源码级解析

gin-vue-admin 前端工具函数全景指南:src/utils 复用规范与源码级解析

gin-vue-admin 前端工具函数全景指南:src/utils 复用规范与源码级解析 【免费下载链接】gin-vue-admin 🚀ViteVue3Gin拥有AI辅助的基础开发平台,企业级业务AI开发解决方案,内置mcp辅助服务,内置skills管理,…

2026/9/21 0:00:01 阅读更多 →
Wox 全功能插件开发实战指南:基于 Python / Node.js 宿主与 WebSocket 的持久化插件体系

Wox 全功能插件开发实战指南:基于 Python / Node.js 宿主与 WebSocket 的持久化插件体系

桌面应用AI 应用插件系统 【免费下载链接】Wox A cross-platform launcher that simply works 项目地址: https://gitcode.com/gh_mirrors/wo/Wox 点击查看 免费下载 全功能插件(Full-featured Plugin)是 Wox 三类插件实现方式中能力最完整的…

2026/9/21 0:00:01 阅读更多 →

周新闻

Flutter for OpenHarmony游戏卡片渐变背景实战:从原理到性能优化

Flutter for OpenHarmony游戏卡片渐变背景实战:从原理到性能优化

直接铺开项目本身吧。这几个月我一直在折腾一件事:用Flutter给OpenHarmony做一款游戏集合类的App,说白了就是把若干小游戏塞进一个壳里,用统一入口分发。这个方向本身不算新鲜,真正让我花了不少心思的,是首页那堆游戏卡…

2026/9/21 3:13:20 阅读更多 →
Word表格编号全攻略:从列表编号到题注交叉引用

Word表格编号全攻略:从列表编号到题注交叉引用

写Word文档,最让人头疼的往往是那些“看起来不起眼”的小问题。比如表格编号这事:今天在表后面多加了两个空白行,明天给客户交稿前发现整个章节的编号全部错位,光是挨个改序号就能耗掉大半个下午。我前阵子帮人整理一份上百页的技…

2026/9/21 2:19:36 阅读更多 →
从第一个站到第二个站:独立开发者的静态网站选型与落地实践

从第一个站到第二个站:独立开发者的静态网站选型与落地实践

1. 项目概述1.1 核心需求解析做独立开发者这几年,说实话,第一个网站上线的那天晚上我兴奋得没睡着。但等它跑了半年,流量惨淡、功能臃肿、代码自己都懒得看第二遍之后,我才慢慢琢磨明白一个道理:第一个网站是练手&…

2026/9/21 4:51:05 阅读更多 →

月新闻

持续集成 流水线自动化与 声明式交付 实践:原型怎样变成可用功能

持续集成 流水线自动化与 声明式交付 实践:原型怎样变成可用功能

持续集成 流水线自动化与 声明式交付 实践:原型怎样变成可用功能分类:[AI/大模型]细分主题:AI 增强型 CI/CD 流水线自动化与 GitOps 实践:Agent 工作流、工具调用与任务拆解:从原型到生产的验收清单很多团队在尝试用大…

2026/9/19 23:01:36 阅读更多 →
容器编排 生产环境运维与排障实战:复盘记录怎样真正派上用场

容器编排 生产环境运维与排障实战:复盘记录怎样真正派上用场

容器编排 生产环境运维与排障实战:复盘记录怎样真正派上用场分类:[工程技术]细分主题:Kubernetes 生产环境运维与排障实战:可复制的项目复盘模板与决策记录大部分团队的事故复盘报告,最后都变成了躺在 Confluence 或钉…

2026/9/19 17:50:38 阅读更多 →
容器 容器化技术与镜像安全管理:核心链路应该先拆哪一步

容器 容器化技术与镜像安全管理:核心链路应该先拆哪一步

容器 容器化技术与镜像安全管理:核心链路应该先拆哪一步分类:[工程技术]细分主题:Docker 容器化技术与镜像安全管理:核心链路的逐步实现与关键代码取舍面对一个积累了五六年历史包袱的单体架构应用(包含 Web 接口、后台…

2026/9/19 23:35:34 阅读更多 →