产品卡片：源码控制的电商内容块

产品卡片将产品提及转化为一个完整、可操作的商业单元：产品图片、官方名称、当前价格以及行动号召（CTA），即推动购买旅程的链接或按钮。其最重要的规则对读者不可见：作者通过库存量单位（SKU，即可售产品或变体的商品目录标识符）放置卡片，而产品来源提供各项值。

该示例展示的是关系而非撰写的报价。在生产环境中，SKU之后的每个可见值均来自经批准的产品来源。目录更新将更改引用该SKU的所有卡片，无需作者查找并编辑旧文章。

为何此元素重要

评估产品的读者需要快速回答四个问题：它是什么？它长什么样？它的价格是多少？我接下来可以做什么？ 埋藏在正文中的产品名称迫使读者在页面中重新拼凑这些答案。而一个有边界的卡片减少了这种努力，同时将商业干扰控制在与推荐相称的范围内。

卡片还通过一致性建立信任。当一篇文章写着"USD 149"而产品页面显示"USD 169"时，这种不一致不仅仅是一个小的编辑缺陷——它会让读者质疑推荐、促销和结算流程。来源控制的卡片防止文章成为独立的价格数据库。它还能随着商品目录的变化反映库存状态、变体标识和目的地变化。

机器可提取性意味着爬虫、购物代理、信息流或内容迁移工具能够保留哪张图片、哪个名称、什么价格、什么库存状态以及哪个操作属于哪个产品。仅靠邻近关系是不够的。如果三张图片位于三个价格之上，视觉上对齐排列，机器仍可能将它们错误关联。一个卡片应暴露一个以SKU为键的单一产品实体，其事实放在一个语义容器内，其目的地明确链接。

该元素不仅仅是样式化的联盟链接。元素编写规则 具有优先权：根据用途选择组件。当一个块呈现一个可购买的产品，包含身份、价格和操作时，应使用产品卡片——即使设计师可以用图片、标题和按钮来模仿它。类型化组件提供来源绑定、验证、无障碍行为和结构化数据挂钩，这些是松散标记无法保证的。

何时使用

当读者拥有足够的上下文来评估特定产品，且直接的产品操作有用时，使用产品卡片。常见情况包括：购买指南中的推荐商品、分类介绍中的产品、产品页面上的配件，或在对比标准解释后的每个入围选项。

产品必须可以在经批准来源中通过一个有效SKU标识。如果名称指的是一个包含多个独立定价变体的产品系列，请将文章推荐解析为特定变体，或使用产品系列处理方式，其CTA要求读者选择变体。不要悄无声息地显示最便宜的变体，仿佛它是所有配置的价格。

常见误用

一旦明确了用途，常见的误用就很容易识别：

• 仅作为示例提及产品名称的句子不需要卡片，除非在该时刻价格和操作对读者有帮助。
• 包含不同计费条款的方案集需要使用价格表格，而不是一排产品卡片。
• 排名列表仍然需要围绕每个项目的编辑推理。卡片不能替代选择标准、证据、权衡取舍或每种产品适合谁的解释。
• 包含资格条件、有效期和优惠券条件的促销活动需要专门的优惠处理方式。卡片可以显示来源控制的当前价格，但不能包含微型条款页面。
• 规格对比属于对比表或规格表。在每个对比单元格中重复完整卡片会产生视觉噪音并削弱关系。
• 没有SKU和商品目录记录的服务，仅仅因为有价格和按钮，就不是产品卡片。

不要仅仅为了将一个信息性提及变现而添加卡片。如果读者尚未遇到说明该产品为何适用的需求、标准或推荐，卡片会显得突兀，机器收到的也将是一个缺少有用上下文的实体。

放置位置

定位的目的是将产品与选择它的推理联系起来。将卡片紧跟在标识产品并解释其适用性的段落、子标题或结论之后。读者应先遇到理由，再看到操作——而不是先看到销售控件，再看到证据。

当一个版块同时包含产品和非产品解决方案时，产品应放在家庭疗法、DIY方法和其他替代方案之前。这种顺序将商业项目保持在一个可预测的组内，为它们的商品目录数据提供清晰边界，并防止家庭方法看起来像另一个SKU。先介绍标准，展示相关产品卡片，然后打开一个明确标记的替代方案版块。

精确的放置规则：

不要在页面的直接答案之前放置卡片，也不要在段落内、主张与其证据之间或编号指令内部放置卡片。不要将其放在冲突的价格、指向同一目的地的第二个CTA、倒计时器、似乎未经证据即认可该特定SKU的推荐语或家庭疗法框旁边。避免相邻出现同一SKU的重复卡片；将后续引用链接回规范放置位置。

