主题风格配置

启用页面生成器主题样式选项

每个主题包含两个相关的JSON文件:json和schema.json。要为商家提供主题样式定制选项，你必须在主题中声明这些选项schema.json文件。此外，您必须在主题中包含这些设置json文件、模板、Sass/CSS文件。

当用户在Page Builder UI中选择并保存选项时，Stencil将自动重写主题的json文件录制新的默认值。

基本分工如下:

• schema.json是一个对象数组，声明在主题样式中哪些主题设置是可编辑的。这些对象还声明了在Page Builder UI中显示的所有可能的值。
• json包含有关主题的元数据，如名称、版本和资源控件。
• json为每个可编辑设置分配和更新默认值。
• 每一个schema.json条目有一个ID元素将其映射到相应的条目json条目。ID值标识相关json关键的名字。
• 位于两个配置文件中的键设置定义主题的外观、感觉和功能。
• 钥匙位于变化的对象json定义主题的变体。每个主题可以包括的变化数量没有限制。
• 要使前端属性是可编辑的，主题的Handlebars模板必须调用某些Handlebars助手来转换json输入到JavaScript值中。
• 字体是可编辑的，Sass样式表必须调用特定的自定义Sass函数来转换json字体输入到CSS值。
• 对于可编辑的样式，Sass样式表必须调用特定的自定义Handlebars助手来转换json条目进入CSS值。

有关Cornerstone主题的主键的文档，请参阅Cornerstone的config.json元数据和schema.jsonMetadata条目。

文件管理的要求

对于任何主题设置为商家可自定义，必须存在该设置及其值schema.json。您必须手动提供这些声明。

创建的每个键schema.json必须有对应的jsonkey的名称与ID值匹配。这jsonKey设置默认值，即使它是一个空字符串。一个schema.json设置不id移植物json键不会出现在页面构建器UI中。

json条目如何管理Page Builder的UI

你在schema.json和json在主题样式中直接塑造用户的选项:

• 主题变体总是出现在主题样式面板的顶部。这些变化仅在json，它们在该文件中的定义顺序决定了它们在主题样式中的显示顺序。
• 商家必须每次选择一个变体进行编辑。他们在Page Builder UI的其余部分中所做的选择将只应用于所选的变体。
• 剩下的顶级节标题序列直接对应于您声明的顶级节对象schema.json。在这些可扩展部分标题中显示的选项直接对应于您在内部嵌套的键值对schema.json对应的section对象。

总之，你给主题的结构json和schema.json文件直接管理Page Builder暴露给商家的UI。

主题样式数据类型

您可以自由决定主题的哪些属性在主题样式中是可编辑的，以及以何种顺序显示它们。主题样式可以公开任何属性集，只要您的schema.json使用Theme Styles支持的数据类型声明它们。

主题样式支持以下数据类型:

• 颜色
• 字体
• 选择(下拉列表)
• 复选框
• imageDimension
• 文本

在schema.json，你可以像这里突出显示的那样在语句中声明每个对象的数据类型:

{“类型”:“颜色”,“标签”:“文本颜色”,“id”:“body-font-color”},

类型与“标题”标签

在schema.json，你也会看到“类型”:“标题”陈述如下面的陈述。

{“名称”:“颜色”,“设置”:({“类型”:“标题”,“内容”:“一般”},{“类型”:“颜色”,“标签”:“文本颜色”,“id”:“body-font-color”},{…}]}

这些“类型”:“标题”语句不引用数据类型。相反，它们声明了Page Builder UI的子类别的显示标题——中间层嵌套在节标题中，但是在商家可以选择的单个选项之外。内部选项由“标签”:<标签文本>语句。

主题样式数据结构schema.json

的schema.json嵌套结构直接映射到显示给商家的Page Builder UI。以下变化中导入的数据json， Page Builder的UI选项的顺序和嵌套直接匹配您的顺序和嵌套schema.json条目。

最佳实践

为了防止主题上传时出现错误，并避免在运行时通过Page Builder UI进行的定制可能丢失，请遵循以下准则:

