跳到主要内容

入门

要创建新的 theme，您需要了解基本的文件结构并据此创建相应文件。

开始之前，请确认您已具备以下前置条件：

  1. 一个 Shoplazza 商店：没有商店就无法操作 theme。
  2. 文本编辑器：您可以使用Shoplazza主题编辑器中的在线构建功能。
  3. HTML、CSS、JavaScript 和 Liquid 的基础知识：Shoplazza theme 使用这些技术构建。

第一步：创建新 Theme​

要创建新的 theme，请先在 Shoplazza 管理后台进入在线商店 → 主题。点击上传主题按钮，上传 theme 的 .zip 压缩包。如果您是从零开始，可以下载现有的 theme 进行修改。

第二步：了解文件结构​

上传 theme 后，了解文件结构至关重要。以下是 Shoplazza theme 的基本目录结构：

my-new-theme/  
├── assets/  
    ├── style.css  
    ├── style.scss  
├── config/  
│   └── settings_data.json  
├── layout/  
│   └── theme.liquid  
├── locales/  
│   └── en.default.json  
├── sections/  
├── snippets/  
└── templates/  
    ├── 404.liquid  
    ├── article.liquid  
    ├── blog.liquid  
    ├── cart.liquid  
    ├── collection.liquid  
    ├── index.liquid  
    ├── list-collections.liquid  
    ├── page.liquid  
    ├── password.liquid  
    └── product.liquid
  • assets/：包含 theme 的所有静态资源，如图片、样式表和 JavaScript 文件。
  • config/：包含 theme 的设置文件。
  • layout/：包含 theme 的 layout 文件，theme.liquid 是主要的 layout 文件。
  • locales/：包含 theme 的 locale 文件，用于商店的文本内容翻译。
  • sections/：包含 theme 的 section，section 是可复用的内容模块，用户可以对其进行自定义和重新排序。
  • snippets/：包含 theme 的 snippet，即可复用的小段代码。
  • templates/：包含其他各类内容的 template，如商品页、博客文章等。

第三步：开始构建 Theme​

基本结构搭建完成后，即可开始构建 theme。每个目录的用途各不相同，请按照对应用途组织文件。

  • 在 layout/ 目录中，需要有一个定义 theme layout 的 theme.liquid 文件。该文件包含站点的主要 HTML 元素，如 <head>、<header>、<footer> 等，并作为页面内容的外层包裹。

  • 在 templates/ 目录中，为不同类型的页面创建不同的 Liquid template，如商品页、商品集页、文章页等。

  • 在 sections/ 目录中，创建可通过 Shoplazza 管理后台添加到页面的 section，即可复用的内容模块。

  • 在 snippets/ 目录中，创建可复用的小段代码，通常在多个 template 或 section 中共用。

  • 在 assets/ 目录中，存放所有静态文件，如图片、样式表（CSS 或 SCSS）和 JavaScript 文件。

  • 在 config/ 目录中，设置各种可配置选项，这些选项可在 Shoplazza 管理后台中修改，无需改动代码。

第四步：预览 Theme​

修改 theme 后，可以在 Shoplazza 商店中预览效果。进入在线商店 → 主题，点击 theme 旁边的操作按钮，然后点击预览，浏览器将在新标签页中打开 theme 预览。

您已成功为 Shoplazza theme 创建了文件结构并开始构建。请记住，开发 Shoplazza theme 需要扎实掌握 HTML、CSS、JavaScript 和 Liquid，务必熟悉这些技术。

Theme Config

settings_data.json 文件是 Shoplazza theme 的重要组成部分，位于 config/ 目录中，用于存储可在管理后台主题编辑器中调整的主题设置数据。

该文件由系统在您通过主题编辑器修改主题设置时自动生成和更新，数据以 JSON 格式存储。

以下是 settings_data.json 文件的简单示例：