结构

该结构包含四个必需的可见区域和一个来源键：

1. 产品图片： 所引用SKU的主要商品目录图片，附带来源管理的替代文本，标识产品和相关可见变体。
2. 产品名称： 面向客户的官方名称，链接或配对的规范产品目标页面。
3. 价格： 当前金额及ISO币种代码，或真实的来源状态（如"价格不可用"）。促销价保持其与原价的关系。
4. CTA： 具体操作，如"查看North Ridge靴"或"将North Ridge靴加入购物车"，从该产品和渠道允许的操作中选择。
5. SKU： 稳定的查找键。在视觉上可以淡化或对购物者隐藏，但必须存在于组件数据和诊断信息中。

库存状态可根据条件展示，但必须在源数据中存在。当库存状态改变CTA的功能时，显示"缺货"、“预售"或其他有意义的状态。徽章、评分、配送说明和变体为可选扩展项；任何扩展都不得挤占四个必需区域，也不得作为无法验证的主张由作者编写。

设计示例

每个变体使用相同的来源合约。变体改变布局和重点，但从不改变产品事实的所有权。

标准垂直卡片： 一到四个产品的默认布局。在文章列中表现良好，在窄屏上可预测地堆叠。

紧凑水平卡片： 用于长列表，其中图片识别重要但垂直空间有限。CTA在阅读顺序中紧随价格之后，即使CSS将其放在边缘。

特色推荐： 在编辑推理已确定清晰适用性时使用一次。“最适合湿滑小径"是来源控制的产品名称之外的作者上下文；“最佳整体"需要明确的标准和证据。

不可用状态： 当暂时不可用对读者有用时保留产品身份，但将购买操作替换为来源批准的下一步。已停产的产品通常应在编辑上替换，而非作为空卡片推广。

参数

界面上刻意给予作者的控制很少。限制作者输入可防止文案覆盖商品目录数据。下表"来源"列标识渲染器从何处获取每个值。

正文为空，除非有一个可选的第一个标题用作编辑上下文，如"最适合湿滑小径”。正文绝不能包含第二个名称、手动编写的价格、替换图片URL、库存声明或目标页面。如果来源记录不完整，请修复来源或阻止发布。

产品卡片语法与代码示例

所有三种格式承载相同的作者指令：将此SKU标识的产品放置在此处。它们不会将产品的当前值序列化到文章中。

可移植Markdown指令

:::product-card{sku="TRAIL-BOOT-042" placement=featured}
### 最适合湿滑小径
:::

Hugo短代码

{{< product-card sku="TRAIL-BOOT-042" placement="featured" >}}
最适合湿滑小径
{{< /product-card >}}

Hugo符号记录了目标适配器的合约。它必须通过站点批准的产品数据层解析SKU，而不是接受产品值作为短代码参数。

WordPress

[product_card sku="TRAIL-BOOT-042" placement="featured"]
最适合湿滑小径
[/product_card]

WordPress实现应使用由同一产品来源支持的动态服务端渲染块或注册短代码。将产品名称和价格的静态副本保存到文章内容中会破坏该合约。

好与坏的示例

好示例：放置承载推荐；来源承载报价

对于陡峭的湿滑路线，应优先考虑防水膜、专为泥地设计的外底以及稳固的跟部包裹性。North Ridge型号满足这些明确的标准，虽然不是最轻的选择。

:::product-card{sku="TRAIL-BOOT-042" placement=featured}

这是有效的，因为正文在产品操作之前解释了适用性和权衡。指令标识了一个SKU，因此渲染器可以将当前图片、官方名称、市场价格、库存状态和URL作为一个产品实体整体检索。

坏示例：商业值被复制到文章中

最佳防水靴——North Ridge，仅$129！
图片：/uploads/north-ridge-final-v2.jpg
立即购买

这是失败的，因为价格、图片、名称处理和URL是手动编写的。金额可能已过时或使用了错误的市场；“仅"添加了未经支持的价值判断；片段URL无法到达产品；图片与目录元数据断开连接。没有SKU、库存状态、币种代码或机器稳定的分组。解决方式不是完善这个文本书写的卡片，而是用来源绑定的指令替换它，并将编辑适用性解释保留在外部。

结构化数据标记与无障碍

当页面、产品和可见事实符合网站的结构化数据政策时，已解析的卡片可以提供Product和Offer结构化数据。SKU可以映射到sku；官方名称和图片可以映射到name和image；真实的报价可以提供price、priceCurrency、availability和url。服务器必须从同一已解析记录生成可见内容和结构化输出，以确保它们不会不一致。

