输入设置

输入设置可以保存值，并且商家可以对其进行配置。

输入设置通常由 标准属性 组成，分为两类：

• 基础输入设置
• 专用输入设置

要了解如何访问这些设置的值并在主题中使用它们，请参阅 设置概述。

提示

如果想在设置显示中添加信息元素（例如标题），请参阅 侧边栏设置。

标准属性

以下是在输入设置中通用的标准属性。根据输入类型的不同，可能会有额外的属性或某些属性不适用：

基础输入设置

以下为基础输入设置类型：

• checkbox
• number
• radio
• range
• select
• text
• textarea

checkbox

checkbox 类型的设置会生成一个复选框字段。此设置类型可用于切换功能的开启或关闭，例如是否显示公告栏。

例如，以下设置生成如下输出：

{  
  "type": "checkbox",  
  "id": "show_announcement",  
  "label": "显示公告",  
  "default": true  
}

访问 checkbox 类型设置的值时，数据以 布尔值 返回。

注意

如果未指定 default，则默认值为 false。

number

number 类型的设置会生成一个数字字段。除了 标准属性 外，number 类型设置还具有以下属性：

您可以使用此设置类型捕获可变的数值，例如集合页面上每页显示的产品数量。

例如，以下设置生成如下输出：

{  
  "type": "number",  
  "id": "products_per_page",  
  "label": "每页产品数量",  
  "default": 20  
}

访问 number 类型设置的值时，数据以以下格式之一返回：

• 数字。
• nil，如果未输入任何内容。

注意

default 属性是可选的。但值必须是数字而非字符串。未遵守此规则会导致错误。

radio

radio 类型的设置会生成一个单选按钮字段。除了 标准属性 外，radio 类型设置需要必填的 options 属性，该属性接受 value 和 label 定义的数组。

您可以使用此设置类型捕获多选项选择，例如页眉标志的对齐方式。

例如，以下设置生成如下输出：

{  
  "type": "radio",  
  "id": "logo_aligment",  
  "label": "标志对齐方式",  
  "options": [  
    {  
      "value": "left",  
      "label": "左对齐"  
    },  
    {  
      "value": "centered",  
      "label": "居中"  
    }  
  ],  
  "default": "left"  
}

访问 radio 类型设置的值时，数据以 字符串 返回。

注意

如果未指定 default，则默认选择第一个选项。

range

range 类型的设置会生成一个滑块字段和输入字段。除了 标准属性 外，range 类型设置还具有以下属性：

您可以使用此设置类型捕获可变的数值，例如字体大小。

您可以通过提供的滑块或直接在输入字段中输入值来更新 range 值：

• 如果输入的值不符合 step 定义，则值会四舍五入到最近的步长。
• 如果输入的值超出指定的 min 和 max 范围，则值会自动调整为 min 或 max。

例如，以下设置生成如下输出：

{  
  "type": "range",  
  "id": "font_size",  
  "min": 12,  
  "max": 24,  
  "step": 1,  
  "unit": "px",  
  "label": "字体大小",  
  "default": 16  
}

访问 range 类型设置的值时，数据以 数字 返回。

注意

default 属性是必填的。min、max、step 和 default 属性不能为字符串值。未遵守此规则会导致错误。

select

select 类型的设置会根据特定条件生成 不同选择器字段。除了 标准属性 外，select 类型设置还具有以下属性：

select 类型设置支持的额外属性

选择器字段

以下条件会渲染选择器字段为 DropDown 或 SegmentedControl：

选择器字段的渲染条件

您可以使用此设置类型捕获多选项选择，例如幻灯片文字的垂直对齐方式。

例如，以下设置生成如下输出：

{  
  "type": "select",  
  "id": "vertical_alignment",  
  "label": "垂直对齐方式",  
  "options": [  
    {  
      "value": "top",  
      "label": "顶部"  
    },  
    {  
      "value": "middle",  
      "label": "中部"  
    },  
    {  
      "value": "bottom",  
      "label": "底部"  
    }  
  ],  
  "default": "middle"  
}

