**版本：202601**

# 查询可添加卡片列表

**GET** `/openapi/2026-01/themes/cards`

聚合当前主题下 `theme`、`pb`、`custom`、`extension`、`public`、`gen` 各来源的可添加卡片，已去重、按来源排序，支持分页。

## 请求

**Query参数**

- `theme_id` string

  主题 ID。可选；仅用于 theme 源，为空时 theme 源返回空
- `source` string[]

  数据源筛选。支持多值（重复参数 `source=pb&source=public`，或逗号 `source=pb,public`），留空聚合全部数据源：

  *   `theme`：主题自带的卡片
  *   `pb`：高级卡片，来自平台的公共模板
  *   `custom`：高级卡片，来自商家的自定义卡片模板
  *   `extension`：应用扩展卡片
  *   `public`：公共卡片
  *   `gen`：AI 卡片
- `category` string

  一级分类筛选。仅作用于 pb 源
- `second_category` string

  二级分类筛选。仅作用于 pb 源
- `limit` int32

  每页条数，默认 10，范围 1-100
- `page` int32

  页码
- `template` string

  模板筛选。取值为模板名（`index`、`product`、`collection`、`cart`、`page`、`search` 及自定义模板名）

## 响应

**200**

OK

**application/json**

**数据结构 | 示例**

**数据结构**

- `code` string

  错误码
- `message` string

  错误信息
- `data` object

  - `items` object[]

    本页卡片列表

    *   Array \[

    - `id` string

      全局唯一 ID，形态随来源而定：pb 源为 `global-<模板id>`；custom 源为 `custom-<模板id>`；theme 源为 section type；extension / public 源为完整 block type，形如 `shoplazza://apps/<app_id>/blocks/<location>/<extension_id>`
    - `source` string

      来源：

      *   `theme`：主题自带的卡片
      *   `pb`：高级卡片，来自平台的公共模板
      *   `custom`：高级卡片，来自商家的自定义卡片模板
      *   `extension`：应用扩展卡片
      *   `public`：公共卡片
      *   `gen`：AI 卡片
    - `name` GoogleProtobufValue

      名称。通常是多语言对象 `{"zh-CN": "...", "en-US": "..."}`，但不同源可能是纯字符串
    - `category` string

      一级分类（仅 pb 有值）
    - `second_category` string

      二级分类（仅 pb 有值）
    - `description` string

      描述（当前各源均为空）
    - `preview_image` string

      预览图 URL（仅 pb 有值）
    - `updated_at` string

      更新时间 RFC3339（仅 pb 有值）
    - `templates` string[]

      该卡片可添加到的模板页。非空 = 仅这些模板页可添加；为空 = 所有页面
    - `limit` int32

      该卡片在单页上的实例数上限。0 = 无限制
    *   \]
  - `total` int32

    所选数据源下的卡片总数
  - `page` int32

    当前页码
  - `limit` int32

    每页条数
  - `has_more` boolean

    是否还有下一页

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "items": [
      {
        "id": "string",
        "source": "string",
        "category": "string",
        "second_category": "string",
        "description": "string",
        "preview_image": "string",
        "updated_at": "string",
        "templates": [
          "string"
        ],
        "limit": 0
      }
    ],
    "total": 0,
    "page": 0,
    "limit": 0,
    "has_more": true
  }
}
```