微格式不是简单添加class，而是复用HTML语义标签并按约定命名class；必须将h-card等类名嵌套在、等语义元素内，配合p-name、dt-published等子类使用，否则机器无法解析。
微格式不是加 class，而是复用已有语义标签
很多人把 class="h-card" 往 <div> 上一塞就以为用了微格式，结果只是给机器扔了个无法解析的字符串。微格式（如 <code>h-card、h-entry、h-event）本质是**在标准 HTML 语义结构上叠加约定好的 class 命名规则**，它不创造新标签，也不改变 DOM 结构——它依赖你 already 用对了 <article></article>、<time></time>、<address></address> 这些原生语义元素。
常见错误现象：
- 给一个
<div class="h-card"> 包着姓名、邮箱、电话，但没用 <code><address></address>或<time></time>，搜索引擎无法提取联系时间或地理上下文 - 在
<section></section>里硬套class="h-entry"，但里面没有<h1></h1>或<time></time>，导致解析器跳过整块 - 用
<span class="p-name"></span>标记人名，却放在<nav></nav>里——nav的语义和「人物信息」冲突，微格式解析器会忽略 -
h-card必须包裹在<article></article>或<section></section>内，且至少含<p class="p-name"></p>和<a class="u-url" href="https://www.php.cn/link/263b1243ca2dbeb358777ceabc4a2e4c"></a> -
h-entry要求有明确标题（<h2 class="p-name"></h2>或<h3></h3>）、发布时间（<time class="dt-published"></time>）、正文（<div class="e-content">） <li>所有微格式 class 都必须配合语义标签使用：<code>u-url只能出现在<a></a>或<link>上；p-photo必须是<img alt="HTML结构如何结合微格式提升语义深度？高级代码质量维护解析" >或<svg></svg>的 class - 博客、新闻页、作者页等结构清晰、模板固定的页面 → 优先用微格式，轻量、兼容性好、校验工具多（如 Schema Markup Validator 也支持 h-*）
- 电商商品页需暴露价格、库存、SKU 等多维属性 → microdata 或 JSON-LD 更稳妥，
itemprop="price"比data-price更易被 Google Shopping 抓取 - 政府/学术机构发布带本体关系的数据集 → RDFa 可能必要，但日常前端开发几乎不用
- 在一个元素上同时写
class="h-card"和itemscope itemtype="https://schema.org/Person"→ 解析器可能冲突或忽略其中一种 - microdata 中
itemprop值直接写文字（如<span itemprop="name">张三</span>），但未包裹在itemscope容器内 → 数据丢失 - 用 RDFa 的
property属性时漏写typeof，导致结构化数据不可识别 - 用浏览器 DevTools 的「Elements」面板，右键目标元素 →「Reveal in Elements panel」→ 查看其完整祖先链：是否从
<article></article>开始？是否有<time></time>同级或子级？ - 运行
npx html-validate --config ./html-validate.json（配html-validate-plugin-microformats插件），它会检查h-card是否缺p-name、h-entry是否缺dt-published - 在 Chrome 中安装插件 «Microdata Inspector»，悬停元素即可看到实时解析出的字段名和值 —— 如果显示
name: null，说明p-name所在节点没被正确识别为文本内容容器 - CSS 用独立 class 控制样式，比如
class="author-name"，而非依赖p-name - JS 查询结构化数据时，用
document.querySelector('article .p-name')，但不要用document.querySelector('.p-name')—— 后者可能命中评论区里的昵称 - 服务端渲染时，确保
p-name总是出现在h-card的第一层子元素中，避免因 CMS 模板插入额外 wrapper 导致解析失败 - 团队协作时，在组件文档里明确标注：“该卡片组件输出符合 h-card 规范，要求传入
name、url、photo字段，且photo必须渲染为<img class="u-photo" alt="HTML结构如何结合微格式提升语义深度？高级代码质量维护解析" >”
实操建议：
microdata 和 RDFa 与微格式不是替代关系
别在项目里混用三种方案。微格式（class-based）和 microdata（itemscope/itemprop）本质是不同解析路径：前者靠 class 名匹配预定义模式，后者靠属性声明类型。RDFa 更重，适合复杂数据建模，但浏览器支持弱、维护成本高。
立即学习“前端免费学习笔记（深入）”；
使用场景：
容易踩的坑：
验证不是“有没有 class”，而是“能否被提取”
写完微格式，不能只靠肉眼检查 class 名是否拼对。真实检验标准是：机器能否从中稳定抽取出结构化字段。Google Rich Results Test 工具常报“未检测到结构化数据”，往往不是 class 错，而是父级语义缺失或嵌套错位。
实操建议：
可维护性陷阱：微格式 class 不是样式锚点
把 class="p-name" 当成 CSS 选择器来写样式，等于把语义逻辑和表现层耦合死。一旦设计改版要换字体大小或颜色，你得同步改 JS 查询逻辑、CSS、甚至微格式校验规则。
正确做法：
最常被忽略的一点：微格式的生命力不在 class 名本身，而在它所依附的语义骨架是否稳固。如果 <article></article> 被误用为广告位，那再标准的 h-entry 也会被搜索引擎降权处理——结构错了，修饰再准也没用。
