输入设置可以保存一个值,商家可以对其进行配置。
输入设置一般由标准属性组成,分为两类:
- 基本输入设置
- 专用输入设置
标准属性
以下是所有输入设置的标准属性。不过,根据输入类型的不同,可能会有额外的属性,或者有些属性并不适用:
属性 | 描述 | 必须 |
type | 设置类型,可以是任何基本或特殊输入设置类型 | 是 |
id | 设置 ID,用于访问设置值 | 是 |
label | 设置标签,将显示在主题编辑器中 | 是 |
default | 设置的默认值 | 否 |
info | 有关设置信息文本的选项 | 否 |
基本输入设置
以下是基本输入设置类型:
- checkbox
- number
- radio
- range
- select
- text
- textarea
checkbox
复选框类型的设置会输出一个复选框字段。这些字段可用于切换功能的开启和关闭,例如是否显示公告栏。
例如,以下设置会产生以下输出:
{
"type": "checkbox",
"id": "show_announcement",
"label": "Show announcement",
"default": true
}

访问复选框类型设置的值时,数据以boolean形式返回。
注意
如果未指定默认值,则默认值为 false
数字
数字类型的设置会输出一个数字字段。除了输入设置的标准属性外,数字类型设置还具有以下属性:
属性 | 描述 | 必须 |
placeholder | 输入的占位符值。 这些值仅出现在 settings_schema.json 中定义的设置中。它们不会出现在分区schema中定义的设置中。 | 否 |
您可以使用这些字获取捉不同的数值,例如在集合页面上每页显示的产品数量。
例如,以下设置会产生以下输出:
{
"type": "number",
"id": "products_per_page",
"label": "Products per page",
"default": 20
}

访问数字类型设置的值时,数据将以下列方式之一返回:
- 数字。
- nil,如果未输入任何内容。
注意事项
默认属性是可选的。但是,值必须是数字而不是字符串。否则将导致错误。
radio
单选框类型的设置输出一个单选框选项字段。除了输入设置的标准属性外,单选框类型设置还有一个必需的options属性,该属性可接受value
和label
定义的数组。
您可以使用这些字段获取多选项选择,例如标题logo的对齐方式。
例如,以下设置会产生以下输出:
{
"type": "radio",
"id": "logo_aligment",
"label": "Logo alignment",
"options": [
{
"value": "left",
"label": "Left"
},
{
"value": "centered",
"label": "Centered"
}
],
"default": "left"
}

访问单选框类型设置值时,数据以字符串形式返回。
注意
如果未指定默认值,则默认选择第一个选项。
range
range 类型的设置会输出一个范围滑块字段。除了输入设置的标准属性外,范围类型设置还具有以下属性:
属性 | 描述 | 必须 |
min | 输入的最小值 | 是 |
max | 输入的最大值 | 是 |
step | 滑块步长之间的增量大小 | 是 |
unit | 入的单位。例如,可以为字体大小滑块设置 px | 否 |
您可以使用这些字段获取变化的数值,如字体大小。
例如,以下设置会产生以下输出:
{
"type": "range",
"id": "font_size",
"min": 12,
"max": 24,
"step": 1,
"unit": "px",
"label": "Font size",
"default": 16
}

访问范围类型设置值时,数据将以数字形式返回。
注意事项
默认属性是必需的。min、max、step 和 default 属性不能是字符串值。否则会导致错误。
select
select 类型的设置会输出一个下拉选择器字段。除了输入设置的标准属性外,选择类型设置还具有以下属性:
属性 | 描述 | 必须 |
options | 获取下拉菜单中每个选项的value /label 定义数组。 | 是 |
group | 可选属性,可以添加到每个选项中,以便在下拉菜单中创建选项组。 | 否 |
您可以使用这些字段获取下拉选项,例如幻灯片文本的垂直对齐方式。
例如,以下设置会产生以下输出:
{
"type": "select",
"id": "vertical_alignment",
"label": "Vertical alignment",
"options": [
{
"value": "top",
"label": "Top"
},
{
"value": "middle",
"label": "Middle"
},
{
"value": "bottom",
"label": "Bottom"
}
],
"default": "middle"
}

