哥本哈根主题

Zendesk 的哥本哈根主题

哥本哈根主题是默认的 Zendesk Guide 主题。它被设计为响应灵敏且易于访问。在此处了解有关自定义 Zendesk Guide 的更多信息。

帮助中心的哥本哈根主题包括：

• 清单文件
• 模板集
• 样式表和 JavaScript 文件
• 资产文件夹。

如何使用

这是可用于指南的哥本哈根主题的最新版本。可以使用此存储库作为构建您自己的自定义主题的起点。您可以根据需要分叉此存储库。您可以使用您最喜欢的 IDE 来开发主题，并使用 ZCLI 在 Web 浏览器中本地预览您的更改。有关详细信息，请阅读 zcli 主题文档。

定制您的主题

一旦你创建了这个存储库，你就可以随意编辑模板、CSS、JavaScript 和管理资产。

清单文件

清单允许您为主题定义一组设置，然后可以通过主题中心中的 UI 进行更改。您可以在此处阅读有关清单文件的更多信息。

设置文件夹

如果您有file类型的变量，则需要在/settings文件夹中为该变量提供默认文件。默认情况下，该文件将在设置面板上使用，用户可以根据需要上传不同的文件。前任。如果您想为某个部分的背景图像使用一个变量，则清单文件中的变量将如下所示：

 {
  ...
  "settings" : [ {
    "label" : "Images" ,
    "variables" : [ {
      "identifier" : "background_image" ,
      "type" : "file" ,
      "description" : "Background image for X section" ,
      "label" : "Background image" ,
    } ]
  } ]
}

这将在设置文件夹中查找名为： background_image的文件

添加资产

您可以将资源添加到资源文件夹并在 CSS、JavaScript 和模板中使用它们。您可以在此处阅读有关资产的更多信息

发布您的主题

自定义主题后，您可以将存储库下载为zip文件并将其导入主题中心。

您可以按照此处的文档进行导入。

您还可以直接从 GitHub 导入 - 在此处了解更多信息。

模板

该主题包括用于具有所有可用功能的帮助中心的所有模板。主题中的模板列表：

• 文章页面
• 类别页面
• 社区帖子列表页面
• 社区帖子页面
• 社区主题列表页面
• 社区主题页面
• 贡献页面
• 文件头
• 错误页面
• 页脚
• 标头
• 主页
• 新的社区帖子页面
• 新请求页面
• 请求页面
• 搜索结果页面
• 章节页面
• 订阅页面
• 用户个人资料页面

您最多可以添加 10 个可选模板：

• 文章页面
• 类别页面
• 章节页面

您可以通过在文件夹templates/article_pages 、 templates/category_pages或templates/section_pages下创建文件来完成此操作。在这里了解更多。

样式表和 JavaScript

我们使用 Rollup 来编译主题中使用的 JS 和 CSS 文件 - style.css和script.js 。不要直接编辑它们，因为它们将在发布期间重新生成。

开始使用：

$ yarn install
$ yarn start

这将编译src和styles中的所有源代码并观察更改。它还将开始preview 。

笔记：

• 我们在编译script.js时故意不使用 babel，这样我们就可以获得干净的捆绑输出。确保仅使用广泛支持的 ecmascript 功能 (ES2015)。
• 不要直接编辑style.css 、 script.js和assets文件夹中的文件。它们在释放期间重新生成。
• 预览需要登录，因此如果您以前没有这样做过，请确保首先运行yarn zcli login -i 。

资产

哥本哈根主题附带了一些 JavaScript 资源，但您可以通过将其他资源放置在assets文件夹中来将它们添加到您的主题中。

反应组件

从版本 4.0.0 开始，哥本哈根主题使用一些 React 组件来渲染部分 UI。这些组件位于src/modules文件夹中，并使用 Zendesk Garden 组件库构建。

作为 Rollup 构建过程的一部分，这些组件作为本机 JavaScript 模块捆绑在一起，并在assets文件夹中作为 JS 文件发出。由于安装主题时资产会被重命名，因此需要使用资产助手导入模块。

为了使导入模块的过程更容易，我们添加了一个 Rollup 插件，它生成一个导入映射，将模块名称映射到资产 URL。然后在构建过程中将此导入映射注入到document_head.hbs模板中。

