企业官网建设流程全解析

• UI组件
• 前端

导读

本文以 Hover.css 仓库的 CONTRIBUTING.md 贡献指南为核心，系统讲解如何为这一 CSS3 悬停效果库设计、编写并提交新效果。你将掌握效果设计的五项硬性准则、跨浏览器测试要求，以及效果必须同时落地的 CSS / Sass / LESS 三种源码形态与对应的底层 mixin 结构，最终能够产出一份符合项目规范、可直接被合并的高质量 pull request。

一、效果设计的第一原则：单个 HTML 元素即可生效

贡献指南第一条准则明确了效果的使用边界：

Effects should work with only one HTML element.

这意味着开发者只需要为目标元素添加一个类名（如hvr-grow），效果即可生效，无需修改现有 HTML 结构。CSS 伪元素（::before、::after）是完全可接受的，因为它们不要求额外的 HTML 改动。仓库中大量效果正是依托伪元素实现的，例如 border-transitions 目录下的_underline-from-center.scss、speech-bubbles 目录下的_bubble-top.scss均通过伪元素绘制装饰层。

对应到 README 的使用方式，这一点与“复制粘贴单个效果”与“整表引用 hover.css”两条路径完全吻合：无论哪种方式，应用效果都只是给元素追加一个类名：

<!-- 应用效果前 --> <a href="#">Add to Basket</a> <!-- 应用效果后：仅追加 hvr-grow 类名 --> <a href="#" class="hvr-grow">Add to Basket</a>

类名的hvr-前缀自 v2.0.0 起固定，用于避免与其他库/样式表的类名冲突；若使用 Sass/LESS 版本，可通过 scss/_options.scss 中的$nameSpace变量或 less/_options.less 中的@nameSpace变量一键更换。

二、效果风格与成对提交策略

指南的后两条准则关乎效果的艺术性与生态完整性：

1. 克制与增强体验：效果应“subtle”，以增强用户体验而非炫技为目标。从源码看，多数效果的位移或缩放幅度都很克制，例如_grow.scss仅scale(1.1)，_float.scss仅translateY(-8px)，_sink.scss仅translateY(8px)。
2. 成对提交：鼓励提交与既有效果互为“镜像”的效果，例如Bounce In/Bounce Out、Float/Sink、Icon Back/Icon Forward。仓库目录结构印证了这一生态：2d-transitions中_float.scss与_sink.scss并列，icons中_icon-back.scss与_icon-forward.scss并列，这种成对设计让用户在不同交互语境下拥有对称的视觉反馈。

三、三格式同步提交：CSS、Sass 与 LESS

Hover.css 的核心工程特色是同一效果维护CSS、Sass、LESS三份源码。指南要求贡献者尽量以多种格式提交，即使不熟悉某种格式也没关系——维护者会代为转换。

三种格式的分工如下：

以Grow效果为例，三种格式的对应实现：

CSS（摘自 css/hover.css 的效果注释块）：

/* Grow */ .hvr-grow { display: inline-block; vertical-align: middle; transform: translateZ(0); box-shadow: 0 0 1px rgba(0, 0, 0, 0); backface-visibility: hidden; -moz-osx-font-smoothing: grayscale; transition-duration: 0.3s; transition-property: transform; } .hvr-grow:hover, .hvr-grow:focus, .hvr-grow:active { transform: scale(1.1); }

Sass（scss/effects/2d-transitions/_grow.scss）：

/* Grow */ @mixin grow { @include hacks(); @include prefixed(transition-duration, $mediumDuration); @include prefixed(transition-property, transform); &:hover, &:focus, &:active { @include prefixed(transform, scale(1.1)); } }

LESS（less/effects/2d-transitions/_grow.less）：结构相同，仅 mixin 调用语法不同，如.hacks();、.prefixed(transition-duration, .3s);。

对比可发现：CSS 版本是所有效果的“最终事实”，而 Sass/LESS 版本通过 mixin 抽象了重复代码。贡献新效果时，最好的起点是直接参照同目录下已有效果的源码结构。

四、禁止在同一效果中混用 transitions 与 animations

指南明确指出，不要在同一效果上同时使用 transitions 和 animations——项目作者已在 Webkit/Blink 浏览器中发现此做法存在 bug。

从仓库源码可以清楚看到这一约定的执行方式：每个效果要么走transition-*体系（如_grow.scss、_float.scss的transition-duration+transition-property），要么走animation-*体系（如_buzz.scss在 hover 时声明animation-name、animation-duration、animation-timing-function、animation-iteration-count）。两类属性从未在同一 mixin 中并存。