但如果您的设置符合下拉字段 (DropDown) 的条件（例如选项超过五个），则会生成以下输出：

{  
  "type": "select",  
  "id": "sizes",  
  "label": "尺寸",  
  "options": [  
    {  
      "value": "xs",  
      "label": "极小号"  
    },  
    {  
      "value": "s",  
      "label": "小号"  
    },  
    {  
      "value": "m",  
      "label": "中号"  
    },  
    {  
      "value": "l",  
      "label": "大号"  
    },  
    {  
      "value": "xl",  
      "label": "加大号"  
    },  
    {  
      "value": "xxl",  
      "label": "特大号"  
    }  
  ],  
  "default": "m"  
}

访问 select 类型设置的值时，数据以 字符串 返回。

注意

如果未指定 default，则默认选择第一个选项。

text

类型为 text 的设置会输出一个单行文本字段。除了 标准属性 之外，text 类型的设置还具有以下属性：

你可以使用这种设置类型来捕获短字符串，例如标题。

例如，以下设置会生成以下输出：

{  
  "type": "text",  
  "id": "footer_linklist_title",  
  "label": "标题",  
  "default": "快速链接"  
}

当访问 text 类型设置的值时，数据会以以下格式之一返回：

• 一个 字符串。
• 如果未输入任何内容，则返回一个 empty 对象。

提示

切换预设时，text 类型的设置不会更新。

textarea

类型为 textarea 的设置会输出一个多行文本字段。除了 标准属性 之外，textarea 类型的设置还具有以下属性：

你可以使用这种设置类型来捕获大段文本，例如消息。

例如，以下设置会生成以下输出：

{  
  "type": "textarea",  
  "id": "home_welcome_message",  
  "label": "欢迎信息",  
  "default": "欢迎光临我的店铺！"  
}

当访问 textarea 类型设置的值时，数据会以以下格式之一返回：

• 一个 字符串。
• 如果未输入任何内容，则返回一个 empty 对象。

专用输入设置

以下是一些专用输入设置类型：

• 文章
• 博客
• 集合
• 集合列表
• 颜色
• 背景颜色
• 颜色方案
• 颜色方案组
• 字体选择器
• HTML
• 图片选择器
• 内联富文本
• 链接列表
• Liquid
• 元对象
• 元对象列表
• 页面
• 产品
• 产品列表
• 富文本
• 文本对齐方式
• URL
• 视频
• 视频URL

article

类型为 article 的设置会输出一个文章选择器字段，该字段会自动填充商店中可用的文章。你可以使用这种设置类型来捕获文章选择，例如选择要在主页上展示的文章。

例如，以下设置会生成以下输出：

{  
  "type": "article",  
  "id": "article",  
  "label": "文章"  
}

当访问 article 类型设置的值时，数据会以以下格式之一返回：

• 一个 article 对象。

  为了与 旧版基于资源的设置 兼容，直接输出该设置会返回对象的句柄。

• 如果未进行选择、选择不可见或选择已不存在，则返回 blank

注意

类型为 article 的设置在切换预设 Preset 时不会更新。article 设置也不支持 default 属性。

blog

类型为 blog 的设置会生成一个自动填充商店可用博客的博客选择字段。你可以使用这种设置类型来捕获博客选择，例如选择要在侧边栏中展示的博客。

例如，以下设置会生成以下输出：

{  
  "type": "blog",  
  "id": "blog",  
  "label": "博客 Blog"  
}

访问 blog 类型设置的值时，数据会以以下格式之一返回：

• 一个 blog 对象。

  为了向后兼容 legacy resource-based settings，直接输出该设置会返回对象的 handle。

• blank，如果未进行选择，或者选择已不存在。

注意

类型为 blog 的设置在切换预设 Preset 时不会更新。blog 设置也不支持 default 属性。

collection

类型为 collection 的设置会生成一个自动填充商店可用集合的集合选择字段。你可以使用这种设置类型来捕获集合选择，例如选择要在首页展示产品的集合。

例如，以下设置会生成以下输出：

