---
title: "数据类型"

doc_type: static
doc_category: static
doc_version: v20260901
source_url:
  html: 'https://developer.shopline.com/zh-hans-cn/docs/apps/metafields/references/data-types'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/apps/metafields/references/data-types.md'
---
# 数据类型

[元字段](https://developer.shopline.com/zh-hans-cn/docs/apps/metafields/overview.md) 通过数据类型规定可存储的内容，并为每种数据类型提供内置格式校验。无论使用何种数据类型，元字段的值均以字符串形式传入和存储。在主题模板中，你可以通过 [`metafield`](https://developer.shopline.com/zh-hans-cn/docs/sline/object/metafield.md) object 访问元字段。

---

## 基础类型

基础类型元字段存储文本、数字、日期和带单位的度量值等信息。

| 类型                     | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | 值类型    |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `boolean`                | 布尔值（`true` 或 `false`）。                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | boolean   |
| `color`                  | 颜色的十六进制代码。                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | string    |
| `date`                   | [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) 格式的日期，不含时区假设。                                                                                                                                                                                                                                                                                                                                                                                                  | string    |
| `date_time`              | [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) 格式的日期和时间，不含时区假设，默认使用格林威治标准时间（GMT）。                                                                                                                                                                                                                                                                                                                                                           | string    |
| `dimension`              | 长度的数值和单位。<br />有效单位：<ul><li><code>mm</code>：毫米</li><li><code>cm</code>：厘米</li><li><code>m</code>：米</li><li><code>in</code>：英寸</li><li><code>ft</code>：英尺</li><li><code>yd</code>：码</li></ul>                                                                                                                                                                                                                                                                     | JSON 对象 |
| `json`                   | JSON 可序列化的值，可以是对象、数组、字符串、数字、布尔值或 `null`。                                                                                                                                                                                                                                                                                                                                                                                                                           | JSON 对象 |
| `link`                   | 文本与 URL 的组合，用于存储链接内容。                                                                                                                                                                                                                                                                                                                                                                                                                                                          | JSON 对象 |
| `money`                  | 数值金额，附带与店铺货币匹配的货币代码。                                                                                                                                                                                                                                                                                                                                                                                                                                                       | JSON 对象 |
| `multi_line_text_field`  | 多行文本字段，最大 65 KB。                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | string    |
| `number_decimal`         | 小数，范围为 ±9,999,999,999,999.999999999。                                                                                                                                                                                                                                                                                                                                                                                                                                                    | string    |
| `number_integer`         | 整数，范围为 ±9,999,999,999,999。                                                                                                                                                                                                                                                                                                                                                                                                                                                              | integer   |
| `rating`                 | 在指定范围内的评分，需要提供 `scale_min` 和 `scale_max` 校验参数。                                                                                                                                                                                                                                                                                                                                                                                                                             | JSON 对象 |
| `rich_text_field`        | 支持标题、列表、链接、加粗和斜体的 [富文本字段](#富文本格式说明)。                                                                                                                                                                                                                                                                                                                                                                                                                             | JSON 对象 |
| `single_line_text_field` | 单行文本字段，最大 65 KB。                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | string    |
| `url`                    | URL，支持以下协议：`https`、`http`、`mailto`、`sms`、`tel`。                                                                                                                                                                                                                                                                                                                                                                                                                                   | string    |
| `volume`                 | 体积的数值和单位。<br />有效单位：<ul><li><code>ml</code>：毫升</li><li><code>cl</code>：厘升</li><li><code>l</code>：升</li><li><code>m3</code>：立方米</li><li><code>us_fl_oz</code>：美制液量盎司</li><li><code>us_pt</code>：美制品脱</li><li><code>us_qt</code>：美制夸脱</li><li><code>us_gal</code>：美制加仑</li><li><code>imp_fl_oz</code>：英制液量盎司</li><li><code>imp_pt</code>：英制品脱</li><li><code>imp_qt</code>：英制夸脱</li><li><code>imp_gal</code>：英制加仑</li></ul> | JSON 对象 |
| `weight`                 | 重量的数值和单位。<br />有效单位：<ul><li><code>kg</code>：千克</li><li><code>g</code>：克</li><li><code>lb</code>：磅</li><li><code>oz</code>：盎司</li></ul>                                                                                                                                                                                                                                                                                                                                 | JSON 对象 |

---

## 基础类型代码示例

以下示例演示每种基础类型的预期值格式：

<table>
<thead>
<tr><th>类型</th><th>示例</th></tr>
</thead>
<tbody>
<tr>
<td><code>boolean</code></td>
<td>

```
true
```

</td>
</tr>
<tr>
<td><code>color</code></td>
<td>

```
#e84c3d
```

</td>
</tr>
<tr>
<td><code>date</code></td>
<td>

```
2026-04-24
```

</td>
</tr>
<tr>
<td><code>date_time</code></td>
<td>

```
2026-04-24T12:30:00
```

</td>
</tr>
<tr>
<td><code>dimension</code></td>
<td>

```json
{
  "value": 25.5,
  "unit": "cm"
}
```

</td>
</tr>
<tr>
<td><code>json</code></td>
<td>

```json
{
  "title": "Summer collection",
  "stock": 100
}
```

</td>
</tr>
<tr>
<td><code>link</code></td>
<td>

```json
{
  "text": "Learn more",
  "url": "https://www.shopline.com"
}
```

</td>
</tr>
<tr>
<td><code>money</code></td>
<td>

```json
{
  "amount": "5.99",
  "currency_code": "CNY"
}
```

</td>
</tr>
<tr>
<td><code>multi_line_text_field</code></td>
<td>

```
Ingredients
Flour
Water
Milk
```

</td>
</tr>
<tr>
<td><code>number_decimal</code></td>
<td>

```
9.99
```

</td>
</tr>
<tr>
<td><code>number_integer</code></td>
<td>

```
42
```

</td>
</tr>
<tr>
<td><code>rating</code></td>
<td>

```json
{
  "value": "4.0",
  "scale_min": "1.0",
  "scale_max": "5.0"
}
```

</td>
</tr>
<tr>
<td><code>rich_text_field</code></td>
<td>

```json
{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "text",
          "value": "Bold text.",
          "bold": true
        }
      ]
    }
  ]
}
```

</td>
</tr>
<tr>
<td><code>single_line_text_field</code></td>
<td>

```
Express shipping
```

</td>
</tr>
<tr>
<td><code>url</code></td>
<td>

```
https://www.shopline.com
```

</td>
</tr>
<tr>
<td><code>volume</code></td>
<td>

```json
{
  "value": 20.5,
  "unit": "ml"
}
```

</td>
</tr>
<tr>
<td><code>weight</code></td>
<td>

```json
{
  "value": 2.5,
  "unit": "kg"
}
```

</td>
</tr>
</tbody>
</table>

---

## 引用类型

引用类型元字段用于存储对店铺资源的引用。

| 类型                   | 描述                 | 值类型 |
| ---------------------- | -------------------- | ------ |
| `collection_reference` | 对商品分类的引用。   | string |
| `file_reference`       | 对文件的引用。       | string |
| `metaobject_reference` | 对元对象条目的引用。 | string |
| `page_reference`       | 对页面的引用。       | string |
| `product_reference`    | 对商品的引用。       | string |
| `variant_reference`    | 对商品款式的引用。   | string |
| `article_reference`    | 对博客文章的引用。   | string |

---

## 引用类型代码示例

<table>
<thead>
<tr><th>类型</th><th>示例</th></tr>
</thead>
<tbody>
<tr>
<td><code>collection_reference</code></td>
<td>

```
gid://shopline/collections/1
```

</td>
</tr>
<tr>
<td><code>file_reference</code></td>
<td>

```
gid://shopline/MediaImage/123
```

</td>
</tr>
<tr>
<td><code>metaobject_reference</code></td>
<td>

```
gid://shopline/Metaobject/2
```

</td>
</tr>
<tr>
<td><code>page_reference</code></td>
<td>

```
gid://shopline/Page/1
```

</td>
</tr>
<tr>
<td><code>product_reference</code></td>
<td>

```
gid://shopline/Product/1
```

</td>
</tr>
<tr>
<td><code>variant_reference</code></td>
<td>

```
gid://shopline/ProductVariant/1
```

</td>
</tr>
<tr>
<td><code>article_reference</code></td>
<td>

```
gid://shopline/Article/1
```

</td>
</tr>
</tbody>
</table>

---

## 列表类型

列表类型元字段用于在单个元字段中存储多个值。值以 JSON 数组格式表示，每个列表类型元字段最多可包含 128 个元素。

| 类型                          | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list.color`                  | 十六进制颜色代码的列表。                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `list.collection_reference`   | 商品分类引用的列表。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `list.date`                   | [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) 格式日期的列表。                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `list.date_time`              | [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) 格式日期时间的列表。                                                                                                                                                                                                                                                                                                                                                                                                              |
| `list.dimension`              | 长度的数值和单位的列表。<br />有效单位：<ul><li><code>mm</code>：毫米</li><li><code>cm</code>：厘米</li><li><code>m</code>：米</li><li><code>in</code>：英寸</li><li><code>ft</code>：英尺</li><li><code>yd</code>：码</li></ul>                                                                                                                                                                                                                                                                     |
| `list.file_reference`         | 文件引用的列表。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `list.link`                   | 文本与 URL 组合的列表，用于存储一组链接。                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `list.metaobject_reference`   | 元对象条目引用的列表。                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `list.number_decimal`         | 小数的列表。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `list.number_integer`         | 整数的列表。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `list.page_reference`         | 页面引用的列表。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `list.article_reference`      | 博客文章引用的列表。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `list.product_reference`      | 商品引用的列表。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `list.rating`                 | 在指定范围内的评分列表。                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `list.single_line_text_field` | 单行文本字段的列表。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `list.url`                    | URL 的列表，支持 `https`、`http`、`mailto`、`sms`、`tel` 协议。                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `list.variant_reference`      | 商品款式引用的列表。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `list.volume`                 | 体积的数值和单位的列表。<br />有效单位：<ul><li><code>ml</code>：毫升</li><li><code>cl</code>：厘升</li><li><code>l</code>：升</li><li><code>m3</code>：立方米</li><li><code>us_fl_oz</code>：美制液量盎司</li><li><code>us_pt</code>：美制品脱</li><li><code>us_qt</code>：美制夸脱</li><li><code>us_gal</code>：美制加仑</li><li><code>imp_fl_oz</code>：英制液量盎司</li><li><code>imp_pt</code>：英制品脱</li><li><code>imp_qt</code>：英制夸脱</li><li><code>imp_gal</code>：英制加仑</li></ul> |
| `list.weight`                 | 重量的数值和单位的列表。<br />有效单位：<ul><li><code>kg</code>：千克</li><li><code>g</code>：克</li><li><code>lb</code>：磅</li><li><code>oz</code>：盎司</li></ul>                                                                                                                                                                                                                                                                                                                                 |

---

## 列表类型代码示例

<table>
<thead>
<tr><th>类型</th><th>示例</th></tr>
</thead>
<tbody>
<tr>
<td><code>list.color</code></td>
<td>

```json
["#e84c3d", "#3498db", "#2ecc71"]
```

</td>
</tr>
<tr>
<td><code>list.collection_reference</code></td>
<td>

```json
["gid://shopline/collections/1", "gid://shopline/collections/2"]
```

</td>
</tr>
<tr>
<td><code>list.date</code></td>
<td>

```json
["2026-01-01", "2026-05-01"]
```

</td>
</tr>
<tr>
<td><code>list.date_time</code></td>
<td>

```json
["2026-01-01T12:30:00", "2026-05-01T12:30:00"]
```

</td>
</tr>
<tr>
<td><code>list.dimension</code></td>
<td>

```json
[
  {
    "value": 25.5,
    "unit": "cm"
  },
  {
    "value": 35.5,
    "unit": "cm"
  }
]
```

</td>
</tr>
<tr>
<td><code>list.file_reference</code></td>
<td>

```json
["gid://shopline/MediaImage/123", "gid://shopline/GenericFile/456", "gid://shopline/video/789"]
```

</td>
</tr>
<tr>
<td><code>list.link</code></td>
<td>

```json
[
  {
    "text": "Get started",
    "url": "https://shopline.com"
  },
  {
    "text": "View documentation",
    "url": "https://developer.shopline.com/docs"
  }
]
```

</td>
</tr>
<tr>
<td><code>list.metaobject_reference</code></td>
<td>

```json
["gid://shopline/Metaobject/123", "gid://shopline/Metaobject/456"]
```

</td>
</tr>
<tr>
<td><code>list.number_decimal</code></td>
<td>

```json
["9.99", "19.9", "99.0"]
```

</td>
</tr>
<tr>
<td><code>list.number_integer</code></td>
<td>

```json
["1", "5", "42"]
```

</td>
</tr>
<tr>
<td><code>list.page_reference</code></td>
<td>

```json
["gid://shopline/Page/1", "gid://shopline/Page/2"]
```

</td>
</tr>
<tr>
<td><code>list.article_reference</code></td>
<td>

```json
["gid://shopline/Article/1", "gid://shopline/Article/2"]
```

</td>
</tr>
<tr>
<td><code>list.product_reference</code></td>
<td>

```json
["gid://shopline/Product/1", "gid://shopline/Product/2"]
```

</td>
</tr>
<tr>
<td><code>list.rating</code></td>
<td>

```json
[
  {
    "value": "4.0",
    "scale_min": "1.0",
    "scale_max": "5.0"
  },
  {
    "value": "2.5",
    "scale_min": "1.0",
    "scale_max": "5.0"
  }
]
```

</td>
</tr>
<tr>
<td><code>list.single_line_text_field</code></td>
<td>

```json
["Express shipping", "Standard shipping"]
```

</td>
</tr>
<tr>
<td><code>list.url</code></td>
<td>

```json
["https://www.shopline.com", "https://developer.shopline.com"]
```

</td>
</tr>
<tr>
<td><code>list.variant_reference</code></td>
<td>

```json
["gid://shopline/ProductVariant/1", "gid://shopline/ProductVariant/2"]
```

</td>
</tr>
<tr>
<td><code>list.volume</code></td>
<td>

```json
[
  {
    "value": 20.5,
    "unit": "ml"
  },
  {
    "value": 40.5,
    "unit": "ml"
  }
]
```

</td>
</tr>
<tr>
<td><code>list.weight</code></td>
<td>

```json
[
  {
    "value": 2.5,
    "unit": "kg"
  },
  {
    "value": 4.5,
    "unit": "kg"
  }
]
```

</td>
</tr>
</tbody>
</table>

---

## 富文本格式说明

`rich_text_field` 类型接受具有以下结构的 JSON 对象：

```jsonc
{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "text",
          "value": "This is regular text.",
          "bold": true,
          "italic": true
        },
        {
          "type": "link",
          "url": "https://example.com",
          "title": "Example link",
          "children": [
            {
              "type": "text",
              "value": "Learn more",
              "bold": true
            }
          ]
        }
      ]
    }
  ]
}
```

### 加粗与斜体

文本节点可通过 `bold` 和 `italic` 设置文本样式，字段说明如下：

| 字段     | 是否必填 | 说明                             |
| -------- | -------- | -------------------------------- |
| `type`   | 是       | 固定为 `text`。                  |
| `value`  | 是       | 文本节点的具体内容。             |
| `bold`   | 否       | 是否加粗文本，默认值为 `false`。 |
| `italic` | 否       | 是否斜体文本，默认值为 `false`。 |

#### 示例

```jsonc
{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "text",
          "value": "This text is bold and italic.",
          "bold": true,
          "italic": true
        }
      ]
    }
  ]
}
```

### 标题

标题节点的字段说明如下：

| 字段       | 是否必填 | 说明                        |
| ---------- | -------- | --------------------------- |
| `type`     | 是       | 固定为 `heading`。          |
| `level`    | 是       | 标题级别，支持 `1` 到 `6`。 |
| `children` | 是       | `text` 节点数组。           |

#### 示例

```jsonc
{
  "type": "root",
  "children": [
    {
      "type": "heading",
      "level": 2,
      "children": [
        {
          "type": "text",
          "value": "This is a level 2 heading"
        }
      ]
    }
  ]
}
```

### 超链接

超链接节点的字段说明如下：

| 字段       | 是否必填 | 说明                                             |
| ---------- | -------- | ------------------------------------------------ |
| `type`     | 是       | 固定为 `link`。                                  |
| `url`      | 是       | 链接跳转地址。                                   |
| `title`    | 否       | 链接标题，可用于无障碍和 SEO。                   |
| `target`   | 否       | 链接打开方式，例如 `_blank` 表示在新标签页打开。 |
| `children` | 是       | `text` 节点数组。                                |

#### 示例

```jsonc
{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "link",
          "url": "https://example.com",
          "title": "Link to example.com",
          "target": "_blank",
          "children": [
            {
              "type": "text",
              "value": "View details"
            }
          ]
        }
      ]
    }
  ]
}
```

### 列表

列表节点和列表项节点的字段说明如下。

列表节点：

| 字段       | 是否必填 | 说明                                      |
| ---------- | -------- | ----------------------------------------- |
| `type`     | 是       | 固定为 `list`。                           |
| `listType` | 是       | 列表类型，支持 `ordered` 或 `unordered`。 |
| `children` | 是       | 固定为 `list-item` 类型的节点数组。       |

列表项节点：

| 字段       | 是否必填 | 说明                 |
| ---------- | -------- | -------------------- |
| `type`     | 是       | 固定为 `list-item`。 |
| `children` | 是       | `text` 节点数组。    |

#### 示例

```jsonc
{
  "type": "root",
  "children": [
    {
      "type": "list",
      "listType": "unordered",
      "children": [
        {
          "type": "list-item",
          "children": [
            {
              "type": "text",
              "value": "First item"
            }
          ]
        },
        {
          "type": "list-item",
          "children": [
            {
              "type": "text",
              "value": "Second item"
            }
          ]
        }
      ]
    }
  ]
}
```
