下载主题时,导出的文件将包含一个名为 manifest.json 的文件。该文件定义了 Guide 中主题的设置面板:
本指南介绍了 manifest 文件及其用途,并提供了其规范参考。例如,导出主题并在文本编辑器中打开 manifest.json 文件。
涵盖的主题:
- 了解 manifest.json 文件
- 将 manifest.json 中的设置用作变量
- 修改 manifest.json 文件
- Manifest 对象
- 设置对象
- 变量对象
- 类型属性
- 文件类型
- 列表类型
- 范围类型
- 翻译
了解 manifest.json 文件
导出主题时,导出的文件包含一个名为 manifest.json 的文件,可用来在 Guide 中定义主题的设置面板。
在该面板中,可以修改现有设置,或创建新设置。如下例所示,manifest 文件将 color_brand_text 设置的默认值设为“#30aabc”:
"settings": [
{
"label": "Colors",
"variables": [
{
"identifier": "color_brand_text",
"type": "color",
"description": "color_brand_text_description",
"label": "color_brand_text_label",
"value": "#30aabc"
},
...
]
},
...
]
将主题导入 Guide 后,color_brand_text 设置将显示在设置面板中,其标签为品牌文本颜色,由 manifest 文件中的“label”属性指定;颜色选取器的十六进制值默认为 #30aabc,由“value”属性指定:
将 manifest.json 中的设置用作变量
设置也称为变量,因为其标识符可用作主题文件中的变量。更改设置面板中的值会更新使用该变量的所有文件中的值。
您可以使用 $identifier
语法在主题的 style.css 文件中插入变量,或使用 Curlybars 中的 settings.identifier
助手在页面模板中插入变量。例如:
style.css
input:focus {
border: 1px solid $color_brand_text;
}
您还可以使用单花括号将帮助程序嵌入 CSS 表达式中(如下所示):
max-width: #{$search_width}px;
页面模板
<div style="background-color:{{settings.color_brand_text}}">
修改 manifest.json 文件
manifest.json 文件未包含在帮助中心“编辑代码”页面的文件列表中。要编辑 manifest.json 文件,您必须将主题导出到文件中,更改系统上的 manifest 文件,然后在 Guide 中导入主题。
导出主题
- 请参阅下载帮助中心主题。
导入已修改主题
- 请参阅导入帮助中心主题。
Manifest 对象
Manifest 文档根对象具有以下属性:
名称 | 类型 | 评论 |
---|---|---|
名称 | 字符串 | 主题名称 |
作者 | 字符串 | 创建主题的人员、团队或组织 |
版本 | 字符串 | 遵循 Semantic 版本控制 2.0.0 标准的主题版本 |
api_version | 字符串 | 模板化 API 版本 |
设置 | 数组 | 设置对象列表。请参阅设置对象 |
例如
{
"name": "My second theme",
"author": "Jane Doe",
"version": "1.0.1",
"api_version": 3,
"settings": [
...
]
}
设置对象
在 Guide 中,manifest 文件和设置面板中的设置都按组(例如颜色或字体)划分。每个设置组在 manifest 文件中由一个设置对象定义。每个对象都包含一个标签和一个或多个设置,例如品牌颜色和文本颜色。
您可以修改或自行创建设置对象。在 Guide 中导入主题时,对象将反映在主题的设置面板中。
每个设置对象都具有以下属性:
名称 | 类型 | 评论 |
---|---|---|
label | 字符串 | 翻译属性名称。请参阅翻译。显示一组设置的标题。 |
变量 | 数组 |
组中设置列表。也称为变量。请参阅变量对象。manifest 文件最多可有 200 个变量对象。 请参阅帮助中心的 Guide 产品限制(manifest.json 中的设置总数)。 |
例如
"settings": [
{
"label": "colors_group_label",
"variables": [{...}, ...]
},
{
"label": "fonts_group_label",
"variables": [{...}, ...]
},
{
"label": "brand_group_label",
"variables": [{...}, ...]
},
{
"label": "banners_group_label",
"variables": [{...}, ...]
}
]
该示例在设置面板中创建了以下类别:
变量对象
每个设置对象都有一个列出实际设置的 variables
数组。设置之所以称为变量,是因为其可作为变量插入帮助中心模板或 CSS。请参阅帮助中心的 Guide 产品限制(manifest.json 中的设置总数)。
您可以根据需要定义任何变量。但是,manifest 文件必须包含两个带有以下标识符的文件变量:“logo”和“favicon”。请参阅必要变量。
每个变量都具有以下属性:
名称 | 类型 | 评论 |
---|---|---|
identifier | 字符串 | 可在 CSS 或 Curlybars 表达式中使用的变量名称。必须有 30 个或更少字符,且仅包含字母数字字符和 _(下划线) |
type | 字符串 | Guide设置面板中的 UI 控件,用于从用户获取值。text 、list 、checkbox 、color 、file 或 range 。请查看类型属性
|
label | 字符串 |
显示在设置面板中 UI 控件旁边的设置名称。字符数不得超过 40。 要翻译此值,请使用翻译属性名称。请参阅翻译。翻译没有字符限制。 |
description | 字符串 |
显示在设置面板中 UI 控件旁边的设置简要说明。必须为 64 个或更少的字符。 要翻译此值,请使用翻译属性名称。请参阅翻译。翻译没有字符限制。 |
value | 字符串 | 设置的默认值 |
options | 数组 | 仅用于 list 类型。列表项数组。请参阅选项对象
|
min | 整数 | 仅用于 range 类型。范围的最小值 |
max | 整数 | 仅用于 range 类型。范围的最大值 |
例如
"variables": [
{
"identifier": "color_brand",
"type": "color",
"label": "color_brand_label",
"description": "color_brand_description",
"value": "#0072EF"
},
...
]
该示例在设置面板中创建了以下标签和控件:
必要变量
您必须在 manifest 文件中指定以下两个变量,否则文件将在导入时被拒绝:
- logo -
identifier
必须是“logo”,且type
必须是“file” - favicon -
identifier
必须是“favicon”,且type
必须是“file”
例如
"variables": [
{
"identifier": "logo",
"type": "file",
"description": "logo_description",
"label": "logo_label"
},
{
"identifier": "favicon",
"type": "file",
"description": "favicon_description",
"label": "favicon_label"
}
]
类型属性
每个变量对象都有一个 type
属性,该属性指定了一个 UI 控件,用于在 Guide 的设置面板中设置值。属性可有以下任一值:
-
text
- 文本输入字段。每个文本字段的长度限制为 1000 个字符。 -
list
- 下拉列表。包括列表项目的选项对象列表。请查看列表类型 -
checkbox
- 复选框。请查看复选框类型 -
color
- 颜色选取器 -
file
- 文件上载程序。请查看文件类型 -
range
- 范围输入字段。请查看范围类型
例如
{
"identifier": "color_headings",
"type": "color",
...
}
列表类型
如果变量对象的类型是“list”,则该对象将包含一个 options
数组,用于填充下拉列表。列表中每个选项都具有以下属性:
名称 | 类型 | 评论 |
---|---|---|
label | 字符串 |
为列表项目显示的适当文本。 字符数不得超过 40。 要翻译此值,请使用翻译属性名称。请参阅翻译。翻译没有字符限制。 |
value | 字符串 | 列表项目的基础值 |
您必须在数组中指定多个选项,否则导入主题将失败。选项数量不得超过 20 个。请参阅帮助中心的 Guide 产品限制(列表类型设置中的选项总数)。
例如
{
"identifier": "font_headings",
"type": "list",
"label": "Heading",
"description": "Font for headings",
"value": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
"options": [
{
"label": "Arial",
"value": "Arial, 'Helvetica Neue', Helvetica, sans-serif"
},
{
"label": "Copperplate Light",
"value": "'Copperplate Light', 'Copperplate Gothic Light', serif"
},
{
"label": "Baskerville",
"value": "Baskerville, 'Times New Roman', Times, serif"
}
]
}
复选框类型
如果变量对象的类型是“checkbox”,则使用对象的 value 属性指定用户选中复选框时设置的值。该值必须为布尔值。
名称 | 类型 | 评论 |
---|---|---|
value | 布尔值 |
true 或 false
|
例如
{
"identifier": "scoped_hc_search",
"type": "checkbox",
"description": "scoped_help_center_search_description",
"label": "scoped_help_center_search_label",
"value": true
}
文件类型
类型为“file”的变量对象可在设置面板中添加一个文件上载程序控件。此类型的变量没有 value 属性。例如:
{
"identifier": "community_image",
"type": "file",
"description": "community_image_description",
"label": "community_image_label"
}
该值是由系统确定的文件 URL。
必须提供一个默认文件供主题使用,直到用户上传不同的文件为止。默认文件的名称必须与变量的标识符相匹配。将文件放入主题文件的设置文件夹。例如:
在主题文件中应有 URL 的地方使用文件变量。例如:
style.css
.community_banner {
background-image: url($community_image);
}
页面模板
<img src="{{settings.community_image}}">
范围类型
类型为“range”的变量对象可在设置面板中添加一个滑块控件。例如:
范围变量包括一个 min 和一个 max 属性,用于指定用户在移动滑块时可设置的值的范围。该值必须为整数。
例如
{
"identifier": "font_size",
"type": "range",
"description": "font_size_description",
"label": "font_size_label",
"min": 70,
"max": 150,
"value": 100
}
翻译
设置面板中的可见字符串都在翻译中定义。翻译由属性名称和值组成。例如:
"text_color_label": "Text color"
属性名称没有固定标准,可任意指定。
翻译存储在主题根文件夹中翻译文件夹下特定语言的 JSON 文件中:
/ translations
- en-us.json
- es.json
- fr.json
- ...
每个文件都包含一个带有翻译列表的 JSON 对象:
en-us.json
{
"brand_color_description": "Brand color for major navigational elements",
"brand_color_label": "Brand color",
...
}
翻译用于指定设置面板中的标签和描述。
为标签和描述指定字符串
-
在翻译文件夹中,找到帮助中心默认语言的 JSON 文件。例如:en-us.json。
-
更新现有属性的值或添加新属性。例如:
{ "text_color_label": "Text color", "text_color_description": "Text color for body and heading elements", ... }
-
在变量中,使用翻译属性名称作为
"label"
或"description"
属性的值。"variables": [ { "identifier": "color_text", "type": "color", "label": "text_color_label", "description": "text_color_description", "value": "#0072EF" }, ... ]
请参阅变量对象。创建属性或更改属性名称时,请确保更新相应变量。
在设置面板中,可以本地化标签和描述,但需要自行提供本地化的字符串。
对标签和描述进行本地化
-
在翻译文件夹中,找到要支持的每种额外语言的 JSON 文件。
-
复制在默认翻译文件中定义的属性名称。例如:
{ "text_color_description": "", "text_color_label": "", ... }
-
为每个属性指定一个本地化的字符串。例如:
fr.json
{ "text_color_description": "Couleur du texte pour les éléments du titre et du corps", "text_color_label": "Couleur du texte", ... }