{  
  "type": "collection",  
  "id": "collection",  
  "label": "集合 Collection"  
}

访问 collection 类型设置的值时，数据会以以下格式之一返回：

• 一个 collection 对象。

  为了向后兼容 legacy resource-based settings，直接输出该设置会返回对象的 handle。

• blank，如果未进行选择、选择不可见，或者选择已不存在。

注意

类型为 collection 的设置在切换预设 Preset 时不会更新。collection 设置也不支持 default 属性。

collection_list

类型为 collection_list 的设置会生成一个自动填充商店可用集合的集合选择字段。你可以使用这种设置类型来捕获多个集合，例如选择一组要在首页展示的集合。

除了 标准属性 之外，collection_list 类型设置还具有以下属性：

{  
  "type": "collection_list",  
  "id": "collection_list",  
  "label": "集合 Collections",  
  "limit": 8  
}

访问 collection_list 类型设置的值时，数据会以以下格式之一返回：

• 一个 collection 对象 数组。

  该数组支持使用 paginate 标签进行分页。你也可以在 设置键 后追加 .count 来返回数组中集合的数量。

• blank，如果未进行选择、选择不可见，或者选择已不存在

color

类型为 color 的设置会生成一个颜色选择器字段。你可以使用这种设置类型来捕获各种主题元素的颜色选择，比如正文文本颜色。

例如，以下设置会生成以下输出：

{  
  "type": "color",  
  "id": "body_text",  
  "label": "Body text",  
  "default": "#000000"  
}

当访问 color 类型设置的值时，数据会以以下格式之一返回：

• 一个 color 对象。
• 如果未进行选择，则返回 blank。

color_background

类型为 color_background 的设置会生成一个文本字段，用于输入 CSS background 属性。你可以使用这种设置类型来捕获各种主题元素的背景设置，比如商店背景。

警告

color_background 类型的设置不支持与图像相关的背景属性。

例如，以下设置会生成以下输出：

{  
  "type": "color_background",  
  "id": "background",  
  "label": "Background",  
  "default": "linear-gradient(#ffffff, #000000)"  
}

当访问 color_background 类型设置的值时，数据会以以下格式之一返回：

• 一个 字符串。
• 如果未输入任何内容，则返回空字符串。

color_scheme

类型为 color_scheme 的设置会生成一个包含所有可用主题颜色方案的选取器，并预览所选颜色方案。选取器中的主题颜色方案通过 color_scheme_group 设置定义。你可以将颜色方案应用于区块、模块和通用主题设置。颜色方案设置在 App 区块中不支持。

例如，以下设置会生成以下输出：

{  
    "type": "color_scheme",  
    "id": "color_scheme",  
    "default": "scheme_1",  
    "label": "Color scheme"  
}

当访问 color_scheme 类型设置的值时，Shopify 会返回从 color_scheme_group 中选中的 color_scheme 对象。

如果未输入值，或者值无效，则返回 color_scheme 中的默认值。如果默认值也无效，则返回 color_scheme_group 中的第一个 color_scheme。

如果主题的 settings_data.json 中没有 color_scheme_group 数据，则返回 nil。

color_scheme_group

一种 color_scheme_group 类型的设置会输出由以下输入设置类型组成的颜色方案：

• header
• color
• color_background

颜色方案只能在 settings_schema.json 中添加。

例如，以下设置会生成以下输出：

