README

本主题为 OCHA 的 Drupal 网站提供了一个起点。通过安装基础主题，您可以获得以下标准功能，这些功能必须在我们网络中的所有网站中通用

通用头部： OCHA 服务菜单，语言切换器，用户菜单，主要导航，站内搜索。
通用底部： 导航，社交媒体链接，法律信息。
通用 SVG 图标： OCHA 人道主义图标的一个子集，请参阅 OCHA Humanitarian Icons

入门

不要修改基础主题。 请按照子主题 README 中的设置指南操作。
有关 Twig 调试和本地开发，请参阅在开发期间禁用 Drupal 8+ 缓存。

Drupal 工具

normalize-css 库包含在 Drupal 核心中，我们依赖于它。
jQuery 可在 Drupal 核心中使用，但 Common Design 不依赖于它。它仅在需要时才加载。
hidden.module.css 包含在 Drupal 核心中，以提供隐藏内容的实用程序类。

其他工具

字体默认值
组件库。请参阅 Common Design 示例以获取实时示例。
- 可以作为 Drupal Libraries附加到 Twig 模板的组件。
- 通过 Components 模块进行命名空间。
- 文档可在 Libraries README 和每个 Drupal Library 中找到，其中每个基础主题都包含一些文档。
基于 https://brand.unocha.org 的 Favicon 和 OCHA 品牌资产

单目录组件

在 Drupal 10+ 中封装组件的首选方式是使用 Single Directory Components。SDC 包含组件的所有元素在一个目录中：HTML（Twig）、CSS、JS 和图片。您不需要在主题的 Libraries YML 中维护条目，也不需要手动调用 attach_library 以确保标记得到样式化。这真是太好了。

有关更多详细信息，请参阅 components 子目录。每个组件也有自己的 README。

如果您无法或不想使用 SDC，请参阅下面的 CSS 和 JS 部分，以获取有关使用 Drupal Libraries 的指导，这是在 Drupal 8/9 中管理前端资产的首选方式，并且在 Drupal 10 中仍然有效。

CSS

为了管理CSS，请使用Drupal Libraries来创建由纯CSS/JS文件组成的组件，将它们存储在libraries中的组件特定文件夹内，并将它们附加到适当的Twig模板，这样它们就只会出现在需要它们的页面上。

JS

JavaScript文件应添加到libraries中的组件特定文件夹，并在common_design.libraries.yml中定义为Drupal Library的一部分。

不是将所有JS放在一个文件中，每个组件都有自己的JS文件与之相关联。它们已被构建为可重用，允许您混合和匹配任何JS文件组合，并将每个文件作为依赖项使用，而不会修改原始文件。引用行为方法的通用模式是

// Use a method called "methodName" inside the same Behavior file
this.methodName();

// Use a method called "methodName" defined in cd-dropdown.js
Drupal.behaviors.cdDropdown.methodName();

使用this适用于大多数函数，除了那些被分配给事件监听器的函数。对于这些函数，我们将所有这些函数都以前缀handle开头。为了方便使用在Behavior中定义的其他方法，您需要手动绑定this。有关CD Dropdown中此过程的示例，请参阅CD Dropdown。

如果您没有手动绑定this，那么您必须使用完整的对象，就像您处于全局全局作用域中一样。请参阅代码

(function (Drupal) {
  'use strict';

  Drupal.behaviors.exampleBehavior = {
    attach: function (context, settings) {
      // ✅ Manually bind `this` before it gets used.
      this.handleClick = this.handleClick.bind(this);

      // Assign handleClick as an event listener. When assigning the handler
      // it is correct to prefix the method name with `this`
      document.addEventListener('click', this.handleClick);
    },

    showAlert: function (message) {
      window.alert(message);
    },

    handleClick: function (ev) {
      // ✅ after binding `this`
      //
      // Shorthand will work as long as the .bind(this) command was run inside
      // the `attach` method.
      this.showAlert(ev.target);

      // ❌ without binding `this`
      //
      // If we hadn't bound `this` inside `attach` then it would be long-winded:
      Drupal.behaviors.exampleBehavior.showAlert(ev.target);
    }
  };
})(Drupal);

遵循Drupal JS编码标准和最佳实践。

无障碍性

Drupal 9+ 核心为无障碍性提供了辅助类。使用官方drupal.org文档中的正确隐藏内容。

我们的基础主题模板已通过自动化工具和屏幕阅读UX的手动验证进行了无障碍性检查。如果您覆盖了模板，请尽量不要破坏已放入的ARIA角色和标签。

如果您创建了一个新模板，请以基础主题模板为指南。它们处理了许多机制，例如翻译后的ARIA标签、地标角色和正确隐藏的标签。如果您编写JavaScript，请以现有组件为指南，创建对用户交互的有效屏幕阅读公告。

打印

在大多数情况下，使用@media print应该足够了，除非有特定的原因需要特定的print.css样式表（例如由Snap Service使用）。有关基本规则，请参阅_print.scss。

字体

该项目定义了一些用于使用Google Fonts的字体CSS变量。实际字体必须通过单独启用它们来加载（见下文）。您可以在OCHA的视觉身份网站上阅读官方指南。

以下是与主题本身相关的技术细节

