Dicebear 头像生成工具

DiceBear能快速为项目创建头像，无论是抽象形状还是精心设计的角色，都能在它提供的头像风格中找到合适的选择。

除了纯随机头像，还能为用户身份创建确定性头像。借助内置的伪随机数生成器（PRNG），基于种子可以重复创建同一个头像。个性化头像也能实现，只需使用每种头像风格提供的众多选项。

DiceBear有JavaScript库、HTTP API、CLI、Figma插件、编辑器和 playground 等工具，创建下一个头像变得很简单。

如何使用？

• 设计师需要头像用于设计时，可以查看Figma插件和编辑器。

• 开发者可以看看HTTP API、CLI、JS库或playground。选择哪一种，取决于使用的编程语言和环境。

• 在JavaScript环境中，如果JS库太大，可以用JS库或HTTP API。

• 在其他环境中，如果担心HTTP API的稳定性或延迟，可能会对HTTP API或CLI感兴趣。

• CLI适合自动化操作，或者需要创建大量不同图片格式的头像时使用。

工作原理

头像以SVG格式创建，这样能动态生成头像，且不需要太多计算能力。大多数情况下，会从一组元素中选择头发、眼睛、耳朵等各种SVG元素，组合成角色或头像。

PRNG使用XorShift32算法，需要注意的是，这个伪随机数生成器并非为加密安全设计。

JS库使用指南

该库用TypeScript/JavaScript编写，可在浏览器和Node.js中使用。其他环境中，可能会对HTTP API或CLI更感兴趣。

它是纯ESM包，若不熟悉ESM包，Sindre Sorhus写了很实用的帮助页面。

安装

至少需要两个包。第一个是核心库@dicebear/core，第二个是头像风格包。示例中使用包含所有官方头像风格的@dicebear/collection包。

npm install @dicebear/core @dicebear/collection

提示：强烈建议使用带有树摇功能的打包工具。如果没有，可以查看“不使用树摇功能使用库”的指南。

使用

示例中使用lorelei头像风格，更多头像风格可以在这里找到。

import { createAvatar } from '@dicebear/core';
import { lorelei } from '@dicebear/collection';

const avatar = createAvatar(lorelei, {
  seed: 'John Doe',
  // ... 其他选项
});

const svg = avatar.toString();

每种头像风格都有多个选项，可在每种头像风格的详情页找到。

提示：如果想将库集成到框架中，可以查看React、React Native、Vue或Svelte的指南。

说明：提供了许多来自不同艺术家的头像风格，这些头像风格的许可证由艺术家自行选择。可以查看许可证概览快速了解。

方法

• createAvatar(style, options)：返回带有.toString()、.toJson()和.toDataUri()方法的对象。第一个参数是头像风格，第二个参数是可选的选项对象，具体选项取决于头像风格。

import { createAvatar } from '@dicebear/core';
import { lorelei } from '@dicebear/collection';

const avatar = createAvatar(lorelei, {
// ... 选项
});

• .toString()：返回类型为string，以XML格式返回SVG头像。

import { createAvatar } from '@dicebear/core';
import { lorelei } from '@dicebear/collection';

const avatar = createAvatar(lorelei, {
// ... 选项
});

const svg = avatar.toString();

• .toJson()：返回类型为{ svg: string, extra: Record<string, unknown> }，返回包含SVG和额外信息（如使用的实际选项）的JSON。

import { createAvatar } from '@dicebear/core';
import { lorelei } from '@dicebear/collection';

const avatar = createAvatar(lorelei, {
// ... 选项
});

const json = avatar.toJson();

• .toDataUri()：返回类型为Promise，以数据URI形式返回头像。

import { createAvatar } from '@dicebear/core';
import { lorelei } from '@dicebear/collection';

const avatar = createAvatar(lorelei, {
// ... 选项
});

const dataUri = avatar.toDataUri();

HTTP API使用指南

HTTP API可能是使用DiceBear最简单的方式，可以使用官方实例，也能自己运行，API是开源的。

使用

使用以下地址，将<styleName>替换为首选的头像风格（驼峰式）。所有官方头像风格都支持。

https://api.dicebear.com/9.x/<styleName>/svg

几个示例：