{  
  "current": "default",  
  "presets": {  
    "default": {  
      "section": {  
        "setting_name": "setting_value"  
      }  
    }  
  }  
}

current 键用于指定当前使用的预设，此处为 "default"。

presets 键包含一个或多个命名预设，每个预设是该 theme 的一组设置。"default" 预设是必需的，在您首次安装 theme 时使用。您可以根据需要添加其他预设。

每个预设包含一个或多个 section，每个 section 可以包含一个或多个设置项。这些设置项就是您可以通过主题编辑器调整的实际主题设置，其值通常为字符串或数字等简单类型，也可以是数组或对象等更复杂的类型，具体取决于设置项本身。

以下是包含多个设置项的复杂示例：

{  
  "current": "default",  
  "presets": {  
    "default": {  
      "colors": {  
        "body_text": "#333333",  
        "background": "#ffffff"  
      },  
      "typography": {  
        "base_font": "Helvetica, sans-serif",  
        "heading_font": "Georgia, serif"  
      },  
      "layout": {  
        "content_width": "1200px",  
        "sidebar_enabled": true  
      }  
    }  
  }  
}

在此示例中，"default" 预设包含三个 section："colors"、"typography" 和 "layout"，每个 section 有各自的设置项。例如，"colors" section 包含 "body_text" 和 "background" 的设置项。

注意：不建议直接编辑此文件，因为它由系统自动管理。请通过管理后台的主题编辑器调整主题设置。
更多信息请参阅官方文档 https://www.shoplazza.dev/docs/theme/architecture/theme-config/overview

如何使用这些配置​

在 Liquid 中，可以通过 settings 对象访问 settings_data.json 文件中的设置项，从而在 theme 文件中使用这些设置数据。

以下是一个基础示例。假设 settings_data.json 文件中有以下数据：

{  
  "current": "default",  
  "presets": {  
    "default": {  
      "colors": {  
        "body_text": "#333333",  
        "background": "#ffffff"  
      }  
    }  
  }  
}

您可以在 Liquid 文件中这样访问正文文字颜色：

<p style="color: {{ settings.colors.body_text }}">这是一段文字。</p>

这将使段落文字以 settings_data.json 中指定的颜色渲染。

同样，您可以这样访问背景颜色：

<body style="background-color: {{ settings.colors.background }}">
  <!-- 页面内容放在这里 -->
</body>

这将把页面背景颜色设置为 settings_data.json 中指定的颜色。

您可以在任何 Liquid 标签、输出或过滤器中使用这些设置项，在 HTML 标签的 style 属性中搭配使用时尤为实用，可根据设置项自定义 theme 外观。

请记住，这些设置项可以在管理后台的主题编辑器中修改，无需改动代码即可调整 theme 外观。

另外请注意，如果某个设置项未被设置，在 Liquid 文件中尝试访问它将返回 null。在使用前应先判断设置项是否存在：

{% if settings.colors.body_text %}
  <p style="color: {{ settings.colors.body_text }}">这是一段文字。</p>
{% endif %}

只有当正文文字颜色设置项存在时，才会渲染该段落。
我们还支持多种配置类型，更多信息请参阅 https://www.shoplazza.dev/docs/theme/architecture/theme-config/overview

Theme Layout

theme.liquid 文件是 Shoplazza theme 的主 layout 文件，包含站点的基本 HTML 结构，包括 <head>、<header>、<footer> 和 <body> 等元素，并作为页面内容的外层包裹。
以下是一个简单的 theme.liquid 文件示例：

<!DOCTYPE html>

<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{ shop.name }} - {{ page.title }}</title>

  {{ 'style.css' | asset_url | stylesheet_tag }}  
  {{ content_for_header }}