{
  "type": "color_scheme_group",
  "id": "color_schemes",
  "definition": [
    {
      "type": "color",
      "id": "background",
      "label": "t:settings_schema.colors.settings.background.label",
      "default": "#FFFFFF"
    },
    {
      "type": "color_background",
      "id": "background_gradient",
      "label": "t:settings_schema.colors.settings.background_gradient.label",
      "info": "t:settings_schema.colors.settings.background_gradient.info"
    },
    {
      "type": "color",
      "id": "text",
      "label": "t:settings_schema.colors.settings.text.label",
      "default": "#121212"
    },
    {
      "type": "color",
      "id": "button",
      "label": "t:settings_schema.colors.settings.button_background.label",
      "default": "#121212"
    },
    {
      "type": "color",
      "id": "button_label",
      "label": "t:settings_schema.colors.settings.button_label.label",
      "default": "#FFFFFF"
    },
    {
      "type": "color",
      "id": "secondary_button_label",
      "label": "t:settings_schema.colors.settings.secondary_button_label.label",
      "default": "#121212"
    },
    {
      "type": "color",
      "id": "shadow",
      "label": "t:settings_schema.colors.settings.shadow.label",
      "default": "#121212"
    }
  ],
  "role": {
    "text": "text",
    "background": {
      "solid": "background",
      "gradient": "background_gradient"
    },
    "links": "secondary_button_label",
    "icons": "text",
    "primary_button": "button",
    "on_primary_button": "button_label",
    "primary_button_border": "button",
    "secondary_button": "background",
    "on_secondary_button": "secondary_button_label",
    "secondary_button_border": "secondary_button_label"
  }
}

role

role 字段会输出颜色方案预览。颜色方案预览会在编辑器中商家可能选择颜色方案的任何地方显示。你可以为颜色方案定义分配角色，以将颜色方案映射到预览。例如，你可以将 role.background 分配给 Background 定义。role 使用以下标准化映射将 color_scheme_group 定义与颜色方案预览关联：

font_picker

一种 font_picker 类型的设置会输出一个字体选择器字段，该字段会自动填充 Shopify 字体库 中的字体。该字体库包括网页安全字体、部分 Google Fonts 和 Monotype 授权的字体。

你可以使用此设置类型来捕获各种主题元素的字体选择，例如基础标题字体。

例如，以下设置会生成以下输出：

{
  "type": "font_picker",
  "id": "heading_font",
  "label": "Heading font",
  "default": "helvetica_n4"
}

当访问 font_picker 类型设置的值时，数据会以 font 对象 的形式返回。

注意事项

default 属性是必填的。如果未包含此属性会导致错误。你可以通过 Shopify 字体库中的 可用字体 查找可能的值。

html

一种 html 类型的设置会输出一个多行文本字段，接受 HTML 标记。除了输入设置的 标准属性 外，html 类型的设置还有以下属性：

你可以使用此设置类型来捕获自定义的 HTML 内容块，例如视频嵌入。

例如，以下设置会生成以下输出：

{
  "type": "html",
  "id": "video_embed",
  "label": "Video embed"
}

以下 HTML 标签会被自动移除：

• <html>
• <head>
• <body>

当访问 html 类型设置的值时，数据会以以下格式之一返回：

• 包含输入内容的 字符串。
• 如果未输入内容，则返回 empty 对象。

注意

保存设置时，未闭合的 HTML 标签会自动闭合。这可能与你的预期格式不一致，因此请务必验证输入内容。

image_picker

一种 image_picker 类型的设置会输出一个图像选择器字段，该字段会自动填充 Shopify 后台 Files 部分中的可用图像，并支持上传新图像。商家还可以为图像输入替代文本并选择 焦点。

你可以使用此设置类型来捕获图像选择，例如标志、favicon 和轮播图图像。

例如，以下设置会生成以下输出：

{
  "type": "image_picker",
  "id": "image_with_text_image",
  "label": "Image"
}

当访问 image_picker 类型设置的值时，数据会以以下格式之一返回：

• 一个 image 对象。
• 如果未进行选择或选择已不存在，则返回 nil。

注意

image_picker 类型的设置在切换预设时不会更新。image_picker 设置也不支持 default 属性。

图像焦点

通过 image_picker 设置选择的图像支持焦点。焦点是商家希望在主题裁剪和调整图像时保留在视图中的位置。焦点可以在主题编辑器的 image_picker 设置中设置，也可以从 Files 页面设置。

为确保你的主题尊重图像的焦点，请执行以下操作：

• 使用 image_tag 过滤器渲染图像。
• 考虑使用 object-fit: cover 在容器中定位图像。

使用 image_tag，如果提供了焦点，则会在图像标签中添加 object-position 样式，值设置为焦点位置。

