---
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/theme-and-editor-interaction/editor-controls'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/theme-and-editor-interaction/editor-controls.md'
---
# 编辑器控件

编辑器控件是指在主题内通过 schema tag 定义的 settings 属性，这些属性定义的控件类型会展示在主题编辑器中。

---


## 基础控件类型{#xAOsu}

### 标准属性{#Ov6JJ}
以下是每个编辑器控件的标准属性。根据控件类型的不同，会有额外的专有属性。

| 属性 | 描述 | 是否必填 |
| --- | --- | --- |
| type | 控件类型 | 是 |
| id | 配置 ID，用于访问配置值 | 是 |
| label | 配置标签，将呈现在主题编辑器中 | 是 |
| default | 配置的默认值 | 否 |
| info | 配置的提示信息 | 否 |



### text{#eBKsA}
此类型的控件会输出一个单行文本输入框。

额外属性：

| **属性** | **描述** | **是否必填** |
| --- | --- | --- |
| placeholder | 输入框的占位文本 | 否 |


此控件可用于单行文本的输入，例如组件的标题。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Title",
      "default": "my section title",
      "placeholder": "please enter title"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://s2cdn.myshopline.com/slfs/op-new/175204397464950/1741330017768-58b69edc-468c-4153-a675-3f6cb762f9fc.png)