• https://api.dicebear.com/9.x/pixel-art/svg

• https://api.dicebear.com/9.x/lorelei/svg

DiceBear提供了许多来自不同艺术家的头像风格，这些头像风格的许可证由艺术家自行选择。可以查看许可证概览快速了解。

选项

选项可以通过查询字符串传递。例如，可以这样设置种子：

• ttps://api.dicebear.com/9.x/pixel-art/svg?seed=John

• https://api.dicebear.com/9.x/pixel-art/svg?seed=Jane

提示：如果要传递多个选项，像通常的查询字符串一样用&连接。

• 数组选项：数组值用逗号分隔。例如，除了种子，还想为伪随机数生成器提供多种发型，URL可能像这样（以Pixel Art头像风格为例）：https://api.dicebear.com/9.x/pixel-art/svg?seed=John&hair=short01,short02,short03,short04,short05

• 布尔选项：布尔值可以设为字符串（true和false）。例如：

• https://api.dicebear.com/9.x/lorelei/svg?flip=true

• https://api.dicebear.com/9.x/lorelei/svg?flip=false

文件格式

API支持SVG、PNG、JPG、WebP、AVIF和JSON。建议尽可能使用SVG！SVG是更现代的格式，可以无限缩放，且需要的流量更少。因为PNG、JPG、WebP和AVIF格式会给API带来更大负载，尺寸限制为256x256。这些格式的速率限制也更低。

PNG、JPG、WebP和AVIF使用Noto Sans字体，目前支持以下子集：cyrillic、cyrillic-ext、devanagari、greek、greek-ext、japanese、korean、latin、latin-ext、simplified-chinese、thai和vietnamese。

示例：

• api.dicebear.com/9.x/bottts/svg

• api.dicebear.com/9.x/bottts/png

• api.dicebear.com/9.x/bottts/jpg

• api.dicebear.com/9.x/bottts/webp

• api.dicebear.com/9.x/bottts/avif

版本控制

可以在URL中设置版本。将前面示例中的9.x替换为需要的版本即可。

支持的版本：5.x、6.x、7.x、8.x、9.x

CLI使用指南

使用CLI能快速创建数千个头像！

安装

确保已安装Node.js和NPM。

npm install dicebear --global

升级

为获取最新功能和头像风格，请定期更新CLI。

npm install dicebear --global

使用

• 创建单个头像：将<style>替换为头像风格名称（驼峰式），[outputPath]替换为目标目录。如果省略[outputPath]，会使用当前目录作为目标目录。

dicebear <style> [outputPath]

例如，创建lorelei风格的头像，使用以下命令：

dicebear lorelei .

说明：提供了许多来自不同艺术家的头像风格，这些头像风格的许可证由艺术家自行选择。可以查看许可证概览快速了解。

• 创建多个头像：可以一次创建多个头像！使用--count选项，将<count>替换为要创建的头像数量。

dicebear <style> [outputPath] --count <count>

警告：seed选项与count选项一起使用时无效。如果count大于1，会生成随机值作为seed，使头像彼此不同。

• 传递选项：可以用--help查看可用选项。除了头像风格提供的选项，还有以下附加选项：

--count      定义要创建的头像数量。          [number]
--format                                                  [string] [choices: "svg", "png", "jpg", "jpeg", "webp", "avif", "json"]
--exif       包含Exif元数据                        [boolean]
--json       除图像文件外，额外保存JSON文件     [boolean]

可以创建SVG以外格式的头像。例如，创建lorelei风格的PNG头像，使用以下命令：

dicebear lorelei . --format png

• 显示帮助：每个命令都能请求帮助。

dicebear --help

命令列表（部分）：

• dicebear adventurer [outputPath]：生成“adventurer”头像 • dicebear avataaars [outputPath]：生成“avataaars”头像 • dicebear bottts [outputPath]：生成“bottts”头像

如何通过编程方式获取头像风格的所有可用选项？

每个官方头像风格都提供JSON schema，可用于验证选项，也能通过这个JSON了解可用选项。

以下是获取头像风格所有选项的示例：

import { schema } from '@dicebear/core';
import { micah } from '@dicebear/collection';

const options = {
  ...schema.properties,
  ...micah.schema.properties,
};

console.log(options);