neat-annotations 快速上手教程:5分钟接入,一行 span 让手绘批注出现在页面上
neat-annotations 快速上手教程:5分钟接入,一行 span 让手绘批注出现在页面上
neat-annotations 是一个纯 CSS 手绘批注库:只写一行 <span> 标记,就能给网页内容加上手写箭头和批注标签,无需 JavaScript、无需构建步骤,一个自包含的 CSS 文件搞定。本教程带你 5 分钟完成接入。
两步接入:引入样式表 + 加一行 span 🚀
第 1 步:在页面 <head> 中引入样式表(使用 CDN,或直接下载本地文件):
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/syabro/neat-annotations/neat-annotations.css">
不想走 CDN?直接把仓库里的 neat-annotations.css 放到你的静态资源目录即可,整个库就这一个文件。
第 2 步:把要批注的内容用带 ann 类的 <span> 包起来,data-note 属性就是批注文字:
仪表盘 <span class="ann ann-n ann-amber" data-note="无需刷新">实时更新</span>
就这两步,效果如下:
💡 可选美化:批注文字默认回退到手写风格字体,加载 Shantell Sans 字体效果最佳:
<link href="https://fonts.googleapis.com/css2?family=Shantell+Sans:wght@400;500;600&display=swap" rel="stylesheet">
⚠️ 排版提醒:批注绘制在目标元素外部、不占文档流空间,给批注行四周留足边距,避免箭头标签被裁剪。
8 个箭头方向:按罗盘方位命名 🧭
方向类名就是箭头的指向,好记到不用查文档:ann-n(上)、ann-s(下)、ann-e(右)、ann-w(左),以及四个斜向 ann-ne、ann-se、ann-sw、ann-nw。
例如 ann-n 表示标签放在目标下方、箭头朝北指向上方的目标:
<span class="ann ann-n" data-note="向上指">重点内容</span>
6 种内置配色 + 彩虹动画 🌈
默认是跟随明暗主题的暖灰色。加一个颜色类,箭头、批注文字、目标高亮会一起变色,并自动适配深色模式:
<span class="ann ann-n ann-red" data-note="注意!">风险提示</span>
| 类名 | 效果 |
|---|---|
ann-amber / ann-blue / ann-green |
琥珀 / 蓝 / 绿 |
ann-red / ann-purple |
红 / 紫 |
ann-rainbow |
彩虹色循环动画(尊重 prefers-reduced-motion) |
想要任意颜色? 直接用 CSS 变量 --ann-color 覆盖:
<span class="ann ann-n" data-note="自定义色" style="--ann-color: #ff1493">热粉</span>
进阶玩法:只高亮不加箭头 ✨
- 纯高亮:去掉
data-note和方向类,就是一个荧光笔式的文本标记:<span class="ann ann-amber">重点</span> - 保留目标自身底色:目标已有背景填充时,加
ann-no-mark去掉批注自带的高亮 - 嵌套批注:同一目标可以从不同方向被多条批注指向
- 长批注自动换行:宽度受
--ann-label-max-width控制(默认 150px)
细节微调:11 个 CSS 变量按需设置 🎛️
以下变量直接写在批注元素上即可,全部在 neat-annotations.css 中有默认值定义:
| 变量 | 默认值 | 作用 |
|---|---|---|
--ann-color |
暖灰(随主题) | 箭头与批注文字颜色 |
--ann-mark |
主题浅色 | 目标高亮底色 |
--ann-font |
'Shantell Sans', cursive |
批注字体 |
--ann-target-gap / --ann-label-gap |
5px / 6px |
目标与箭头、箭头与标签的间距 |
--ann-label-max-width |
150px |
批注换行宽度 |
--ann-rotate |
-4deg |
批注文字倾斜角度 |
位置微调用 --ann-arrow-x/y 与 --ann-text-x/y 控制箭头和标签的偏移。
无障碍使用建议 ♿
批注只是视觉增强,不要让它成为说明、状态或校验信息的唯一来源。重要内容请在正文中重复,或用 aria-describedby 把真实描述关联到目标元素上。
相关文件速查 📁
- 项目说明与完整 API:README.md
- 核心样式文件(整个库的唯一依赖):neat-annotations.css
- 可交互示例页面:index.html
- 预览渲染页面:render-previews.html
- 许可证(MIT):LICENSE
纯 CSS、零 JS、单文件——neat-annotations 就是这样:5 分钟接入,一行 <span> 让你的页面多几分手写批注的温度。



