企业官网建设流程全解析

• 前端
• UI组件

Balloon.css 是一个以"纯 CSS 实现 Tooltip"为核心理念的轻量级开源库，它不依赖任何 JavaScript，只要在元素上添加aria-label与data-balloon-pos属性，就能获得带箭头、带动画的悬浮提示气泡。本文将以仓库 readme.md 为主体脉络，结合 src/balloon.scss、src/_mixins.scss、src/_variables.scss 等源码与 test.html 演示页，完整讲解安装引入、八个方向定位、程序化显示、动画控制、CSS 变量定制、富文本内容，以及底层的伪元素与边框箭头实现原理，让你既能直接上手，也能深入理解其工作机制。

Balloon.css 是什么

Balloon.css 的核心卖点正如项目描述所写——"Simple tooltips made of pure CSS"（纯 CSS 制作的简单提示气泡）。它具备以下显著特点：

• 完全不需要 JavaScript：提示的显示、隐藏、定位、动画全部由 CSS 完成，只是给元素打上aria-label和data-balloon-pos两个属性；
• 体积极小：根据 readme 说明，minified 压缩后仅约1.1KB（Brotli 压缩后）；
• 直接复用无障碍属性：提示文字取自aria-label，兼顾了屏幕阅读器语义；
• MIT 协议开源，仓库根目录提供 LICENSE 文件，当前仓库对应版本为1.2.0（见 package.json）。

它的适用场景非常典型：按钮、图标、链接等元素上的简短解释说明，在悬停（hover）或聚焦（focus）时弹出，无需为这一小功能引入动辄几十 KB 的 JS 工具库。

快速安装与引入

方式一：npm 安装

npm install balloon-css

安装后有两种引入方式。第一种是直接在 JS 入口中引入打包好的 CSS（适用于 Webpack 等打包器）：

// Your index.js file, etc. import 'balloon-css';

第二种是在使用 SASS/SCSS 的项目中引入源码（注意这里的src/balloon指向的是 src/balloon.scss）：

/* Your main.scss file, etc. */ @import "~balloon-css/src/balloon"

方式二：CDN 引入

如果不使用 npm，可以直接用 unpkg 的 CDN 版本，该地址始终指向最新版本：

<!-- This link will always fetch the latest version of Balloon.css --> <link rel="stylesheet" href="https://unpkg.com/balloon-css/balloon.min.css">

方式三：手动下载

从本仓库下载构建产物 balloon.min.css（或未压缩的 balloon.css），放到项目目录后引入：

<link rel="stylesheet" href="path/to/balloon.min.css">

提示：balloon.css与balloon.min.css都是通过node-sass从 SASS 源码构建出来的生成文件（参见 package.json 中的build脚本），两者内容一致，仅压缩程度不同，日常使用引入任一个即可。

基础用法：用><button aria-label="Whats up!">&[data-balloon-pos^="up"] { &:before, &:after { bottom: 100%; transform-origin: top; transform: translate(0, var(--balloon-move)); } &:after { margin-bottom: $balloon-arrow-size + 5px; } }

程序化显示：data-balloon-visible

默认情况下提示只在:hover或:focus时出现，但如果你希望在没有用户交互时也显示提示（例如引导新手、默认展示某项说明），可以给元素添加data-balloon-visible属性：

<button aria-label="Whats up!">&:hover, &[data-balloon-visible], &:not([data-balloon-nofocus]):focus { &:before, &:after { opacity: 1; pointer-events: none; } }

注意这里还隐藏了一个配套特性：如果只想让提示在 hover 时显示、不希望聚焦（focus）也触发，可以在元素上添加data-balloon-nofocus属性，它是 readme 未展开说明、但源码明确支持的细节能力。pointer-events: none保证气泡本体不会拦截鼠标事件。

禁用动画：data-balloon-blunt

如果某些场景不需要过渡动画（例如追求极简、或在特定布局下动画会引起跳动），只需添加data-balloon-blunt属性：

<button>/* Add this to your CSS */ .tooltip-red { --balloon-color: red; } .tooltip-big-text { --balloon-font-size: 20px; } .tooltip-slide { --balloon-move: 30px; }

配合 HTML：

<button aria-label="I am red!">/* All tooltips would now be square and blue */ :root { --balloon-border-radius: 0; --balloon-color: blue; }

由于 CSS 变量具备继承特性，在任意中间容器上声明同样会生效——这也意味着你可以为某个页面区块整体换肤，而无需逐元素打类名。

富文本内容：HTML 字符、Emoji 与图标字体

提示文字取自aria-label，因此理论上可以放入任意 HTML 实体字符甚至 Emoji：

<button aria-label="HTML special characters: &#9787; &#9986; &#9820;"><button class="fa" aria-label="Font Awesome: &#xf030; &#xf133; &#xf1fc; &#xf03e; &#xf1f8;">&.font-awesome:after { font-family: FontAwesome, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif; }

在 test.html 的 Glyphs and Icon Fonts 演示段中可以看到对应的完整示例。

源码级进阶：长文本、换行与更多隐藏属性

readme 主要面向基础使用，但源码中还包含一批"隐藏"能力，可以在不引入任何新依赖的情况下解决长文本场景：

data-balloon-length：控制气泡宽度

默认气泡是white-space: nowrap单行显示的，过长的文本会撑爆布局。data-balloon-length提供 5 档固定宽度（见 src/balloon.scss）：

