neat-annotations 快速上手教程:5分钟接入,一行 span 让手绘批注出现在页面上

原创2026-10-14 15:26:211,338 阅读

neat-annotations 快速上手教程:5分钟接入,一行 span 让手绘批注出现在页面上

neat-annotations 是一个纯 CSS 手绘批注库:只写一行 <span> 标记,就能给网页内容加上手写箭头和批注标签,无需 JavaScript、无需构建步骤,一个自包含的 CSS 文件搞定。本教程带你 5 分钟完成接入。

neat-annotations 手绘批注效果预览

两步接入:引入样式表 + 加一行 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>

就这两步,效果如下:

neat-annotations 基础用法:手绘箭头指向高亮文本

💡 可选美化:批注文字默认回退到手写风格字体,加载 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>

neat-annotations 八种箭头方向示意图

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)

neat-annotations 内置配色效果:五种颜色加彩虹动画

想要任意颜色? 直接用 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 把真实描述关联到目标元素上。

相关文件速查 📁

纯 CSS、零 JS、单文件——neat-annotations 就是这样:5 分钟接入,一行 <span> 让你的页面多几分手写批注的温度。

登录后查看全文
neat-annotations