</head>
<body>
  <header>
    <h1>{{ shop.name }}</h1>
    <nav>
      <ul>
        <li><a href="/">Home</a></li>
        <li><a href="/collections">Collections</a></li>
        <li><a href="/blog">Blog</a></li>
      </ul>
    </nav>
  </header>

  <main role="main">
    {{ content_for_layout }}
  </main>

  <footer>
    <p>&copy; {{ 'now' | date: "%Y" }} {{ shop.name }}</p>
  </footer>

  {{ 'script.js' | asset_url | script_tag }}  
  {{ content_for_js }}

</body>
</html>

在此示例中：

  • {{ shop.name }} 和 {{ page.title }} 是 Liquid 变量，分别动态输出商店名称和当前页面标题。
  • {{ 'style.css' | asset_url | stylesheet_tag }} 和 {{ 'script.js' | asset_url | script_tag }} 使用 Liquid 过滤器引入 assets 目录中的 CSS 文件和 JavaScript 文件。
  • {{ content_for_layout }} 是一个特殊的 Liquid 变量，用于注入不同 template（如 product.liquid、collection.liquid 等）的内容。
  • content_for_header：将 Shoplazza 功能正常运行所需的脚本动态加载到文档头部，包括 Shoplazza 分析脚本、客户登录链接等，必须放置在 <head> 标签内。
  • content_for_js：用于动态向页面添加特定 JavaScript，应放置在 </body> 标签关闭之前。
  • <header>、<main> 和 <footer> 元素分别包含站点页眉、主内容区域和页脚的 HTML。
    这只是一个非常基础的示例，实际的 theme.liquid 文件会包含更多 Liquid 变量、过滤器、标签和 HTML，复杂度远超于此。

更多信息请参阅 https://www.shoplazza.dev/docs/theme/architecture/theme-layouts/overview

Theme Locale​

以下是在 theme 中使用 locale 的方法：

  1. 在 JSON 文件中定义翻译：在 locales/ 目录的 JSON 文件中定义翻译内容，键的层级结构应与 theme 结构保持一致。

示例如下：

{  
  "products": {  
    "product": {  
      "sold_out": "Sold out",  
      "save": "Save {{amount}}{{amount_symbol}}"  
    }  
  }  
}
  1. 在 Theme 中引用翻译：使用翻译键和 Liquid 翻译过滤器（t 过滤器）引用翻译内容，翻译键以 i18n. 为前缀，例如：
<p>{{ 'i18n.products.product.sold_out' | t }}</p>

在英文语言下将输出 "Sold out"，在其他激活语言下则输出对应译文。

  1. 插值：您可以在翻译字符串中包含变量，这些变量在 Liquid 中引用该字符串时动态填入，适合在翻译内容中包含动态数据。

以下是插值翻译的示例：

<p>{{ 'i18n.products.product.save' | t: amount: 18.88, amount_symbol: '$' }}</p>

将输出 "Save 18.88$"，或在激活语言下输出对应译文。

要切换语言，需要将商店配置为支持多语言，并让客户选择偏好语言，所选语言将决定使用哪个 locale 文件。
更多信息请参阅 https://www.shoplazza.dev/docs/theme/architecture/theme-locales/overview

Theme Section​

在 Shoplazza 中，section 是一段可复用的 Liquid 代码模块，包含在线商店内容的特定部分。Section 可以是静态的（如页眉、页脚），也可以是动态的（如可自定义的商品选择器）。

Section 存储在 theme 的 sections/ 目录中，每个 section 有独立的 .liquid 文件。

以下是编写 Shoplazza section 的基础示例：

{% stylesheet %}  
h1 {  
  color: blue;  
}  
{% endstylesheet %}

{% javascript %}  
console.log('This is a custom section.');  
{% endjavascript %}

<h1>{{ section.settings.title }}</h1>
<p>{{ section.settings.content }}</p>
{% schema %}
{
  "name": "My custom section",
  "settings": [
    {
      "id": "title",
      "type": "text",
      "label": "Title",
      "default": "Default title"
    },
    {
      "id": "content",
      "type": "textarea",
      "label": "Content",
      "default": "Default content"
    }
  ]
}
{% endschema %}

