框架​

主题应用扩展是由 App Block、App Embed Block、Assets 和 Snippets 一起构成的。

文件结构​

当你创建主题应用扩展时，SHOPLINE 会将以下 theme-app-extension目录和子目录添加到你的应用中：

├── theme-app-extension
  ├── assets
  │   ├── app-block.css
  │   ├── app-block.js
  │   ├── app-embed-block.css
  │   ├── app-embed-block.js
  │   ├── logo.png
  │   └── sheep.jpg
  ├── blocks
  │   ├── app-block.html
  │   └── app-embed-block.html
  ├── locales
  │   ├── en.schema.json
  │   ├── zh-hans-cn.schema.json
  │   └── zh-hant-tw.schema.json
  ├── snippets
  │   └── logo-icon.html
  ├── .gitignore
  ├── .shopline-cli.yml
子目录描述
assets包含 CSS、JavaScript 和其他注入主题的静态应用程序内容。
应用可以使用javascript
、stylesheet
schema 属性
或从 asset_url
Handlebars helper  加载 assets
。
blocks包含 App Block
和 App Embed Block
HTML 文件。
snippets包含主题应用扩展代码片段文件，这些是你可以在其他 App Block 和 App Embed Block 中引用的、可重复使用的代码片段
locales包含 JSON 格式的语言环境文件，这些文件是用于存放面向商家和面向客户的翻译。这些文件的模式和用法类似于主题语言环境文件
。你可以包含以下文件类型：
- Schema 本地化文件
：包含面向商家的翻译。使用这些文件来翻译主题编辑器中显示的设置。
- 店铺本地化文件
：包含面向客户的翻译。在呈现 App Block 或 App Embed Block 时，使用这些文件翻译店面中显示的文本。
注意：商家无法编辑主题应用扩展店面语言环境文件中的字符串。

App Blocks​

应用使用 App Blocks 在页面上注入内容以扩展主题能力。商家可以将 App Block 添加到主题的 section，或者作为 section 级别添加到页面的区域中。通过 target 指向 section 来创建 App Block。
默认情况下，主题在安装应用程序后不包含 App Block。商家需要从主题编辑器的添加组件将 App Block 添加到主题中。
将 App Block 用于以下类型的应用：

  • 给产品详情添加产品评论、产品星级的应用
  • 覆盖整个页面宽度的应用

示例​

以下示例创建一个具有 style 属性的 span 元素。 style 值 ( color: {{ block.settings.color }}) 在 schema 内寻找 settings key，然后寻找包含 "default": "#000000" 值 的 color key。最后该值使用默认颜色 #000000 填充 style 属性，这会渲染黑色的 App blocks let you build powerful integrations with online store themes! 文本。

