theme-shopify-html-data-comments

Shopify HTML、数据属性与注释

Shopify 主题中 HTML 结构、数据属性用法和代码注释的指南。

适用场景

• 在分区中组织 HTML 标记
• 通过属性向 JavaScript 传递数据
• 为 Liquid 模板添加注释
• 组织 HTML 元素

HTML 与数据属性

自定义 HTML 标签

• 适当时使用自定义 HTML 标签
• 自定义元素适用于 JavaScript 自定义元素
• 改善语义结构

示例

<product-card data-product-id="{{ product.id }}">
  
</product-card>

数据属性

• 通过 data-* 属性传递动态数据
• 在 JavaScript 中通过 dataset 属性访问
• 属性名称使用 kebab-case

数据属性命名

<div 
  data-product-id="{{ product.id }}"
  data-variant-id="{{ variant.id }}"
  data-product-handle="{{ product.handle }}">
</div>


<div data-productId="{{ product.id }}"></div>

在 JavaScript 中访问数据

class ProductCard extends HTMLElement {
  constructor() {
    super();
    this.productId = this.dataset.productId;
    this.variantId = this.dataset.variantId;
    this.productHandle = this.dataset.productHandle;
  }
}

用于配置的数据属性

使用数据属性将配置从 Liquid 传递给 JavaScript：

<image-gallery 
  data-autoplay="{{ section.settings.autoplay }}"
  data-interval="{{ section.settings.interval }}"
  data-transition="{{ section.settings.transition }}">
  
</image-gallery>

class ImageGallery extends HTMLElement {
  constructor() {
    super();
    this.autoplay = this.dataset.autoplay === 'true';
    this.interval = parseInt(this.dataset.interval, 10);
    this.transition = this.dataset.transition;
  }
}

注释

注释指南

• 注释应尽量精简
• 仅为不明显的逻辑添加注释
• 不要解释每一行代码
• 注释应说明“为什么”，而不是“是什么”

Liquid 注释

{%- comment -%}
  Calculate discount percentage for products with compare_at_price.
  Only show discount badge if discount is greater than 20%.
{%- endcomment -%}

{% liquid
  if product.compare_at_price > product.price
    assign discount = product.compare_at_price | minus: product.price
    assign discount_percent = discount | times: 100 | divided_by: product.compare_at_price
    if discount_percent > 20
      assign show_badge = true
    endif
  endif
%}

片段用法注释

始终在片段中包含用法注释：

{%- comment -%}
Usage:
{% render 'product-card', 
  product: product, 
  show_vendor: true, 
  show_price: true %}
{%- endcomment -%}

HTML 注释

仅在需要组织分区时少量使用 HTML 注释：

{%- comment -%}
  Product Card Section
  Displays product information with image, title, price, and add to cart button
{%- endcomment -%}

<div class="product-card">
  
  <div class="product-card__image">
    {{ product.featured_image | image_tag: widths: '360, 720', loading: 'lazy' }}
  </div>

  
  <div class="product-card__info">
    <h3 class="product-card__title">{{ product.title }}</h3>
    <p class="product-card__price">{{ product.price | money }}</p>
  </div>
</div>

何时添加注释

应添加注释：

• 复杂的业务逻辑
• 不明显的计算
• 变通方案或临时技巧
• 片段用法说明
• 分区级文档说明

不应添加注释：

• 明显的代码（例如，{% if product.available %})
• 每一行代码
• 含义不言自明的变量名
• 标准 Liquid 语法

示例：好的注释与不好的注释

{%- comment -%}
  Good: Explains why, not what
  Calculate discount percentage. Shopify doesn't provide this directly,
  so we calculate it from compare_at_price and current price.
{%- endcomment -%}
{% liquid
  assign discount = product.compare_at_price | minus: product.price
  assign discount_percent = discount | times: 100 | divided_by: product.compare_at_price
%}

{%- comment -%}
  Bad: Explains what, which is obvious
  Check if product is available. If available, show add to cart button.
{%- endcomment -%}
{% if product.available %}
  <button>Add to Cart</button>
{% endif %}

HTML 结构最佳实践

语义化 HTML

使用语义化 HTML 元素：

<article class="product-card">
  <header class="product-card__header">
    <h2 class="product-card__title">{{ product.title }}</h2>
  </header>
  <div class="product-card__image">
    {{ product.featured_image | image_tag: widths: '360, 720', loading: 'lazy' }}
  </div>
  <footer class="product-card__footer">
    <p class="product-card__price">{{ product.price | money }}</p>
    <button class="product-card__button">Add to Cart</button>
  </footer>
</article>

无障碍性

添加适当的无障碍属性：

<button 
  aria-label="Add {{ product.title }} to cart"
  data-product-id="{{ product.id }}">
  Add to Cart
</button>

Shopify 主题文档

请参阅以下 Shopify 官方资源：

• HTML 元素
• 数据属性
• Web 无障碍
• Shopify 主题结构

说明

1. 适当时使用自定义 HTML 标签，以实现语义化结构
2. 通过 data-* 属性传递数据，并使用 kebab-case
3. 注释应尽量精简——仅用于说明不明显的逻辑
4. 注释应说明“为什么”，而不是“是什么”——解释原因，而不是显而易见的代码
5. 在所有片段中添加用法注释
6. 使用语义化 HTML，改善结构和无障碍性
7. 添加无障碍属性（aria-label、alt 文本等）