DiceBear Icons 头像风格实战指南：在着色背景上渲染 Bootstrap Icons 图形徽标

• UI组件
• 后端

Icons 是 DiceBear 官方提供的一种极简头像风格：它不绘制人脸或卡通形象，而是在一块着色的背景上放置单个 Bootstrap Icons 图形（pictogram），产出一个"图标徽章"式的方形 SVG 头像。本指南将带你掌握 Icons 风格的全部能力——从 HTTP API 和 JavaScript 库的零配置上手，到背景色板、渐变填充、预置方案（Presets）的深度定制，再到它的许可证归属与种子确定性原理，让你可以直接在项目中落地使用。

Icons 风格是什么

按 Icons 风格文档 的定义，Icons 是 DiceBear 的一个免费图标头像生成器："A single Bootstrap Icons pictogram on a tinted background."（在着色背景上放置单个 Bootstrap Icons 图形）。它的特征可以概括为三点：

• 单个图形：每个头像只含一个图标，没有复杂图层，天然适合作为占位符、功能图标或列表徽章；
• 着色背景：背景是画面的"主角"，通过背景色板承载风格；
• 确定性生成：与 DiceBear 所有风格一致，只要 seed 相同，无论通过哪种方式渲染，得到的 SVG 都完全一致。

风格分类与渊源

从仓库的样式分类表 styleCategories.ts 可以看出，icons被归入Minimalist（极简）类别，与identicon、shapes、triangles、glyphs等风格并列。

同时，license.ts 的注释明确记录：Icons 是目前仓库中唯一的port（忠实移植）风格，其图形素材移植自Bootstrap Icons（MIT 许可证）。这意味着它的法律署名措辞是"Based on Bootstrap Icons"，这一点我们会在"许可证与署名"一节详细展开。

文档页面是如何组装出来的

你看到的 Icons 风格页面并非纯静态 Markdown，而是由 SiteStylePage.vue 在运行时动态组装的：它从风格定义、预置文件与统计数据中读取信息，渲染出Usage（用法）、Presets（预置）、Options（选项）、Popularity（热度）、Details（详情）五个区段。因此，本文后续内容也会按照这五个维度展开，并深入各自的源码与数据文件。

快速上手：三种方式渲染 Icons 头像

无论你使用哪种方式，Icons 风格的渲染都遵循同一个模式：输入 seed，输出 SVG。下面的用法代码来自文档站的统一代码生成模块 usageSnippets.ts，同一份代码同时驱动着风格页面上的交互式标签页和供 AI 助手阅读的 Markdown 镜像。

方式一：HTTP API（零安装）

DiceBear 提供了官方托管的 HTTP API。Icons 风格的地址模板为：

https://api.dicebear.com/{major}.x/icons/svg?seed=Felix

其中{major}是当前主版本号（具体以 版本说明 为准），seed决定头像内容。把上面的 URL 直接放进<img src>即可渲染头像：

<img src="https://api.dicebear.com/{major}.x/icons/svg?seed=Felix" alt="icons avatar" />

API 支持把几乎所有渲染选项作为查询参数传递，例如&backgroundColor=b6e3f4。完整参数约定见 HTTP API 集成指南。

方式二：JavaScript 库

先安装核心库与风格包：

npm install @dicebear/core @dicebear/styles --save

然后加载icons.json风格定义并渲染：

import { Style, Avatar } from '@dicebear/core'; import definition from '@dicebear/styles/icons.json' with { type: 'json' }; const style = new Style(definition); const avatar = new Avatar(style, { seed: 'Felix' }); const svg = avatar.toString();

avatar.toString()返回标准 SVG 字符串，可以直接插入 DOM 或传给其他工具。更详细的库用法见 JavaScript 集成文档。

方式三：CLI

全局安装 CLI 后可以直接生成 SVG 文件：

npm install --global dicebear dicebear create icons --seed "Felix"

CLI 的更多参数（输出路径、大小、格式等）见 CLI 集成文档。

在更多语言中渲染 Icons 头像

DiceBear 为每种语言都实现了等价的核心库，Icons 风格的定义文件（icons.json）同样适用于它们。以下是官方用法模块为 Icons 生成的其他语言片段：

各语言的风格定义加载方式（PHP 读取包内icons.json、Rust 用dicebear_styles::ICONS常量、Dart 用Style.parse(icons)等）都封装在对应库中，具体见 PHP、Python、Rust、Go、Dart、C# 的集成文档。

定制 Icons 头像的核心选项

Icons 风格的灵魂是"背景 + 图形"，因此背景色系选项是它的核心定制杠杆。以下选项在 DiceBear 全部核心与 HTTP API 中行为一致（仅传参语法因语言而异），完整定义见 核心选项文档。

seed：一切的确定性来源

seed（字符串，默认''）是 DiceBear 的确定性根基。同一 seed 会在任何语言、任何核心中渲染出完全相同的头像，这正是风格页面"Same seed, same avatar, whichever way you render it"（同一 seed、无论哪种方式渲染都是同一头像）这一提示语的含义。