例如，如果您在src/modules/my-module文件夹中定义了一个名为my-module模块，则可以将其添加到rollup.config.mjs文件中，如下所示：

 export default defineConfig ( [
  // ...
  // Configuration for bundling modules in the src/modules directory
  {
    // ...
    input : {
      "my-module" : "src/modules/my-module/index.js" ,
    } ,
    // ...
  }
] ) ;

Rollup 将在assets文件夹中生成一个名为my-module-bundle.js的文件，并且此导入映射将被添加到document_head.hbs模板中：

{ "imports": { "my-module": "{{asset 'my-module-bundle.js'}}", } } ">

 < script type =" importmap " >
{
  "imports" : {
    "my-module" : "{{asset 'my-module-bundle.js'}}" ,
  }
}
 script >

然后，您可以像这样在模板中导入模块：

import { something } from "my-module"; // ... ">

 < script type = " module " >
  import { something } from " my-module " ;

  // ...
script > 

国际化

I18n 是使用 React-i18next 库在 React 组件中实现的。我们使用平面 JSON 文件，并使用.作为复数的分隔符，与默认的_不同，它是在初始化期间配置的。

我们还添加了一些工具，以便能够将该库与 Zendesk 使用的内部翻译系统集成。如果您正在构建自定义主题并且想要提供自己的翻译，您可以参考库文档来设置翻译的加载。

与 Zendesk 翻译系统集成

添加翻译字符串

翻译字符串直接在源代码中添加，通常使用useTranslation钩子，传递键和默认的英文值：

}">

 import { useTranslation } from 'react-i18next' ;

function MyComponent ( ) {
  const { t } = useTranslation ( ) ;

  return < div > { t ( "my-key" , "My default value" ) } < / div>
}

在代码中提供默认的英文值，可以在字符串尚未翻译时将其用作后备值，并将字符串从源代码提取到翻译 YAML 文件中。

复数

当使用复数时，我们需要根据翻译系统的要求为zero 、 one和other值提供默认值。这可以通过在t函数的选项中传递默认值来完成。

 t ( "my-key" , {
  "defaultValue.zero" : "{{count}} items" ,
  "defaultValue.one" : "{{count}} item" ,
  "defaultValue.other" : "{{count}} items" ,
  count : ...
} ) 

字符串提取

bin/extract-strings.mjs脚本可用于从源代码中提取翻译字符串，并将其放入由我们的内部翻译系统拾取的 YAML 文件中。脚本的用法记录在脚本本身中。

该脚本包装i18next-parser工具并将其输出转换为内部使用的 YAML 格式。可以在自定义主题中使用类似的方法，使用标准i18next-parser输出作为翻译源或实现自定义转换器。

更新翻译文件

使用bin/update-modules-translations.mjs下载所有模块的最新翻译。然后，构建过程会将所有文件捆绑在单个[MODULE]-translations-bundle.js文件中。

第一次将翻译添加到模块时，您需要将模块文件夹和翻译系统上的包名称之间的映射添加到脚本中的MODULE变量。例如，如果模块位于src/modules/my-module且包名为cph-theme-my-module ，则需要添加：

 const MODULES = {
  ... ,
  "my-module" : "cph-theme-my-module"
}

辅助功能测试

我们使用运行 lighthouse 的自定义节点脚本来进行自动可访问性测试。

运行脚本有两种方式：

• 开发模式- 它在特定帐户的本地主题预览上运行可访问性审核。它需要zcli themes:preview才能运行；
• CI 模式- 它对特定帐户的实时主题运行可访问性审核。

根据测试范围，除了上述之外，可能还需要一些手动测试。 ax DevTools、屏幕阅读器（例如 VoiceOver、对比度检查器等）等工具可以协助此类测试。

发展模式

要在更改主题时运行可访问性审核：

1. 像平常一样开始编译和预览更改：

$ yarn install
$ yarn start

2. 在根文件夹中创建.a11yrc.json文件（参见示例）；

   1. 指定帐户/子域以预览主题，确保其与活动的zcli配置文件匹配
   2. 使用管理员用户的凭据填写username和password ；
   3. 指定要测试的urls （如果留空，脚本将测试所有 url）；

