自定义主题的设置面板

What's my plan?

Suite

Growth, Professional, Enterprise, or Enterprise Plus

Support with

Guide all plans

下载主题时，导出的文件将包含一个名为 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 中的设置用作变量

设置也称为变量，因为其标识符可用作主题文件中的变量。更改设置面板中的值会更新使用该变量的所有文件中的值。

注意：如果您在导入 Guide 主题时遇到变量错误，可能是格式有问题。有关更多信息，请参阅文章：错误：对象类型的属性“#/settings/X/variables/X”与所有必要架构都不匹配。

您可以使用 $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": [{...}, ...]
  }
]

注意："label" 属性的值是翻译属性名称。请参阅翻译。

该示例在设置面板中创建了以下类别：

变量对象

每个设置对象都有一个列出实际设置的 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",
  ...
}

翻译用于指定设置面板中的标签和描述。

为标签和描述指定字符串

1. 在翻译文件夹中，找到帮助中心默认语言的 JSON 文件。例如：en-us.json。

2. 更新现有属性的值或添加新属性。例如：

   {
     "text_color_label": "Text color",
     "text_color_description": "Text color for body and heading elements",
     ...
   }
   

3. 在变量中，使用翻译属性名称作为 "label" 或 "description" 属性的值。

   "variables": [
     {
       "identifier": "color_text",
       "type": "color",
       "label": "text_color_label",
       "description": "text_color_description",
       "value": "#0072EF"
     },
     ...
   ]
   

   请参阅变量对象。创建属性或更改属性名称时，请确保更新相应变量。

在设置面板中，可以本地化标签和描述，但需要自行提供本地化的字符串。

对标签和描述进行本地化

1. 在翻译文件夹中，找到要支持的每种额外语言的 JSON 文件。

2. 复制在默认翻译文件中定义的属性名称。例如：

   {
     "text_color_description": "",
     "text_color_label": "",
     ...
   }
   

3. 为每个属性指定一个本地化的字符串。例如：

   fr.json

   {
     "text_color_description": "Couleur du texte pour les éléments du titre et du corps",
     "text_color_label": "Couleur du texte",
     ...
   }