@suifei/hash-avatar 0.0.0-stage → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +202 -0
- package/README.md +243 -2
- package/README.zh-CN.md +243 -0
- package/package.json +44 -4
- package/src/hash-avatar.js +679 -0
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
<img src="https://avatar.onrpc.com/v1/flynn.svg?gender=male&age=youth&race=asian&size=180" width="180" alt="flynn · male · youth · asian" title="flynn · male · youth · asian">
|
|
4
|
+
|
|
5
|
+
<sub>☝️ <code>flynn</code>,由 <code>avatar.onrpc.com/v1/flynn.svg?gender=male&age=youth&race=asian</code> 实时生成</sub>
|
|
6
|
+
|
|
7
|
+
# hash-avatar
|
|
8
|
+
|
|
9
|
+
把名称或 email 经 SHA-256 映射成确定性的 SVG 头像。<br>零依赖 · 同步执行 · 浏览器和 Node 通用 · 每个头像约 0.1ms、约 6KB
|
|
10
|
+
|
|
11
|
+
[](https://www.npmjs.com/package/@suifei/hash-avatar)
|
|
12
|
+
[](https://github.com/suifei/hash-avatar/actions/workflows/ci.yml)
|
|
13
|
+
[](package.json)
|
|
14
|
+
[](LICENSE)
|
|
15
|
+
|
|
16
|
+
<a href="https://suifei.github.io/hash-avatar/">在线演示</a> · <a href="#1-图片-url无需代码">作为图片嵌入</a> · <a href="#3-npm">npm</a> · <a href="#版本契约">版本契约</a>
|
|
17
|
+
|
|
18
|
+
[English](README.md) | 简体中文
|
|
19
|
+
|
|
20
|
+
</div>
|
|
21
|
+
|
|
22
|
+
## 同一身份,全部维度
|
|
23
|
+
|
|
24
|
+
性别、年龄、人种是**渲染参数,不参与哈希**,所以同一个人换了设置依然认得出来:外圈相同,配色相同,特征也相同。下面是 `flynn`(人种 `asian`)在 3 种性别 × 5 个年龄段下的全部 15 种组合:
|
|
25
|
+
|
|
26
|
+
<table align="center">
|
|
27
|
+
<tr><th></th><th>婴儿</th><th>少年</th><th>青年</th><th>中年</th><th>老年</th></tr>
|
|
28
|
+
<tr><th>男</th><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=male&age=baby&race=asian&size=96" width="96" alt="flynn · male · baby · asian" title="flynn · male · baby · asian"></td><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=male&age=teen&race=asian&size=96" width="96" alt="flynn · male · teen · asian" title="flynn · male · teen · asian"></td><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=male&age=youth&race=asian&size=96" width="96" alt="flynn · male · youth · asian" title="flynn · male · youth · asian"></td><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=male&age=middle&race=asian&size=96" width="96" alt="flynn · male · middle · asian" title="flynn · male · middle · asian"></td><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=male&age=old&race=asian&size=96" width="96" alt="flynn · male · old · asian" title="flynn · male · old · asian"></td></tr>
|
|
29
|
+
<tr><th>女</th><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=female&age=baby&race=asian&size=96" width="96" alt="flynn · female · baby · asian" title="flynn · female · baby · asian"></td><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=female&age=teen&race=asian&size=96" width="96" alt="flynn · female · teen · asian" title="flynn · female · teen · asian"></td><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=female&age=youth&race=asian&size=96" width="96" alt="flynn · female · youth · asian" title="flynn · female · youth · asian"></td><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=female&age=middle&race=asian&size=96" width="96" alt="flynn · female · middle · asian" title="flynn · female · middle · asian"></td><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=female&age=old&race=asian&size=96" width="96" alt="flynn · female · old · asian" title="flynn · female · old · asian"></td></tr>
|
|
30
|
+
<tr><th>中性</th><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=neutral&age=baby&race=asian&size=96" width="96" alt="flynn · neutral · baby · asian" title="flynn · neutral · baby · asian"></td><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=neutral&age=teen&race=asian&size=96" width="96" alt="flynn · neutral · teen · asian" title="flynn · neutral · teen · asian"></td><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=neutral&age=youth&race=asian&size=96" width="96" alt="flynn · neutral · youth · asian" title="flynn · neutral · youth · asian"></td><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=neutral&age=middle&race=asian&size=96" width="96" alt="flynn · neutral · middle · asian" title="flynn · neutral · middle · asian"></td><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=neutral&age=old&race=asian&size=96" width="96" alt="flynn · neutral · old · asian" title="flynn · neutral · old · asian"></td></tr>
|
|
31
|
+
</table>
|
|
32
|
+
|
|
33
|
+
再看青年男性 `flynn` 在 `race` 各个取值下的样子(`auto` 会从全部调色板中取值)。人种只影响肤色、发色、瞳色的取值范围和发型质地的权重,不改变五官几何。
|
|
34
|
+
|
|
35
|
+
<table align="center">
|
|
36
|
+
<tr><th><code>asian</code></th><th><code>white</code></th><th><code>black</code></th><th><code>brown</code></th><th><code>auto</code></th></tr>
|
|
37
|
+
<tr><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=male&age=youth&race=asian&size=96" width="96" alt="flynn · male · youth · asian" title="flynn · male · youth · asian"></td><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=male&age=youth&race=white&size=96" width="96" alt="flynn · male · youth · white" title="flynn · male · youth · white"></td><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=male&age=youth&race=black&size=96" width="96" alt="flynn · male · youth · black" title="flynn · male · youth · black"></td><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=male&age=youth&race=brown&size=96" width="96" alt="flynn · male · youth · brown" title="flynn · male · youth · brown"></td><td><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=male&age=youth&race=auto&size=96" width="96" alt="flynn · male · youth · auto" title="flynn · male · youth · auto"></td></tr>
|
|
38
|
+
</table>
|
|
39
|
+
|
|
40
|
+
## 外圈指纹
|
|
41
|
+
|
|
42
|
+
外圈逐位画出哈希的前 **128 位**,从 12 点钟方向起顺时针。输入不同,外圈就不同,碰撞概率低于 UUIDv4。小于约 96px 时刻度会糊在一起,所以小尺寸下可以用 `fp=0` 关掉外圈。
|
|
43
|
+
|
|
44
|
+
<table align="center"><tr>
|
|
45
|
+
<td align="center" valign="bottom"><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=male&age=youth&race=asian&size=192" width="192" alt="flynn" title="flynn"><br><sub>开启外圈,192px</sub></td>
|
|
46
|
+
<td align="center" valign="bottom"><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=male&age=youth&race=asian&fp=0&size=192" width="192" alt="flynn" title="flynn"><br><sub>关闭外圈(<code>fp=0</code>)</sub></td>
|
|
47
|
+
<td align="center" valign="bottom"><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=male&age=youth&race=asian&size=96" width="96" alt="flynn" title="flynn"><br><sub>96px</sub></td>
|
|
48
|
+
<td align="center" valign="bottom"><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=male&age=youth&race=asian&size=48" width="48" alt="flynn" title="flynn"><br><sub>48px</sub></td>
|
|
49
|
+
<td align="center" valign="bottom"><img src="https://avatar.onrpc.com/v1/flynn.svg?gender=male&age=youth&race=asian&fp=0&size=32" width="32" alt="flynn" title="flynn"><br><sub>32px</sub></td>
|
|
50
|
+
</tr></table>
|
|
51
|
+
|
|
52
|
+
## 画廊
|
|
53
|
+
|
|
54
|
+
48 个不同的名字,轮换覆盖所有性别、年龄和人种。每张图都只是一个指向线上服务的普通 `<img>`。
|
|
55
|
+
|
|
56
|
+
<p align="center">
|
|
57
|
+
<img src="https://avatar.onrpc.com/v1/alice.svg?gender=male&age=baby&race=asian&size=80" width="80" alt="alice · male · baby · asian" title="alice · male · baby · asian">
|
|
58
|
+
<img src="https://avatar.onrpc.com/v1/bob.svg?gender=female&age=youth&race=white&size=80" width="80" alt="bob · female · youth · white" title="bob · female · youth · white">
|
|
59
|
+
<img src="https://avatar.onrpc.com/v1/carol.svg?gender=neutral&age=old&race=black&size=80" width="80" alt="carol · neutral · old · black" title="carol · neutral · old · black">
|
|
60
|
+
<img src="https://avatar.onrpc.com/v1/dave.svg?gender=male&age=teen&race=brown&size=80" width="80" alt="dave · male · teen · brown" title="dave · male · teen · brown">
|
|
61
|
+
<img src="https://avatar.onrpc.com/v1/eve.svg?gender=female&age=old&race=auto&size=80" width="80" alt="eve · female · old · auto" title="eve · female · old · auto">
|
|
62
|
+
<img src="https://avatar.onrpc.com/v1/frank.svg?gender=neutral&age=teen&race=asian&size=80" width="80" alt="frank · neutral · teen · asian" title="frank · neutral · teen · asian">
|
|
63
|
+
<img src="https://avatar.onrpc.com/v1/grace.svg?gender=male&age=middle&race=white&size=80" width="80" alt="grace · male · middle · white" title="grace · male · middle · white">
|
|
64
|
+
<img src="https://avatar.onrpc.com/v1/heidi.svg?gender=female&age=baby&race=black&size=80" width="80" alt="heidi · female · baby · black" title="heidi · female · baby · black">
|
|
65
|
+
<img src="https://avatar.onrpc.com/v1/ivan.svg?gender=neutral&age=middle&race=auto&size=80" width="80" alt="ivan · neutral · middle · auto" title="ivan · neutral · middle · auto">
|
|
66
|
+
<img src="https://avatar.onrpc.com/v1/judy.svg?gender=male&age=baby&race=asian&size=80" width="80" alt="judy · male · baby · asian" title="judy · male · baby · asian">
|
|
67
|
+
<img src="https://avatar.onrpc.com/v1/mallory.svg?gender=female&age=youth&race=white&size=80" width="80" alt="mallory · female · youth · white" title="mallory · female · youth · white">
|
|
68
|
+
<img src="https://avatar.onrpc.com/v1/niaj.svg?gender=neutral&age=old&race=black&size=80" width="80" alt="niaj · neutral · old · black" title="niaj · neutral · old · black">
|
|
69
|
+
<img src="https://avatar.onrpc.com/v1/olivia.svg?gender=male&age=youth&race=brown&size=80" width="80" alt="olivia · male · youth · brown" title="olivia · male · youth · brown">
|
|
70
|
+
<img src="https://avatar.onrpc.com/v1/peggy.svg?gender=female&age=old&race=auto&size=80" width="80" alt="peggy · female · old · auto" title="peggy · female · old · auto">
|
|
71
|
+
<img src="https://avatar.onrpc.com/v1/rupert.svg?gender=neutral&age=teen&race=asian&size=80" width="80" alt="rupert · neutral · teen · asian" title="rupert · neutral · teen · asian">
|
|
72
|
+
<img src="https://avatar.onrpc.com/v1/sybil.svg?gender=male&age=middle&race=white&size=80" width="80" alt="sybil · male · middle · white" title="sybil · male · middle · white">
|
|
73
|
+
<img src="https://avatar.onrpc.com/v1/trent.svg?gender=female&age=teen&race=brown&size=80" width="80" alt="trent · female · teen · brown" title="trent · female · teen · brown">
|
|
74
|
+
<img src="https://avatar.onrpc.com/v1/victor.svg?gender=neutral&age=middle&race=auto&size=80" width="80" alt="victor · neutral · middle · auto" title="victor · neutral · middle · auto">
|
|
75
|
+
<img src="https://avatar.onrpc.com/v1/walter.svg?gender=male&age=baby&race=asian&size=80" width="80" alt="walter · male · baby · asian" title="walter · male · baby · asian">
|
|
76
|
+
<img src="https://avatar.onrpc.com/v1/xiao.ming.svg?gender=female&age=youth&race=white&size=80" width="80" alt="xiao.ming · female · youth · white" title="xiao.ming · female · youth · white">
|
|
77
|
+
<img src="https://avatar.onrpc.com/v1/%E6%9D%8E%E4%BC%9F.svg?gender=neutral&age=baby&race=black&size=80" width="80" alt="李伟 · neutral · baby · black" title="李伟 · neutral · baby · black">
|
|
78
|
+
<img src="https://avatar.onrpc.com/v1/%E7%8E%8B%E8%8A%B3.svg?gender=male&age=youth&race=brown&size=80" width="80" alt="王芳 · male · youth · brown" title="王芳 · male · youth · brown">
|
|
79
|
+
<img src="https://avatar.onrpc.com/v1/%E5%BC%B5%E5%81%89.svg?gender=female&age=old&race=auto&size=80" width="80" alt="張偉 · female · old · auto" title="張偉 · female · old · auto">
|
|
80
|
+
<img src="https://avatar.onrpc.com/v1/yuki.svg?gender=neutral&age=teen&race=asian&size=80" width="80" alt="yuki · neutral · teen · asian" title="yuki · neutral · teen · asian">
|
|
81
|
+
<img src="https://avatar.onrpc.com/v1/amara.svg?gender=male&age=old&race=black&size=80" width="80" alt="amara · male · old · black" title="amara · male · old · black">
|
|
82
|
+
<img src="https://avatar.onrpc.com/v1/kwame.svg?gender=female&age=teen&race=brown&size=80" width="80" alt="kwame · female · teen · brown" title="kwame · female · teen · brown">
|
|
83
|
+
<img src="https://avatar.onrpc.com/v1/priya.svg?gender=neutral&age=middle&race=auto&size=80" width="80" alt="priya · neutral · middle · auto" title="priya · neutral · middle · auto">
|
|
84
|
+
<img src="https://avatar.onrpc.com/v1/arjun.svg?gender=male&age=baby&race=asian&size=80" width="80" alt="arjun · male · baby · asian" title="arjun · male · baby · asian">
|
|
85
|
+
<img src="https://avatar.onrpc.com/v1/sofia.svg?gender=female&age=middle&race=white&size=80" width="80" alt="sofia · female · middle · white" title="sofia · female · middle · white">
|
|
86
|
+
<img src="https://avatar.onrpc.com/v1/mateo.svg?gender=neutral&age=baby&race=black&size=80" width="80" alt="mateo · neutral · baby · black" title="mateo · neutral · baby · black">
|
|
87
|
+
<img src="https://avatar.onrpc.com/v1/noah.svg?gender=male&age=youth&race=brown&size=80" width="80" alt="noah · male · youth · brown" title="noah · male · youth · brown">
|
|
88
|
+
<img src="https://avatar.onrpc.com/v1/zoe.svg?gender=female&age=old&race=auto&size=80" width="80" alt="zoe · female · old · auto" title="zoe · female · old · auto">
|
|
89
|
+
<img src="https://avatar.onrpc.com/v1/liam.svg?gender=neutral&age=youth&race=white&size=80" width="80" alt="liam · neutral · youth · white" title="liam · neutral · youth · white">
|
|
90
|
+
<img src="https://avatar.onrpc.com/v1/emma.svg?gender=male&age=old&race=black&size=80" width="80" alt="emma · male · old · black" title="emma · male · old · black">
|
|
91
|
+
<img src="https://avatar.onrpc.com/v1/chen.jie.svg?gender=female&age=teen&race=brown&size=80" width="80" alt="chen.jie · female · teen · brown" title="chen.jie · female · teen · brown">
|
|
92
|
+
<img src="https://avatar.onrpc.com/v1/lin.mei.svg?gender=neutral&age=middle&race=auto&size=80" width="80" alt="lin.mei · neutral · middle · auto" title="lin.mei · neutral · middle · auto">
|
|
93
|
+
<img src="https://avatar.onrpc.com/v1/hiro.svg?gender=male&age=teen&race=asian&size=80" width="80" alt="hiro · male · teen · asian" title="hiro · male · teen · asian">
|
|
94
|
+
<img src="https://avatar.onrpc.com/v1/sakura.svg?gender=female&age=middle&race=white&size=80" width="80" alt="sakura · female · middle · white" title="sakura · female · middle · white">
|
|
95
|
+
<img src="https://avatar.onrpc.com/v1/min-jun.svg?gender=neutral&age=baby&race=black&size=80" width="80" alt="min-jun · neutral · baby · black" title="min-jun · neutral · baby · black">
|
|
96
|
+
<img src="https://avatar.onrpc.com/v1/ji-woo.svg?gender=male&age=youth&race=brown&size=80" width="80" alt="ji-woo · male · youth · brown" title="ji-woo · male · youth · brown">
|
|
97
|
+
<img src="https://avatar.onrpc.com/v1/fatima.svg?gender=female&age=baby&race=asian&size=80" width="80" alt="fatima · female · baby · asian" title="fatima · female · baby · asian">
|
|
98
|
+
<img src="https://avatar.onrpc.com/v1/omar.svg?gender=neutral&age=youth&race=white&size=80" width="80" alt="omar · neutral · youth · white" title="omar · neutral · youth · white">
|
|
99
|
+
<img src="https://avatar.onrpc.com/v1/chidi.svg?gender=male&age=old&race=black&size=80" width="80" alt="chidi · male · old · black" title="chidi · male · old · black">
|
|
100
|
+
<img src="https://avatar.onrpc.com/v1/ngozi.svg?gender=female&age=teen&race=brown&size=80" width="80" alt="ngozi · female · teen · brown" title="ngozi · female · teen · brown">
|
|
101
|
+
<img src="https://avatar.onrpc.com/v1/lucas.svg?gender=neutral&age=old&race=auto&size=80" width="80" alt="lucas · neutral · old · auto" title="lucas · neutral · old · auto">
|
|
102
|
+
<img src="https://avatar.onrpc.com/v1/ines.svg?gender=male&age=teen&race=asian&size=80" width="80" alt="ines · male · teen · asian" title="ines · male · teen · asian">
|
|
103
|
+
<img src="https://avatar.onrpc.com/v1/olaf.svg?gender=female&age=middle&race=white&size=80" width="80" alt="olaf · female · middle · white" title="olaf · female · middle · white">
|
|
104
|
+
<img src="https://avatar.onrpc.com/v1/freya.svg?gender=neutral&age=baby&race=black&size=80" width="80" alt="freya · neutral · baby · black" title="freya · neutral · baby · black">
|
|
105
|
+
</p>
|
|
106
|
+
|
|
107
|
+
## 用法
|
|
108
|
+
|
|
109
|
+
有三种用法:
|
|
110
|
+
|
|
111
|
+
| | 适用场景 | 需要 |
|
|
112
|
+
|---|---|---|
|
|
113
|
+
| [图片 URL](#1-图片-url无需代码) | README、Markdown、任意 `<img>` | 什么都不用 |
|
|
114
|
+
| [CDN 脚本](#2-浏览器cdn) | 在网页里渲染 | 一个 `<script>` 标签 |
|
|
115
|
+
| [npm 包](#3-npm) | Node、打包工具、服务端渲染 | `npm i @suifei/hash-avatar` |
|
|
116
|
+
|
|
117
|
+
### 1. 图片 URL(无需代码)
|
|
118
|
+
|
|
119
|
+
用法和 shields.io 徽章一样,凡是能填图片 URL 的地方都能用:
|
|
120
|
+
|
|
121
|
+
```html
|
|
122
|
+
<img src="https://avatar.onrpc.com/v1/octocat.svg?gender=male&size=128" width="128" alt="octocat">
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
```markdown
|
|
126
|
+

|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
| URL | 行为 |
|
|
130
|
+
|---|---|
|
|
131
|
+
| `/v1/<name>.svg` | 锁定契约 v1,**推荐**。缓存一年 |
|
|
132
|
+
| `/<name>.svg` | 跟随最新的契约版本,缓存一天 |
|
|
133
|
+
| `/avatar.svg?name=<name>` | 查询参数形式,适合不方便放进路径的名称 |
|
|
134
|
+
|
|
135
|
+
查询参数有 `gender`、`age`、`race`、`size`(16–1024)和 `fp=0`(隐藏外圈指纹),取值与下面的[选项](#选项)相同。名称需要 URL 编码(`encodeURIComponent`),长度上限 256 个字符。
|
|
136
|
+
|
|
137
|
+
> 不要把真实 email 放进公开的图片 URL,它会出现在服务器日志和 `Referer` 头里。详见[隐私](#已知限制)。
|
|
138
|
+
|
|
139
|
+
> **域名与中国大陆访问:** 服务部署在两个域名上,输出完全相同。`avatar.onrpc.com` 是主域名,中国大陆可以直接访问。`hash-avatar.suifei.workers.dev` 是备用域名,但 `*.workers.dev` 在中国大陆不挂代理无法访问。GitHub README 用哪个域名都可以,因为 GitHub 会通过自己的 `camo` 代理加载 README 里的图片。
|
|
140
|
+
|
|
141
|
+
这个服务是一个很小的 Cloudflare Worker([`worker/index.js`](worker/index.js))。如果要自建,运行 `npx wrangler deploy`。
|
|
142
|
+
|
|
143
|
+
### 2. 浏览器(CDN)
|
|
144
|
+
|
|
145
|
+
```html
|
|
146
|
+
<script src="https://cdn.jsdelivr.net/npm/@suifei/hash-avatar@1/src/hash-avatar.js"></script>
|
|
147
|
+
<div id="me"></div>
|
|
148
|
+
<script>
|
|
149
|
+
document.getElementById('me').innerHTML =
|
|
150
|
+
HashAvatar.svg('alice@example.com', { gender: 'female', age: 'youth', size: 96 });
|
|
151
|
+
</script>
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
也可以用 unpkg:`https://unpkg.com/@suifei/hash-avatar@1/src/hash-avatar.js`。脚本会定义全局的 `window.HashAvatar`。
|
|
155
|
+
|
|
156
|
+
### 3. npm
|
|
157
|
+
|
|
158
|
+
```sh
|
|
159
|
+
npm i @suifei/hash-avatar
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
```js
|
|
163
|
+
const HashAvatar = require('@suifei/hash-avatar');
|
|
164
|
+
|
|
165
|
+
const svg = HashAvatar.svg('alice@example.com', { gender: 'female', age: 'youth', race: 'auto', size: 128 });
|
|
166
|
+
|
|
167
|
+
// 作为 data URL 使用:
|
|
168
|
+
const src = 'data:image/svg+xml;charset=utf-8,' + encodeURIComponent(svg);
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## API
|
|
172
|
+
|
|
173
|
+
### `svg(input, options?) → string`
|
|
174
|
+
|
|
175
|
+
返回完整的 SVG 文档字符串。
|
|
176
|
+
|
|
177
|
+
#### 选项
|
|
178
|
+
|
|
179
|
+
| 选项 | 取值 | 默认 |
|
|
180
|
+
|---|---|---|
|
|
181
|
+
| `gender` | `male` · `female` · `neutral` | `neutral` |
|
|
182
|
+
| `age` | `baby` · `teen` · `youth` · `middle` · `old` | `youth` |
|
|
183
|
+
| `race` | `asian` · `white` · `black` · `brown` · `auto`(不指定) | `auto` |
|
|
184
|
+
| `size` | 宽高像素(viewBox 固定为 256) | `256` |
|
|
185
|
+
| `salt` | 任意字符串,会混入哈希 | `''` |
|
|
186
|
+
| `fingerprint` | 是否绘制 128 位外圈指纹 | `true` |
|
|
187
|
+
|
|
188
|
+
传入非法值时使用默认值。
|
|
189
|
+
|
|
190
|
+
### `hash(input, salt?) → { input, bytes, hex }`
|
|
191
|
+
|
|
192
|
+
返回规范化后的输入、32 字节 SHA-256 摘要(`Uint8Array`)和它的十六进制字符串。
|
|
193
|
+
|
|
194
|
+
### `normalize(input) → string`
|
|
195
|
+
|
|
196
|
+
依次做 NFC、去掉首尾空白、把连续空白合并成一个空格。只有形如 email(`x@y`)的输入才转小写。所以 `Alice@Example.com` 和 `alice@example.com` 得到同一个头像,`Alice` 和 `alice` 则不同。
|
|
197
|
+
|
|
198
|
+
### `sha256(bytes) → Uint8Array`
|
|
199
|
+
|
|
200
|
+
内置的同步 SHA-256。
|
|
201
|
+
|
|
202
|
+
### `GENDERS`、`AGES`、`RACES`、`version`
|
|
203
|
+
|
|
204
|
+
各选项的合法取值,以及契约版本号(`'v1'`)。
|
|
205
|
+
|
|
206
|
+
## 唯一性原理
|
|
207
|
+
|
|
208
|
+
五官、发型、配饰等特征的组合是有限的,单靠它们做不到唯一。所以每个头像的外圈有 **128 个刻度**,逐位画出哈希的前 128 位:高位在前,从 12 点钟方向起顺时针,长刻度表示 1,暗点表示 0。
|
|
209
|
+
|
|
210
|
+
哈希前 128 位不同,外圈就一定不同。两个不同输入得到相同外圈,需要 SHA-256 截断到 128 位后发生碰撞,这个概率**低于 UUIDv4 的碰撞概率**(122 位随机)。
|
|
211
|
+
|
|
212
|
+
性别、年龄、人种**不参与哈希**,只是渲染参数。所以同一身份切换这些维度后,外圈和特征依然可以辨认。
|
|
213
|
+
|
|
214
|
+
## 已知限制
|
|
215
|
+
|
|
216
|
+
- **小尺寸**:头像小于约 96px 时,外圈刻度肉眼分辨不清。此时唯一性退化为概率性的,靠特征组合来区分。
|
|
217
|
+
- **隐私**:外圈相当于哈希明文。对 email 而言,别人可以读出这 128 位后做字典反查。公开展示时,应在服务端使用保密的 `salt` 渲染。公共图片服务做不到这一点,因为写在 URL 里的 salt 不是秘密,所以应该传用户名或不透明 ID,而不是 email。
|
|
218
|
+
- **人种的作用范围**:人种只影响肤色、发色、瞳色的取值范围和发型质地的权重,**不改变五官几何**。这是刻意的设计,避免画成刻板印象。
|
|
219
|
+
|
|
220
|
+
## 版本契约
|
|
221
|
+
|
|
222
|
+
头像一旦对外展示,输入到图像的映射就是公开契约。v1 契约规定:
|
|
223
|
+
|
|
224
|
+
1. 哈希输入为 `'hash-avatar/v1\0' + salt + '\0' + normalize(input)`。
|
|
225
|
+
2. 字节 0–15 画成外圈指纹,字节 16–31 通过固定槽位驱动主特征,次要特征复用字节 0–15。
|
|
226
|
+
3. 性别、年龄、人种不参与哈希。
|
|
227
|
+
|
|
228
|
+
改动以下任何一项都会改变已有头像:**槽位分配**、**任何列表的内容或顺序**(`pick` 用的是取模,往列表里追加一项也算)、**调色板**、**几何参数**。这类改动必须发布 **v2**,换用新的哈希标签,并写进 CHANGELOG。golden 快照测试(`test/golden.json`)负责守住这一条。
|
|
229
|
+
|
|
230
|
+
npm 主版本号与契约版本对应:`1.x` 永远是契约 v1。
|
|
231
|
+
|
|
232
|
+
## 开发
|
|
233
|
+
|
|
234
|
+
```sh
|
|
235
|
+
npm test # node:test,几秒内跑完
|
|
236
|
+
npm run build:demo # 把库内联进单文件 dist/index.html
|
|
237
|
+
npm run sheet # 渲染全部发型、帽子、胡须、衣物、眼镜(需要 rsvg-convert)
|
|
238
|
+
npm run worker:dev # 在本地运行图片服务
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
## 许可证
|
|
242
|
+
|
|
243
|
+
[Apache-2.0](LICENSE)
|
package/package.json
CHANGED
|
@@ -1,6 +1,46 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@suifei/hash-avatar",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "1.0.1",
|
|
4
|
+
"description": "Deterministic SVG avatars from a name or email via SHA-256. Zero dependencies, synchronous, browser and Node.",
|
|
5
|
+
"main": "src/hash-avatar.js",
|
|
6
|
+
"unpkg": "src/hash-avatar.js",
|
|
7
|
+
"jsdelivr": "src/hash-avatar.js",
|
|
8
|
+
"files": [
|
|
9
|
+
"src",
|
|
10
|
+
"README.md",
|
|
11
|
+
"README.zh-CN.md",
|
|
12
|
+
"LICENSE"
|
|
13
|
+
],
|
|
14
|
+
"scripts": {
|
|
15
|
+
"test": "node --test",
|
|
16
|
+
"build:demo": "node scripts/build-demo.js",
|
|
17
|
+
"sheet": "node tools/sheet.js",
|
|
18
|
+
"worker:dev": "npx wrangler dev",
|
|
19
|
+
"worker:deploy": "npx wrangler deploy"
|
|
20
|
+
},
|
|
21
|
+
"keywords": [
|
|
22
|
+
"avatar",
|
|
23
|
+
"identicon",
|
|
24
|
+
"svg",
|
|
25
|
+
"sha256",
|
|
26
|
+
"deterministic",
|
|
27
|
+
"generator"
|
|
28
|
+
],
|
|
29
|
+
"author": "suifei",
|
|
30
|
+
"license": "Apache-2.0",
|
|
31
|
+
"repository": {
|
|
32
|
+
"type": "git",
|
|
33
|
+
"url": "git+https://github.com/suifei/hash-avatar.git"
|
|
34
|
+
},
|
|
35
|
+
"homepage": "https://github.com/suifei/hash-avatar#readme",
|
|
36
|
+
"bugs": {
|
|
37
|
+
"url": "https://github.com/suifei/hash-avatar/issues"
|
|
38
|
+
},
|
|
39
|
+
"engines": {
|
|
40
|
+
"node": ">=18"
|
|
41
|
+
},
|
|
42
|
+
"publishConfig": {
|
|
43
|
+
"access": "public",
|
|
44
|
+
"registry": "https://registry.npmjs.org/"
|
|
45
|
+
}
|
|
46
|
+
}
|