在此示例中：

  • {% schema %} 和 {% endschema %} 标签定义 section 的配置结构（schema），包含 section 的名称和设置项。每个设置项有 id、type、label 和默认值，id 用于在 section 代码中引用该设置项。除示例中的 text 和 textarea 之外，还有更多输入类型，请参阅 https://www.shoplazza.dev/docs/theme-settings-input-settings。
  • {% stylesheet %} 和 {% endstylesheet %} 标签定义 section 的 CSS，当 section 被引入 template 时，该 CSS 会被包含在 theme 的主样式表中。
  • {% javascript %} 和 {% endjavascript %} 标签定义 section 的 JavaScript，当 section 被引入 template 时，该 JavaScript 会被包含在 theme 的主 JavaScript 文件中。
  • {{ section.settings.title }} 和 {{ section.settings.content }} 是 Liquid 变量，动态输出 title 和 content 设置项的值。

这只是一个基础示例，根据 theme 的设计，section 可以更加复杂，包含更多设置项、Liquid 逻辑、HTML、CSS 和 JavaScript。

使用 {% section %} 标签可以在 template 中引入 section。例如，如果 section 文件名为 my-custom-section.liquid，可以这样引入：

{% section 'my-custom-section' %}

这将在 template 中渲染该 section，且 section 的设置项可在主题编辑器中进行配置。

Theme Snippet

在 Shoplazza 中，snippet 是一段可在其他 Liquid template 中引用的可复用代码块，有助于保持代码整洁并遵循 DRY（不重复自己）原则。Snippet 存储在 theme 的 snippets/ 目录中。

以下是创建 snippet 的基础示例：

  1. 创建 snippet 文件：在 snippets/ 目录中新建一个 .liquid 文件，例如 my-custom-snippet.liquid。

  2. 编写 snippet 代码：在文件中编写 snippet 代码，例如：

<p>This is a custom snippet.</p>
  1. 在 template 中引入 snippet：使用 include 标签在任意 Liquid template 中引入该 snippet，例如：
{% include 'my-custom-snippet' %}

在使用 include 标签的位置将输出 "This is a custom snippet."。

您也可以向 snippet 传递参数，参数是在引入 snippet 时定义的变量，可在 snippet 内部使用。

以下是传递参数的示例：

  1. 创建 snippet 文件：在 snippets/ 目录中新建文件，例如 product-card.liquid。

  2. 编写 snippet 代码：

<div class="product-card">
  <h2>{{ product.title }}</h2>
  <p>{{ product.description }}</p>
</div>
  1. 带参数引入 snippet：使用 include 标签并传递参数：
{% include 'product-card', product: featured_product %}

在此示例中，featured_product 是在 template 其他位置定义的变量，作为 product 参数传入 product-card snippet。

在 product-card snippet 内部，可以使用 product 访问 featured_product 对象，{{ product.title }} 将输出 featured_product 的标题，{{ product.description }} 将输出其描述。

实战示例与 Liquid 对象​

Liquid 对象​

Liquid 是 Shoplazza theme 中使用的模板语言，用于在店铺前台加载动态内容。

在 Liquid 中，对象是一种表示复杂事物的变量类型，例如商品、商品集、购物车或当前页面。

对象具有属性，您可以输出这些属性或在逻辑语句中使用它们。例如，商品对象具有 title、description、price、images 等属性。

在 template 中使用点号语法引用对象及其属性。例如，如果有一个名为 product 的商品对象，可以这样输出商品标题：{{ product.title }}。

以下是 Shoplazza theme 中最常用的 Liquid 对象：

  • product：代表一个商品，具有 title、description、price、images、variants 等属性。
  • collection：代表一个商品集，具有 title、description、products 等属性。
  • cart：代表当前用户的购物车，具有 items、total_price 等属性。
  • customer：代表当前登录用户，具有 name、email、orders 等属性。
  • page：代表当前页面，具有 title、content、url 等属性。
  • shop：代表您的 Shoplazza 商店，具有 name、description、url、products、collections 等属性。