访问选择类型设置值时,数据以字符串形式返回。
注意
如果未指定默认值,则默认选择第一个选项。
文本
文本类型设置可输出单行文本字段。除了输入设置的标准属性外,文本类型设置还具有以下属性:
属性 | 描述 | 必须 |
placeholder | 输入的占位符值。 这些值仅出现在 settings_schema.json 中定义的设置中。它们不会出现在分区schema中定义的设置中。 | 否 |
您可以使用这些字段获取短字符串,如标题。
例如,以下设置会产生以下输出
{
"type": "text",
"id": "footer_linklist_title",
"label": "Heading",
"default": "Quick links"
}

访问文本类型设置值时,数据将以下列形式之一返回:
- 字符串
- 空对象(如果未输入任何内容)。
提示
切换预置时,文本类型的设置不会更新。
textarea
textarea类型的设置会输出一个多行文本字段。除了输入设置的标准属性外,textarea类型设置还具有以下属性:
属性 | 描述 | 必须 |
placeholder | 输入的占位符值。 这些值仅出现在 settings_schema.json 中定义的设置中。它们不会出现在分区schema中定义的设置中。 | 否 |
您可以使用这些字段获取较大的文本块,如信息。
例如,以下设置会产生以下输出:
{
"type": "textarea",
"id": "home_welcome_message",
"label": "Welcome message",
"default": "Welcome to my shop!"
}

访问文本区域类型设置的值时,数据将以下列形式之一返回:
- 字符串
- 空对象,如果没有输入任何内容。
专用输入设置
以下是专用输入设置类型:
- article
- blog
- collection
- collection_list
- color
- color_background
- color_scheme
- color_scheme_group
- font_picker
- html
- image_picker
- inline_richtext
- link_list
- liquid
- page
- product
- product_list
- richtext
- url
- video
- video_url
article
文章类型的设置会输出一个文章选择器字段,该字段会自动填充商店的可用文章。您可以使用这些字段来获取文章选择,例如在主页上显示的文章。
例如,以下设置会产生以下输出:
{
"type": "article",
"id": "article",
"label": "Article"
}

访问文章类型设置的值时,数据将以下列方式之一返回:
- 文章对象。为确保与传统的基于资源的设置向后兼容,直接输出设置将返回对象的handle。
- 如果没有进行选择、选择不可见或选择不再存在,则返回
blank
。
注意
切换预设时,文章类型的设置不会更新。文章设置也不支持默认属性。
blog
博客类型的设置会输出一个博客选择器字段,该字段会自动填充商店的可用博客。您可以使用这些字段来获取博客选择,如在侧边栏中显示的博客。
例如,以下设置会产生以下输出:
{
"type": "blog",
"id": "blog",
"label": "Blog"
}

访问博客类型设置值时,数据将以下列方式之一返回:
- 博客对象。为确保与传统的基于资源的设置向后兼容,直接输出设置将返回对象的句柄。
blank
,如果没有进行选择或选择不再存在。
注意
博客类型的设置在切换预设时不会更新,博客设置也不支持default
属性
collection
集合类型的设置会输出一个集合选择器字段,该字段会自动填充商店的可用集合。您可以使用这些字段来获取集合选择,例如在主页上展示产品的集合。例如,以下设置会产生以下输出:
{
"type": "collection",
"id": "collection",
"label": "Collection"
}

