框架

通过本文了解主题应用扩展的结构及配置。

目录结构​

主题应用扩展的标准目录结构如下：

└── theme-app-extension
    ├── blocks
    │   ├── app-block.html
    │   ├── app-embed-block.html
    │   ├── conditional-app-block.html
    │   └── ...
    ├── components
    │   ├── logo-icon.html
    │   └── ...
    ├── i18n
    │   ├── en.json
    │   ├── en.schema.json
    │   ├── zh-hans-cn.json
    │   ├── zh-hans-cn.schema.json
    │   ├── zh-hant-tw.json
    │   ├── zh-hant-tw.schema.json
    │   └── ...
    ├── public
    │   ├── app-block.css
    │   ├── app-block.js
    │   ├── app-embed-block.css
    │   ├── app-embed-block.js
    │   └── ...
    └── .shopline-cli.yml

目录和文件说明：

目录或文件描述
blocks包含 App Block 和 App Embed Block 的 HTML 文件。
components包含主题应用扩展的代码片段文件，这些是你可以在 App Block
和 App Embed Block 中引用的、可重复使用的代码片段。
i18nJSON 格式的多语言环境文件，这些文件是用于存放商家和面向客户的翻译。这些文件的用法与 主题语言环境文件 保持一致。
public包含 CSS、JavaScript 和其他静态资源。
可以通过 schema 里面的 javascript 和 stylesheet 属性引入，或者使用 asset_url filter 进行引入。
.shopline-cli.yml主题应用扩展的配置文件。

App Block​

App Block 可以让商家在主题组件中，添加来自应用的区块。

默认情况下，主题在安装应用程序后，不会自动添加 App Block。商家需要自行在主题编辑器中添加来自应用的 App Block。

以下示例是创建一个简单的具有 style 属性的 span 元素。示例中的 Schema 标签中的详情配置参考见 Schema。

<span style="color: {{ block.settings.color }}">
  App Block
</span>
{{#schema}}
  {
    "name": "App Block",
    "target": "section",
    "stylesheet": ["public/app.css"],
    "javascript": ["public/app.js"],
    "settings": [
        {
          "label": "Color",
          "id": "color",
          "type": "color",
          "default": "#000000"
        }
    ]
  }
{{/schema}}

以下是在主题组件中添加 App Block 的示例：

以下是在主题独立添加 App Block 的示例：

App Block 很灵活。商家可以使用主题编辑器在主题的组件级别对 App Block 进行添加、删除和排序。

App Embed Block​

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

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

App Embed Block 可以让商家在主题中，添加来自应用的一些没有 UI 界面的功能或者页面上的全局浮动元素。

你可以通过在 schema 中的 target 属性设置 head 或者 body 来决定在 HTML 的 <head> 还是 <body> 标签内注入 App Embed Block。

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

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

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

页面渲染示例：

Schema​

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

属性名类型是否必填描述
namestring是App Block 或 App Embed Block 在主题编辑器中的标题。
建议将此标题控制在 25 个字符以下，以便它们适合在主题编辑器侧边栏展示。
targetstring是

App Block 或 App Embed Block 在页面渲染的位置。

可选值：
App Block：

  • section：在主题的组件内。

App Embed Block:

  • head：在页面的 <head> 标签内。
  • body：在页面的 <body> 标签内。
stylesheetarray否要从 public 目录加载的 CSS 文件。
加载路径需添加 public，如：public/app.css。
rtl_stylesheetarray否

要从 public 目录加载的 RTL CSS 文件。
加载路径需添加 public，如：public/rtl-app.css。

注意

此属性只有在 ar（阿拉伯语）语言下才会生效。若在 ar 语言下未提供此属性，则会使用 stylesheet 属性。

javascriptarray否要从 public 目录加载的 JavaScript 文件。
加载路径需添加 public，如：public/app.js。
注入的 <script> 会自动添加 defer 属性。
resourceobject否

整合资源文件对象，可更加细致控制资源文件的加载。
若添加此属性，则 stylesheet、rtl_stylesheet、javascript 属性会无效。
示例：

{   
  "resource": {     
    "css": [       
      {
        "src": "public/app.css"       
      }     
    ],     
    "rtl_css": [       
      {         
        "src": "public/rtl_app.css"       
      }     
    ],     
    "js": [       
      {         
        "src": "public/app.js"       
      }     
    ]   
  } 
}
resource.cssarray否

CSS 资源配置数组。
属性：

  • src（必填）: 要从 public 目录加载的 CSS 文件。
  • preload（选填）：是否预加载资源。
    • true：预加载资源。
    • false（默认值）：不执行预加载。
  • position（选填）：资源注入位置。
    • "header"（默认值）：在 {{#content "header" /}} 中注入。
    • "footer"：在 {{#content "footer" /}} 中注入。
resource.rtl_cssarray否

RTL CSS 资源配置数组。
属性：

  • src（必填）: 要从 public 目录加载的 CSS 文件。
  • preload（选填）：是否预加载资源。
    • true：预加载资源。
    • false（默认值）：不执行预加载。
  • position（选填）：资源注入位置。
    • "header"（默认值）：在 {{#content "header" /}} 中注入。
    • "footer"：在 {{#content "footer" /}} 中注入。
注意

此属性只有在 ar（阿拉伯语）语言下才会生效。若在 ar 语言下未提供此属性，则会使用 resource.css 属性。

resource.jsarray否

JavaScript 资源配置数组。
属性：

  • src（必填）: 要从 public 目录加载的 JavaScript 文件。
  • preload （选填）：是否预加载资源。
    • true：预加载资源。
    • false （默认值）：不执行预加载。
  • position （选填）：资源注入位置。
    • "header"（默认值）：在 {{#content "header" /}} 中注入。
    • "footer"：在 {{#content "footer" /}} 中注入。
  • loadStrategy（选填）：资源加载策略。
    • "sync"：同步加载。
    • "async"：异步加载。
    • "defer"（默认值）：延迟执行。
templatesarray否

App Block 或 App Embed Block 可注入的页面模板。
具体页面对应参考：templates。
如果未设置，则默认为所有页面。
可选值：

  • index
  • collections_all
  • collection
  • product
  • cart
  • blog
  • article
  • 404
  • search
  • page
  • policy
  • password
  • gift_card
  • customers/login
  • customers/register
  • customers/account
  • customers/addresses
  • customers/orders
  • customers/order
  • customers/activate_account
  • customers/forgot_password
  • customers/company
classstring否

要包含在包裹标签元素的其他 CSS 类，类似于主题 组件的 class 属性。
主题应用扩展默认包含 shopline-block 类。
当 App Embed Block 的 target 值为 head 时该配置无效。

tagstring否

用于包裹 block 输出的标签，默认为 div 标签。
可选值:

  • article
  • aside
  • div（默认）
  • footer
  • header
  • section

App Block 不支持该属性配置。
当 App Embed Block 的 target 值为 head 时，该配置无效。

settingsarray否

App Block 或者 App Embed Block 的配置项。详情配置参考 settings in sections。

limitinteger否在主题的组件中可以添加 App Block 或者 App Embed Block 的最大数量。
这篇文章对你有帮助吗？
SHOPLINE
SHOPLINE
SHOPLINE Enterprise
条款协议
隐私
条款
开发者协议
LinkedInEmail
LinkedInEmail
© Copyright 2013-2026 SHOPLINE Limited.