3. 在单独的控制台中，在开发模式下运行可访问性审核：

 yarn test-a11y -d

然后，A11y 审核将在步骤1中开始的预览上运行。

持续集成模式

要对特定帐户的实时主题运行可访问性审核，必须：

1. 安装节点模块：

 yarn install

2. 将end_user_email 、 end_user_password 、 subdomain和urls设置为环境变量，并在 CI 模式下运行可访问性审核，即：

.zendesk.com/hc/en-us/ https://.zendesk.com/hc/en-us/requests/new https://.zendesk.com/hc/en-us/requests" yarn test-a11y">

 end_user_email= 
end_user_password= 
subdomain= 
urls="
    https://.zendesk.com/hc/en-us/
    https://.zendesk.com/hc/en-us/requests/new
    https://.zendesk.com/hc/en-us/requests" 
yarn test-a11y 

忽略列表

如果存在应忽略或无法立即修复的已知可访问性问题，则可以在脚本配置对象的忽略列表中添加一个新条目。这会将可访问性问题转变为警告而不是错误。

该条目应包括：

• 审核 ID；
• 作为 url 模式字符串的path ；
• 作为字符串的selector 。

例如：

a.skip-navigation", }, ], aria-allowed-attr: [ { path: "/hc/:locale/profiles/:id", selector: "body > div.profile-info" } ] }, },">

  custom: {
    ignore: {
      tabindex: [
        {
          path : "*" ,
          selector : "body > a.skip-navigation" ,
        } ,
      ] ,
      aria - allowed - attr : [
        {
          path : "/hc/:locale/profiles/:id" ,
          selector : "body > div.profile-info"
        }
      ]
    } ,
  } ,

在此示例中，选择器body > a.skip-navigation的审核tabindex错误将在所有页面 ( * ) 中报告为警告。对于使用选择器body > div.profile-info的审核aria-allowed-attr也会发生同样的情况，但仅适用于用户配置文件页面/hc/:locale/profiles/:id 。

请记住，只有在绝对必要时才应使用此功能。更改主题时，可访问性应该是重点和优先事项。

贡献

欢迎在 GitHub 上提出拉取请求：https://github.com/zendesk/copenhagen_theme。创建拉取请求时请提及@zendesk/vikings。

我们使用传统的提交来提高项目历史的可读性并自动化发布过程。因此，提交消息应遵循以下格式：

 [optional scope]: 

[optional body]

[optional footer(s)]

• type：描述变更的类别。请参阅支持的类型。
• 范围：（可选）描述受更改影响的内容
• 主题：更改的一个小描述
• body：（可选）有关更改的附加上下文信息
• 页脚：（可选）添加外部链接、问题引用和其他元信息

IE：

 chore: automate release
fix(styles): fix button padding
feat(script): add auto focus to fields with errors

我们在提交时使用husky和commitlint来验证消息。

一旦 PR 合并，我们就会使用 Github actions 和semantic-release来发布主题的新版本。在每次合并时， semantic-release都会分析提交消息并推断语义版本冲突。然后它创建一个 git 标签，更新清单版本并生成相应的变更日志。

提交类型

下面的列表描述了支持的提交类型及其在发布和变更日志中的效果。

类型	描述	发布	变更日志
建造	影响构建系统或外部依赖项的更改	-	-
杂务	其他不修改源代码的更改	-	-
词	CI 配置文件和脚本的更改	-	-
文档	仅文档更改	-	-
壮举	一个新功能	次要的	特征
使固定	错误修复	修补	错误修复
性能	提高性能的代码更改	修补	性能改进
重构	既不修复错误也不添加功能的代码更改	-	-
恢复	恢复之前的提交	修补	恢复
风格	不影响代码含义的更改（空格、格式、缺少分号等）	-	-
测试	添加缺失的测试或纠正现有测试	-	-

重大变化

添加重大更改的提交应在提交消息的正文或页脚中包含BREAKING CHANGE 。

IE：

 feat: update theme to use theming api v2

BREAKING CHANGE: theme is now relying on functionality that is exclusive to the theming api v2

然后，这将生成一个主要版本并在变更日志中添加BREAKING CHANGES部分。

错误报告

错误报告必须通过 Zendesk 的标准支持渠道提交：https://www.zendesk.com/contact/