基本概念
Cravatar 初认头像服务可以像普通的图片 URL 一样请求,具体格式是:
https://cravatar.cn/avatar/HASH
https://cn.cravatar.com/avatar/HASH
其中 HASH 部分是你的电子邮箱的哈希值,此电子邮箱必须在 Cravatar.com / Cravatar.cn 上注册并绑定头像,否则会尝试返回 Gravatar 头像和 QQ 头像,如果都不存在,则返回默认头像。
电子邮箱的哈希方法
总体一共以下三步:
- 去除首尾两边的空格
- 所有字母转小写
- 计算 MD5 值
以下以 PHP 语言进行演示:
$email = 'cravatar@feibisi.com';
$address = strtolower( trim( $email ) );
$hash = md5( $address );
拼接图片请求 URL
依然以 PHP 语言进行演示:
$url = 'https://cravatar.cn/avatar/' . $hash;
指定图片格式
我们当前支持四种图片返回格式,分别是:jpg 、 jpeg 、 png 、 gif 。
你可以简单的通过向图片访问 URL 拼接文件后缀的方式来访问特定格式的图片,完整的请求 URL 类似如下:
https://cravatar.cn/avatar/e1e7ba949ade0936e071132d2edd3b3c.png
https://cn.cravatar.com/avatar/e1e7ba949ade0936e071132d2edd3b3c.png
特别地:在浏览器明确表明支持 webp(Accept 中包含
image/webp
) 的情况下我们会强制返回 webp 格式,此时用户无法手工指定图片格式。之所以这样设计是因为 webp 已经可以完全取代其他格式,同时其提供了更小的体积,这给予了我们更快的加载速度。
额外的参数
调整头像大小
默认情况下,我们会返回 80x80 尺寸的头像,但是你可以通过 s
或 size
参数来指定要获取的头像大小,完整的 URL 类似如下:
https://cravatar.cn/avatar/e1e7ba949ade0936e071132d2edd3b3c?s=400
https://cn.cravatar.com/avatar/e1e7ba949ade0936e071132d2edd3b3c?s=400
以上 URL 将返回一个 400x400 的图像
默认头像
如果你的邮箱哈希无法匹配到任何头像,则返回我们的默认头像:
你可以通过 d
或 default
参数自己指定默认头像:
https://cravatar.cn/avatar/245467ef31b6f0addc72b039b922a4?d=https%3A%2F%2Fcravatar.com%2Fwp-content%2Fuploads%2Fsites%2F9%2F2021%2F07%2F4.png
https://cn.cravatar.com/avatar/245467ef31b6f0addc72b039b922a4?d=https%3A%2F%2Fcravatar.com%2Fwp-content%2Fuploads%2Fsites%2F9%2F2021%2F07%2F4.png
需要注意的是,传递的默认头像地址必须经过 URL 编码,在 PHP 中你可以这样写:
urlencode( 'https://cravatar.cn/wp-content/uploads/sites/9/2021/07/4.png' );
urlencode( 'https://cn.cravatar.com/wp-content/uploads/sites/9/2021/07/4.png' );
同时默认头像需要满足以下几个条件:
- 必须是公开可用的 (例如,不能位于内部网、本地开发机器、或是存在防火墙等) 。
- 必须可以通过标准端口 80 和 443 上的 HTTP 或 HTTPS 进行访问。
- 必须具有可识别的图像扩展名 (jpg 、 jpeg 、 gif 、 png)
- 不得包含查询字符串 (如果包含,它将被忽略)
除了允许你自己指定默认头像外,我们还准备了一组内置的默认头像,只需要传入 d=默认头像 ID
即可调用:
- 404:如果没有与电子邮件哈希关联的图像,则不加载任何图像,而是返回 HTTP 404(未找到文件) 响应
- mp:一个简单的卡通风格的人物轮廓
- identicon:一个几何图案 (随机生成)
- monsterid:具有不同颜色、面孔的 「怪物」(随机生成)
- wavatar:具有不同特征和背景的人脸 (随机生成)
- retro:8 位色的像素人脸 (随机生成)
- robohash:具有不同颜色、面部的机器人 (随机生成)
- blank:透明的 PNG 图像 (为方便演示,已为其添加了一个边框)
强制加载默认头像
如果由于某种原因你想强制始终返回默认头像,您可以使用 f
或 forcedefault
参数并将其值设置为 y
。
https://cravatar.cn/avatar/e1e7ba949ade0936e071132d2edd3b3c?f=y
https://cn.cravatar.com/avatar/e1e7ba949ade0936e071132d2edd3b3c?f=y
指定要显示的头像级别
该选项存在于 Gravatar 中,但 Cravatar 并不提供对该选项的支持。这同样是为了符合中国法律。
组合参数
以上所介绍的所有关于 Cravatar 的参数都可以自由组合,比如你可以提供这样的一个头像 URL:
https://cravatar.cn/avatar/e1e7ba949ade0936e071132d2edd3b3c.png?s=200&d=retro&f=y
https://cn.cravatar.com/avatar/e1e7ba949ade0936e071132d2edd3b3c.png?s=200&d=retro&f=y
以上头像 URL 将始终返回格式为 png 、尺寸为 200 的 8 位色像素人脸。