README

真实规范（GNorm）是真实UI项目的全面起点，提供架构方向、快速搭建、代码熟悉度，并促进开发者可扩展性。

依赖关系

• Docksal

或

• Node JS
• Gulp

如果你使用的是Mac或Linux环境，该项目已配置为使用Docksal进行本地开发。如果你使用的是Windows机器，或者使用新M1处理器的Mac，或者不希望使用基于Docker的容器化环境，你需要本地安装Node.JS。

安装

Docksal

• 在主题根目录下，从命令行运行 fin init。这将安装所需的依赖项，并运行资产文件的初始构建。

本地

1. 在主题根目录（此文件所在的目录），运行 npm ci 以安装所需的Node依赖项。
2. 然后，运行 npm run build 以进行资产文件的初始构建。

开发

本地

• npm run dev - 运行一个Gulp任务，以开发模式构建前端资产，并使用BrowserSync启动监视任务，并自动打开浏览器中的原型索引 https://:8080/。

Docksal

从项目根目录，可以在终端发出几个命令

• fin up - 确保必要的Docker容器正在运行。原型索引可在 http://lw.docksal/ 找到
• fin fe [command] - 是一个Docksal命令，具有多个可能的参数
  • watch - 运行与本地相同的Gulp开发任务，但不自动打开浏览器。
  • build - 运行Gulp构建任务。
• fin ps - 显示项目统计信息。如果 state 不是 Up (healthy)，则需要使用 fin up 重新启动容器

其他Gulp任务

• [fin/npx] gulp [task] - 手动运行单个Gulp任务。使用 [fin/npx] gulp --tasks 可以获取任务列表的完整列表

依赖关系

项目依赖项通过npm添加，并在 package.json 文件中列出。要安装新的依赖项，请运行 [fin] npm i -S [package name]。

项目架构

文件夹结构

• app/: 所有工作都应在 app 文件夹中完成。这是网站源代码所在的位置。
• build/: 当运行Gulp时，来自 app 的文件会被编译到 build 中。如果你在 build 文件夹中工作，你的工作将被覆盖，你会感到难过。不要在 build 文件夹中工作。
• gnorm/: 该文件夹包含项目依赖的所有Gulp任务。还有一个 config.js 文件，大多数任务都会引用它来使文件路径和首选项更易于管理。
• node_modules/: 存储项目Node依赖项的文件夹。
• .eslintrc.js: 指定JavaScript代码检查语法的配置文件。编辑器扩展程序会提醒你潜在的错误或样式警告。
• gulpfile.babel.js: 该文件引用 gulp/tasks/ 中的所有任务。任务被拆分以进行组织，并在运行 gulp 时从根文件引用。
• package.json: 定义项目的依赖项、首选项和脚本。
• package-lock.json: 当任何npm依赖项更改时，此文件会自动生成和修改。你不应该手动编辑此文件。
• README.md: 你正在阅读它。

用法

原子组织

为了提高组织性、可扩展性和代码重用，我们在构建HTML和Sass时通常采用原子设计方法。我们的Sass部分和HTML包含被拆分到用原子式构建模块命名的文件夹中（原子/部件、分子/组件、有机体/区域等）。

HTML / Twig

GNorm使用Twig模板引擎来创建HTML模板，使用可重用组件。Twig提供了以下功能：

• 一次编写代码，在多个地方重用。
• 使用条件代码以允许模板或组件的变异。
• 使用json数据填充每个模板的内容，允许在单个或多个模板中使用相同的组件部分，每个实例具有不同的内容。

您的标记位于app文件夹中，可以包含对可重用包含（位于app/includes/）的引用。例如

{% include '@includes/2_pieces/icon.twig' %}

根目录下app文件夹中的每个twig模板都需要一个包含模板中使用的任何数据的json文件。这些数据文件位于app/json文件夹中，必须使用与模板文件相同的名称。这些数据旨在模拟可能来自CMS的数据。

当Gulp运行时，它会获取包含数据和数据，并将完整的HTML编译到build文件夹中。

更多文档可以在这里找到。

SCSS

样式使用SCSS编写。使用原子设计原则组织部分，使用BEM方法编写类名。

结构

您的样式位于app/styles/文件夹中。该文件夹按原子方式组织

• screen.scss：这包含全局模式，包含以下文件夹中包含的工具和部分@include
• 0_utility/：这包含字体、辅助工具、混合和变量声明。
• 1_core/：裸（无类的）HTML
• 2_pieces/：这是您的“原子”所在之处。
• 3_components/：这是您的“分子”所在之处。
• 4_regions/：这是您的“有机体”所在之处。
• 5_pages/：这是您的“布局”所在之处。

JS

结构

GNorm使用Webpack以及一个JS模块加载系统。JavaScript源文件位于app/scripts/中，组织如下

• app.js：这是您的应用程序引导。所有JS从这里开始。
• libs/：这是供应商库和插件所在之处。大多数第三方代码将通过npm安装，但在此目录中使用不通过包管理器可用的东西。
• modules/：这是您的自定义JS模块所在之处。
  • modules/index.js：这是“模块注册”。它列出了项目中的每个模块。

创建新模块

您可以从命令行快速生成新模块。运行[fin\npx] gulp create-module。您将被提示输入新模块的名称。名称应为PascalCase，不含空格或数字。

在app/scripts/modules/中生成新文件夹，并添加对模块注册表的引用。

新模块文件夹包含一个与同名的*.main.js文件。它导出一个ES6类

class SampleModule {
  constructor(el) {
    this.$el = el
    this.method(this.$el)
  }

  method($element) {
    console.log($element)
  }
}
export default SampleModule

（如果您不熟悉ES6类语法，可以在这里了解更多信息这里。）

要使用此新模块，请在HTML中使用data-module属性调用它

<div data-module="SampleModule">
  <p>My Module</p>
</div>

当页面加载主assets/scripts/app.built.js文件时，它会初始化模块注册表。这将搜索DOM中带有data-module属性的任何节点，并通过模块注册表中的引用实例化该模块的新版本。

注意：模块加载器传递包含data-module的元素。这允许在页面上加载该模块的多个实例时轻松地进行范围控制。

故障排除

请确保您时不时地运行[fin] npm ci命令，尤其是在从可能包含对package.json中找到的Node依赖项的添加或更新的提交中导入任何提交之后。