README

这是一个为爱荷华州立大学网络项目设计和构建的前端库。

预览站点：staging2.idfive.com，目前显示主分支。用户名/密码使用 guest/guest。
仓库：Bitbucket私有。
构建管道：Buddy，仅限idfive访问。

将此库安装到您的项目中

通过composer安装

在可能的情况下，我们建议使用composer安装此库，以确保所有未来的更新都可以拉入您的项目。

composer require iastate/frontend-component-library

使用库

通常，要在您的项目中使用此库，您需要链接构建文件夹中的CSS/JS文件

链接到 /build/css/index.css
链接到 /build/css/print.css（仅限打印样式）
链接到 /build/js/index.js

然后您可以在自己的项目中拉取并使用提供的标记示例。

开发

此库设计为大多数开发者可以直接使用。如果您想修改此库，您需要创建自己的分支。本节仅提供信息给在此项目上工作并提交的人。

组件库包括Fractal，用于基于组件的开发。您可以将自己的组件添加到src/components文件夹中。静态资产（如JavaScript、CSS和图片）将从build文件夹中提供，但也可以通过编辑fractal.js文件进行配置以符合您的特定需求。更多信息，请阅读fractal指南。

一般备注

已安装Bootstrap 5.1，网站使用默认断点
使用爱荷华州立大学颜色变量
使用爱荷华州立大学Font Awesome用于社交媒体图标和各种元素
所有CSS/JS都被封装，不会干扰Bootstrap，相关类使用前缀“iastate22-”
所有组件都位于src/components目录中
页面结构可在src/components/_page-preview.twig中找到。对于单个组件，结构位于src/components/_preview.twig

依赖项

依赖项需要通过node/npm安装，并通过nvm锁定到稳定版本。更多关于在idfive上使用node的信息，请参阅node使用。

cd idfive-component-library
nvm use
npm install

开发构建

要启动Fractal开发服务器

cd idfive-component-library
nvm use
npm run fractal

生产构建

在发布之前，要为生产构建您的代码，请运行以下命令

npm run build
npm run fractal:build

此操作将在您项目的根目录下生成build和fractal文件夹。其中，build文件夹包含您所有编译的资源（CSS、JavaScript等），而fractal文件夹包含您的Fractal组件库的静态生成版本，可用于预览和在线参考您的组件库。为了保证项目可以直接使用，build文件夹已被提交。

版本控制

本项目的版本发布应遵循语义化版本控制。

发布步骤

提交（或合并）并推送master到origin。
标记1.0.1（新版本号），并推送至origin。标记是composer用来定义新版本的方式。

标记

使用Twig模板编写
使用适当的ARIA功能以满足WCAG无障碍性指南

页面包装器和整体结构

下面的结构展示了正确显示布局所需的总体包装器和排序

<body>
  <a class="skip-link" href="#main-content">Skip To Main Content</a>
  <div class="off-canvas">
    <div class="max-bound">
      {% include "@site-header" with header %}
      <main id="main-content">
        {{ yield }}
      </main>
      {% include "@site-footer" with footer %}
    </div>
  </div>
  <!-- Scripts Here -->
</body>

提供了.skip-link链接以实现无障碍性
使用.off-canvasdiv来设置整个页面的overflow-x: hidden;，以防止出现不希望的横向滚动
接下来是.max-bounddiv，它提供最大宽度（和100%宽度），居中内容，并为整个文档提供背景色
接下来添加了主网站头部{% include "@site-header" with header %}
然后添加了<main id="main-content">，其中包含页面内容{{ yield }}
在<main>标签关闭后，添加了页脚{% include "@site-footer" with footer %}
厨房水槽页面在<main>之后直接添加了额外的标签<div class="outer-pad">，为页面提供左右填充

图像

所有图像应添加到src/images，它编译为build/images/*。

CSS/JS

所有CSS/JS/图像都将从src/*编译。
所有CSS应以SCSS编写，并通过Webpack编译。
所有CSS均从src/scss/index.scss编译。
所有主题JS以TypeScript编写，并通过Webpack编译为稳定、浏览器兼容的JS。
所有JS将从src/js/index.ts中的TypeScript编译。

实用类

在_base.scss中，.align-left、.align-right和.align-center用于处理WYSIWYG部分中的图像
在_base.scss中，.skip-link类用于“跳转到主要内容”按钮的无障碍性
在_placeholder-selectors.scss中，.visible-for-screen-readers用于隐藏内容，但允许其可访问性阅读/朗读
在_placeholder-selectors.scss中，.outer-pad-x处理网站各个部分中的水平填充
在_placeholder-selectors.scss中，%responsive-img是一个占位符选择器，用于设置图像的对象拟合和关联伪元素的padding-top百分比，以设置图像的高度
在_placeholder-selectors.scss中，.caption是用于图像和视频标题的重用样式类型
在_placeholder-selectors.scss中，.arrow是用于各种按钮和导航样式的箭头形状
在_base.scss中，有两个辅助类用于移除段落小部件的上下空间。 .paragraph-widget-no-margin-bottom将小部件的margin-bottom减少到零，而.paragraph-widget-no-margin-top将margin-top减少到零。这两个类都有!important标签，以确保没有冲突。

验收标准

W3C验证
使用WAVE和Google Lighthouse通过无障碍性检查
为非JS用户提供完整内容回退。

iastate / frontend-component-library

维护者

详细信息