当访问集合类型的设置值时,返回的数据可能是以下之一:
- 集合对象。
- 为了确保与旧的基于资源的设置的向后兼容性,直接输出该设置将返回对象的handle。
- 如果没有进行选择,选择不可见,或选择不再存在,则返回
blank
。
注意
切换预设时,不会更新集合类型的设置。集合设置也不支持默认属性。
collection_list
collection_list 类型的设置会输出一个集合选择器字段,该字段会自动填充商店的可用集合。您可以使用这些字段获取多个产品集合,例如在主页上显示一组产品集合。
除了输入设置的标准属性外,collection_list 类型设置还具有以下属性:
属性 | 描述 | 必须 |
limit | 商家可选择的最大集合数量。默认限制和可设置的最大限制均为 50。 | 否 |
{
"type": "collection_list",
"id": "collection_list",
"label": "Collections",
"limit": 8
}


访问 collection_list 类型设置的值时,数据将以下列形式之一返回:
- 集合对象数组。该数组支持使用分页标签进行分页。也可以在设置key上附加 .count 来返回数组中的集合数。
- 如果没有选择、选择不可见或选择不再存在,则返回
blank
。
color
颜色类型的设置会输出一个颜色选择器字段。您可以使用这些字段获取各种主题元素的颜色选择,例如正文文本的颜色。
例如,以下设置会产生以下输出:
{
"type": "color",
"id": "body_text",
"label": "Body text",
"default": "#000000"
}

访问颜色类型设置值时,数据将以下列方式之一返回:
- 颜色对象。
- blank,如果没有进行选择。
color_background
color_background 类型的设置会输出一个文本字段,用于输入 CSS 背景属性。您可以使用这些字段获取各种主题元素的背景设置,如商店背景。
注意事项
color_background 类型的设置不支持与图像相关的背景属性。
例如,以下设置会产生以下输出:
{
"type": "color_background",
"id": "background",
"label": "Background",
"default": "linear-gradient(#ffffff, #000000)"
}

访问 color_background 类型设置的值时,数据将以下列形式之一返回:
- 字符串。
- 如果未输入任何内容,则返回空字符串。
color_scheme
color_scheme 类型的设置会输出一个包含所有可用主题配色方案的拾取器,以及所选配色方案的预览。拾取器中的主题配色方案是通过 color_scheme_group 设置定义的。你可以将配色方案应用到分区、块和一般主题设置中。应用程序块不支持配色方案设置。
例如,以下设置会产生以下输出
{
"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": "header",
"content": "Typography"
},
{
"type": "color",
"id": "text",
"label": "Text",
"default": "#121212"
},
{
"type": "header",
"content": "Background"
},
{
"type": "color",
"id": "background",
"label": "Background",
"default": "#FFFFFF"
},
{
"type": "color_background",
"id": "background_gradient",
"label": "Gradient",
"info": "Background gradient replaces background where possible."
},
{
"type": "header",
"content": "Additional"
},
{
"type": "color",
"id": "primary_button",
"label": "Primary",
"default": "#121212"
},
{
"type": "color",
"id": "on_primary_button",
"label": "On Primary Button",
"default": "#FFFFFF"
},
{
"type": "color",
"id": "primary_button_border",
"label": "Primary Button Border",
"default": "#121212"
},
{
"type": "color",
"id": "secondary_button",
"label": "Secondary Button"
},
{
"type": "color",
"id": "on_secondary_button",
"label": "On Secondary Button",
"default": "#121212"
},
{
"type": "color",
"id": "secondary_button_border",
"label": "Secondary Button Border",
"default": "#FFFFFF"
},
{
"type": "color",
"id": "icons",
"label": "Icons",
"default": "#FFFFFF"
},
{
"type": "color",
"id": "links",
"label": "Links",
"default": "#121212"
}
],
"role": {
"background": {
"solid": "background",
"gradient": "background_gradient"
},
"text": "text",
"primary_button": "primary_button",
"on_primary_button": "on_primary_button",
"primary_button_border": "primary_button_border",
"secondary_button": "secondary_button",
"on_secondary_button": "on_secondary_button",
"secondary_button_border": "secondary_button_border",
"icons": "icons",
"links": "links"
}
}

