Gravatar开发者手册

Jeff

11 年前

Gravatar上所有URL都是基于电子邮箱地址的哈希值。图像和个人档都是通过电子邮件的哈希值访问获取的，这是系统识别用户身份的主要方式。为确保哈希值的一致性和准确性，在生成哈希值时应遵循下列步骤：

去除掉电子邮箱地址头尾的空格符。
先将所有字母强行转换成小写字母。
使用md5算法计算处理后的电子邮箱哈希值。

比如，以"MyEmailAddress@example.com " 为例（注意我们这里假设用户在邮箱地址末尾不小心多按了个空格），如果我们用md5直接对字符串进行编码，我们会得到下列内容（以PHP为例）：

echo md5( "MyEmailAddress@example.com " ); 
// "f9879d71855b5ff21e4963273a886bfc"

如果我们按照文章开头提到的流程处理同样的电子邮件地址，你会发现得到一个完全不同的计算结果（还是以PHP为例）：

$email = trim( "MyEmailAddress@example.com " ); // "MyEmailAddress@example.com"
$email = strtolower( $email ); // "myemailaddress@example.com"
echo md5( $email );
// "0bc83cb571cd1c50ba6f3e8a78ef1346"

上述代码可写成一行代码：

echo md5( strtolower( trim( "MyEmailAddress@example.com " ) ) );

一旦获得生成的哈希值，你就可以请求获取图像或是个人档。

图片请求

我们可以像使用一般的图片，使用IMG标签请求Gravatar图像。为获取用户图像，我们首先需要计算用户电子邮箱的哈希值。

一般的图片请求URL形式类似下面：

http://www.gravatar.com/avatar/哈希值

上面的哈希值用你所请求用户电子邮箱的哈希值替换掉，比如下面就是一个基本的URL链接。

http://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50

使用IMG标签显示该链接时，效果如下：

<img src="http://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50" />

如果你需要添加文件扩展名，你也可以在URL后面添加.jpg文件名后缀。

http://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50.jpg

图像尺寸

若没有提供尺寸参数，则图像大小默认是80px × 80px。不过，你可以通过s=或size=参数传递一个值（图像是正方形的），动态规定Gravatar图像大小。

http://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50?s=200

你可以请求从1px到512px范围内任意尺寸的图像，不过需要指出的是，许多用户头像的分辨率较低，因此大尺寸的头像效果可能较差。

默认图像

如果某个电子邮件地址没有相应的Gravatar头像时会怎样呢？Gravatar会返回如下的默认头像：

如果你需要使用自己的默认头像（可能是Logo等图片），你可以在图片链接后面的d=或者default=参数中指定你自己默认图片的URL地址。这个URL链接需要进行URL编码，确保传输的正确性。

<img src="http://www.gravatar.com/avatar/00000000000000000000000000000000?d=http%3A%2F%2Fexample.com%2Fimages%2Favatar.jpg" />

如何在PHP中对字符串进行URL编码，你可以参看下面这行代码：

echo urlencode( 'http://example.com/images/avatar.jpg' );

当你指定了默认的头像时，Gravatar在电子邮箱哈希值没有对应的头像时会显示你指定的默认头像。

除了可以设置默认的头像外，Gravatar还提供一系列的内置参数选项作为默认值。这类内置参数选项会接受电子邮箱地址的哈希值，并使用该哈希值生成主题图片。若要启用这些参数，你只需在图片请求中添加上d=参数，并将参数值设置为下列值即可：

404: 不载入任何头像。如果电子邮件地址哈希值没有对应的图像，则返回404响应（文件没有找到）
mm： 简约、卡通风格的人物轮廓像（不会随邮箱哈希值变化而变化）。
identicon：几何图案，其形状会随电子邮箱哈希值变化而变化。
monsterid：程序生成的“怪兽”头像，颜色和面孔会随会随电子邮箱哈希值变化而变化。
wavatar:：用不同面容和背景组合生成的面孔头像。
retro：程序生成的8位街机像素头像。

强制显示默认头像

出于某些原因，你可能需要强制显示默认头像。这时你可使用f=或forcedefault=参数，并将参数值设置为y。

http://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50?f=y

分级

Gravatar允许用户自行对头像分级，表明头像是否适合特定的受众群。只有G级的头像是默认显示的，除非希望看到更高分级的头像。你可以使用r=或rating=参数，指定下列参数，请求特定分级的头像。

g：适合在所有网站的所有受众类型。
pg：可能包含粗鲁手势，挑逗性的着装，少许粗话，及轻微暴力等内容。
r：可能包含亵渎，极度暴力，裸体或吸毒等内容。
x:：可能包含赤裸的性爱或极端暴力内容。

如果请求的邮箱没有头像符合对应的分级，则Gravatar会显示默认头像。

若要允许G或者PG级别的头像，可以参照下面实例设置。

http://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50?r=pg

参数混用

你可以混用上述所有参数，以生成复杂的请求。比如下面这个URL请求的是200像素大小，分级为G或者PG级的Gravatar头像，如果对应的邮箱哈希值没有头像，则默认返回404响应。

http://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50?s=200&r=pg&d=404

安全请求

如果你需要在SSL传输的页面上显示Gravatar头像（比如HTTPS开头的URL页面），你希望Gravatar也是通过SSL传输的，若不这样，你会看到浏览器提示烦人的安全警告。若要进行安全请求，只需将Gravatar请求链接换成下面这样开头的链接即可。

https://secure.gravatar.com/...

除此之外，一切照旧，你只需确保URL开头跟上面一样即可。