当访问此控件的配置值时，数据以 [string](https://developer.shopline.com/zh-hans-cn/docs/sline/basics.md#UpnuY) 类型的形式返回。


### textarea{#v9t0Z}
此类型的控件会输出一个多行文本输入框。

额外属性：

| **属性** | **描述** | **是否必填** |
| --- | --- | --- |
| placeholder | 输入框占位文本 | 否 |
| limit | 文本输入最大长度 | 否 |


此控件可用于多行文本的输入，例如组件的内容。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "textarea",
      "id": "content",
      "label": "Content",
      "default": "my section content",
      "placeholder": "please enter content",
      "limit": 500
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://s2cdn.myshopline.com/slfs/op-new/175204406521305/1741334729460-ad8fcc91-bef3-4bd2-a7b9-d330ff00f0c7.png)

当访问此控件的配置值时，数据以 [string](https://developer.shopline.com/zh-hans-cn/docs/sline/basics.md#UpnuY) 类型的形式返回。


### richtext{#fiT6c}
此类型的控件会输出一个富文本输入框。会输出具有以下基本格式的文本：

+ 加粗文本
+ 斜体文本
+ 超链接
+ 段落

此控件可用于多类型内容的正文文本展示，例如博客文章的正文。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "richtext",
      "id": "content",
      "label": "Content",
      "default": "content"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://s2cdn.myshopline.com/slfs/op-new/175204413532050/1741335384406-3bfb8e8b-59b8-4e75-976e-d6c96624e897.png)

当访问此控件的配置值时，数据以 [string](https://developer.shopline.com/zh-hans-cn/docs/sline/basics.md#UpnuY) 类型的形式返回。


### range{#V2UPS}
此控件会输出一个滑动控制器。

额外属性：

| **属性** | **描述** | **是否必填** |
| --- | --- | --- |
| min | 最小值 | 是 |
| max | 最大值 | 是 |
| step | 滑块步长，设置的值必须大于 0，并且可被最大值和最小值的差值整除。 | 是 |
| unit | 输入值的单位。此单位将展示在控件上 | 否 |


> **注意**
>
> + default 属性是必填的。
> + min、max、step 和 unit 属性必须是数字类型。

此控件可用于调整多个数值，例如组件的宽度。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "range",
      "id": "width",
      "label": "Width",
      "default": 100,
      "min": 100,
      "max": 1000,
      "step": 10,
      "unit": "px"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://s2cdn.myshopline.com/slfs/op-new/175204421579950/1741589195491-ecba606b-f345-4115-818f-9e1aa860380d.png)

当访问此控件的配置值时，数据以 [string](https://developer.shopline.com/zh-hans-cn/docs/sline/basics.md#UpnuY) 类型的形式返回。


### select{#b8g0k}
此控件会输出一个下拉选择框。

额外属性：

| **属性** | **描述** | **是否必填** |
| --- | --- | --- |
| options | 选项数组，数组的每项包括<br/>• `label`：名称<br/>• `value`：值 | 是 |


此控件可用于选项数量多的单选场景，例如图标选择。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "select",
      "id": "icon",
      "label": "Icon",
      "default": "none",
      "options": [
        {
          "label": "none",
          "value": "none"
        },
        {
          "label": "pay",
          "value": "pay"
        },
        {
          "label": "package",
          "value": "package"
        },
        {
          "label": "email",
          "value": "email"
        },
        {
          "label": "position",
          "value": "position"
        },
        {
          "label": "customer",
          "value": "customer"
        },
        {
          "label": "chat",
          "value": "chat"
        },
        {
          "label": "gift",
          "value": "gift"
        },
        {
          "label": "phone",
          "value": "phone"
        },
        {
          "label": "faq",
          "value": "faq"
        },
        {
          "label": "logistics",
          "value": "logistics"
        },
        {
          "label": "discount",
          "value": "discount"
        }
      ]
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://s2cdn.myshopline.com/slfs/op-new/175204426226644/1741590514587-ef60ac01-2223-4608-8327-1e9d4e13d8c2.png)

当访问此控件的配置值时，数据以 [string](https://developer.shopline.com/zh-hans-cn/docs/sline/basics.md#UpnuY) 类型的形式返回。


### switch{#k0XnP}
此控件会输出一个开关控件。

此控件可用于切换功能的开启和关闭，例如是否展示国家选择器。

> **注意**
>
> 如果没有指定 default 的值，则默认为 false。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "switch",
      "id": "show_country_selector",
      "label": "Show country selector",
      "default": true
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701950998287/1741591291884-f5363b64-358b-4155-930c-4a73a636e87b.png)

当访问此控件的配置值时，数据以 [boolean](https://developer.shopline.com/zh-hans-cn/docs/sline/basics.md#DeWGb) 类型的形式返回。


### text_align{#D3h8p}
此控件会输出一个文本在水平方向上对齐方式的选择控件。

此控件可用于文本对齐方式，例如标题在水平方向上的对齐方式。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "text_align",
      "id": "text_align",
      "label": "Text align",
      "default": "left"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://s2cdn.myshopline.com/slfs/op-new/175204447690525/1741591893885-ad9fe748-1a66-4976-9f86-e5f8e6ebc0af.png)

当访问此控件的配置值时，数据以 [string](https://developer.shopline.com/zh-hans-cn/docs/sline/basics.md#UpnuY) 类型的形式返回。

此控件返回的枚举值如下，也是 default 属性可以设置的值：

+ left
+ center
+ right


### vertical_align{#pZKIH}
此控件会输出一个垂直方向上对齐方式的选择控件。

此控件可用于垂直交叉轴上元素的对齐方式，例如组件区块之间的对齐方式。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "vertical_align",
      "id": "vertical_align",
      "label": "Vertical align",
      "default": "top"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://s2cdn.myshopline.com/slfs/op-new/175204451938951/1741593470788-75a37bad-c7a2-496d-b961-0d2357398cbd.png)

当访问此控件的配置值时，数据以 [string](https://developer.shopline.com/zh-hans-cn/docs/sline/basics.md#UpnuY) 类型的形式返回。

此控件返回的枚举值如下，也是 default 属性可以设置的值：

+ top
+ middle
+ bottom


### horizontal_align{#chzBd}
此控件会输出一个水平方向上对齐方式的选择控件。

此控件可用于水平主轴上元素的对齐方式，例如组件区块之间的对齐方式。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "horizontal_align",
      "id": "horizontal_align",
      "label": "Horizontal align",
      "default": "left"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![image-7.png](https://s2cdn.myshopline.com/slfs/op-new/177832228636516/image-7.png)

当访问此控件的配置值时，数据以 [string](https://developer.shopline.com/zh-hans-cn/docs/sline/basics.md#UpnuY) 类型的形式返回。

此控件返回的枚举值如下，也是 default 属性可以设置的值：

+ left
+ center
+ right


### url{#wD7dq}
此类型的控件会输出一个统一的 URL 配置器，供商家在构建在线商店时配置跳转目标。

商家可以在输入框中输入外部的 URL、相对路径，或是一个电话拨号。同时，商家也可以在下拉选择器中选择其网站内的预设页面。

支持页面的枚举如下：

+ 首页
+ 商品分类页
+ 商品详情页
+ 自定义页面
+ 政策页
+ 博客集合页面
+ 博客文章页
+ 个人中心页
+ 购物车页

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "url",
      "id": "url",
      "label": "Url"
    },
    {
      "type": "url",
      "id": "tel",
      "label": "Tel"
    }
  ],
  "presets": [
    {
      "name": "My Section",
      "settings": {
        "tel": "tel:+86123456789"
      }
    }
  ]
}
```

输出：

![image.png](https://s2cdn.myshopline.com/slfs/op-new/176594018163971/image.png)
![image2.png](https://s2cdn.myshopline.com/slfs/op-new/176593998279806/image2.png)


当访问此控件的配置值时，数据会以以下形式之一返回：

+ 字符串 (String)：商家直接在输入框中填写的 URL 字符串。例如，`tel:+1123-***-7890` 或 `https://example.com`。
+ 资源对象 (Resource object)：商家在下拉选择器中选择预设页面时，系统会返回一个包含页面类型和 ID 的结构化对象。
+ 空字符串 (Empty string)：如果商家没有输入任何内容或选择任何页面，则返回空字符串。


### color{#RObRI}
此类型的控件会输出一个颜色选择器控件。

你可以在输入框中输入颜色色值，或者使用颜色面板选择器来选择所需要的颜色。

此控件可用于控制元素的各种颜色，例如页面背景颜色。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "color",
      "id": "text_color",
      "label": "Text color",
      "default": "#ffffff"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701951330069/1741676428546-3c5f956b-c9a7-4914-a8ca-41d6483e53e9.png)


当访问此控件的配置值时，数据会以以下形式之一返回：

+ [color](https://developer.shopline.com/zh-hans-cn/docs/sline/object/color.md) object
+ 如果未进行选择，则返回空。


### color_background{#F0U67}
此类型的控件会输出一个渐变颜色选择器控件。

你可以在控件中选择预设的渐变颜色方案，也可以自行调整渐变颜色方案。

此控件可用于控制元素的渐变背景颜色，例如页面背景颜色。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "color_background",
      "id": "color_background",
      "label": "Background color",
      "default": ""
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

> **注意**
>
> 此控件的 default 属性设置为空字符串，会以无颜色的进行展示。

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701951162299/1741681907141-04f143f7-0f93-47c6-b737-65b6e085274b.png)

当访问此控件的配置值时，数据会以 CSS 代码中的线性渐变或者径向渐变返回：

+ [linear-gradient()](https://developer.mozilla.org/zh-CN/docs/Web/CSS/gradient/linear-gradient)
+ [radial-gradient()](https://developer.mozilla.org/zh-CN/docs/Web/CSS/gradient/radial-gradient)


### color_scheme{#IeZGc}
此类型的控件会输出一个包含所有可用主题配色方案的选择器，并展示所选配色方案的预览效果。

选择器中的主题配色方案通过 `color_scheme_group` 设置项进行定义。

你可以将配色方案应用到全局主题配置、组件和区块中。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "color_scheme",
      "id": "color_scheme",
      "label": "Color scheme",
      "default": "scheme-1"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701950970344/1746523754260-da6aabff-1dde-424a-8d59-fb698ad64eef.png)

在访问此控件设置的值时，SHOPLINE 会从 `color_scheme_group` 中返回选中的 [color_scheme](https://developer.shopline.com/zh-hans-cn/docs/sline/object/color-scheme.md) object。


### color_scheme_group{#Leu90}
此类型的控件会输出一个颜色方案，你可以通过此控件修改主题的配色方案。

颜色方案中定义的颜色只能在 `settings.schema.json` 中添加。

```json
{
  "type": "color_scheme_group",
  "id": "color_schemes",
  "definition": [
    {
      "type": "color_background",
      "id": "color_background",
      "label": "t:settings_schema.color.settings.color_schemes.definition_0.label",
      "default": "#F3F2E0"
    },
    {
      "type": "color",
      "id": "color_text",
      "label": "t:settings_schema.color.settings.color_schemes.definition_1.label",
      "default": "#3D3819"
    },
    {
      "type": "color",
      "id": "color_light_text",
      "label": "t:settings_schema.color.settings.color_schemes.definition_2.label",
      "default": "#726C4A"
    },
    {
      "type": "color",
      "id": "color_entry_line",
      "label": "t:settings_schema.color.settings.color_schemes.definition_3.label",
      "default": "#DDDDDD"
    },
    {
      "type": "color",
      "id": "color_button_background",
      "label": "t:settings_schema.color.settings.color_schemes.definition_4.label",
      "default": "#3D3819"
    },
    {
      "type": "color",
      "id": "color_button_text",
      "label": "t:settings_schema.color.settings.color_schemes.definition_5.label",
      "default": "#F3F2E0"
    },
    {
      "type": "color",
      "id": "color_button_secondary_background",
      "label": "t:settings_schema.color.settings.color_schemes.definition_6.label",
      "default": "#F3F2E0"
    },
    {
      "type": "color",
      "id": "color_button_secondary_text",
      "label": "t:settings_schema.color.settings.color_schemes.definition_7.label",
      "default": "#3D3819"
    },
    {
      "type": "color",
      "id": "color_button_secondary_border",
      "label": "t:settings_schema.color.settings.color_schemes.definition_8.label",
      "default": "#726C4A"
    },
    {
      "type": "color",
      "id": "color_button_text_link",
      "label": "t:settings_schema.color.settings.color_schemes.definition_9.label",
      "default": "#3D3819"
    }
  ],
  "role": {
    "text": "color_text",
    "background": {
      "solid": "color_background"
    },
    "primary_button": "color_button_background",
    "primary_button_border": "color_entry_line",
    "secondary_button": "color_button_secondary_background",
    "secondary_button_border": "color_button_secondary_border"
  }
}
```

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701951427848/1746525485203-e0d416ce-504f-4ba3-93fc-9a341cf08391.png)

在 `definition` 中定义颜色控件，颜色控件的类型仅支持以下类型：

+ color
+ color_background

`role` 字段会输出配色方案的预览。每个字段代表预览图上的位置，每个字段的值是在 `definition` 里面定义控件的 `id` 值。

![](https://cdn.myshopline.com/sl/slfs/sl-new/174702035481608/1747020270879-361cdee6-c95b-42b5-a158-3e6d6c0075cb.png)

`role` 字段定义规则：

| Role 字段 | 类型 | 描述 | 是否必填 |
| --- | --- | --- | --- |
| background | •  string<br/>•  \{<br/>        solid: string;<br/>        gradient: string;<br/>      \} | 渲染背景颜色 | 是 |
| text | string | 渲染文本颜色 | 是 |
| primary_button | string | 渲染文本下方第一个按钮颜色 | 是 |
| secondary_button | string | 渲染文本下方第二个按钮颜色 | 是 |
| primary_button_border | string | 渲染文本下方第一个按钮的边框颜色 | 是 |
| secondary_button_border | string | 渲染文本下方第二个按钮的边框颜色 | 是 |



### image{#p8qLE}
此类型的控件会输出一个图片选择器。

此控件可以直接选择 SHOPLINE 商家后台图片库内的图片，并且可以选择上传新的图片。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "image",
      "id": "image",
      "label": "Image"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701951076834/1741684786206-7bc1a818-41e5-48c8-b47e-5e8209e54657.png)


当访问此控件的配置值时，数据会以 [image](https://developer.shopline.com/zh-hans-cn/docs/sline/object/image.md) object 的形式返回。


### font{#WhnmF}
此类型的控件会输出一个字体选择器。

你可以使用此控件来给页面注入不同的字体，例如页面的标题字体。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "font",
      "id": "title_font",
      "label": "Title font",
      "default": "Brygada 1918:400"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

> **提示**
>
> 此控件的 default 属性规则为：`字体:字重`

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701951378844/1741686997093-2422fac4-4d10-4c34-8b6b-c18588f68f08.png)

当访问此控件的配置值时，数据以 [font](https://developer.shopline.com/zh-hans-cn/docs/sline/object/font.md?_highlight=font) object 类型的形式返回。可与 [font_modify](https://developer.shopline.com/zh-hans-cn/docs/sline/filter/font-modify.md?_highlight=font) 和 [font_face](https://developer.shopline.com/zh-hans-cn/docs/sline/filter/font-face.md?_highlight=font) 等字体相关的 filter 进行搭配使用。


### article{#dYj5m}
此类型的控件会输出一个博客文章选择器。

此控件可以用于选择需要的博客文章进行展示。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "article",
      "id": "article",
      "label": "Article"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701951252627/1741747449412-bb68479d-beb1-4957-b9ab-41551d8a1a0f.png)

当访问此控件的配置值时，数据会以 [article](https://developer.shopline.com/zh-hans-cn/docs/sline/object/article.md) object 的形式进行返回。


### blog{#MAqVL}
此类型的控件会输出一个博客集合选择器。

此控件可以用于选择需要的博客集合进行展示。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "blog",
      "id": "blog",
      "label": "blog"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701950959786/1741749172121-c186ff1d-91bc-45b4-bc4e-bb99b626ea29.png)

当访问此控件的配置值时，数据会以 [blog](https://developer.shopline.com/zh-hans-cn/docs/sline/object/blog.md) object 的形式进行返回。


### collection{#hwIJ6}
此类型的控件会输出一个商品集合选择器。

你可以选择店铺里面所有可用的商品的集合。

此控件可以用于选择需要展示的商品集合，例如在首页展示指定商品集合的前 10 个商品。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "collection",
      "id": "collection",
      "label": "Collection"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701951411728/1741749927360-469c552a-4893-44bb-8e8f-6d5a910aece7.png)

当访问此控件的配置值时，数据会以 [collection](https://developer.shopline.com/zh-hans-cn/docs/sline/object/collection.md) object 的形式进行返回。


### product{#EkIYe}
此类型的控件会输出一个商品选择器。

此控件可以用于选择需要的商品进行展示，例如在首页展示单个商品的详情。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "product",
      "id": "product",
      "label": "Product"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701951476090/1741761929734-dc2805b7-c141-4b92-98c1-6ae4035189b3.png)

当访问此控件的配置值时，数据会以 [product](https://developer.shopline.com/zh-hans-cn/docs/sline/object/product.md) object 的形式进行返回。

### product_id
此类型的控件会输出一个商品选择器。

此控件可以用于选择需要的商品进行展示，例如在首页展示单个商品的详情。

该控件主要用于 CSR 场景，可使用 `product_id` 获取对应的商品详情以进行渲染。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "product_id",
      "id": "product_id",
      "label": "Product ID"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```
![image-18.png](https://cdn.myshopline.com/sl/slfs/sl-new/178045513790223/image-18.png)

当访问此控件的配置值时，数据会以实际存储值返回，为 `product_id`。

### product_list{#HKgVR}
此类型的控件会输出一个商品列表选择器。

此控件可用于直接选择多个指定商品，组成一个商品列表，用于展示如首页商家推荐的多款商品。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "product_list",
      "id": "product_list",
      "label": "Product list"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![image-8.png](https://s2cdn.myshopline.com/slfs/op-new/177832245839549/image-8.png)

当访问此控件的配置值时，数据会以 [product](https://developer.shopline.com/zh-hans-cn/docs/sline/object/product.md) object 的数组形式进行返回。


### page{#Nbabt}
此类型的控件会输出一个自定义页面选择器。

此控件可以用于选择需要的自定义页面进行展示，例如在首页展示自定义页面的信息。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "page",
      "id": "page",
      "label": "Page"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701951445637/1741771169536-a7f2f889-1279-46c7-9918-cfe38fdafd41.png)

当访问此控件的配置值时，数据会以 [page](https://developer.shopline.com/zh-hans-cn/docs/sline/object/page.md) object 的形式进行返回。


### menu{#B2mAi}
此类型的控件会输出一个菜单导航选择器。

此控件可以直接选择店铺内所有可用的菜单导航。

此控件可用于菜单导航的展示，例如页头上展示的菜单导航。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "menu",
      "id": "menu",
      "label": "Menu"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701951476832/1741847663038-bd9496c2-079c-45cd-9b14-2bc4cc10058c.png)

当访问此控件的配置值时，数据会以 menu object 的形式进行返回。


### video{#pKucM}
此类型的控件会输出一个视频选择器。

此控件可直接选择 SHOPLINE 商家后台文件库中的可用视频或上传视频，用于如首页展示商品视频等场景。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "video",
      "id": "video",
      "label": "Video"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![image-11.png](https://s2cdn.myshopline.com/slfs/op-new/177846704653014/image-11.png)

当访问此控件的配置值时，数据会以 [video](https://developer.shopline.com/zh-hans-cn/docs/sline/object/video.md) object 的形式进行返回。


### external_video{#pqUH5}
此类型的控件会输出一个 URL 输入框。

额外属性：

| **属性** | **描述** | **是否必填** |
| --- | --- | --- |
| format | 若添加此属性，则会校验输入的文本是否为此控件支持的视频提供商。<br/>支持的视频提供商列表<br/>• youtube<br/>• vimeo<br/>枚举值为 <br/>• video | 否 |
| placeholder | 输入框的占位文本 | 否 |


此控件可用于获取来自 YouTube 或 Vimeo 视频的信息，一般与 [external_video_tag](https://developer.shopline.com/zh-hans-cn/docs/sline/tag/external-video-tag.md?_highlight=external_video_url&_highlight=filter) tag 和 [external_video_url](https://developer.shopline.com/zh-hans-cn/docs/sline/filter/external-video-url.md) filter 进行搭配使用：

```json
{{#external_video_tag section.settings.external_video | external_video_url() /}}
```

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "external_video",
      "id": "external_video",
      "label": "External video"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701951421217/1741855055010-fc0bedaf-748a-455d-9213-397e42c57fb2.png)

当访问此控件的配置值时，数据会以 [external_video](https://developer.shopline.com/zh-hans-cn/docs/sline/object/external-video.md) object 的形式进行返回。


### padding{#VPrdJ}
此类型的控件会输出一个边距输入框。

此控件可用于存储桌面端以及移动端的上、下、左、右四个方向的数值。一般用于设置容器元素的内边距。

此控件的 default 值的结构是一个对应桌面端和移动端的对象，每个对象都有四个方向的属性。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "padding",
      "id": "padding",
      "label": "Padding",
      "default": {
        "pc":{
          "left":10,
          "right":10,
          "top":10,
          "bottom":10
        },
        "mobile":{
          "left":10,
          "right":10,
          "top":10,
          "bottom":10
        }
      }
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![image-9.png](https://s2cdn.myshopline.com/slfs/op-new/177832253710297/image-9.png)

当访问此控件的配置值时，数据会以 default 值的数据结构形式进行返回。


### sline{#NBcaz}
此类型的控件会输出一个接受 [Sline](https://developer.shopline.com/zh-hans-cn/docs/sline/sline-overview.md) 模板语言的代码输入框。

此控件可让商家使用 sline 语法输入自定义的内容，例如在首页特定组件里面注入额外信息。

额外属性：
| **属性** | **描述** | **是否必填** |
| --- | --- | --- |
| limit | 文本输入最大长度 | 否 |

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "sline",
      "id": "sline",
      "label": "Sline"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701951136918/1741858938881-1a0c0be6-1aaf-4a66-847c-4c4ae13eea6c.png)

当访问此控件的配置值时，数据会以 [string](https://developer.shopline.com/zh-hans-cn/docs/sline/basics.md#UpnuY) 形式进行返回。


### html{#XH1q0}
此类型的控件会输出一个接受 HTML 语言的多行文本输入框。

额外属性：

| **属性** | **描述** | **是否必填** |
| --- | --- | --- |
| placeholder | 输入框的占位文本 | 否 |
| limit | 文本输入最大长度 | 否 |

此控件可让商家使用 HTML 语法输入自定义的内容，例如在首页特定组件里面编写 HTML。

示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "html",
      "id": "html",
      "label": "HTML"
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701951432197/1741860544069-309ed15a-5606-4e2e-b87f-01769f8a416e.png)

当访问此控件的配置值时，数据会以 [string](https://developer.shopline.com/zh-hans-cn/docs/sline/basics.md#UpnuY) 形式进行返回。


### payment_icon{#HhBp7}
此类型的控件会输出一个支付图标的列表。

此控件可用于选择展示当前店铺所支持的支付方式。

此控件的 default 属性值的一个 JSON 结构，用于在主题编辑器中展示默认选择的 icon 列表。

| **default 属性名** | **default 属性值** | **描述** |
| --- | --- | --- |
| show | • `true`：展示<br/>• `false`：不展示 | 是否展示支付图标 |
| pay_channel_list | [<br/>  \{<br/>    "type": \<Type>,<br/>    "show": \<Boolean><br/>  \}<br/>] | 包含支付类型图标的列表 |


示例代码：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "payment_icon",
      "id": "payment_icon",
      "label": "Payment icon",
      "default": {
        "show": true,
        "pay_channel_list": [
          {
            "type": "visa",
            "show": true
          },
          {
            "type": "master-card",
            "show": true
          },
          {
            "type": "master-card2",
            "show": true
          },
          {
            "type": "visa-electron",
            "show": true
          }
        ]
      }
    }
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701950989131/1741860759726-93d4dbdf-a130-4ad4-8f75-b60f00c3ae94.png)

当访问此控件的配置值时，一般需要和 [payment_type_svg](https://developer.shopline.com/zh-hans-cn/docs/sline/tag/payment-type-svg.md?_highlight=payment_type_svg) tag 搭配使用：

```html
<div class="footer__payment-icons">
  {{#for pay_channel in block.settings.payment_icons.pay_channel_list}}
    {{#payment_type_svg pay_channel.type /}}
  {{/for}}
</div>
```


### favicon{#N1jWF}
此类型的控件会输出一个上传网站图标控件。

此控件可用于选择展示网站的图标，一般在 `theme.schema.json` 进行设置：

```json
{
  ...
  "schemas": [
    {
      "name": "website icon",
      "settings": [
        {
          "type": "favicon",
          "id": "favicon_image",
          "label": "website icon",
        }
      ]
    }
  ]
}
```

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701951130300/1742806178226-807864d0-6760-461d-8537-984618a61078.png)

在 layout/theme.html 设置网站图标：

```html
<!DOCTYPE html>
<html>
  <head>
    {{#if settings.favicon_image}}
      <link rel="icon" type="image/png" href="{{settings.favicon_image}}" />
    {{/if}}
  </head>
  <body>
    ...
  </body>
</html>
```

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701951310950/1742806567456-b11ae49a-f62f-46d3-a16c-c7e5c9884a13.png)


### date

此类型控件用于展示或选择日期信息，适用于所有与日期相关的配置场景。

输出采用美式日期格式：`MM-DD-YYYY`。

示例代码：

```json
{
  "name": "countdown-date",
  "tag": "",
  "settings": [
    {
      "type": "date",
      "id": "deadline",
      "label": "Deadline"
    }
  ]
}
```

输出：
![image3.png](https://s2cdn.myshopline.com/slfs/op-new/176594163412083/image3.png)


### datetime

此类型控件用于展示或选择完整的日期与时间信息，适用于所有需要精确到分钟的配置场景。

输出采用美式日期时间格式：`MM-DD-YYYY HH:mm` 。例如：`12-25-2023 14:30` 。

示例代码：

```json
{
  "name": "countdown-datetime",
  "tag": "",
  "settings": [
    {
      "type": "datetime",
      "id": "deadline",
      "label": "Deadline"
    }
  ]
}
```

输出：
![image4.png](https://s2cdn.myshopline.com/slfs/op-new/176594176569409/image4.png)


---


## 展示控件类型{#XlDow}
展示类型的控件只能用于展示信息，一般用于组织分组展示基础控件。


### group_header{#FSyw1}
此类型的控件会新增一个标题元素，并之后的配置项设置为一组。

此控件的配置属性：

| 属性 | 描述 | 是否必填 |
| --- | --- | --- |
| type | 控件类型 | 是 |
| label | 配置标签，将呈现在主题编辑器中 | 是 |
| info | 配置的提示信息 | 否 |


例如将以下配置进行分组：

```json
{
  "name": "My Section",
  "settings": [
    {
      "type": "group_header",
      "label": "Desktop"
    },
    {
      "type": "range",
      "label": "desktop columns",
      "id": "desktop_columns",
      "default": 2,
      "min": 1,
      "max": 8,
      "step": 1
    },
    {
      "type": "group_header",
      "label": "Mobile"
    },
    {
      "type": "range",
      "label": "mobile columns",
      "id": "mobile_columns",
      "default": 2,
      "min": 1,
      "max": 8,
      "step": 1
    },
  ],
  "presets": [
    {
      "name": "My Section"
    }
  ]
}
```

输出：

![](https://cdn.myshopline.com/sl/slfs/sl-new/174701951077925/1742805038753-18db5c00-3451-49e5-8762-a060768b1d6a.png)

> **提示**
>
> `group_header` 的分组逻辑：按顺序渲染，当类型为 `group_header` 时，接下来的配置项都会在此分组下，直到遇到下一个 `group_header` 类型的配置。