{{ section.settings.image_with_text_image | image_url: width: 1500 | image_tag }}

输出

<img src="octopus-tentacle.jpg?v=1&width=1500" alt="My alt text"
 srcset="octopus-tentacle.jpg?v=1&width=352 352w,
         octopus-tentacle.jpg?v=1&width=832 832w,
         octopus-tentacle.jpg?v=1&width=1200 1200w"
 width="1500" height="1875"
 style="object-position:25% 10%;">

如果需要针对特定用例覆盖 object-position 样式，则向 image_tag 过滤器传递 style: object-position: inherit; 属性。

提示

你可以通过 image.presentation.focal_point 访问焦点数据。

inline_richtext

类型为 inline_richtext 的设置会输出未被段落标签（<p>）包裹的 HTML 标记。该设置包含以下基础格式选项：

• 粗体
• 斜体
• 链接

注意

inline_richtext 设置不支持以下功能：

• 换行符（<br>）
• 富文本编辑器中的下划线选项。商家可以通过 Command+U 或 Control+U 快捷键对文本添加下划线。

你可以使用此设置类型来捕获格式化的文本内容，例如首页上的品牌介绍内容。

例如，以下设置会生成以下输出：

{  
  "type": "inline_richtext",  
  "id": "inline",  
  "default": "my <i>inline</i> <b>text</b>",  
  "label": "Inline rich text"  
}

访问 inline_richtext 类型设置的值时，数据以以下格式之一返回：

• 包含输入内容的 字符串。
• 如果未输入内容，则返回 empty 对象。

link_list

类型为 link_list 的设置会输出一个菜单选择字段，该字段会自动填充商店的可用菜单。你可以使用此设置类型来捕获菜单选择，例如页脚链接使用的菜单。

例如，以下设置会生成以下输出：

{  
  "type": "link_list",  
  "id": "menu",  
  "label": "Menu"  
}

访问 link_list 类型设置的值时，数据以以下格式之一返回：

• linklist 对象。
• 如果未进行选择或选择已不存在，则返回 blank。

注意

default 属性的可接受值为 main-menu 和 footer。

liquid

类型为 liquid 的设置会输出一个多行文本字段，该字段接受 HTML 和 有限制的 Liquid 标记。你可以使用此设置类型来捕获自定义的 HTML 和 Liquid 内容块，例如产品特定消息。商家还可以使用 liquid 设置来添加代码，以将某些类型的 应用 集成到你的主题中。

例如，以下设置会生成以下输出：

{  
  "type": "liquid",  
  "id": "battery_message",  
  "label": "Battery message",  
  "default": "{% if product.tags contains 'battery' %}This product can only be shipped by ground.{% else %}This product can be shipped by ground or air.{% endif %}"  
}

访问 liquid 类型设置的值时，数据以以下格式之一返回：

• 包含输入内容的 字符串。
• 如果未输入内容，则返回 empty 对象。

注意

default 属性是可选的。但如果你使用它，则其值不能是空字符串。此外，保存设置时未闭合的 HTML 标签会自动闭合。这可能与你的预期格式不一致，因此请务必验证输入内容。

限制

liquid 类型的设置无法访问以下 Liquid 对象/标签：

• layout
• content_for_header
• content_for_layout
• content_for_index
• section
• javascript
• stylesheet
• schema
• settings

但 liquid 设置可以访问以下内容：

• 全局 Liquid 对象
• 诸如 collection、product 等模板特定对象（在其各自的模板内）
• 标准 Liquid 标签 和 过滤器

如果内容包含不存在或为空的 Liquid 标签，则它们会被渲染为空字符串。例如，以下设置会生成以下输出：

{  
  "type": "liquid",  
  "id": "message",  
  "label": "Message",  
  "default": "Hello {{ not_a_real_tag }}, welcome to our shop."  
}

Hello , welcome to our shop.

警告

在这些设置中输入的内容不能超过 50KB。保存超出此限制或包含无效 Liquid 的内容会导致错误。

metaobject

