---
title: "框架"

doc_type: static
doc_category: static
doc_version: v20270301
source_url:
  html: 'https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/integrate-apps-with-themes/theme-app-extension/structure'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/integrate-apps-with-themes/theme-app-extension/structure.md'
---
# 框架
通过本文了解主题应用扩展的结构及配置。

---


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

```json
└── 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](#omBjg) 和 [App Embed Block](#FMKEk) 的 HTML 文件。 |
| components | 包含主题应用扩展的代码片段文件，这些是你可以在 App Block<br/> 和 App Embed Block 中引用的、可重复使用的代码片段。 |
| i18n | JSON 格式的多语言环境文件，这些文件是用于存放商家和面向客户的翻译。这些文件的用法与 [主题语言环境文件](https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/theme-structure/i-18-n.md) 保持一致。 |
| public | 包含 CSS、JavaScript 和其他静态资源。<br/>可以通过 [schema](#RcWSB) 里面的 `javascript` 和 `stylesheet` 属性引入，或者使用 [asset_url](https://developer.shopline.com/zh-hans-cn/docs/sline/filter/asset-url.md) filter 进行引入。 |
| .shopline-cli.yml | 主题应用扩展的配置文件。 |


---


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

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

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

```json
<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 的示例：

![](https://s2cdn.myshopline.com/slfs/op-new/175090745875359/1746601177865-e73485ac-29b4-4c2d-922d-2e14b0409fae.png)

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

![](https://s2cdn.myshopline.com/slfs/op-new/175090747544198/1746601544128-1ff34264-c6da-47cb-9eb1-76322eb173cd.png)

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

---


## App Embed Block{#FMKEk}
App Embed Block 适用于以下类型的应用：

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



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

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

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




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

```html
<div style="position: fixed; bottom: 0; right: 0">
  <img src="{{ `comment.jpg` | asset_url() }}" />
</div>

{{#schema}}
{
  "name": "App Embed Block",
  "target": "body",
  "settings": []
}
{{/schema}}
```

页面渲染示例：

![](https://s2cdn.myshopline.com/slfs/op-new/175090751435544/1746604849862-9e90ffb3-5040-472f-9690-ef16c131f1ac.png)

---


## Schema{#RcWSB}
App Block 和 App Embed Block 的 schema 类似于 [主题组件 schema](https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/theme-structure/sections.md#HWiNw)。它支持以下属性，其中一些属性是 App Block 和 App Embed Block 所独有的：

<table>
  <tr>
    <th>属性名</th>
    <th>类型</th>
    <th>是否必填</th>
    <th>描述</th>
  </tr>
  <tr>
    <td>name</td>
    <td>string</td>
    <td>是</td>
    <td>App Block 或 App Embed Block 在主题编辑器中的标题。<br/> 建议将此标题控制在 25 个字符以下，以便它们适合在主题编辑器侧边栏展示。</td>
  </tr>
  <tr>
    <td>target</td>
    <td>string</td>
    <td>是</td>
    <td>
      App Block 或 App Embed Block 在页面渲染的位置。<br/>
        
       可选值：<br/>
        App Block：<br/>
         
         - `section`：在主题的组件内。<br/>
       
        App Embed Block:   
    - `head`：在页面的 `<head>` 标签内。<br/>
    - `body`：在页面的 `<body>` 标签内。
    </td>
  </tr>
  <tr>
    <td>stylesheet</td>
    <td>array</td>
    <td>否</td>
    <td>要从 public 目录加载的 CSS 文件。<br/>加载路径需添加 `public`，如：`public/app.css`。</td>
  </tr>
<tr>
    <td>rtl_stylesheet</td>
    <td>array</td>
    <td>否</td>
    <td>
      要从 public 目录加载的 RTL CSS 文件。<br/>
      加载路径需添加 `public`，如：`public/rtl-app.css`。
      > **注意**
>
> 此属性只有在 `ar`[（阿拉伯语）](https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/best-practice/arabic.md)语言下才会生效。若在 `ar` 语言下未提供此属性，则会使用 `stylesheet` 属性。
      </td>
  </tr>
  <tr>
    <td>javascript</td>
    <td>array</td>
    <td>否</td>
    <td>要从 public 目录加载的 JavaScript 文件。<br/>加载路径需添加 `public`，如：`public/app.js`。<br/>注入的 `<script>` 会自动添加 `defer` 属性。</td>
  </tr>
<tr>
    <td>resource</td>
    <td>object</td>
    <td>否</td>
    <td>
      整合资源文件对象，可更加细致控制资源文件的加载。<br/>
      若添加此属性，则 `stylesheet`、`rtl_stylesheet`、`javascript` 属性会无效。<br/>
      示例：<br/>
        ```json
      {   
          "resource": {     
            "css": [       
              {
                "src": "public/app.css"       
              }     
            ],     
            "rtl_css": [       
              {         
                "src": "public/rtl_app.css"       
              }     
            ],     
            "js": [       
              {         
                "src": "public/app.js"       
              }     
            ]   
          } 
        } 
        ```  
        </td>
  </tr>
  <tr>
    <td>resource.css</td>
    <td>array</td>
    <td>否</td>
    <td>
      CSS 资源配置数组。<br/> 
      属性：<br/>
    - `src`（必填）: 要从 public 目录加载的 CSS 文件。<br/>
    - `preload`（选填）：是否预加载资源。<br/>
       - `true`：预加载资源。
       - `false`（默认值）：不执行预加载。
    - `position`（选填）：资源注入位置。<br/>
       - `"header"`（默认值）：在 `{{#content "header" /}}` 中注入。
       - `"footer"`：在 `{{#content "footer" /}}` 中注入。
    </td>
  </tr>
<tr>
    <td>resource.rtl_css</td>
    <td>array</td>
    <td>否</td>
    <td>
      RTL CSS 资源配置数组。<br/> 
      属性：<br/>
    - `src`（必填）: 要从 public 目录加载的 CSS 文件。<br/>
    - `preload`（选填）：是否预加载资源。<br/>
       - `true`：预加载资源。
       - `false`（默认值）：不执行预加载。
    - `position`（选填）：资源注入位置。<br/>
       - `"header"`（默认值）：在 `{{#content "header" /}}` 中注入。
       - `"footer"`：在 `{{#content "footer" /}}` 中注入。
    > **注意**
>
> 此属性只有在 `ar`[（阿拉伯语）](https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/best-practice/arabic.md)语言下才会生效。若在 `ar` 语言下未提供此属性，则会使用 `resource.css` 属性。
      </td>
  </tr>
  <tr>
    <td>resource.js</td>
    <td>array</td>
    <td>否</td>
    <td>
      JavaScript 资源配置数组。<br/> 
      属性：<br/>
    - `src`（必填）: 要从 public 目录加载的 JavaScript 文件。<br/>
    - `preload` （选填）：是否预加载资源。<br/>
       - `true`：预加载资源。
       - `false` （默认值）：不执行预加载。
    - `position` （选填）：资源注入位置。<br/>
       - `"header"`（默认值）：在 `{{#content "header" /}}` 中注入。
       - `"footer"`：在 `{{#content "footer" /}}` 中注入。
    - `loadStrategy`（选填）：资源加载策略。<br/>
       - `"sync"`：同步加载。
       - `"async"`：异步加载。
       - `"defer"`（默认值）：延迟执行。
    </td>
  </tr>
  <tr>
    <td>templates</td>
    <td>array</td>
    <td>否</td>
    <td>
      App Block 或 App Embed Block 可注入的页面模板。<br/> 具体页面对应参考：<a href="https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/theme-structure/templates">templates</a>。<br/> 如果未设置，则默认为所有页面。<br/>
      可选值：<br/>
      - `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`
    </td>
  </tr>
  <tr>
    <td>class</td>
    <td>string</td>
    <td>否</td>
    <td>
      要包含在包裹标签元素的其他 CSS 类，类似于主题 [组件的 class 属性](https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/theme-structure/sections.md#S9g2T)。<br/>
      主题应用扩展默认包含 `shopline-block` 类。<br/>
      当 App Embed Block 的 `target` 值为 `head` 时该配置无效。
    </td>
  </tr>
  <tr>
    <td>tag</td>
    <td>string</td>
    <td>否</td>
    <td>
      用于包裹 block 输出的标签，默认为 `div` 标签。<br/>
      可选值:<br/>
     - `article`
      - `aside`
      - `div`（默认）
      - `footer`
      - `header`
      - `section`
 
      App Block 不支持该属性配置。<br/>
      当 App Embed Block 的 `target` 值为 `head` 时，该配置无效。
    </td>
  </tr>
  <tr>
    <td>settings</td>
    <td>array</td>
    <td>否</td>
    <td>
      App Block 或者 App Embed Block 的配置项。详情配置参考 <a href="https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/theme-structure/sections">settings in sections</a>。
    </td>
  </tr>
  <tr>
    <td>limit</td>
    <td>integer</td>
    <td>否</td>
    <td>在主题的组件中可以添加 App Block 或者 App Embed Block 的最大数量。</td>
  </tr>
</table>