不要使用猜测的价格发出Offer，不要对不可用的金额使用零，也不要仅仅因为CTA写着"查看产品"就将商品标记为有库存。如果多个卡片描述同一SKU，结构化数据不应创建矛盾的重复实体。通过一个稳定的产品标识连接或去重。

无障碍始于文档关系。将每个卡片包裹在article或等效的标签组中，使产品名称成为逻辑标题，并将CTA的可访问名称与该产品关联。“查看产品"重复六次在链接列表中会造成歧义；“查看North Ridge防水登山靴"在没有视觉上下文的情况下仍然有用。

替代文本应描述产品和有意义的可见变体，不要重复价格或写"图片”。装饰性次要图片使用空的替代文本。不要仅通过颜色、删除线、徽章形状或图标传达库存状态、促销状态或推荐信息。键盘焦点必须遵循阅读顺序，整个卡片在包含独立按钮或变体控件时不得成为一个巨大的链接。

编写规则

卡片保持简洁，因为它的职责是身份和操作，而非说服。每条规则保护来源完整性或读者理解：

• 一个SKU防止身份混淆。 每个卡片解析恰好一个SKU。不要将一个变体的图片与另一个变体的价格组合。
• 来源所有权防止过时的商业声明。 作者提供放置位置，以及可选的2-6个词的上下文标签。他们从不在卡片中输入名称、图片路径、价格、币种、库存状态、URL或CTA。
• 编辑上下文解释适用性。 特色标签可以说明有据可查的用例，如"最适合小厨房”。限制在50个字符内，并在附近的正文中提供支持。
• 当前价格需要完整上下文。 渲染器显示ISO币种代码，并从产品来源处理原价与促销价。除非有单独的经过验证的主张支持，否则不要添加"便宜”、“仅"或节省金额的措辞。
• 一个操作减少歧义。 使用一个映射到库存状态的主要CTA。不要在规范卡片内添加新闻通讯订阅、优惠券输入、分享控件或竞争零售商链接。
• 紧凑边界便于提取。 可见卡片包含一张图片、一个官方名称、一个价格状态、一个在必要时显示的库存状态和一个CTA。长描述、测试结果、优缺点及法律条款保留在相邻元素中。
• 产品优先于非产品。 当家庭疗法或其他非产品替代方案共享一个版块时，先显示相关产品卡片，然后开始一个单独的替代方案子版块。

语气应客观冷静。周围的正文可以推荐、比较或提醒，但来源控制的字段保持中立。绝不要将推荐语、未经支持的夸张用语、倒计时、隐藏的联盟披露、处方、用药说明、保修解释或退货政策摘要放在卡片内部。这些声明需要自己的证据、所有权和更新行为。

使用该元素的文章类型

postTypes前置元数据数组是规范的关系记录。下表说明了卡片在每个列出的规格中的角色。

QA检查清单

• 该块的用途是否与优先级规则下的产品卡片匹配？
• 指令是否包含一个有效SKU且没有作者撰写的产品值？
• 解析的SKU是否标识了预期市场和精确变体？
• 图片、名称、价格、币种、库存状态、URL和CTA是否来自经批准来源？
• 可见价格在渲染时是否与目标页面及任何结构化数据匹配？
• 促销状态是否包含有效的原价关系和来源控制的活跃周期？
• 不可用产品是否如实标记并带有适当的非购买操作？
• 附近的正文是否在卡片要求操作之前解释了产品为何合适？
• 产品是否放在家庭疗法、DIY方法和非产品替代方案之前？
• 卡片是否与冲突的价格、倒计时器、推荐语和重复CTA分离？
• 产品名称是否创建了清晰的标题或可访问的卡片标签？
• CTA的可访问名称在链接脱离上下文阅读时是否能标识其产品？
• 替代文本是否描述了有意义的产品和变体，且不与附近的文案重复？
• 推荐、价格、库存状态和促销状态是否用文本表达，而非仅靠颜色？
• 键盘顺序是否在逻辑上遵循图片、名称、价格、库存状态和操作？
• 结构化数据是否仅对有资格且已解析的产品发出，没有猜测或矛盾的值？
• 缺失或已停产的SKU是否根据商品目录政策安全失败，而非渲染空白或虚构的卡片？
• 页面是否避免了同一SKU的重复卡片，并将编辑声明保留在来源控制字段之外？

只有当读者和机器能够识别同一产品、当前商业状态和下一步操作时，产品卡片才算准备就绪。如果作者必须在文章正文中维护其中任何一项事实，来源合约已被破坏。