---
title: "组件渲染 API"

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/section-rendering-api'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/section-rendering-api.md'
---
# 组件渲染 API

你可以使用组件渲染 API，通过 AJAX 请求为主题页面内容获取到 HTML 新组件。这样的话，你就可以通过获取和动态替换某些元素来更新页面内容，而无需重新加载整个页面。

例如，你可以使用组件渲染 API 对搜索结果进行分页，而无需在切换页码的时候重新加载整个页面。

## 请求多个组件{#请求多个片段}

你可以使用 `sections` 查询参数来渲染页面中的某些组件，该查询参数是由渲染组件的 [组件 ID](#MvtJF) 组成。响应结果是一个 JSON 对象，其中包括每个组件 ID 和对应渲染的 HTML。

`sections` 参数必须是以逗号分隔的 `section.id` 列表:

```typescript
?sections=sections--header-group__announcement-bar,sections--header-group__header
```

通过将 sections 参数附加到任何页面 URL，可以在任何页面的上下文中渲染组件。例如，你可以在首页请求 `/?sections=sections--header-group__header`，返回对应的 section 的 html 组件填充到页面上。

> **warning**
>
> 注意：
> 
> 你无法通过组件渲染 API 指定组件的设置值。如果请求的组件存在于模版中，那就应用主题的配置。否则，将使用组件的默认配置。

以下示例代码使用 JavaScript fetch 请求两个组件：

```javascript
fetch('/?sections=sections--header-group__announcement-bar,sections--header-group__header').then((response) => {
  const renderSections = response.json();

  const announcementBarHtml = renderSections['sections--header-group__announcement-bar'];
  const headerHtml = renderSections['sections--header-group__header'];
})

```

响应结果：

```null
{
  "sections--header-group__announcement-bar": "<div id=\"shopline-section-sections--header-group__announcement-bar\" class=\"section\">\n<!-- section content -->\n</div>",
  "sections--header-group__header": "<div id=\"shopline-section-sections--header-group__header\" class=\"section\">\n<!-- section content -->\n</div>"
}
```

> **tip**
>
> 提示：  
>   
> 渲染整个页面使用到的 query 参数，在组件渲染时也同时支持。比如请求 `/collections /clothing/?page_num=2&section_id=template--collection__main-collection-products` 来获取第二页的商品列表组件，填充到第一页的下方。

### 组件错误响应{#BAMRg}

无法正常渲染的组件（包括因已发布主题不存在而失败的组件）将会在 JSON 响应中返回 `null` 。响应可能是返回 `HTTP 200` 状态，不过响应体中会包含一个或多个 `null` 值的组件。因此，你需要考虑和处理返回 `null` 值的情况。

## 请求单个组件{#WvQWa}

在大多数情况下，你可以使用以上提到的 `sections` 参数及其响应数据来处理组件的渲染，当然也可以是渲染单个组件的场景。不过如果想渲染单组件的话，更推荐是使用 `section_id`查询参数来请求单个组件。

```json
?section_id=sections--header-group__announcement-bar
```

使用 `section_id` 查询参数渲染出来的组件直接以 HTML 形式返回，并且与 `sections` 一样，此参数可用于在任何页面的上下文中渲染组件。

```html
<div id=\"shopline-section-sections--header-group__announcement-bar\" class=\"section\">\n<!-- section content -->\n</div>
```

> **tip**
>
> 提示：  
> 你无法通过组件渲染 API 指定组件的设置值。如果请求的组件存在于模版中，那就应用主题的配置。否则，将使用组件的默认配置。

## 查找组件 ID{#MvtJF}

你可以通过两种方式找到组件 ID：

-   通过 Sline [section 对象](https://developer.shopline.com/zh-hans-cn/docs/sline/object/section.md)，使用 `section.id`。
    
-   从组件 Document 节点的 ID 属性中获取。
    

### 从组件 DOM 节点的 ID 属性中获取{#yLOv2}

你可以从组件对应 DOM 节点的 ID 属性中提取组件 ID。例如，以下是组件 DOM 节点的一般格式：

```html
<div id="shopline-section-[section-id]" class="section">
  <!-- section content -->
</div>
```

你在 [JSON 模板](https://developer.shopline.com/zh-hans-cn/docs/online-store-3-0-themes/theme-structure/templates.md) 中添加了组件后，我们就会为组件生成一个唯一 ID。例如在同一个页面里，加了两个商品列表组件，两个组件是对应不一样的 ID，这样能方便你对每个组件去做定位。