<span style="color: {{ block.settings.color }}">
App blocks let you build powerful integrations with online store themes!
</span>
<img src="{{ asset_url 'logo.png' }}" />
{{ snippet 'app_snippet' }}
{{#schema}}
  {
    "name": "App Block",
    "target": "section",
    "stylesheet": ["app.css"],
    "javascript": ["app.js"],
    "settings": [
        {
          "label": "Color",
          "id": "color",
          "type": "color",
          "default": "#000000"
        }
    ]
  }
{{/schema}}

主题中的 App Block 示例​

以下是添加到 section 的 App Block 示例：

image.png

以下是独立添加 App Block 的示例：
image.png

App Block 的好处​

App Block 很灵活。商家可以使用主题编辑器在 section 级别添加、删除和重新排序 App Block，以便于自定义。

App Embed Blocks​

应用使用 App Embed Block 添加没有 UI 组件、浮动元素以扩展主题能力。SHOPLINE 在 HTML 的 </head> 和 </body> 结束标记前注入 App Embed Block。 通过将 schema 中的 target属性设置为 head 或 body 决定 App Embed Block 的渲染位置。

默认情况下，安装应用后不会自动开启 App Embed Block。商家需要在主题编辑器中激活 App Embed Block，从主题设置 > 应用嵌入。

App Embed Block 用于以下类型的应用：

  • 为页面提供浮动元素的应用，例如客服咨询应用和公告提示应用。
  • 添加 SEO 元标记、分析或自定义表单的应用。

示例​

这个示例展示了 App Embed Block 插入到 body 底部，这会渲染成一个悬浮在页面底部的评论按钮。

<div style="position: fixed; bottom: 0; right: 0">
  <img src="{{ asset_url 'comment.jpg' }}" />
</div>
{{#schema}}
  {
    "name": "App Embed Block",
    "target": "body",
    "settings": []
  }
{{/schema}}

主题中的 App Embed Block 示例​

image.png

App Embed Block 的好处​

SHOPLINE 在线商店全部主题都已支持 App Embed Block。
安装后，商家可以使用主题编辑器配置 App Embed Block 设置，以获得更加个性化的体验。

Conditional App Blocks​

你可以根据自定义条件控制 App Block 或 App Embed Block 的可见性。例如，你可能希望根据地理位置限制内容的可见性。

可以通过 available_if 属性将条件包含在 block 下面的 schema 中，available_if 属性值的状态存储在应用拥有的元字段中。

注意

应用元字段的值必须是一个 boolean 类型。

格式必须满足：{{ apps.metafields.<namespace>.<key>.value }}，其中 apps 对应的是 resource。

例如，如果你有一个命名空间为 conditional 和 key 为 block1 的应用程序元字段，那么你可以使用以下 schema:

{{#schema}}
{
   "name": "Conditional App block",
   "target": "section",
   "stylesheet": ["app.css"],
   "javascript": ["app.js"],
   "available_if": "{{ apps.metafields.conditional.block1.value }}",
   "settings": [
      {
        "label": "Colour",
        "id": "colour",
        "type": "color",
        "default": "#000000"
      }
   ]
 }
{{/schema}}

Schema​

App Block 和 App Embed Block 的 schema 类似于主题 section schema。它支持以下属性，其中一些是 App Block 和 App Embed Block 所独有的：

字段名类型描述是否必填
nameStringApp Block 或 App Embed Block 在主题编辑器中的标题。
将 App Block 和 App Embed Block 名称保持在 25 个字符以下，以便它们适合在主题编辑器侧边栏中展示。		是
targetStringblock 所在的位置。可能的值为 section
、head
和 body
。
App Block 的值为 section
。
App Embed Block 的值为 head
和 body
。		是
stylesheetArray要从 assets
子目录加载的 CSS 文件。
如果页面上存在该 block，则你可以通过在页面部分添加 <link rel="stylesheet">
标签来自动加载此文件。		否
javascriptArray要从 assets
子目录加载的 JavaScript 文件。
如果页面上存在该 block，则你可以通过在页面部分添加 <script async>
标签来自动加载此文件。		否
templatesArray可以在其中呈现 block 的模板。如果未设置，则默认为所有页面。可以支持如下的页面：
- index
- 首页
- collections_all
- 分类页
- collection
- 商品列表页
- product
- 商品详情页
- cart
- 购物车页
- blog
- 博客集合页
- article
- 博客页
- 404
- 404页
- search
- 搜索页
- page
- 自定义页面
- customers/login
- 登录页
- customers/register
- 注册页
- customers/account
- 用户中心页
- customers/activate_account
- 用户激活页面
- customers/forget_password
- 忘记密码页
- customers/addresses
- 用户地址
- customers/orders
- 个人中心订单列表页
- customers/order
- 个人中心订单详情页
- password
- 密码页（App Block 不生效）
App Block 和 App Embed Block 无法在结账页面上呈现		否
classString要包含在包裹标签元素中的其他 CSS 类，类似于主题 section class
主题应用扩展将总是包含 shopline-block
类。		否
tagString如果设置该值，那么该标签将包裹 block 的输出，默认输出被包裹在一个 div
中。
可选值有：
- article
- aside
- div
(默认)
- footer
- header
- section		否
localesObject渲染 block 所使用到的翻译文本配置。例如：locales 配置否
settingsArray你向商家提供的用于自定义 App Block 或 App Embed Block 的 settings
。选择 block 时，这些设置会出现在主题编辑器中。可以使用 Handlebar block.settings 对象访问设置值。
如果希望配置支持动态取值，可以使用应用元字段。例如，如果你有一个命名空间为 select 和 key 为 options 的应用程序元字段，那么你可以使用 options schema。
支持配置动态取值的控件类型：
- select
- radio
- checkbox		否
defaultArrayblock 的默认配置。有关示例，请参阅 section schema否
available_ifString用于确定是否会呈现在店铺上并在主题编辑器中可见。
该值必须是一个应用拥有的元字段值的引用。如果应用程序拥有的元字段返回 true, 那么该 block 就会被渲染并在主题编辑器中可用。		否
limitInteger可以使用该类型的 block 的数量。否
注意

应用元字段的值必须是一个 array json 类型，参考 select 控件配置。

locales 配置​

{{#schema}}
{
  "locales": {
    "en": {
      "title": "Title"
    },
    "ja": {
      "title": "タイトル"
    },
    "de": {
      "title": "Titel"
    }
  }
}
{{/schema}}

options schema​

{{#schema}}
{
   "name": "App block",
   "target": "section",
   "stylesheet": ["app.css"],
   "javascript": ["app.js"],
   "settings": [
      {
        "label": "Select",
        "id": "select",
        "type": "select",
      	"options": "{{ apps.metafields.select.options.value }}"
      }
   ]
 }
{{/schema}}

通过深层链接简化安装流程​

安装后，你的应用程序可以通过深层链接提示商家。单击时，深层链接会激活主题编辑器中的 App Embed Block / App Block ，供商家在保存和发布之前进行预览和调整。深层链接简化了应用程序的安装流程，因为商家不需要导航到主题编辑器、找到 block，然后对其进行操作。相反，你的应用程序会为他们完成工作。因为商家可以预览区块，所以你可以让他们控制店面中包含的内容。

App Block 深层链接​

你可以实现深层链接以将应用块添加到以下位置：

  • 任何 JSON 模板。例如： product 模板。
  • 指定ID的section。例如，index.json 模板中的 image-with-text section 。
提示

你只能深层链接到支持 App Block 的 section。此外，你一次只能添加一个带有深层链接的 App Block。

App Block 示例网址

你的应用需要将商家重定向到以下 URL，并填充 URL 查询参数：

https://<myshoplineDomain>/admin/theme/editor/editing/${templateAlias}?themeId=${themeID}&templateName=${templateName}&activateAppId=${uuid}/${handle}&target=newAppsSection

参考以下例子:

https://test.myshopline.com/admin/theme/editor/editing/Home?themeId=6486e09af9bbc878f5da89ff&templateName=templates/index.json&activateAppId=6bba0cf9-c86a-4d23-b71e-a144f95c2cc7/promotion-card&target=newAppsSection

App Block 深层链接查询参数
涉及到的插值有（以下所有插值，需要 URL encode):

插值描述
myshoplineDomain安装 app 时商家的店铺域名，可以在 app 服务获取到
templateAlias编辑器选择的页面, 枚举值是:
Home
Products
AllCollections
ProductsDetail
Cart
404
ProductsSearch
Page
BlogsList
BlogsDetail
Checkout
Other
Policy
themeID主题ID, 用于定位编辑的主题
templateName编辑器渲染的页面模板, 如: templates/index.json
uuid主题应用扩展的 uuid
值，可以在 .env
读取 EXTENSION_UUID
值
handle需要激活的 App Embed Block
文件名，例如，文件位于 theme-app-extension/blocks/app-embed.html
，{handle}
则为 app-embed
sectionId指定 App block
添加的 section 的 ID。( target 为 sectionId 时需传入)
targetblock 支持以下 2 个位置添加：
  • newAppsSection：在模板 section 列表的底部，增加一个新的应用组件并把 block 添加到这个新的应用组件中；
  • sectionId:{sectionId}：指定 id 的 section 添加 block

    • 将 App Block 添加到任何 JSON 模板

    以下是将 App Block 添加到 JSON 模板的深层链接格式：

    https://<myshoplineDomain>/admin/theme/editor/editing/${templateAlias}?themeId=${themeID}&templateName=${templateName}&activateAppId=${uuid}/${handle}&target=newAppsSection

    例如，将限时促销卡片添加到首页的最后一个 section，参考以下例子:

    https://test.myshopline.com/admin/theme/editor/editing/Home?themeId=6486e09af9bbc878f5da89ff&templateName=templates/index.json&activateAppId=6bba0cf9-c86a-4d23-b71e-a144f95c2cc7/promotion-card&target=newAppsSection

    将 App Block 添加到指定 ID 的 section

    以下是将 App Block 添加指定 ID 的 section 深层链接格式：

    https://<myshoplineDomain>/admin/theme/editor/editing/${templateAlias}?themeId=${themeID}&templateName=${templateName}&activateAppId=${uuid}/${handle}&target=sectionId:{sectionId}

    例如，将限时促销卡片添加到首页的 image-with-text 中，参考以下例子:

    https://test.myshopline.com/admin/theme/editor/editing/Home?themeId=6486e09af9bbc878f5da89ff&templateName=templates/index.json&activateAppId=6bba0cf9-c86a-4d23-b71e-a144f95c2cc7/promotion-card&target=sectionId:1695572437385bfbbd3a

    你可以在模板的 JSON 文件中找到需要定位 section 的 id，例如首页的 image-with-text 的JSON 数据如下：

    {
      "sections": {
        "1695572437385bfbbd3a": {
          "type": "image-with-text"
        }
      },
      "order": [
        "1695572437385bfbbd3a"
      ]
    }
    提示

    你可以使用查询主题资产详情 API 获取主题模板JSON文件的内容，用于检测主题是否使用了特定的组件和获取其ID。

    App Embed Block 深层链接​

    你可以实现深层链接以直接在主题中激活 App Embed Block。

    App Embed Block 示例网址

    你的应用需要将商家重定向到以下 URL，并填充 URL 查询参数：

    https://<myshoplineDomain>/admin/theme/editor/editing/${templateAlias}?themeId=${themeID}&templateName=${templateName}&activateAppId=${uuid}/${handle}

    参考以下例子:

    https://test.myshopline.com/admin/theme/editor/editing/Home?themeId=63abc8fcf8a25d2d8854de5a&templateName=templates%2Findex.json&activateAppId=ac5292dd-7a66-41a4-b69f-5a163da0a421%2Fback-to-top

    App Embed Block 深层链接查询参数
    涉及到的插值有（以下所有插值，需要 URL encode):

    插值描述
    myshoplineDomain安装 App 时商家的店铺域名，可以在 App 服务获取到
    templateAlias编辑器选择的页面, 枚举值是:
    Home
    Products
    AllCollections
    ProductsDetail
    Cart
    404
    ProductsSearch
    Page
    BlogsList
    BlogsDetail
    Checkout
    Other
    Policy
    themeID主题 ID, 用于定位编辑的主题
    templateName编辑器渲染的页面模板, 如: templates/index.json
    uuid主题应用扩展的 uuid
    值，可以在 .env
    读取 EXTENSION_UUID
    值
    handle需要激活的 App Embed Block
    文件名，例如，文件位于 theme-app-extension/blocks/app-embed.html
    ，{handle}
    则为 app-embed

    性能​

    assets/ 文件夹内的所有文件均自动从 SHOPLINE 的 CDN 提供服务，以实现快速、可靠的资产交付。通过使用 javascript 和 stylesheet schema 属性或使用 asset_url 和 asset_img_url Handlebars URL helper 来引用你的资产。 对于 App Embed Block，利用它们的能力仅加载特定页面上的脚本。

    文件和内容大小限制​

    当你推送到草稿扩展版本时，SHOPLINE 会验证主题应用扩展。如果应用程序的内容超出强制限制，则主题应用程序扩展将无法通过验证并且不会更新。
    下表提供了对主题应用扩展的强制限制：

    应用内容限制
    主题应用扩展中的所有文件10 MB
    block 数量25
    所有 block 的 Handlebars 文件大小100 KB
    assets 目录下的资源类型.jpg
    、.js
    、.css
    、.png
    、.svg

    局限​

    以下页面和对象不能与主题应用扩展一起使用。

    页面​

    主题 App Block 和 App Embed Block 无法在结帐页面上呈现。这包括客户发起结账时呈现的所有页面，例如联系信息、运输方式、付款方式和订单状态。

    Handlebar 对象​

    主题应用扩展无权访问以下 Handlebar 对象：

    这篇文章对你有帮助吗？
    SHOPLINE
    SHOPLINE
    SHOPLINE Enterprise
    条款协议
    隐私
    条款
    开发者协议
    LinkedInEmail
    LinkedInEmail
    © Copyright 2013-2025 SHOPLINE Limited.