跳到主要内容

Theme extension 开发指南

Theme App Extension（主题应用扩展）是主题通用的一种扩展机制，用于将应用能力以扩展形式注入店铺主题。通常由区块文件（blocks）、资源文件（assets）、代码片段（snippets）和多语言文件（locales）组成。

Theme App Extension 支持两种类型的主题扩展：

  • 基础扩展（App Block）：用于在页面可视化区域中渲染内容，商家可在主题编辑器中将其添加到支持 @app 的 Section。

  • 嵌入扩展（App Embed Block）：用于注入全局脚本、浮层或无固定布局区域的能力，通常在 </head> 或 </body> 前渲染。

Image

Image

这两种扩展的使用场景、代码结构与 Schema 配置见 Theme extension 参考。

你将学到什么​

  • 如何用 CLI 初始化并创建一个 Theme App Extension

  • App Block 与 App Embed Block 两种扩展类型的区别与适用场景

  • 如何编写并预览一个最小可用的 App Block

  • 如何编写、启用并预览一个最小的 App Embed Block

前置需求​

  • 已安装 shoplazza-cli

  • 拥有 Shoplazza 开发者账号与测试店铺

  • 已有 shoplazza app 项目，或在空目录中开发

开发流程​

第一步：初始化​

在 app 项目根目录（或空目录）执行：

shoplazza app init --name "my-app"

该命令会创建一个名为 my-app 的应用，并在当前目录下生成同名项目子目录。

第二步：创建 Theme Extension​

进入生成的 app 目录后执行：

shoplazza app extension create --type theme --name my-theme-app-extension --theme-type basic

该命令会在 extensions/ 目录下创建一个名为 my-theme-app-extension 的基础类型主题扩展。如果需要 App Embed Block，将 basic 替换为 embed。目录结构如下：

my-app/
└── extensions/
  └── my-theme-app-extension/
    ├── assets/
    │   ├── my-theme-app-extension.css
    ├── blocks/
    │   ├── my-theme-app-extension.liquid
    ├── snippets/
    │   └── my-theme-app-extension.liquid
    ├── locales/
    │   ├── en-US.json
    │   └── zh-CN.json
    ├── package.json
    └── shoplazza.extension.toml

在 extensions/my-theme-app-extension/ 目录下进行 Theme Extension 开发。

第三步：启动预览​

开发过程中，在 app 目录中执行：

shoplazza app dev

扩展会自动发布到绑定店铺，随后可在店铺后台主题编辑器中添加 App Block，或在「主题编辑 > 应用管理」中启用 App Embed Block。

目录结构​

通过 CLI 创建 Theme App Extension 后，会在项目的 extensions/ 目录下自动生成包含示例代码的完整目录结构：

└── extensions/
    └── my-theme-app-extension/
        ├── assets/
        │   ├── app_block.css
        │   ├── app_embed_block.css
        │   ├── app_embed_block.js
        │   └── thumbs_up.svg
        ├── blocks/
        │   ├── app_block.liquid          ← App Block
        │   └── app_embed_block.liquid    ← App Embed Block
        ├── snippets/
        │   └── rating_stars.liquid
        ├── locales/
        │   ├── en-US.json
        │   └── zh-CN.json
        ├── package.json
        └── shoplazza.extension.toml

子目录说明：

子目录说明
assets/存放 CSS、JavaScript、图片等静态资源，会通过 Shoplazza CDN 分发。在 Liquid 中通过 {% use %} 标签或 asset_abs_url 过滤器引用。
blocks/存放 App Block 和 App Embed Block 的 Liquid 文件，每个文件对应一个独立的区块。
snippets/存放可复用的 Liquid 代码片段，可在多个 Block 中通过 {% render %} 或 {% include %} 引用。
locales/存放多语言 JSON 文件，用于店面文本的国际化翻译。
shoplazza.extension.toml扩展配置文件，包含扩展的 ID、名称和类型。脚手架自动维护，不需要手动修改。

各文件的详细配置见 Theme extension 参考。

一个最小 App Block 示例​

在 blocks/ 下新建一个最简单的可渲染区块，商家即可在主题编辑器中添加看到效果：

<div class="my-app-block">
  {{ block.settings.text | default: "Hello from app block" }}
</div>

{% schema %}
{
  "name": {
    "en-US": "My App Block",
    "zh-CN": "我的区块"
  },
  "settings": [
    {
      "type": "text",
      "id": "text",
      "label": { "en-US": "Text", "zh-CN": "文本" }
    }
  ]
}
{% endschema %}

完整的 Block 类型、Schema、资源引用与多语言，见 Theme extension 参考。

一个最小 App Embed Block 示例​

与 App Block（渲染在某个 section 内）不同，App Embed Block 把全局内容注入到 </head> 或 </body> 之前。它的 Schema 必须声明 target（"body" 或 "head"）。

编辑 blocks/app_embed_block.liquid，写一个最小可渲染的 embed：

<div class="my-app-embed">
  {{ block.settings.text | default: "Hello from app embed" }}
</div>

{% schema %}
{
  "name": { "en-US": "My App Embed", "zh-CN": "我的全局嵌入" },
  "target": "body",
  "settings": [
    {
      "type": "text",
      "id": "text",
      "label": { "en-US": "Text", "zh-CN": "文本" }
    }
  ]
}
{% endschema %}
提示

App Embed Block 默认是关闭的。 执行 shoplazza app dev 发布扩展后，商家必须在主题编辑器的 主题编辑 > 应用管理 中手动开启，否则店面上不会渲染任何内容。

完整的 Schema（含 target）、资源引用，以及一个完整的浮动按钮示例，见 Theme extension 参考。

下一步​

排障​

App Embed Block 在店面上没有生效​

问题： App Embed Block 在店面上没有任何效果。

原因： App Embed Block 安装后默认处于关闭状态。

解决： 在主题编辑器的 主题编辑 > 应用管理 中开启它。

App Block 在页面上不显示​

问题： 发布后 App Block 不可见。

原因： App Block 不会自动插入，需商家手动添加。

解决： 在主题编辑器中，把该区块添加到支持 @app 的 Section。