---
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/development-tools/theme-editor'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/development-tools/theme-editor.md'
---
# 主题编辑器

主题编辑器是一款编辑店铺主题的工具，允许商家自定义店铺的内容与样式，并能实时预览主题效果。

作为主题开发者，可以通过提供主题配置项，以及模块化的组件和区块功能，让商家在主题编辑器中灵活地个性化主题。



![image-15.png](https://cdn.myshopline.com/sl/slfs/sl-new/178036605259647/image-15.png)


---

## 访问主题编辑器
### 商家通过后台访问
商家可以在 SHOPLINE 商家后台访问主题编辑器，步骤如下：

1. 登录并进入 SHOPLINE 商家后台，然后点击 **在线商店** > **店铺设计**。
2. 找到需要编辑的主题，然后点击 **设计**。

### 开发者预览主题访问
作为开发者，若想了解商家看到的主题呈现效果，你可以在主题编辑器中预览主题。开发过程中，可通过以下方式访问主题编辑器：

+ **实时预览**：使用 SHOPLINE CLI 的 [serve](https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/development-tools/cli/theme-commands.md#X1eER) 命令将主题作为 [开发主题](https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/development-tools/cli/overview.md#开发中主题) 来运行，进行实时预览开发。
+ **同步至主题库**：使用 SHOPLINE CLI 的 [push](https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/development-tools/cli/theme-commands.md#Gnj3S) 命令将主题推送到商店。
+ **手动安装预览**：使用 SHOPLINE CLI 的 [package](https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/development-tools/cli/theme-commands.md#yH4zB) 命令将主题打包成 zip 文件，在 SHOPLINE 商家后台前往 **店铺设计** > **添加主题** > **上传主题** 进行上传。

---

## 主题配置的定义与存储
商家在主题编辑器中可以使用的配置由主题控制。配置的定义位置与保存位置如下表所示：

| 配置类型 | 定义位置 | 保存位置 |
| --- | --- | --- |
| 全局配置 | [theme.schema.json](https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/theme-structure/theme-schema-json.md) 文件 | [theme.config.json](https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/theme-structure/theme-config-json.md) 文件 |
| 组件配置 | 组件文件内 ```{{#schema}}``` tag 下的 [settings](https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/theme-structure/sections.md#HWiNw) 配置 | [templates](https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/theme-structure/templates.md#kwgVv) 目录下对应的页面 template 文件 |
| 区块配置 | 区块文件内 ```{{#schema}}``` tag 下的 [settings](https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/theme-structure/blocks.md#xHpGT) 配置 | 嵌套于所属组件配置中，保存至页面 template 文件 |


---

## 主题与主题编辑器集成
在主题编辑器中自定义组件时，组件的 HTML 会直接在现有 DOM 中动态添加、移除或重新渲染，无需整页刷新。但页面初次加载时执行的相关 JavaScript 不会自动再次运行。

同时，要确保商家在选择组件或区块时，其选中状态能够保持。例如，选择轮播图组件时，应自动滚动到可见区域并定位到对应的轮播图区块；选择该区块时，还应暂停自动轮播。

为了识别主题编辑器中的操作，例如组件或区块的选择、重排等，可以监听主题编辑器触发的 [JavaScript 事件](#javascript-事件)。

如果你希望某些代码不要在主题编辑器中运行，可以使用 Sline 和 JavaScript 变量来 [识别主题编辑器环境](#识别主题编辑器环境)，并据此控制代码是否执行。

### JavaScript 事件
为了识别组件和区块，主题编辑器会在相关组件或区块的父元素上查找特定的数据属性。组件会被 SHOPLINE 生成的元素包裹，该元素默认包含此属性。

主题编辑器会发出组件和区块的 JavaScript 事件，这些事件会冒泡且不可取消。每个事件都有一个目标对象（```event.target```），该目标对象是基于上述 SHOPLINE 数据属性的相关组件或区块元素。

下表概述了主题编辑器发出的事件：

| 事件名称 | 目标对象 | 事件详情 | 是否冒泡 | 是否可取消 | 动作 | 预期行为 |
| --- | --- | --- | --- | --- | --- | --- |
| ```shopline:section:load``` | 组件 | ```{sectionId}``` | 是 | 否 | 已添加或重新渲染了一个组件。 | 重新执行该 组件所需的任何 JavaScript 才能正常工作和显示（就像页面刚刚加载一样）。 |
| ```shopline:section:unload``` | 组件 | ```{sectionId}``` | 是 | 否 | 组件已被删除或正在重新呈现。 | 清理相关事件监听器、变量等，以便在与页面交互时不会中断并且不会发生内存泄漏。 |
| ```shopline:section:select``` | 组件 | ```{sectionId, selected}``` | 是 | 否 | 已选择侧栏中的组件。 | 确保该组件 在视图中并在选择时保持在视图中（自动滚动）。 |
| ```shopline:section:reorder``` | 组件 | ```{sectionId}``` | 是 | 否 | 组件已重新排序。 | - |
| ```shopline:block:select``` | 区块 | ```{sectionId, blockId}```| 是 | 否 | 已选择侧栏中的区块。 | 确保该区块在视图中并在选择时保持在视图中（自动滚动）。 |


在上表中，```blockId``` 表示区块 ID，```sectionId``` 表示组件 ID，```selected``` 表示组件的选中状态，```selected``` 的值为 ```true``` 或 ```false```。

### 识别主题编辑器环境
主题需要区分两种运行环境：客户浏览的店铺前台与商家编辑时的预览模式。通过检测当前环境，你可以控制代码在特定场景下的执行逻辑，确保编辑器内的预览效果与真实店铺保持一致。

识别编辑器环境后，你可以按需控制代码执行：

+ 禁用仅在客户浏览时才需要运行的代码。
+ 启用或禁用仅在主题编辑期间需要运行的代码。
+ 确保在添加、删除、自定义或移动组件时，相关代码能正确执行或被重置。

你可以在 Sline 和 JavaScript 中检测是否在主题编辑器中。

#### 使用 Sline
在主题的 HTML 文件中可以使用 ```request.design_mode``` 全局变量来识别前台店铺是否处于主题编辑器的预览状态。如果处于主题编辑器的预览状态，这个变量的值为 ```true```，否则为 ```false```。

```html
{{#if request.design_mode}}
  <!-- 这个只会在主题编辑器中渲染 -->
{{/if}}

```

#### 使用 JavaScript
在主题的 JavaScript 文件中可以使用 ```window.Shopline.designMode``` 全局变量来识别前台店铺是否处于主题编辑器的预览状态。如果处于主题编辑器的预览状态，这个变量的值为 ```true```，否则为 ```false```。

```javascript
if (window.Shopline.designMode) {
  // 这只会在主题编辑器中执行
}
```