最稳妥方式是用标准<table>结构，每行一个字段，三列分别为字段名、类型、说明，表头用<th>，配<caption>语义化标题，禁用<br>和colspan，data-*属性仅作前端辅助。
HTML里怎么给导出数据字典加字段说明
直接用 <table> + <thead> + <tbody> 最稳妥，别想用 <dl> 或 <figure> 伪装成文档表格——解析工具（比如 Excel 导入、Python pandas.read_html()）基本只认标准表格结构。
常见错误是把字段名和说明写在 <div> 里用换行或空格分隔，结果导出 CSV 或被爬虫抓取时全串成一团，字段A 字段说明A 字段B 字段说明B 这种根本没法用。
- 每列对应一个字段：第一列固定为
字段名，第二列为类型（如string、int、datetime），第三列为说明 - 表头必须用
<th>，不能用<td>，否则语义丢失，部分自动化工具会跳过识别 - 如果字段有约束（如“非空”“唯一”“默认值”），统一放在
说明列里，用中文短句，别塞 Markdown 或 HTML 标签
导出时字段名和说明对不齐？检查 colspan 和换行符
有人用 <br> 在一个 <td> 里强行换行写“字段名
说明”，这会导致 Excel 打开时所有内容挤在一格，且 pandas.read_html() 默认按行拆分，直接错位。
正确做法是让每一行对应一个字段的完整信息，而不是一个字段占多行。如果字段说明太长要换行显示，用 CSS 控制 white-space: normal，HTML 结构仍保持单行单字段。
立即学习“前端免费学习笔记（深入）”；
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 禁用
<br>、<p>、<div>嵌套在表格单元格内 - 避免用
colspan="2"合并字段名和说明——这会让解析器误判列数，尤其当某些字段没说明时，列对齐立刻崩坏 - 导出前用浏览器开发者工具选中表格，右键“复制为 HTML”，粘贴到文本编辑器里看是否每行都有且仅有 3 个
<td>（或对应列数）
data-* 属性能用来存字段含义吗
不能当主要方案。虽然你可以给每个输入框加 data-dict-desc="用户手机号，11位数字"，但这种信息只存在于 DOM，不会随 HTML 表格一起导出为 CSV/Excel，也不进搜索引擎索引，更不会被下游系统读取。
它适合做前端 hover 提示或调试用，但数据字典的核心要求是「可提取、可交换、可验证」，这些都依赖显式、扁平、结构化的表格内容。
-
data-*只能辅助，不能替代<table>中的文本内容 - 如果后端渲染时动态插入
data-dict-type等属性，记得同步更新对应<td>的文本，否则人眼看到的和机器读到的不一致 - 某些老旧 Excel 导出插件（如 table2excel）会忽略
data-属性，纯靠 innerText 解析，此时属性再全也没用
为什么用 <caption> 而不是 <h3> 标题
因为 <caption> 是表格的语义化标题，会被屏幕阅读器朗读，也会被 pandas.read_html() 自动识别为该表的 name 属性（df.name），而普通 <h3> 就只是页面上的一个标题，和表格无绑定关系。
例如导出多个字典表时，没有 <caption> 就只能靠上下文猜哪段表格对应哪个模块，容易张冠李戴。
- 每个
<table>必须配一个<caption>，内容如用户主表字段说明，不要写“数据字典”这种泛称 - 避免在
<caption>里塞格式化字符（如【用户表】、<em>必填</em>），纯文本最安全 - 如果页面有多个字典表，
<caption>是唯一能稳定区分它们的 HTML 机制，比靠 class 名或附近文字靠谱得多
字段说明里的「可空」「默认值」「枚举范围」这些细节，看着琐碎，但少写一条，下游开发联调时就得多问三次。别指望靠注释或口头约定，HTML 表格就是契约本身。
