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