role
角色字段输出配色方案预览。商家可以在编辑器中的任何地方看到配色方案预览,从而选择配色方案。您可以为配色方案定义分配角色,以便将配色方案映射到预览中。例如,您可以将 role.background 指定给 Background 定义。角色使用以下 color_scheme_group 定义到配色方案预览的标准化映射:
角色 | 描述 | 必须 | 倾斜度 |
role.background | 渲染预览的背景颜色 | 是 | 可选的 |
role.text | 渲染预览文本的颜色 | 是 | 否 |
role.primary_button role.secondary_button | 在预览中渲染第 1 和第 2 个按钮 | 是 | 可选的 |
role.primary_button_border role.secondary_button_border | 在预览中渲染第一个和第二个按钮的边框 | 是 | 否 |
role.on_primary_button role.on_secondary_button | 预览中没有使用 | 是 | 否 |
role.links role.icons | 预览中没有使用 | 是 | 否 |

font_picker
font_picker 类型的设置会输出一个字体选择器字段,该字段会自动填充 Shopify 字体库中的字体。该库包括网络安全字体、Google 字体精选和 Monotype 授权字体。
您可以使用这些字段获取各种主题元素的字体选择,例如基本标题字体。
例如,以下设置会产生以下输出:
{
"type": "font_picker",
"id": "heading_font",
"label": "Heading font",
"default": "helvetica_n4"
}

访问 font_picker 类型设置的值时,数据将作为字体对象返回。
注意事项
default属性是必需的。不包含该属性将导致错误。您可以通过 Shopify 字体库中的可用字体找到可能的值。
html
html 类型的设置可输出可接受 HTML 标记的多行文本字段。除了输入设置的标准属性外,html 类型设置还具有以下属性:
属性 | 描述 | 必须 |
placeholder | 输入的占位符值。 | 否 |
您可以使用这些字段获取自定义 HTML 内容块,如视频嵌入。
例如,以下设置会生成以下输出:
{
"type": "html",
"id": "video_embed",
"label": "Video embed"
}

以下 HTML 标签将被自动删除:
- <html>
- <head>
- <body>
访问 html 类型设置的值时,数据将以下列方式之一返回:
- 包含输入内容的字符串。
- 空对象,如果没有输入任何内容。
注意
保存设置时,未关闭的 HTML 标记会自动关闭。这可能与您想要的格式不一致,因此请务必验证您的输入。
image_picker
image_picker 类型的设置会输出一个图片选择器字段,该字段会从 Shopify 管理的 “文件 “部分自动填充可用图片,并提供上传新图片的选项。商家还可以输入alt文本,并选择图片的焦点。
您可以使用这些字段捕捉图像选择,如徽标、收藏夹和幻灯片图像。
例如,以下设置会产生以下输出:
{
"type": "image_picker",
"id": "image_with_text_image",
"label": "Image"
}

输出

访问图像选取器类型设置的值时,数据将以下列方式之一返回:
- 图像对象。
- nil,如果没有进行选择或选择不再存在。
注释
切换预置时,image_picker 类型的设置不会更新。image_picker 设置也不支持默认属性。
图像焦点
使用图像选取器设置选取的图像支持焦点。焦点是商家希望在主题对图片进行裁剪和调整时仍能看到的图片位置。焦点可以在主题编辑器的图像选取器设置中设置,也可以在文件页面中设置。
要确保您的主题使用图片的焦点,请执行以下操作:
- 使用 image_tag filter渲染图片。
- 考虑使用 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 样式,请将 style: object-position: inherit; 属性传递给 image_tag filter。
提示:您也可以使用 image.presentation.focal_point 来访问焦点数据。
inline_richtext
inline_richtext 类型的设置输出未包含在段落标签(<p>
)中的 HTML 标记。该设置包括以下基本的格式选项:
- Bold
- Italic
- Link
注意:inline_richtext
设置不支持以下功能:
- 换行(
<br>
) - 富文本编辑器中的下划线选项。商家可以使用 CMD+U 或 CTRL+U 键盘快捷键为文本添加下划线。
您可以使用这些字段来获取格式化的文本内容,例如首页的品牌介绍内容。
例如,以下设置将生成以下输出:
{
"type": "inline_richtext",
"id": "inline",
"default": "my <i>inline</i> <b>text</b>",
"label": "Inline rich text"
}