底层实现上，seed 首先经 Fnv1a.ts 做哈希，再作为 Mulberry32.ts 伪随机数生成器的输入，随后所有组件与颜色的挑选都从这个 PRNG 的取值序列中采样。因此 seed 的选择直接影响图标的呈现方式与背景颜色。

背景选项：Icons 的主要定制手段

所有 DiceBear 风格都支持以下背景选项，即使该风格的定义没有显式声明background颜色组：

例如，让背景呈现一张 45 度角的双色渐变：

const avatar = new Avatar(style, { seed: 'Felix', backgroundColor: ['b6e3f4', 'c1a7fb'], backgroundColorFill: 'linear', backgroundColorAngle: 45, });

搭配backgroundColorOrder: 'fixed'时，颜色会严格按给定顺序作为渐变停靠点从首到尾排列。一个值得注意的细节是：当固定顺序生效时，风格定义里的contrastTo（对比度约束）会被跳过，而notEqualTo（不等约束）仍然生效，因此结果依然可以随种子变化。

通用变换与输出选项

除了背景，以下通用选项同样作用于 Icons 头像：

对 Icons 这类"单图标 + 背景"风格，最实用的组合是borderRadius: 50得到圆形徽章，或用scale调整图标的视觉占比。另外，组件级的旋转、平移、缩放由风格定义在渲染时采样，不是用户可选项（不存在{component}Rotate这类选项）。

变体过滤：tags 选项

tags（string \| string[]）可以按标签过滤风格定义的变体池，语法为category或category:value（如hairLength:long），同类别内用"或"、跨类别用"与"，前缀!表示禁止。详细规则见 标签过滤文档。

Icons 预置方案（Presets）：开箱即用的色板

为了让用户快速获得成品效果，DiceBear 为 Icons 准备了 9 套预置方案，全部存放在 icons.json 中。每套 preset 本质上就是一组普通的渲染选项，因此它不依赖定义格式、也适用于所有语言库与 HTTP API。

如何使用预置方案

预置页面 presets/index.md 说明：preset 是普通渲染选项集合，你可以把其中的 options 直接复制进自己的代码，也可以在 Playground 中通过?preset=链接打开并继续微调。

例如使用 Sepia 方案：

const avatar = new Avatar(style, { seed: 'Felix', backgroundColor: ['8a6a48', '6b4f35', 'a3855f', '54402c'], });

值得注意的是，preset 未涉及的选项仍会随 seed 变化——例如 Sepia 的四色背景默认按random顺序洗牌，所以即使固定了色板，不同 seed 依然能产生多个不同的头像。

预置方案的校验机制

预置数据由 validate-presets.ts 脚本守护。它以 6 个探测种子（Felix、Aneka、Milo、Luna、Dara、Erik）对每套 preset 调用new Avatar(style, { seed, ...preset.options })做真实渲染，并检查：

• 每个 preset 的id、name、summary、description非空，且id为 kebab-case；
• 不存在重复 id；
• 设置的每个选项键都是该风格真正接受的（即存在于OptionsDescriptor中）；
• 枚举选项的值是该风格当前仍存在的变体；
• 渲染结果非空——SVG 必须包含<use>元素，防止概率或变体选项把头像清空。

这保证了仓库里的 9 套 Icons 预置在任何种子下都能正常渲染、不会"静默腐烂"。

许可证与署名

DiceBear 的代码本身是 MIT 许可（见 许可证页面），而每个头像风格的素材由各自艺术家选择许可。对于 Icons：

• 素材来自Bootstrap Icons，MIT 许可；
• 按 license.ts 的归属判定逻辑，Icons 属于port（忠实移植）而非 remix（再创作），因此署名措辞是"Based on Bootstrap Icons"，在风格页面与社交卡片（OG 卡）上保持一致。

在你把 Icons 头像用于自己的产品时，建议保留与 Bootstrap Icons MIT 许可相符的署名信息。

附：示例种子与关键文件索引

文档站在生成 Icons 预览时使用固定的种子集。例如 previewRowSeeds.ts 为 Icons 风格页首行选用了Dahlia, Iona, Callum, Edgar, Berta, Ella, Aden, Reza八个种子——前四个的字母恰好拼出DICE，让任何一位读者打开页面都能看到风格化又不重复的示例。你也可以用任意自己喜欢的英文单词作 seed 来探索该风格。

本文涉及的关键仓库文件一览：

• 风格文档主体：styles/icons/index.md
• 预置文档：styles/icons/presets/index.md
• 预置数据：theme/presets/icons.json
• 风格页动态组件：SiteStylePage.vue
• 多语言用法代码生成器：usageSnippets.ts
• 核心选项全表：customize/options/index.md
• 许可证与归属逻辑：utils/license.ts
• 风格分类表：config/styleCategories.ts
• 预置校验脚本：scripts/validate-presets.ts
• 确定性随机数实现：Prng/Fnv1a.ts、Prng/Mulberry32.ts

掌握了这些，你就可以把 Icons 头像灵活嵌入网页、桌面端、移动端与各类服务端项目，并用背景色板与预置方案快速统一整套头像的视觉语言。

• UI组件
• 后端