数据类型

元字段 通过数据类型规定可存储的内容，并为每种数据类型提供内置格式校验。无论使用何种数据类型，元字段的值均以字符串形式传入和存储。在主题模板中，你可以通过 metafield object 访问元字段。

基础类型​

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

类型描述值类型
boolean布尔值（true 或 false）。boolean
color颜色的十六进制代码。string
dateISO 8601 格式的日期，不含时区假设。string
date_timeISO 8601 格式的日期和时间，不含时区假设，默认使用格林威治标准时间（GMT）。string
dimension长度的数值和单位。
有效单位：
  • mm：毫米
  • cm：厘米
  • m：米
  • in：英寸
  • ft：英尺
  • yd：码
JSON 对象
jsonJSON 可序列化的值，可以是对象、数组、字符串、数字、布尔值或 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
urlURL，支持以下协议：https、http、mailto、sms、tel。string
volume体积的数值和单位。
有效单位：
  • ml：毫升
  • cl：厘升
  • l：升
  • m3：立方米
  • us_fl_oz：美制液量盎司
  • us_pt：美制品脱
  • us_qt：美制夸脱
  • us_gal：美制加仑
  • imp_fl_oz：英制液量盎司
  • imp_pt：英制品脱
  • imp_qt：英制夸脱
  • imp_gal：英制加仑
JSON 对象
weight重量的数值和单位。
有效单位：
  • kg：千克
  • g：克
  • lb：磅
  • oz：盎司
JSON 对象

基础类型代码示例​

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

类型示例
boolean
true
color
#e84c3d
date
2026-04-24
date_time
2026-04-24T12:30:00
dimension
{
  "value": 25.5,
  "unit": "cm"
}
json
{
  "title": "Summer collection",
  "stock": 100
}
link
{
  "text": "Learn more",
  "url": "https://www.shopline.com"
}
money
{
  "amount": "5.99",
  "currency_code": "CNY"
}
multi_line_text_field
Ingredients
Flour
Water
Milk
number_decimal
9.99
number_integer
42
rating
{
  "value": "4.0",
  "scale_min": "1.0",
  "scale_max": "5.0"
}
rich_text_field
{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "text",
          "value": "Bold text.",
          "bold": true
        }
      ]
    }
  ]
}
single_line_text_field
Express shipping
url
https://www.shopline.com
volume
{
  "value": 20.5,
  "unit": "ml"
}
weight
{
  "value": 2.5,
  "unit": "kg"
}

引用类型​

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

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

引用类型代码示例​

类型示例
collection_reference
gid://shopline/collections/1
file_reference
gid://shopline/MediaImage/123
metaobject_reference
gid://shopline/Metaobject/2
page_reference
gid://shopline/Page/1
product_reference
gid://shopline/Product/1
variant_reference
gid://shopline/ProductVariant/1
article_reference
gid://shopline/Article/1

列表类型​

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

类型描述
list.color十六进制颜色代码的列表。
list.collection_reference商品分类引用的列表。
list.dateISO 8601 格式日期的列表。
list.date_timeISO 8601 格式日期时间的列表。
list.dimension长度的数值和单位的列表。
有效单位：
  • mm：毫米
  • cm：厘米
  • m：米
  • in：英寸
  • ft：英尺
  • yd：码
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.urlURL 的列表，支持 https、http、mailto、sms、tel 协议。
list.variant_reference商品款式引用的列表。
list.volume体积的数值和单位的列表。
有效单位：
  • ml：毫升
  • cl：厘升
  • l：升
  • m3：立方米
  • us_fl_oz：美制液量盎司
  • us_pt：美制品脱
  • us_qt：美制夸脱
  • us_gal：美制加仑
  • imp_fl_oz：英制液量盎司
  • imp_pt：英制品脱
  • imp_qt：英制夸脱
  • imp_gal：英制加仑
list.weight重量的数值和单位的列表。
有效单位：
  • kg：千克
  • g：克
  • lb：磅
  • oz：盎司

列表类型代码示例​

类型示例
list.color
["#e84c3d", "#3498db", "#2ecc71"]
list.collection_reference
["gid://shopline/collections/1", "gid://shopline/collections/2"]
list.date
["2026-01-01", "2026-05-01"]
list.date_time
["2026-01-01T12:30:00", "2026-05-01T12:30:00"]
list.dimension
[
  {
    "value": 25.5,
    "unit": "cm"
  },
  {
    "value": 35.5,
    "unit": "cm"
  }
]
list.file_reference
["gid://shopline/MediaImage/123", "gid://shopline/GenericFile/456", "gid://shopline/video/789"]
list.link
[
  {
    "text": "Get started",
    "url": "https://shopline.com"
  },
  {
    "text": "View documentation",
    "url": "https://developer.shopline.com/docs"
  }
]
list.metaobject_reference
["gid://shopline/Metaobject/123", "gid://shopline/Metaobject/456"]
list.number_decimal
["9.99", "19.9", "99.0"]
list.number_integer
["1", "5", "42"]
list.page_reference
["gid://shopline/Page/1", "gid://shopline/Page/2"]
list.article_reference
["gid://shopline/Article/1", "gid://shopline/Article/2"]
list.product_reference
["gid://shopline/Product/1", "gid://shopline/Product/2"]
list.rating
[
  {
    "value": "4.0",
    "scale_min": "1.0",
    "scale_max": "5.0"
  },
  {
    "value": "2.5",
    "scale_min": "1.0",
    "scale_max": "5.0"
  }
]
list.single_line_text_field
["Express shipping", "Standard shipping"]
list.url
["https://www.shopline.com", "https://developer.shopline.com"]
list.variant_reference
["gid://shopline/ProductVariant/1", "gid://shopline/ProductVariant/2"]
list.volume
[
  {
    "value": 20.5,
    "unit": "ml"
  },
  {
    "value": 40.5,
    "unit": "ml"
  }
]
list.weight
[
  {
    "value": 2.5,
    "unit": "kg"
  },
  {
    "value": 4.5,
    "unit": "kg"
  }
]

富文本格式说明​

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

{
  "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。

示例​

{
  "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 节点数组。

示例​

{
  "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 节点数组。

示例​

{
  "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 节点数组。

示例​

{
  "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"
            }
          ]
        }
      ]
    }
  ]
}
这篇文章对你有帮助吗？
SHOPLINE
SHOPLINE
SHOPLINE Enterprise
条款协议
隐私
条款
开发者协议
LinkedInEmail
LinkedInEmail
© Copyright 2013-2026 SHOPLINE Limited.