<button>&[data-balloon-break] { &:after { white-space: pre; } &[data-balloon-length] { &:after { white-space: pre-line; word-break: break-word; } } }

无障碍与兼容性细节

源码中还包含了三个"看不见但很有用"的处理：

• 键盘可达性：[aria-label][data-balloon-pos]在获得焦点（:focus）时同样显示气泡（除非加了data-balloon-nofocus），键盘用户也能获得提示；
• IE 11 修复：button[aria-label][data-balloon-pos] { overflow: visible; }专门修复 IE 11 中按钮默认样式导致气泡被裁剪的问题（src/balloon.scss）；
• iOS Safari 修复：为带提示的元素设置cursor: pointer，规避 iOS Safari 上点击事件无法触发的问题（源码注释中给出了原由）。

工作原理：纯 CSS 的秘密

整个库的实现只依赖一个属性选择器和两个伪元素，这是它体积能做到 1.1KB 的根本原因。

1. 内容来源：attr(aria-label)。气泡正文由::after伪元素承载，其content直接取用宿主元素的aria-label（src/balloon.scss），因此 HTML 结构零冗余：

&:after { @include base-effects(); @include normalized-text(); background: var(--balloon-color); border-radius: var(--balloon-border-radius); content: attr(aria-label); padding: .5em 1em; position: absolute; white-space: nowrap; z-index: 10; }

2. 箭头：经典边框三角形。箭头由::before承载，借助arrow($direction)mixin（src/_mixins.scss）生成：把元素宽高设为 0，设置 5px 的透明边框，再单独给某一侧上色，就形成了指向任意方向的三角形。方向与"着色边"的映射关系用 Sass Map 维护：

$ARROW_DIRECTIONS: ( down: top, up: bottom, left: right, right: left, ); @mixin arrow($direction) { @if not map-has-key($ARROW_DIRECTIONS, $direction) { @error '[balloon] The $direction parameter must be one of: ...'; } width: 0; height: 0; border: $balloon-arrow-size solid transparent; border-#{map-get($ARROW_DIRECTIONS, $direction)}-color: var(--balloon-color); }

比如"上方"位置的气泡箭头，着色边是top，箭头朝上；down位置则调用arrow(up)，着色边是bottom，箭头朝下。箭头与气泡背景统一使用var(--balloon-color)，保证换色时两者始终一致。

3. 动画：透明度过过渡 + 位移。base-effects()mixin（src/_mixins.scss）为气泡和箭头统一设置初始opacity: 0、pointer-events: none，并以0.18s ease-out 0.18s过渡透明度和位移；显示时位移量由--balloon-move变量控制，不同方向用translate/calc(var(--balloon-move) * -1)处理正向与反向滑动，形成"浮现 + 滑入"的柔和动效。

4. 整体接线。宿主元素只需position: relative，气泡与箭头绝对定位在它周围，配合各方向的left/right/top/bottom与margin（箭头尺寸 + 5px 间距）完成贴合。整个逻辑串联在 src/balloon.scss 这一份文件中，结构非常清晰。

本地演示与测试

仓库根目录自带了 test.html，它引入本地balloon.min.css，并覆盖了所有核心能力的分节演示：

• Positioning：8 个方向逐一展示；
• Length：small/medium/large/xlarge/fit五档宽度对比；
• Disabling animation：data-balloon-blunt示例；
• Showing tooltips programatically：data-balloon-visible示例；
• Customizing Tooltips：.tooltip-red、.tooltip-big-text、.tooltip-slide三个定制类示例；
• Glyphs and Icon Fonts：特殊字符、Emoji 与 Font Awesome 示例。

克隆仓库后直接用浏览器打开该文件（或配合本地静态服务器访问），即可在一个页面里完整验证本文涉及的全部特性。

参与贡献与构建流程

Balloon.css 的源码以 SASS（.scss）维护，readme 给出如下开发流程：

1. 克隆仓库：git clone https://github.com/kazzkiq/balloon.css.git；
2. 安装依赖：npm install；
3. 修改 SASS 源码后执行npm run build生成生产环境 CSS；
4. 在网站（gh-pages分支）上验证生成文件无误后再提交 Pull Request。

需要特别留意的是 readme 中的两条注意点：

• 务必修改 SASS 源码（即 src/balloon.scss 及其引入的 _variables.scss、_mixins.scss），而不是直接改生成的balloon.css/balloon.min.css——因为它们在每次构建时都会被覆盖；
• 构建命令定义在 package.json 中：

"scripts": { "build": "node-sass src/balloon.scss ./balloon.css && node-sass src/balloon.scss ./balloon.min.css --output-style compressed", "prepublishOnly": "npm run build" }

即先用node-sass生成未压缩版，再用--output-style compressed生成压缩版，开发依赖为node-sass ^4.14。

小结

Balloon.css 用极小的代价（约 1.1KB minified + Brotli、零 JavaScript）解决了 Web 开发中高频的 Tooltip 需求：data-balloon-pos负责 8 向定位，data-balloon-visible支持程序化常显，data-balloon-blunt一键去动画，CSS 变量体系覆盖颜色、字号、圆角与位移的定制，data-balloon-length/data-balloon-break则补齐了长文本场景。配合 src/balloon.scss 中"::after气泡 +::before箭头 +attr(aria-label)内容"的精简实现，你可以快速把它接入现有项目，也能在需要时读懂并二次定制它。

• 前端
• UI组件