徽章简介

经常使用GitHub的朋友可能会看到一些项目的介绍(README.md)中添加了对项目进行标记和说明的徽章(Badge),这些好看的小图标不仅简洁美观清晰易读,而且可以自动更新相关数据,免去了每次手动更新的麻烦。

徽章主要由图片和对应的链接组成,徽章图片的话一般由左半部分的名称和右半部分的值组成。

GitHub本身并不提供徽章这种格式,而是需要借助第三方网站:shields.io

常用徽章模板(动态)

打开网站:shields.io,界面是英文的,可以使用浏览器的翻译功能(大多数浏览器自带)查看。

我们通过一个例子来看一下如何创建徽章:

1.比如我要显示GitHub项目的下载数量,打开shields.io,我们点击“Downloads(下载)”

2.在Downloads列表中找到“GitHub”,点击我们需要的一项,弹出新对话框。

3.填写所需信息,预览无误后,点击最下方蓝色按钮就可以复制链接,粘贴到浏览器中看一看效果吧。还可以直接复制MarkDown、HTML等多种格式。

最后实现效果:GitHub All Releases

当这个项目的下载量增加时,徽章中的数字就可以自动更新了。当然我们还可以自定义徽章中的文字或者背景颜色(请查看“自定义徽章”部分)。

常用的徽标主要有持续集成状态、项目版本信息、代码测试覆盖率、项目支持平台、项目语言、代码分析等。

自定义徽章(静态)

上面介绍了自动更新数据的方式,但是有的时候我们只想放一个静态的数字或者文字或者向定制自己的个性化徽标,应该怎么办呢?其实shields.io也提供了自定义徽标的功能。

标题/内容/颜色/链接

模板:https://img.shields.io/badge/徽标标题-徽标内容-徽标颜色.svg

  • 【徽标标题】:徽标左半部分的文本(可以使用“ _ ”或空格);
  • 【徽标内容】:徽标右半部分的文本,同上;
  • 【徽标颜色】:徽标右半部分的背景颜色,可以是 red、green等颜色单词,也可以直接写十六进制代码,如“ff69b4”。

GitHub All Releases

<img src="https://img.shields.io/badge/徽标标题-徽标内容-red.svg" />

GitHub All Releases

<img src="https://img.shields.io/badge/biaoti-neirong-green.svg" />

搭配超链接实现点击徽章跳转:GitHub All Releases

<a href="https://www.weibo.com/6027243059"><img src="https://img.shields.io/badge/weibo-唉呦呵喂-ff5722.svg" /></a>

附加参数

在徽章的URL后面带上一些参数来控制徽标的样式。使用方法就是在徽标章 URL 后面跟上?{参数名}={参数值},多个参数联用的话就是 ?{参数名1}={参数值1}&{参数名2}={参数值2}&…,注意“?”小写。

附加参数在第一种自动更新数据的方式中也可以使用。

1. style

style 控制徽标的主体样式,有四种,不设置的话默认是 flat 。

plastic:

<img src="https://img.shields.io/badge/weibo-唉呦呵喂-ff5722.svg?style=plastic" />

flat(默认):

<img src="https://img.shields.io/badge/weibo-唉呦呵喂-ff5722.svg" />

flat-square:

<img src="https://img.shields.io/badge/weibo-唉呦呵喂-ff5722.svg?style=flat-square" />

social:

<img src="https://img.shields.io/badge/weibo-唉呦呵喂-ff5722.svg?style=social" />

2. label

该参数可以用来强制覆盖原有的徽标标题文字。

原有的 "weibo" 字样已经被覆盖为"微博":

<img src="https://img.shields.io/badge/weibo-唉呦呵喂-ff5722.svg?label=微博" />

3. logo

该参数可以用来为徽章添加 logo,logo 图片会出现在左半部分的徽标标题左边,logo 图片高度必须 ≥ 14px,logo 图片需要先转为 base64 编码然后直接插入到 URL 中(可以用 b64.io 将图片转为 base64 编码的字符串),格式如下。

....svg?logo=【base64编码后的图片数据】(没有中括号)。

4.logoWidth:该参数可以设置在上一个参数 logo 中添加的图标的宽度,设为 0 的话即为忽略该参数,示例代码和效果如下:

....svg?logoWidth=100&logo=【base64编码后的图片数据】

5.colorA、colorB

colorA 用来控制徽标左半部分的背景色;

colorB 用来控制徽标右半部分的背景色;

注意两者只能用十六进制的颜色代码作为参数,不能直接写 red、green之类的单词。

<img src="https://img.shields.io/badge/weibo-唉呦呵喂-ff5722.svg?colorA=FFB6C1&colorB=4B0082" />
6.maxAge

该参数用来设置 HTTP 缓存时间,以秒为单位,直接在 svg 地址后跟 ?maxAge={缓存秒数} 即可,这个普通用户不需要设置,会前端的朋友自然懂。

注意

徽章的作用就是让数据直观显示,因此徽标并不是越多越好,不要盲目地追求徽章的数量。

过多的徽章适得其反,会导致读者很难快速寻找重点。