Back to Details

shopify-html-data-comments

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Shopify HTML, Data Attributes & Comments

Shopify HTML、数据属性与注释

Guidelines for HTML structure, data attributes usage, and code commenting in Shopify themes.
Shopify主题中HTML结构、数据属性使用及代码注释的规范指南。

When to Use

适用场景

  • Structuring HTML markup in sections
  • Passing data to JavaScript via attributes
  • Adding comments to Liquid templates
  • Organizing HTML elements
  • 构建区块中的HTML标记
  • 通过属性向JavaScript传递数据
  • 为Liquid模板添加注释
  • 组织HTML元素

HTML & Data Attributes

HTML与数据属性

Custom HTML Tags

自定义HTML标签

  • Use custom HTML tags when appropriate
  • Custom elements work well with JavaScript custom elements
  • Improves semantic structure
  • 酌情使用自定义HTML标签
  • 自定义元素可与JavaScript自定义元素良好配合
  • 提升语义化结构

Example

示例

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

Data Attributes

数据属性

  • Pass dynamic data via 
    data-*
    attributes
  • Access in JavaScript via 
    dataset
    property
  • Use kebab-case for attribute names
  • 通过
    data-*
    属性传递动态数据
  • 在JavaScript中通过
    dataset
    属性访问
  • 属性名称使用短横线分隔命名（kebab-case）

Data Attribute Naming

数据属性命名规范

liquid
<!-- Good - kebab-case -->
<div 
  data-product-id="{{ product.id }}"
  data-variant-id="{{ variant.id }}"
  data-product-handle="{{ product.handle }}">
</div>

<!-- Bad - camelCase or other formats -->
<div data-productId="{{ product.id }}"></div>
liquid
<!-- 推荐 - 短横线分隔命名 -->
<div 
  data-product-id="{{ product.id }}"
  data-variant-id="{{ variant.id }}"
  data-product-handle="{{ product.handle }}">
</div>

<!-- 不推荐 - 驼峰式或其他格式 -->
<div data-productId="{{ product.id }}"></div>

Accessing Data in JavaScript

在JavaScript中访问数据

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

Data Attributes for Configuration

用于配置的 data 属性

Use data attributes to pass configuration from Liquid to JavaScript:
liquid
<image-gallery 
  data-autoplay="{{ section.settings.autoplay }}"
  data-interval="{{ section.settings.interval }}"
  data-transition="{{ section.settings.transition }}">
  <!-- Gallery content -->
</image-gallery>
javascript
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传递到JavaScript：
liquid
<image-gallery 
  data-autoplay="{{ section.settings.autoplay }}"
  data-interval="{{ section.settings.interval }}"
  data-transition="{{ section.settings.transition }}">
  <!-- Gallery content -->
</image-gallery>
javascript
class ImageGallery extends HTMLElement {
  constructor() {
    super();
    this.autoplay = this.dataset.autoplay === 'true';
    this.interval = parseInt(this.dataset.interval, 10);
    this.transition = this.dataset.transition;
  }
}

Comments

注释规范

Comment Guidelines

注释准则

  • Keep comments minimal
  • Comment only non-obvious logic
  • Do NOT explain every line
  • Use comments to explain "why", not "what"
  • 注释应精简
  • 仅对非直观逻辑添加注释
  • 无需为每一行代码添加注释
  • 注释用于解释“原因”，而非“内容”

Liquid Comments

Liquid注释

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
%}
liquid
{%- comment -%}
  为带有对比价的商品计算折扣百分比。
  仅当折扣大于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
%}

Snippet Usage Comments

代码片段使用注释

Always include usage comments in snippets:
liquid
{%- comment -%}
Usage:
{% render 'product-card', 
  product: product, 
  show_vendor: true, 
  show_price: true %}
{%- endcomment -%}
务必在代码片段中添加使用说明注释：
liquid
{%- comment -%}
使用方式：
{% render 'product-card', 
  product: product, 
  show_vendor: true, 
  show_price: true %}
{%- endcomment -%}

HTML Comments

HTML注释

Use HTML comments sparingly for section organization:
liquid
{%- comment -%}
  Product Card Section
  Displays product information with image, title, price, and add to cart button
{%- endcomment -%}

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

  <!-- Product Info -->
  <div class="product-card__info">
    <h3 class="product-card__title">{{ product.title }}</h3>
    <p class="product-card__price">{{ product.price | money }}</p>
  </div>
</div>
可少量使用HTML注释进行区块组织：
liquid
{%- comment -%}
  商品卡片区块
  展示包含图片、标题、价格及加入购物车按钮的商品信息
{%- 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>

When to Comment

注释时机

Do comment:
  • Complex business logic
  • Non-obvious calculations
  • Workarounds or hacks
  • Snippet usage instructions
  • Section-level documentation
Don't comment:
  • Obvious code (e.g., 
    {% if product.available %}
    )
  • Every line of code
  • Self-explanatory variable names
  • Standard Liquid syntax
建议添加注释的场景：
  • 复杂业务逻辑
  • 非直观计算
  • 临时解决方案或特殊处理
  • 代码片段使用说明
  • 区块级文档说明
无需添加注释的场景：
  • 直观代码（如
    {% if product.available %}
    ）
  • 每一行代码
  • 自解释性变量名
  • 标准Liquid语法

Example: Good vs Bad Comments

示例：优质注释 vs 劣质注释

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 %}
liquid
{%- comment -%}
  优质：解释原因而非内容
  计算折扣百分比。Shopify未直接提供该功能，
  因此我们通过对比价和当前价格进行计算。
{%- endcomment -%}
{% liquid
  assign discount = product.compare_at_price | minus: product.price
  assign discount_percent = discount | times: 100 | divided_by: product.compare_at_price
%}

{%- comment -%}
  劣质：解释内容，属于显而易见的信息
  检查商品是否可售。如果可售，显示加入购物车按钮。
{%- endcomment -%}
{% if product.available %}
  <button>Add to Cart</button>
{% endif %}

HTML Structure Best Practices

HTML结构最佳实践

Semantic HTML

语义化HTML

Use semantic HTML elements:
liquid
<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>
使用语义化HTML元素：
liquid
<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>

Accessibility

可访问性

Include proper accessibility attributes:
liquid
<button 
  aria-label="Add {{ product.title }} to cart"
  data-product-id="{{ product.id }}">
  Add to Cart
</button>
添加合适的可访问性属性：
liquid
<button 
  aria-label="Add {{ product.title }} to cart"
  data-product-id="{{ product.id }}">
  Add to Cart
</button>

Shopify Theme Documentation

Shopify主题文档参考

Reference these official Shopify resources:
可参考以下Shopify官方资源：

Instructions

操作指引

  1. Use custom HTML tags when appropriate for semantic structure
  2. Pass data via 
    data-*
    attributes     using kebab-case
  3. Keep comments minimal - only for non-obvious logic
  4. Comment "why", not "what" - explain reasoning, not obvious code
  5. Include usage comments in all snippets
  6. Use semantic HTML for better structure and accessibility
  7. Add accessibility attributes (aria-label, alt text, etc.)
  1. 酌情使用自定义HTML标签以优化语义化结构
  2. 通过
    data-*
    属性传递数据    ，并使用短横线分隔命名
  3. 精简注释 - 仅针对非直观逻辑添加
  4. 注释“原因”而非“内容” - 解释设计思路，而非直观代码的功能
  5. 为所有代码片段添加使用说明注释
  6. 使用语义化HTML以提升结构合理性与可访问性
  7. 添加可访问性属性（如aria-label、替代文本等）