# neat-annotations
为你的网站提供手绘箭头和手写标签。纯 CSS 实现，无需 JavaScript，无需构建步骤 —— 仅需一个独立文件。
[演示](https://neat-annotations.syabro.com/) · [CSS 文件](neat-annotations.css) · [GitHub](https://github.com/syabro/neat-annotations)
## 快速开始
通过 jsDelivr 添加样式表，或者下载 [`neat-annotations.css`](neat-annotations.css) 并在本地提供：
```
```
包裹你想要添加标注的元素：
```
The dashboard updates
in real time
```
Shantell Sans 是可选的。加载它可以获得与演示一致的效果；否则标签将回退到草书字体：
```
```
**布局提示：** 标注定位在其目标外部，且不会预留空间。请在被标注的行周围预留足够的边距，以便容纳箭头和标签。
## API
以 `ann` 开始，然后在需要时添加方向和颜色。标签内容来自 `data-note`。
### 方向
方向类名指示了箭头的指向位置。例如，`ann-n` 会将标签放置在目标下方，并让箭头朝北指向目标。
`ann-n` · `ann-ne` · `ann-e` · `ann-se` · `ann-s` · `ann-sw` · `ann-w` · `ann-nw`
```
target
```
### 颜色
默认颜色是暖灰色。内置的六个类会同时更改箭头、标签和目标高亮颜色：
`ann-amber` · `ann-blue` · `ann-green` · `ann-red` · `ann-purple` · `ann-rainbow`
`ann-rainbow` 会在不同色相之间产生动画过渡，并响应 `prefers-reduced-motion`。
### 自定义颜色
使用 `--ann-color` 直接设置任何 CSS 颜色：
```
hot pink
```
### 仅高亮
省略 `data-note` 和方向类，即可将标注用作没有箭头或标签的文本标记：
```
important
```
### 目标高亮
当目标本身已有填充色时，添加 `ann-no-mark`：
```
stable
```
标注可以嵌套，从而从不同方向指向同一个目标。较长的笔记会根据 `--ann-label-max-width` 进行换行。有关这两种模式的用法，请参阅[演示](https://neat-annotations.syabro.com/)。
## 微调
直接在被标注的元素上设置以下变量：
| 变量 | 默认值 | 控制内容 |
| --- | --- | --- |
| `--ann-color` | 暖灰色 | 箭头和标签颜色 |
| `--ann-mark` | 随主题变化的色调 | 目标高亮；`ann-no-mark` 可移除 |
| `--ann-font` | `'Shantell Sans', cursive` | 标签字体 |
| `--ann-target-gap` | `5px` | 目标与箭头之间的间距 |
| `--ann-label-gap` | `6px` | 箭头与标签之间的间距 |
| `--ann-lower-label-gap` | `-4px` | 对目标下方的标签进行调整 |
| `--ann-label-max-width` | `150px` | 换行前的最大标签宽度 |
| `--ann-arrow-x` / `--ann-arrow-y` | `0px` | 箭头位置 |
| `--ann-text-x` / `--ann-text-y` | `0px` / `5px` | 标签位置 |
| `--ann-rotate` | `-4deg` | 标签倾斜角度 |
## 无障碍设计
标注仅作为视觉增强效果。请勿将 `data-note` 用作说明、状态、验证或其他重要信息的唯一来源。请在可见的 HTML 中重复重要内容，或使用 `aria-describedby` 将真实的描述与目标元素关联起来。
## 许可证
[MIT](LICENSE)