• 每个店面的单实例限制。我们强烈建议对每个店面每次只打开一个主题样式的实例。我们建议这样做，因为目前没有同步机制来协调多个Theme Styles实例所做的配置更改。的schema.json文件将记录任何实例所做的最后更改，但是其他实例早先保存的更改可能会丢失。
• 每个编辑器的单一店面限制。在当前版本中，用户一次只能在主题样式中打开一个店面。要绕过施加这种限制的cookie，一个变通办法是在另一个店面上打开“隐身”/私人浏览窗口。
• 文件名、位置和结构。你的主题schema.json文件必须命名schema.json。它必须位于主题目录的根目录中，并且必须是有效的JSON。
• 文件大小。一个schema.json文件大小为64kb。超过此限制将在向BigCommerce上传主题时触发错误。除了这个大小限制，在主题中可以放置的键和值的数量没有限制schema.json。

管理版本之间的密钥

为了确保对主题的修订是向后兼容的，我们建议在您的json和schema.json以加法的方式保存文件。具体建议见下表:

行动	建议
添加新密钥	添加新键通常是可以接受的。然而，每一个关键schema.json必须有一个匹配的默认json。
删除一个关键	删除密钥时请谨慎操作。这样做可能会破坏新主题版本的向后兼容性。
重命名一个关键	我们不推荐重命名键。相反，我们建议在维护旧密钥的同时介绍一个新密钥，直到不再需要使用旧版本的主题。
移除一个变化	每个对象json文件变化对象定义一个主题变体。如果你改编了一个现有的主题，并有意识地想删除一个或多个变体，你可以删除相应的键。

持久设置存储

当商店管理员使用主题样式定制商店的主题时，他们会将商店的最终配置设置保存到BigCommerce的单独配置服务中。

主题升级和设置

当商家将您的主题升级到新版本时，他们会将保存到BigCommerce配置服务中的所有键值对保存下来。例如，假设这个定制/升级场景:

你发布了你的Star Glow主题，1.0版。这个主题的json包含一个名为logo_size，建立一个默认值为100 x 250px。键和值的组合构成alogo_size设置。商家使用页面生成器来更改logo_size设置为175 x 275px，并将此自定义设置存储在BigCommerce配置服务中。你发布了Star Glow 1.1版。在这个主题修订中，您更改了logo_size到300 * 300px。当商家将Star Glow版本1.1应用到他们的商店，他们的定制logo_size175 x 275像素的设置仍然有效。如果商家创建了第二个商店，并将Star Glow版本1.1应用于它，该商店将没有自定义logo_size设置并默认为新主题版本的300 x 300px值。

故障排除

在设置页面构建器UI时，您可能会遇到问题。我们建议您检查启动Stencil CLI的终端窗口，以了解在开发Stencil主题时遇到的任何意外行为。在某些情况下，终端将提供一个冗长的错误消息，指定在何处查找问题。有关不那么详细的错误消息，请参阅下面的潜在问题列表和诊断建议。

主题样式面板中的空下拉列表

• 症状:下拉列表的大纲显示在其配置的标签下面。然而，列表似乎是空的。
• 可能的原因:的schema.json文件不列出主题中指定的默认值json文件。
• 解决方法:更新schema.json包括json价值。

主题样式面板中缺少配置控件

• 症状:已在其中配置的控件schema.json在Page Builder UI中完全没有。
• 可能的原因:指定的数据类型是以下之一：文本，文本区域，无线电[按钮]或图像。主题样式目前不支持这些数据类型。
• 解决方法:使用支持的数据类型之一显示用户选项:颜色、字体、选择(下拉列表)或复选框。

主题更改没有从页面构建器UI保存

• 症状:店面不会反映浏览器主题样式面板中保存的更改。
• 可能的原因:检查主题样式是否可以自定义相同的店面。
• 解决方法:我们强烈建议每个店面每次只打开一个主题样式的实例。BigCommerce目前没有为来自多个Theme Styles实例的配置更改提供同步机制。所以店面的schema.json将记录任何实例所做的最后更改，但是其他实例早先保存的更改可能会丢失。