metaobject 设置允许商家通过选择器界面选择指定类型的 metaobject 条目。此设置支持标准和自定义的 metaobject 定义：

1. 标准 metaobject 定义：这些在主题编辑器中即刻可用，无需在商店中预先启用。一个标准 metaobject 的例子是 product_review metaobject。了解更多 关于当前标准 metaobject 定义。
2. 自定义 metaobject 定义：这些专为自定义主题设计，要求 metaobject 定义已存在。注意，Theme Store 中列出的主题不允许使用自定义 metaobject 定义。一个自定义 metaobject 的例子是 author metaobject。

此外，应用程序可以使用其自己的应用程序拥有的 metaobject 定义和条目来利用 metaobject 设置。

metaobject 类型的设置除了具有 输入设置的标准属性 外，还具有以下属性：

metaobject 设置的值可以是以下格式之一：

• metaobject 对象
• 如果未进行选择、选择不可见或选择已不存在，则返回 blank

标准 metaobject 示例

{  
  "type": "metaobject",  
  "id": "my_material_setting",  
  "label": "Material",  
  "metaobject_type": "shopify--material"  
}

自定义 metaobject 示例

{  
  "type": "metaobject",  
  "id": "my_artist",  
  "label": "Artist",  
  "metaobject_type": "artist"  
}

限制

• 同一时间仅支持一个 metaobject_type，如设置模式中定义的那样。
• 为了使主题符合 Shopify Theme Store 的 发布指南，只能使用标准定义。不能使用自定义或应用程序拥有的定义。
• 当引用 自定义 或 应用程序创建的 metaobject_type 时，定义必须存在于商店中并可供 storefront 使用。如果任一条件未满足，设置会在主题编辑器中显示错误。

在应用中的使用

应用可以通过其应用模块或嵌入组件中的 metaobject 设置来增强主题功能。通过在 保留命名空间（reserved namespaces） 下创建 metaobject 定义，应用可以为商家提供高级配置选项，同时保持简单的用户体验。

举个例子，假设有一个旨在通过客户证言提升品牌叙事的应用。以下是可能的实现步骤：

1. 创建一个名为 Customer Testimonial 的自定义 metaobject 定义
2. 使用应用模块在购买后页面收集客户数据
3. 将这些数据写入 Customer Testimonial metaobject 条目
4. 提供一个 Testimonial 应用模块，并添加一个 metaobject 设置，使用 Customer Testimonial metaobject 类型
5. 在 Liquid 中访问 metaobject 设置值，以展示选中的证言

{
  "type": "metaobject",
  "id": "my_testimonial",
  "label": "Testimonial",
  "metaobject_type": "app--<appid>-testimonial"
}

metaobject_list

metaobject_list 设置允许商家通过选择器界面选择多个指定类型的 metaobject 条目。此设置支持标准和自定义 metaobject 定义：

1. 标准 metaobject 定义：这些定义在主题编辑器中直接可用，无需预先在商店中启用。例如 product_review metaobject。了解更多 当前标准 metaobject 定义。
2. 自定义 metaobject 定义：这些定义专为自定义主题设计，要求 metaobject 定义已存在。注意：Theme Store 列表中的主题不允许使用自定义 metaobject 定义。例如 author metaobject。

此外，应用可以利用 metaobject_list 设置与自身的应用拥有的 metaobject 定义和条目结合使用。

metaobject_list 类型的设置具有以下属性（除 标准属性（standard attributes） 外）：

metaobject_list 设置值可以是以下格式之一：

• 一个 metaobject 对象 的数组
  该数组支持使用 paginate 标签进行分页。你也可以在 设置键（setting key） 后追加 .count 以返回数组中 metaobject 条目的数量。
• 如果未选择内容、选择不可见或选择已不存在，则返回 blank

标准 metaobject 列表示例

{
  "type": "metaobject_list",
  "id": "my_material_list_setting",
  "label": "Materials",
  "metaobject_type": "shopify--material",
  "limit": 12
}

自定义 metaobject 列表示例

