zyrous/drupal-theme-base

此主题用于创建基于storybook的基础主题

维护者

详细信息

bitbucket.org/zyrous/drupal-theme

主页

源代码

安装次数: 4,454

依赖关系: 0

建议者: 0

安全: 0

类型:drupal-custom-theme

v2.0.0 2023-10-30 10:33 UTC

Requires

  • drupal/components: ^3.0@beta
  • drupal/twig_tweak: ^3.2

proprietary df969eaafbb99f605c6ea9eba6dba74d04fef45b

  • Riaz Afridi <riaz.afridi.woop@zyrous.com>

This package is auto-updated.

Last update: 2024-09-10 05:37:21 UTC

README

Zyrous基础主题包托管在[Packagist] (https://packagist.org.cn/packages/zyrous/drupal-theme-base)，Zyrous基础主题仓库托管在[Bitbucket] (https://bitbucket.org/zyrous/drupal-theme)。Zyrous Gesso是基于Sass的起始主题，输出可访问的HTML5标记。它采用移动优先的响应式方法，并利用SMACSS来组织样式。这鼓励通过创建离散的可重用UI元素来采用基于组件的主题方法。Gesso与Storybook和组件库模块高度集成，允许Drupal和Storybook共享相同的标记。

访问Gesso Storybook演示站点。

全局先决条件

为了编译和使用Gesso，以下包需要在您的系统上安装。

  • Node版本14.x.x或更高。推荐使用长期稳定版本。

  • npm版本7.x.x或更高。

创建子主题

您可以通过shell脚本来创建子主题。

  1. 导航到"themes/contrib/drupal-theme-base"文件夹，更改权限为shell
script chmod +x scripts/create_subtheme.sh

并运行

./scripts/create_subtheme.sh or bash scripts/create_subtheme.sh
  1. 脚本将询问一系列配置问题，然后创建您的子主题。
  2. 如果您还没有"themes/custom"文件夹，它将创建一个，然后将您的子主题放置在那里。

在子主题文件夹中

  1. 安装gulp
npm install --global gulp-cli

更新gulpfile.js文件的第19行，使用您的自己的域名。

browserSync.init({ proxy: "http://yourdomain.com", });

执行

只需运行

gulp

这将在子主题/css文件夹中生成一个style.css文件。

安装

  1. 按照上述步骤创建子主题。

  2. 启用Gesso Helper模块。此模块包含在主题中，但必须手动启用才能使主题正常工作。

  3. 安装组件库模块。由于许多Drupal模板在Storybook中使用Twig命名空间引用twig文件，因此需要此模块才能使主题正常工作。

  4. 安装Twig Tweak模块。

  5. 可选：安装Twig Field Value模块。这不是必需的，但它可以使处理Twig模板更容易。请注意，但是，使用此模块中的|field_value Twig过滤器将破坏Drupal的快速编辑功能。

  6. 可选：安装背景图像格式化器模块及其响应式背景图像格式化器子模块。这不是必需的，但它将允许您使用上传到Drupal的图像作为背景图像，在不同的断点处使用不同的图像大小。

入门

在开发过程中，您可以将主题设置为Drupal站点的组成部分，或者仅在Storybook中工作。Zyrous Gesso包含npm任务来编译设计令牌、CSS、JS、Storybook以及SVG精灵，使用的是webpack。

要使用这些任务，首先在主题文件夹中运行以下npm命令来安装节点依赖项。

npm i

要编译主题，启动Storybook，并监视更改，请在主题目录中运行以下命令

npm run dev

打开localhost:6006以查看Storybook。如果您正在使用Docker（或某些其他容器引擎）进行本地开发，这可能是映射到自定义域名或自定义域的端口号，例如storybook.ddev.site或site.ddev.site:6006。

如果您添加了新的SCSS和/或JS文件，您需要通过取消并重新运行npm run dev来重新启动webpack。新文件将不会在webpack重启前处理。如果文件名重复，也会显示错误。

要仅启动构建任务（不监视更改），请在主题目录中运行以下命令

npm run build

生成新组件

运行npm run component以创建新组件的模板文件。这是一个推荐的方法，因为它将设置基本的Twig和Storybook文件，您可以对其进行修改。

Storybook

将故事文件命名为[component].stories.jsx。请参见menu.stories.jsx作为示例。

要使Storybook与您的网站品牌匹配，请更改.storybook/manager.js中的颜色。任何字体都可以添加到.storybook/manager-head.html中。有关主题化和示例的更多信息，请参阅Storybook文档。

Sass

Sass可以作为全局样式.css文件的一部分进行编译，或者编译为用于Drupal库的单独CSS文件。

使用@use将Sass变量、混合或/或函数导入到单独的SCSS文件中。Sass团队不鼓励使用@import，最终将逐步淘汰。这意味着大多数文件将开始于@use '00-config' as *;。这允许您使用设计令牌访问器函数而无需额外的命名空间。其他函数和混合可以类似使用。请注意，为了避免命名空间冲突，仅应使用与Gesso相关的变量、混合和函数与*一起使用。

所有编译为单独CSS文件的所有Sass文件都必须具有唯一的文件名，即使它们位于不同的目录中。

全局样式

使用_作为Sass文件的名称前缀，例如_card.scss。将其添加到适当的聚合文件中（即_components.scss）。

单独组件/库样式

不要使用_作为Sass文件名称的前缀，例如menu.scss。导入配置和全局聚合文件。在Storybook文件顶部导入您的SCSS文件。请参见dropdown-menu.stories.jsx作为示例。别忘了将其也添加到gesso.libraries.yml文件中。

Sass Linting

Stylelint和Prettier用于检查CSS和SCSS文件。警告将中断构建，因此如果您有合理理由违反Stylelint规则，您可以通过以下两种方式使其忽略代码

  1. 在触发Stylelint警告的行之前添加// stylelint-disable-next-line。

  2. 要忽略多行，在要忽略的代码之前添加// stylelint-disable，之后添加// stylelint-enable。

在上述两种情况下，请添加有关在您的用例中禁用Stylelint规则的有效原因的注释。

Stylelint 的规则可以在 .stylelintrc.yml 文件中更改。默认情况下，Gesso 遵循 sass-guideline.es 和 Prettier 的推荐指南，并做了一些额外的自定义。

Prettier 的配置可以在 .prettierrc 文件中更改。

JavaScript

JavaScript 可以编译成单独的 JS 文件以用于 JavaScript 库或包含在其他 JS 文件中。使用现代 (ES2015+) 语法编写的 JS 文件必须命名为 [name].es6.js，但这不是编译器的要求。JavaScript 文件应放在源目录下的适当文件夹中（例如，与菜单相关的 JavaScript 应放在 source/03-components/menu）。Gesso 的上一个版本中有一个单独的 JS 文件夹。

所有 JavaScript 文件都必须有一个唯一的文件名，即使它们在不同的目录中。

模块

将你的 JavaScript 文件名以 _ 开头，例如 _Menu.es6.js。将其导入到适当的 JavaScript 文件中（例如，primary-menu.es6.js）。

单独的组件/库脚本

不要在 JS 文件名前加上 _。在 Storybook 文件顶部导入你的 JS 文件。参见 dropdown-menu.stories.jsx 作为示例。别忘了将它添加到 gesso.libraries.yml 文件中。

JS 检查

ESLint 和 Prettier 用于检查 JavaScript 文件。如果你有合理的理由违反其中一条规则，可以使用 ESLint 文档中的任何选项 来忽略特定的行。

请在你的用例中添加关于禁用 ESLint 规则的合理原因的注释。

ESLint 的配置可以在 .eslintrc.js 文件中更改。Gesso 遵循 Airbnb 标准，这些标准也由 Drupal 遵循。

Prettier 的配置可以在 .prettierrc 文件中更改。

设计令牌

Gesso 使用配置文件 source/00-config/config.design-tokens.yml 来管理主题的设计令牌。npm 构建和开发任务将自动生成一个全局 Sass 映射，以便轻松将设计令牌拉入单个 SCSS 文件。

函数

以下 Sass 函数可以用来访问在 config.design-tokens.yml 中定义的令牌。

gesso-box-shadow($shadow)

从 box-shadow 令牌列表输出阴影值。

box-shadow: gesso-box-shadow(1);

gesso-breakpoint($breakpoint)

从 breakpoints 令牌列表输出尺寸值。

@include breakpoint(gesso-breakpoint(desktop)) {
  display: flex;
}

@include breakpoint-max(gesso-breakpoint(mobile), true) {
  display: none;
}

@include breakpoint-min-max(
  gesso-breakpoint(mobile),
  gesso-breakpoint(tablet),
  true
) {
  display: block;
}

gesso-brand($color, $variant)

从调色板品牌令牌列表输出颜色值。

color: gesso-brand(blue, light);

gesso-color($type, $subtype)

从颜色令牌列表输出颜色值。

color: gesso-color(text, primary);

gesso-constrain($constrain)

从 constraints 令牌列表输出尺寸值。

max-width: gesso-constrain(sm);

gesso-duration($duration)

从 transitions duration 令牌列表输出时间值。

transition-duration: gesso-duration(short);

gesso-easing($easing)

从 transitions ease 令牌列表输出缓动值。

transition-timing-function: gesso-easing(ease-in-out);

gesso-font-family($family)

从 font-family 令牌列表输出堆栈值。

font-family: gesso-font-family(primary);

gesso-font-size($size)

从 font-size 令牌列表输出尺寸值。

font-size: rem(gesso-font-size(2));

gesso-font-weight($weight)

从 font-weight 令牌列表输出权重值。

font-weight: gesso-font-weight(semibold);

gesso-grayscale($color)

从调色板灰度令牌列表输出颜色值。

color: gesso-grayscale(gray-2);

gesso-line-height($height)

从 line-height 令牌列表输出高度值。

line-height: gesso-line-height(tight);

gesso-spacing($spacing)

从 spacing 令牌列表输出尺寸值。

margin-bottom: rem(gesso-spacing(md));

gesso-z-index($index)

从 z-index 令牌列表输出索引值。

z-index: gesso-z-index(modal);

JavaScript 中的设计令牌

Gesso 配置文件中的值也导出到 JavaScript 对象中，以便在 CSS 和 JS 中使用相同的值。这些 JS 对象可以在 source/00-config/_GESSO.es6.js 中找到。每当运行 npm run dev 或 npm run build 时，此文件也将被重新构建。

例如，要在脚本中使用断点

import { BREAKPOINTS } from '../../../00-config/_GESSO.es6';

if (window.matchMedia(`min-width: ${BREAKPOINTS.desktop}`).matches) {
  // Some script that should only run on larger screens.
}

这将在您的Sass中使用与 breakpoint(gesso-breakpoint(desktop)) 相同的断点。

基于宽度的媒体查询

Gesso使用自定义混合来指定基于视口宽度的媒体查询。

  • breakpoint：最小宽度查询
  • breakpoint-max：最大宽度查询
  • breakpoint-min-max：同时包含最小和最大宽度的查询

每个混合函数接受一个或两个宽度参数，这些参数可以是直接值（例如，800px，40em）或使用gesso-breakpoint函数调用的设计令牌值（例如，gesso-breakpoint(tablet-lg)）。breakpoint-max和breakpoint-min-max混合函数也可以接受一个可选参数，用于从最大宽度值中减去1像素，这在您想要查询的值到达但不包括该值时很有用，例如在使用Gesso断点令牌值时。

@include breakpoint($width) { // 样式 }

输出一个基于最小宽度的媒体查询。

@include breakpoint(800px) {
  display: flex;
}

@include breakpoint(gesso-breakpoint(desktop)) {
  display: none;
}

@include breakpoint-max($width, $subtract_1_from_max) { // 样式 }

输出一个基于最大宽度的媒体查询。可选的$subtract_1_from_max参数如果设置为true，则将从宽度值中减去1像素（默认：false）。

@include breakpoint-max(900px) {
  display: block;
}

@include breakpoint-max(gesso-breakpoint(mobile), true) {
  display: none;
}

@include breakpoint-min-max($min-width, $max-width, $subtract_1_from_max) { // 样式 }

输出一个同时包含最小和最大宽度的媒体查询。可选的$subtract_1_from_max参数如果设置为true，则将从最大宽度值中减去1像素（默认：false）。

@include breakpoint-min-max(400px, 700px) {
  display: flex;
}

@include breakpoint-min-max(
  gesso-breakpoint(mobile),
  gesso-breakpoint(tablet),
  true
) {
  display: block;
}

构建Storybook

可以使用npm run build-storybook构建静态Storybook站点。然后您可以在YOUR_URL/themes/gesso/storybook/index.html上查看Storybook。

主题设置

可以配置Gesso的一些方面，包括“返回顶部”组件、面包屑选项和链接的按钮样式。

对于按钮，将每个按钮大小和按钮样式应添加的类放在每一行，类之间用 .分隔，类似于您向WYSIWYG编辑器添加自定义类的方式。

c-button|Primary
c-button.c-button--secondary|Secondary
c-button.c-button--tertiary|Tertiary

要使用这些类，在实体的显示设置下选择Gesso按钮作为链接字段的格式化程序。