当访问inline_richtext类型的设置值时,数据将以以下之一的形式返回:
- 包含输入内容的字符串。
- 一个空对象,如果没有输入任何内容。
link_list
link_list类型的设置会输出一个菜单选择器字段,该字段会自动填充为商店中可用的菜单。您可以使用这些字段来获取菜单选择,比如用于页脚链接的菜单。
例如,以下设置会生成以下输出:
{
"type": "link_list",
"id": "menu",
"label": "Menu"
}

访问 link_list 类型设置的值时,数据将以下列方式之一返回:
- 链接列表对象。
- blank,如果没有进行选择或选择已不存在。
注意
默认属性的可接受值是主菜单和页脚。
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类型设置值时,数据将以下列方式之一返回:
- 包含输入内容的字符串。
- 如果未输入任何内容,则返回空对象。
注意
默认属性是可选的。但是,如果使用默认属性,其值就不能是空字符串。此外,在保存设置时,未关闭的 HTML 标记会自动关闭。这可能与您想要的格式不一致,因此请务必验证您的输入
限制
liquid类型的设置无法访问以下liquid 对象/标记:
- layout
- content_for_header
- content_for_layout
- content_for_index
- section
- javascript
- stylesheet
- schema
- settings
不过,liquid设置可以访问以下内容:
- 全局 Liquid 对象
- 特定模板对象,如集合、产品等(在各自模板内)
- 标准 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 的内容将导致错误。
page
页面 “类型的设置会输出一个页面选择器字段,该字段会自动填充商店的可用页面。您可以使用这些字段获取页面选择。
例如,以下设置会产生以下输出:
{
"type": "page",
"id": "page",
"label": "Page"
}

访问页面类型设置值时,数据将以下列方式之一返回:
- 页面对象。为确保与传统的基于资源的设置向后兼容,直接输出设置将返回对象的handle。
- blank,如果没有进行选择、选择不可见或选择不再存在。
注意
切换预设时,页面类型的设置不会更新。页面设置也不支持默认属性。
产品
产品类型的设置会输出一个产品选择器字段,该字段会自动填充商店的可用产品。您可以使用这些字段来获取产品选择,例如在主页上显示的产品。
例如,以下设置会产生以下输出:
{
"type": "product",
"id": "product",
"label": "Product"
}

访问产品类型设置值时,数据将以下列形式之一返回:
- 产品对象。为确保与传统的基于资源的设置向后兼容,直接输出设置将返回对象的handle。
- 如果没有进行选择、选择不可见或选择不再存在,则返回blank 。
注意
切换预设时,产品类型的设置不会更新。产品设置也不支持默认属性。
product_list
product_list 类型的设置会输出一个产品选择器字段,该字段会自动填充商店的可用产品。您可以使用这些字段获取多个产品,例如在主页上展示的一组产品。
除了输入设置的标准属性外,产品列表类型设置还具有以下属性:
属性 | 描述 | 必要 |
limit | 商家可选择的最大产品数量。默认限制和可设置的最大限制均为 50 | 否 |
{
"type": "product_list",
"id": "product_list",
"label": "Products",
"limit": 12
}