{
  "type": "metaobject_list",
  "id": "my_artist_list",
  "label": "Artists",
  "metaobject_type": "artist",
  "limit": 12
}

限制

• 每个设置仅支持一种 metaobject_type，由设置的 schema 定义。
• 为了符合 Shopify Theme Store 的 发布指南（publishing guidelines），主题不能使用自定义或应用拥有的定义。
• 当引用 自定义 或 应用创建的 metaobject_type 时，定义必须存在于商店中并向 storefront 可用。若任一条件未满足，主题编辑器中的设置将显示错误。

在应用中的使用

应用可以在其应用模块或嵌入组件中使用 metaobject_list 设置来增强主题功能。通过在 保留命名空间（reserved namespaces） 下创建 metaobject 定义，应用可以为商家提供高级配置选项，同时保持简单的用户体验。使用上述 示例（example） 中的 Testimonials 应用模块，商家可以选择多个证言条目。metaobject_list 设置使这一实现成为可能。

{
  "type": "metaobject_list",
  "id": "my_testimonial_list",
  "label": "Testimonials list",
  "metaobject_type": "app--<appid>-testimonial",
  "limit": 12
}

page

page 类型的设置会输出一个自动填充商店可用页面的页面选择器字段。你可以使用此设置类型捕获页面选择，例如在尺码表展示中选择要显示内容的页面。

例如，以下设置生成如下输出：

{
  "type": "page",
  "id": "page",
  "label": "Page"
}

当访问 page 类型设置的值时，数据以以下格式之一返回：

• 一个 page 对象
  为了向后兼容 遗留资源型设置（legacy resource-based settings），直接输出设置值将返回对象的 handle。
• 如果未选择内容、选择不可见或选择已不存在，则返回 blank

注意

切换预设时，page 类型的设置不会更新。page 设置也不支持 default 属性。

product

product 类型的设置会输出一个自动填充商店可用产品的商品选择器字段。你可以使用此设置类型捕获商品选择，例如在首页上展示的商品。

例如，以下设置生成如下输出：

{
  "type": "product",
  "id": "product",
  "label": "Product"
}

当访问 product 类型设置的值时，数据以以下格式之一返回：

• 一个 product 对象
  为了向后兼容 遗留资源型设置（legacy resource-based settings），直接输出设置值将返回对象的 handle。
• 如果未选择内容、选择不可见或选择已不存在，则返回 blank

注意

类型为 product 的设置在切换预设时不会更新。product 类型的设置也不支持 default 属性。

product_list

类型为 product_list 的设置会输出一个产品选择器字段，该字段会自动填充商店中可用的产品。你可以使用此设置类型来捕获多个产品，例如在首页上展示的一组产品。

注意

只能从已发布到在线商店且状态为 active 的产品中进行选择。

除了 标准属性 之外，product_list 类型的设置还支持以下属性：

{  
  "type": "product_list",  
  "id": "product_list",  
  "label": "Products",  
  "limit": 12  
}

当访问 product_list 类型设置的值时，数据会以以下格式之一返回：

• 包含 product 对象 的数组。
  该数组支持通过 paginate 标签进行分页。你也可以在 设置键 后添加 .count 来返回数组中的产品数量。
• 如果未进行选择、选择不可见或选择已不存在，则返回 blank。

richtext

类型为 richtext 的设置会输出一个多行文本字段，支持以下基本格式选项：

• 加粗
• 斜体
• 下划线
• 链接
• 段落
• 无序列表

注意

富文本组件中不会显示下划线选项。商家可以通过 Command+U 或 Control+U 键盘快捷键添加下划线。

你可以使用此设置类型来捕获格式化文本内容，例如首页上的品牌介绍内容。

例如，以下设置会生成以下输出：

{  
  "type": "richtext",  
  "id": "paragraph",  
  "label": "Paragraph"  
}

当访问 richtext 类型设置的值时，数据会以以下格式之一返回：

• 包含输入内容的 字符串。
• 如果未输入内容，则返回 empty 对象。

default

default 属性不是必填项。但如果使用它，则仅支持 <p> 或 <ul> 标签作为顶级元素。