更多信息请参阅 https://www.shoplazza.dev/docs/liquid-objects

以上只是部分示例，Liquid 对象还有很多，每个对象也有大量属性，完整参考请查阅 Shoplazza Liquid 文档。以下是具体用法示例。

如何创建导航栏​

创建带有动态菜单链接的页眉，需要创建并使用一个从商店 linklist 配置中读取数据的 snippet。

首先，在 theme 的 sections/ 目录中创建 header.liquid 文件，代码示例如下：

<header class="site-header">
  <h1 class="site-title">{{ shop.name }}</h1>

  <nav class="main-navigation">
    {% include 'navigation', links: linklists.main-menu.links %}
  </nav>
</header>

在此示例中，我们引入了名为 navigation 的 snippet，并将 main-menu linklist 的链接传入。

接下来，在 theme 的 snippets/ 目录中创建 navigation.liquid 文件，代码示例如下：

<ul class="menu">
  {% for link in links %}
    <li class="menu-item">
      <a href="{{ link.url }}">{{ link.title }}</a>
      {% if link.links %}
        <ul class="submenu">
          {% for sublink in link.links %}
            <li class="submenu-item">
              <a href="{{ sublink.url }}">{{ sublink.title }}</a>
            </li>
          {% endfor %}
        </ul>
      {% endif %}
    </li>
  {% endfor %}
</ul>

该 snippet 遍历传入的 linklist 中的每个链接，为每个链接创建列表项和链接标签。如果某个链接本身还有子链接（说明它是有子级的父链接），则创建子菜单并遍历子链接。

最后，确保在 theme.liquid layout 文件中引入 header section：

<!DOCTYPE html>

<html lang="en">
<head>
  <!-- head 内容放在这里 -->
</head>
<body>
  {% section 'header' %}

  <!-- 其他内容放在这里 -->

</body>
</html>

在主题编辑器中，您可以将 linklist 分配给 main-menu，页眉中的导航菜单将自动更新以显示 linklist 中的链接。

请注意，这只是一个基础示例，您可能需要根据 theme 的样式和结构调整代码。

如何创建商品详情 Section​

创建商品详情 section，需要创建一个可读取并展示商品对象信息的 section。

首先，在 theme 的 sections/ 目录中创建 product-template.liquid 文件，代码示例如下：

{% schema %}  
{  
  "name": "Product template",  
  "settings": [  
    {  
      "type": "checkbox",  
      "id": "show_vendor",  
      "label": "Show vendor",  
      "default": true  
    }  
  ]  
}  
{% endschema %}

{% if product %}

  <h1>{{ product.title }}</h1>
  <p>{{ product.description }}</p>
  {% if section.settings.show_vendor %}
    <p>{{ product.vendor }}</p>
  {% endif %}
  <img src="{{ product.featured_image | img_url: '480x480' }}" alt="{{ product.featured_image.alt | escape }}">
  <p>{{ product.price | money }}</p>
{% else %}
  <p>该商品不存在。</p>
{% endif %}

在此示例中，section 有一个 show_vendor 设置项，可在主题编辑器中开启或关闭。开启时显示商品品牌，section 展示商品的标题、描述、品牌（若 show_vendor 开启）、主图和价格。

要在商品详情页展示该 section，需在商品详情 template 中使用 product-template section。在 templates/ 目录中创建 product.liquid 文件，代码如下：

{% section 'product-template' %}

这将在商品详情页渲染该 section，section 中的 product 对象将自动对应当前商品。

这只是一个基础示例，根据 theme 的设计，商品详情 section 可以更加复杂，包含更多设置项、Liquid 逻辑、HTML、CSS 和 JavaScript。