当访问product_list类型设置的值时,数据将以以下之一的形式返回:
富文本
richtext类型的设置会输出一个带有以下基本格式选项的多行文本字段:
- Bold
- Italic
- Underline
- Link
- Paragraph
- Unordered list
注意事项
富文本组件中没有下划线选项。商家可使用 CMD+U 或 CTRL+U 快捷键为文本加下划线。
您可以使用这些字段获取格式化的文本内容,例如主页上的品牌介绍内容。
例如,以下设置会产生以下输出:
{
"type": "richtext",
"id": "paragraph",
"label": "Paragraph"
}

当访问富文本类型设置的值时,数据将以以下之一的形式返回:
- 包含输入内容的字符串。
- 如果没有输入任何内容,则为空对象。
default
默认属性是可选的。但是,如果使用了它,那么只支持 <p>
或 <ul>
标签作为顶层元素。
父<p>标签内还支持以下 HTML 标记:
<p>
<br>
<strong>
<b>
<em>
<i>
<u>
<span>
<a>
注意
未将default 内容用 <p> 或 <ul> 标签包裹会导致错误
url
url 类型的设置会输出一个 URL输入字段,您可以在此手动输入外部 URL 和相对路径。它还有一个选择器,可自动填充商店的以下可用资源:
- 文章
- 博客
- 系列
- 页面
- 产品
您可以使用这些字段获取 URL 选择,例如用于幻灯片按钮链接的 URL。
例如,以下设置会产生以下输出:
{
"type": "url",
"id": "button_link",
"label": "Button link"
}

访问 url 类型设置的值时,数据将以下列方式之一返回:
- 包含所选 URL 的字符串。
- nil,如果没有输入任何内容。
注释
默认属性的接受值为 /collections 和 /collections/all。
video
视频类型的设置会输出一个视频选择器,该选择器会从 Shopify 管理器的 “文件 “部分自动填充可用的视频。商家还可以选择上传新视频。
例如,以下设置会产生以下输出:
{
"type": "video",
"id": "video",
"label": "A Shopify-hosted video"
}

video类型设置还接受 file_reference 类型的元字段作为动态源。
访问视频类型设置的值时,数据将以下列方式之一返回:
- 视频对象。
- nil,如果未进行选择、选择不再存在,或选择是指向非视频文件的 file_reference 元字段。
注意
视频设置不支持默认属性。
video_url
video_url 类型的设置会输出一个 URL 输入字段。除了输入设置的标准属性外,video_url 类型的设置还具有以下属性:
属性 | 描述 | 必须 |
accept | 接受视频提供商的数组。有效值为 youtube、vimeo 或两者 | 是 |
placeholder | 输入内容的占位符值 | 否 |
这些字段可用于从 YouTube 和/或 Vimeo 捕捉视频 URL,例如在产品描述中显示静态视频的 URL。
例如,以下设置会产生以下输出:
{
"type": "video_url",
"id": "product_description_video",
"label": "Product description video",
"accept": [
"youtube",
"vimeo"
]
}

在访问 video_url 类型设置的值时,数据将以下列方式之一返回:
- 包含输入 URL 的字符串。
- nil,如果没有输入任何内容。
此外,还可以访问视频的 id 和类型(YouTube 或 Vimeo)。
例如,假设您在使用该视频时使用了上述设置,则以下 Liquid 会产生以下输出:
ID: {{ settings.product_description_video.id }}
Type: {{ settings.product_description_video.type }}
输出
ID: _9VUPq3SxOc
Type: youtube
Create links
您可以在 info 设置属性中添加链接,方法是将链接文本放在括号中,然后在括号中紧跟 URL。
例如,以下设置会产生以下输出:
{
"type": "checkbox",
"id": "enable_payment_button",
"label": "Show dynamic checkout button",
"info": "Each customer will see their preferred payment method from those available on your store, such as PayPal or Apple Pay. [Learn more](https://help.shopify.com/manual/online-store/dynamic-checkout)",
"default": true
},

原文:https://shopify.dev/docs/themes/architecture/settings/input-settings#liquid
发表回复