Roboto默认包含在HTML响应中。如果您在Drupal之外实施CD，应直接将以下HTML复制到全局页面模板中

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link rel="preload" href="https://fonts.googleapis.com/css?family=Roboto:ital,wght@0,300%3B0,400%3B0,500%3B0,700%3B0,900%3B1,400%3B1,700&amp;display=swap" as="style" onload="this.onload=null;this.setAttribute(`rel`, `stylesheet`);" />

用于高级排版和其他不使用拉丁字符集的语言的附加字体可用作Drupal Libraries。列表在common_design.libraries.yml中定义。出于性能原因，我们默认不包括这些字体。如果您的网站必须支持基础主题中未包含的字符集，请参阅子主题的Libraries文件common_design_subtheme.libraries.yml，以查看帮助您创建自己的Drupal Library的注释示例。

启用单个字体

字体可以通过两种方式之一启用。

首先，在 common_design_subtheme 中，将相关的基础主题库作为依赖添加到全局样式 common_design_subtheme.libraries.yml 中。

global-styling:
  css:
    theme:
      css/styles.css: {}
  dependencies:
    - common_design/fonts-advanced
    - common_design/fonts-arabic
    - common_design/fonts-chinese
    - common_design/fonts-russian

其次，您也可以在 Drupal 管理界面下子主题主题设置中启用它们，地址为 /admin/appearance/settings/common_design_subtheme。

任务管理

此项目使用 node.js 来处理一些开发任务：监控和代码检查、JavaScript 代码检查和 SVG 图标精灵生成。有关完整配置，请参阅 package.json 中的脚本。要在基础主题内部获取命令列表，请执行 npm run，这将输出所有可能的选项。

图标

可用的图标位于 img/icons 中。根据上下文，使用了两种技术：

带有 <use> 元素的 SVG 精灵
作为背景图像的 SVG

首选精灵技术。当无法使用精灵时，我们才将 SVG 作为背景图像使用。使用背景图像会阻止使用许多 SVG 特性，例如动态更改颜色。

1. SVG 精灵

带有 <use> 元素的 SVG 符号精灵。精灵作为单个内联资产在 html.html.twig 中的关闭 body 标签之前加载。可以按其 ID 引用精灵内的每个图标。例如

<svg class="cd-icon cd-icon--arrow-down" width="16" height="16" aria-hidden="true" focusable="false">
  <use xlink:href="#cd-icon--arrow-down"></use>
</svg>

每个图标应具有 cd-icon 类和一个格式为 cd-icon--SYMBOL-ID 的 BEM 选择器。现在可以编写控制尺寸、填充颜色等的 CSS。

每个图标应具有合理的宽度和高度属性值。这些控制 CSS 慢或未加载时 SVG 的显示。如果图标是装饰性的，请添加 aria-hidden="true" focusable="false" 以从无障碍性树中删除元素。

我们使用 SVG 精灵节点包。有关更多详细信息，请参阅此处。

2. SVG 背景图像

将 SVG 作为背景图像值，通常通过 CSS 的伪元素。SVG 填充颜色在 SVG 文件中以属性的形式添加。图标默认为黑色。如果需要其他颜色，最好复制文件并手动调整填充/描边以满足您的需求。将复制的文件重命名为包含颜色的文件名，例如 arrow-down--white.svg。

生成图标精灵

如节点脚本中定义的，所有新图标应放置在 img/icons 目录中。运行 npm run svg:sprite 以生成新的精灵。这将生成精灵 SVG img/icons/cd-icons-sprite.svg 并创建一个包含所有 SVG 的 HTML 页面以供参考 img/icons/sprite.symbol.html。

网站图标

提供了 OCHA 默认的网站图标。用您的标志更新它们。

http://realfavicongenerator.net/ 是生成网站图标的良好工具。

浏览器支持

基于对 OCHA 流量模式的持续监控以及公司对标准笔记本电脑的政策，我们假设正在使用现代浏览器。我们不再保证 IE11 或较老移动浏览器等浏览器的 100% 功能兼容性。

该主题使用渐进式增强构建，首先提供广泛使用的 CSS 技术，然后使用功能查询为每个访问者逐个启用更高级的功能。

我们假设存在 addEventListener 并支持 CSS Flexbox 作为我们的基线。

我们测试的浏览器

请参阅测试浏览器和草案 - 支持全球受众。

我们使用 browserstack 进行浏览器和设备测试。在开发过程中，我们可以使用本地开发环境进行持续测试，选择特定的浏览器进行手动测试，并一次性生成多个浏览器的截图。加入 OCHA Slack #developers 频道以获取访问权限。

测试

子主题中使用了 Jest 和 Puppeteer 进行端到端测试。有一个使用 backstopjs 进行视觉回归测试的仓库，以及一个 Jenkins 任务在服务器上运行 VRT。根据 JSON 配置文件，我们可以从 URL 列表（包括认证用户页面）生成截图，支持多个视口尺寸，并捕获按键、悬停和点击动作。

端到端测试

有关运行测试的信息，请参阅 common_design_subtheme README 端到端测试。

渐进式Web应用

子主题中提供了 Web Manifest 的 site.webmanifest 文件。应根据实现情况进行调整，并使用 <link> 元素在 <head> 中添加，需要额外的配置。有关实现细节，请参阅 Manifest 文档。

翻译

Common Design 提供了阿拉伯语、法语和西班牙语字符串翻译文件，例如页眉中的 OCHA 服务和页脚中的 OCHA 命令。请参阅 translations 目录中的 .po 文件和 README。

unocha / common_design

维护者

详情