/* Buzz：仅使用 animation 体系（摘自 _buzz.scss） */ &:hover, &:focus, &:active { @include prefixed(animation-name, #{$nameSpace}-buzz); @include prefixed(animation-duration, .15s); @include prefixed(animation-timing-function, linear); @include prefixed(animation-iteration-count, infinite); }

五、跨浏览器测试要求与降级策略

指南要求：所有提交的效果至少要在最新版现代浏览器（Firefox、Chrome、Safari、Opera、Internet Explorer 10+）中正常工作，若不满足必须如实告知维护者。

其技术背景在 README 的 Browser Support 一节有详细说明——Hover.css 效果依赖大量 CSS3 特性，各特性的浏览器下限不同：

旧浏览器降级方案由使用者负责，而非贡献者。README 建议在集成时使用旧浏览器可理解的 CSS 兜底样式，或借助 Modernizr 等特性检测库。常见的降级示例是：当rgba()不被支持时，先声明一个纯色background作为兜底，再声明rgba()背景。贡献者应确保自己提交的效果在目标现代浏览器上无异常，并在提交说明中注明测试范围。

六、从源码看新效果的“标准骨架”

贡献新效果时，理解三个 Sass/LESS 工具文件能显著提高合并概率：

1._hacks.scss：通用 Hack 层

scss/_hacks.scss 封装了三个几乎所有效果都会调用的 mixin，并由hacks()组合调用：

• forceBlockLevel()：输出display: inline-block; vertical-align: middle;，因为 CSS Transforms 只对可变换元素生效（README 中专门有 “A Note on thedisplayProperty” 一节说明这一行为及其覆盖方法）；
• hardwareAccel()：输出transform: perspective(1px) translateZ(0)，提升移动端/平板性能并缓解 Chrome 下文字模糊；
• improveAntiAlias()：输出box-shadow: 0 0 1px rgba(0, 0, 0, 0)，改善移动端抗锯齿。

如果你的效果不需要inline-block（例如应用在块级元素上），可按 README 建议移除/注释掉forceBlockLevel()调用，或在使用方 CSS 中以“后声明”方式覆盖。

2._mixins.scss：前缀与关键帧

scss/_mixins.scss 提供两个核心 mixin：

• prefixed($property, $value)：根据_options.scss中开启的前缀开关（默认仅-webkit-为true，因为现代浏览器大多已无需前缀），为属性输出带前缀版本并追加无前缀标准版本。使用方式：

// Sass @include prefixed(transition-duration, .3s); // LESS .prefixed(transition-duration, .3s);

• keyframes($name)：按相同开关生成@-webkit-keyframes、@-moz-keyframes等前缀关键帧及无前缀标准关键帧。Sass 版通过@content接收关键帧内容：

// Sass @include keyframes(my-animation) { to { color: red; } } // LESS .keyframes(my-animation, { to { color: red; } });

3._options.scss：可配置的默认值

scss/_options.scss 集中定义了全部可调参数，新效果应尽量复用这些变量而非硬编码数值：

• 命名空间：$nameSpace: 'hvr'；
• 时长档位：$fastDuration: .1s、$mediumDuration: .3s、$slowDuration: .5s；
• 颜色：$primaryColor、$activeColor: #2098D1等；
• 气泡、箭头、卷角效果的尺寸与颜色变量（如$tipWidth、$curlWidth）；
• $includeClasses: true：默认生成全部效果的具名类（如.hvr-grow）；若你希望把效果属性应用到自己的类名上，可设为false。

对照_grow.scss可见其使用$mediumDuration作为过渡时长，而_bounce-in.scss使用$slowDuration，_icon-back.scss则使用$fastDuration——新效果按视觉节奏选择合适档位，是符合项目习惯的做法。

4. 图标类效果的约定

若提交图标类效果（icons目录），需遵循 README 的图标约定：图标元素必须带hvr-icon类，父元素带效果类名。如 scss/effects/icons/_icon-back.scss 所示，mixin 内通过.hvr-icon { … }嵌套选择器对图标施加过渡与位移：

<a href="#" class="hvr-icon-back"> Icon Back <i class="fa fa-chevron-circle-left hvr-icon"></i> </a>

自 v2.3.0 起图标不再局限于 FontAwesome，任何图标库或图片（<img class="hvr-icon" src="myicon.svg">）均可。

七、本地开发与验证工作流

贡献效果后，可借助项目自带的 Gruntfile.js 快速验证与构建：

• 运行grunt启动开发服务器（http://127.0.0.1:8000/），并开启 live-reload 监听；
• watch任务会监听 scss/ 与 less/ 目录，改动后自动执行sass/less任务将源码编译为 css/hover.css，再由cssmin任务压缩生成 css/hover-min.css；
• version任务会在package.json版本变更时同步更新 CSS/SCSS/LESS 文件头部的版本号注释。

因此，贡献者只需维护scss/与less/下的源码，构建产物（css/）由 Grunt 自动生成；而 CSS 格式的提交内容，本质上就是编译产物中对应注释块（如/* Grow */）下的规则。

结语：一份合格贡献的检查清单

综合 CONTRIBUTING.md 全文与仓库源码结构，一个高质量的效果 PR 应当满足：

1. 仅凭一个类名即可生效，必要时使用伪元素，不要求改动 HTML；
2. 效果克制、服务于用户体验，并与既有效果保持风格一致；
3. 尽可能同时提供 CSS、Sass、LESS 三种格式，Sass/LESS 源码放置于 scss/effects/ 与 less/effects/ 对应分类目录；
4. 不混用 transitions 与 animations，避免 Webkit/Blink 的已知 bug；
5. 复用_hacks.scss、_mixins.scss、_options.scss提供的 mixin 与变量，不硬编码前缀和魔法数值；
6. 在最新版 Firefox、Chrome、Safari、Opera、IE10+ 中实测通过，并在提交说明中如实汇报测试情况。

遵循以上要点，你的效果将有更高概率被合并进这个同时维护 CSS、Sass、LESS 三套产物的悬停效果库。

• UI组件
• 前端