以下 HTML 标签也支持在父级 <p> 标签内使用：

• <p>
• <br>
• <strong>
• <b>
• <em>
• <i>
• <u>
• <span>
• <a>

注意

如果未将 default 内容包裹在 <p> 或 <ul> 标签中，会导致错误。

text_alignment

类型为 text_alignment 的设置会输出一个带图标的 SegmentedControl 字段。除了 标准属性 之外，text_alignment 类型的设置还支持以下属性：

text_alignment 类型设置支持的附加属性

以下默认值无法更改为其他值：

值	图标展示
Left
Right
Center

例如，以下设置会生成以下输出：

{  
   "type": "text_alignment",  
   "id": "alignment",  
   "label": "Text alignment",  
   "default": "center"  
}

当访问 text_alignment 类型设置的值时，数据会以 字符串 格式返回。

注意

如果未指定 default 属性，则默认选择 left。

url

类型为 url 的设置会输出一个 URL 输入字段，你可以手动输入外部 URL 或相对路径。它还有一个自动填充以下商店可用资源的选取器：

• 文章
• 博客
• 集合
• 页面
• 产品

你可以使用此设置类型来捕获 URL 选择，例如幻灯片按钮链接要使用的 URL。

例如，以下设置会生成以下输出：

{  
  "type": "url",  
  "id": "button_link",  
  "label": "Button link"  
}

当访问 url 类型设置的值时，数据会以以下格式之一返回：

• 包含所选 URL 的 字符串。
• 如果未输入内容，则返回 nil。

注意

default 属性的可接受值为 /collections 和 /collections/all。

video

类型为 video 的设置会输出一个视频选择器，该选择器会自动从 Shopify 管理后台的 Files（文件） 部分中填充可用的视频。商家还可以选择上传新的视频。

例如，以下设置会生成如下输出：

{
  "type": "video",
  "id": "video",
  "label": "A Shopify-hosted video"
}

video 类型的设置还支持类型为 file_reference 的 metafields 作为 动态源。

当访问 video 类型设置的值时，数据会以以下格式之一返回：

• 一个 video 对象。
• nil，如果：
  • 未进行任何选择，
  • 选择的视频已不存在，或
  • 选择的是指向非视频文件的 file_reference metafield。

注意

video 设置不支持 default 属性。

video_url

类型为 video_url 的设置会输出一个 URL 输入字段。除了输入设置的标准属性外，video_url 类型设置还包含以下属性：

此设置类型可用于捕获来自 YouTube 和/或 Vimeo 的视频 URL，例如产品描述中静态视频的 URL。

例如，以下设置会生成如下输出：

{
  "type": "video_url",
  "id": "product_description_video",
  "label": "Product description video",
  "accept": [
    "youtube",
    "vimeo"
  ]
}

当访问 video_url 类型设置的值时，数据会以以下格式之一返回：

• 一个 字符串，包含输入的 URL。
• nil，如果未输入任何内容。

此外，还可以访问视频的 id 和 type（YouTube 或 Vimeo）。

例如，假设你使用了 这个视频，并通过上述设置调用，以下 Liquid 代码会生成如下输出：

ID: {{ settings.product_description_video.id }}
Type: {{ settings.product_description_video.type }}

ID: _9VUPq3SxOc
Type: youtube

创建链接

你可以通过将链接文本用方括号包裹，并在其后立即用括号添加 URL 的方式，在 info 设置属性中添加链接。

例如，以下设置会生成如下输出：

{
  "type": "checkbox",
  "id": "enable_payment_button",
  "label": "Show dynamic checkout button",
  "info": "Each customer will see their preferred payment method [Learn more](https://help.shopify.com/manual/online-store/dynamic-checkout)",
  "default": true
},

注：

1. 所有技术术语（如 Liquid、metafields、Shopify admin 等）均保留原英文，符合 Shopify 官方文档规范。
2. 链接和代码格式严格按照原文保留，确保可直接复制使用。
3. 翻译内容完全基于原文，未添加额外信息。