企业官网建设流程全解析

• UI组件
• 后端

Gaze 是 DiceBear 中最极简的头像风格之一——一个彩色几何形身体上只有一双眼睛。本文以仓库文档中的 Gaze 预设画廊（apps/docs/pages/styles/gaze/presets/index.md）为线索，逐一拆解它提供的 12 个现成预设（配色、背景、几何形态、动效与缩放），并深入源码讲解预设的本质、校验机制、变化数量计算方式以及背后用到的渲染参数。读完本文，你可以直接复制任意预设到自己的代码中，或通过 Playground、HTTP API、CLI 快速落地，也能自己动手"调出"一套新的 Gaze 风格。

什么是 DiceBear 预设

官方文档对预设的定义非常朴素："A preset is an ordinary set of render options."——预设不过是一组普通的渲染选项（render options）而已。选中一个预设，读取它的代码，或是在 Playground 里打开它继续微调；预设没有改动的那些选项，仍然会随着 seed 不断变化，因此画廊里每一行都会列出该预设"还剩下多少种不同的头像"。

这个"预设即普通选项集"的设计有一个关键优势：预设不需要被任何核心库感知。正如 apps/docs/.vitepress/theme/config/presets.ts 中的注释所说明的：

A preset is nothing but a bag of regular render options, so it works in every library and as HTTP-API query parameters without the definition format or any of the seven cores knowing that presets exist.

也就是说，同一份预设数据可以直接用于 JavaScript、PHP、Python、Rust、Go、Dart、C# 七种官方核心库，也能直接作为 HTTP API 的查询参数，无需任何转换。

Gaze 的预设数据保存在 apps/docs/.vitepress/theme/presets/gaze.json，共 12 条，每条由四个字段组成：

在文档页面侧，预设画廊由SitePresetsPage组件渲染（SitePresetsPage.vue），页面标题会根据预设数量动态生成，例如 "Twelve Gaze starting points"。每一行预设使用同一组 seed（Gaze 使用预览种子表Dries / Ida / Curtis / …，见 apps/docs/.vitepress/theme/config/previewRowSeeds.ts），方便横向对比不同预设在同一 seed 下的效果；行内还提供Code与Playground两个入口按钮（见 SitePresetRow.vue）。

Gaze 风格速览

在深入预设之前，先了解 Gaze 风格本身。其风格主页（apps/docs/pages/styles/gaze/index.md）的描述是：

A pair of eyes on a colored body and nothing else: eleven silhouettes and eleven eye pairs. With the animation on, the eyes wander and blink while the body hops.

即：一个彩色身体上放一双眼睛，仅此而已。风格内置11 种剪影（silhouettes）与11 组眼睛（eye pairs）；开启动画后，眼睛会转动、眨眼，身体会上下跳动。Gaze 默认输出透明背景，不声明自己的背景色（这一点在后面讲背景预设时还会提到）。

12 个 Gaze 预设全览

以下完整列出 gaze.json 中的全部预设及其选项，并按主题分组展开。所有颜色值均为不带#的 6 位十六进制。

配色基调类

1. Sepia（暖棕身体 + 奶油底色）

{ "backgroundColor": ["efe3d2"], "bodyColor": ["d5b28c", "c49a70", "e0c6a8", "b3835c"] }

暖棕色的身体立在奶油色底上。预设说明提到眼睛并不单独上色，而是自动选用两种"墨色"中能与身体形成对比的那一种——身体换成棕色系后，眼睛会自行跟随调整。

2. Greyscale（去色灰阶）

{ "backgroundColor": ["ececee"], "bodyColor": ["c9c9cd", "aeaeb4", "dcdce0", "94949a"] }

同一组身体造型，只是去掉色相。Gaze 的内容本身只有剪影和一双眼睛，因此失去颜色几乎不损失信息量。官方注释指出它适合打印样式表或"颜色另有含义"的图表场景。

3. Duotone（单一薄荷绿身体）

{ "backgroundColor": ["e2f5ef"], "bodyColor": ["7ad0b4"] }

整个系列共用一种身体颜色。此时区分两个头像的只剩下剪影、眼睛以及它们之间的距离。

4. Muted（哑光低饱和）

{ "backgroundColor": ["e8e4dc"], "bodyColor": ["a5a58d", "b98b73", "8e9aaf", "9c8a94", "8fa38f", "b0a58c"] }

Gaze 官方默认调色板是 6 种明亮的粉彩（pastel）色；这里换成同样造型但更沉稳的 6 种低饱和色，适合侧边栏中"一次出现十几个头像"的场合。

5. Electric（霓虹撞色）

{ "backgroundColor": ["0f0f12"], "bodyColor": ["ff2e88", "00e5ff", "7cff00", "ffe600", "ff6a00", "b400ff"] }

与 Muted 相反：近黑色背景上铺 6 种霓虹色身体。因为霓虹色在每次配对中都是较亮的一方，墨色（眼睛）会自动翻转到较深的那个选择上。

背景处理类

6. Pastel Wall（粉彩浅底）

{ "backgroundColor": ["ffe3ea", "e3edff", "e2f5e9", "fdf1d4", "efe6ff"] }

Gaze 本身不声明背景、渲染为透明；给一个浅色地面能让剪影获得"立得住"的边缘，且不触碰主体画面。

7. Bold Pop（高饱和彩底）

{ "backgroundColor": ["ff5d8f", "ffb703", "43aa8b", "4d96ff", "b57bff"] }

比 Pastel Wall 更张扬。身体保持浅色，因此在高饱和底上仍然轮廓清晰。

8. Night Shift（深色模式专用）

{ "backgroundColor": ["16161a"] }

为深色界面准备：近黑背景，身体沿用默认粉彩色。因为出厂身体本来就是 pastel 色系，无需改动其他任何选项，剪影依然可见。

9. Sunrise（暖色渐变背景）

{ "backgroundColor": ["ffd9b0", "ffa8bf"], "backgroundColorFill": "linear", "backgroundColorAngle": 135 }

这个预设演示的是渐变背景选项：两个颜色、线性填充（linear）、固定角度 135°。seed 仍然决定哪个颜色落在渐变的上方。

形态与构图类

10. Geometric（只保留几何直边剪影）

{ "shapeVariant": ["circle", "square", "triangle", "pentagon", "hexagon", "octagon", "diamond"] }

11 种身体剪影中，7 种是标准多边形，另外 4 种是手绘形状。只保留多边形会让整套头像的边缘处理一致，更像"一套图标系统"而非"一群生物"。

11. Close Up（拉近特写）

{ "scale": 1.3 }

不用颜色而是用scale构图：放大到身体溢出画布边缘，只剩下一双眼睛和少量轮廓。在评论区那样的小尺寸头像场景下可读性更好。

动效类

12. Animated（开启内置动画）

{ "animation": true }

动画默认关闭，animation: true将其打开：眼睛转动、眨眼，身体跳动。预设说明还提到hopAnimation: true可只播放"跳动"这一个动画，animationSpeed控制节奏，并且动画尊重prefers-reduced-motion。

从源码结构看，hopAnimation对应 src/js/core/src/OptionsDescriptor.ts 中"每个动画名各有一个开关"的设计——当风格声明了声明式动画时，核心库会为每个动画名生成${name}Animation、${name}AnimationSpeed、${name}AnimationDelay三个选项（见该文件第 171–185 行），hopAnimation正是名为hop的动画轨道对应的开关。

在代码中使用预设

每个预设本质都是选项对象，因此使用方式与手写选项完全一致。以 Sepia 预设为例，在 JavaScript 库中（@dicebear/core+ 风格定义）：

import { createAvatar } from '@dicebear/core'; import { style } from '@dicebear/styles/gaze'; const avatar = createAvatar(style, { seed: 'Dries', backgroundColor: ['efe3d2'], bodyColor: ['d5b28c', 'c49a70', 'e0c6a8', 'b3835c'], }); const svg = avatar.toString();

文档画廊里的Code按钮会弹出 StylePresetDialog.vue，其中内嵌的 StyleOptionsCodePanel.vue 会为同一套选项同时生成 9 种形态的代码：HTTP API、JavaScript、PHP、Python、Rust、Go、Dart、C# 与 CLI（生成逻辑见 apps/docs/.vitepress/theme/utils/code-examples.ts）。这意味着一套预设数据可以无差别地用在七种官方核心库中。

对应到 CLI（命令形态见 apps/docs/.vitepress/theme/utils/avatar/api.ts 的getAvatarApiCommand）：

dicebear create gaze \ --backgroundColor 'efe3d2' \ --bodyColor 'd5b28c' 'c49a70' 'e0c6a8' 'b3835c'

对应到 HTTP API，则表现为查询参数（数组用逗号连接，见同一文件getAvatarApiUrl）：

/11.x/gaze/svg?backgroundColor=efe3d2&bodyColor=d5b28c,c49a70,e0c6a8,b3835c

此外，画廊每一行的Playground按钮会生成深链/playground/?style=gaze&preset=<id>（见 SitePresetRow.vue 的playgroundUrl），在浏览器里打开即可继续调参。

每个预设还剩多少种变化

画廊每一行都会展示类似"2 options · N distinct avatars"的信息：预设设定了几个选项，以及在这个设定下仍然能产生多少种不同的头像。这个数字不是写死的，而是由 apps/docs/.vitepress/theme/utils/avatar/combinationCount.ts 的computeCount实时计算的：

1. 先用 narrowDefinition.ts 把用户设置的选项"收缩"到风格定义上——固定*Color会收窄调色板，固定*Variant会收窄变体池；
2. 再统计收缩后的定义还能产生多少种不同的渲染结果。

narrowDefinition的注释还明确了一点：画布级变换（flip、rotate、scale、borderRadius、translateX/Y）和表现类选项（fontFamily、*Fill、*FillStops、*Angle、seed、size）不会改变基数，因此不计入变化数量。这也解释了为什么 Sunrise 预设使用了渐变填充和角度，画廊里显示的变化数量依然只与它固定的背景/身体颜色有关。

"预设未触及的选项仍随 seed 变化"正是计数成立的前提：例如 Sepia 只固定了背景色与身体色，而剪影、眼睛、旋转等仍由 seed 驱动，所以它保留的变化数远大于 Duotone（只留 1 种身体色 + 1 种背景色）。

预设的底层实现与校验机制

数据加载

presets.ts 定义了StylePreset类型，并用import.meta.glob惰性加载../presets/*.json下的所有文件。采用惰性加载是为了让 Vite 为每个风格单独生成 chunk，避免所有 55 个风格文件被打包进一个 214 KB 的公共 chunk 拖慢页面。

校验脚本

apps/docs/scripts/validate-presets.ts 是预设质量的"守门人"。它针对每个预设执行以下检查：

• id必须是非空的 kebab-case，且全文件内不重复；
• name、summary、description必须是非空字符串；
• options必须是非空对象，且每个键都必须被该风格接受（用OptionsDescriptor比对，未知键直接报错）；
• 枚举类选项的值必须存在于风格定义中（防止组件被重命名后预设静默失效）；
• 用 6 个探测种子（Felix / Aneka / Milo / Luna / Dara / Erik）真实渲染每个预设，任何种子渲染失败都会报错，渲染结果为空（输出中不含<use元素）也会报错；
• 对 HTTP API 不支持的选项（*ColorOrder、idRandomization、fontFamily、fontWeight、title）给出警告。

该脚本由文档构建流程调用（apps/docs/package.json中build前置validate:presets），确保预设不会随风格定义演化而腐烂。

页面同步与渲染工具

apps/docs/scripts/sync-preset-pages.ts 负责把有预设的风格自动接入文档：在风格主页插入 Presets 栏目、生成presets/index.md画廊页，并提供--check模式用于 CI 校验。它被设计为幂等，可随时重跑。

apps/docs/scripts/render-presets.ts 则是一个面向开发者的可视化工具：把某个风格的全部预设渲染成一张"联系人表"（contact sheet）——每个预设一行，使用同一组 seed 横向并排，方便肉眼挑选。它的注释提醒：预设的失败模式往往是验证器看不见的视觉问题（深色预设吞掉线条、颜色冲突、裁切切掉耳朵），这张表就是"用眼睛检查"的工具。用法：

node scripts/render-presets.ts gaze [out.png] [--seeds=6]

预设用到的渲染参数详解

以上预设共涉及 7 个渲染参数，它们在 src/js/core/src/OptionsDescriptor.ts 中都有对应的字段定义，底层行为可在 src/js/core/src/Renderer.ts 中找到实现。

backgroundColor/bodyColor：颜色组

颜色选项接受单个值或值数组。数组语义是"从这些颜色中随机抽取"，单值则是"固定为这一种"。例如 Duotone 的bodyColor: ["7ad0b4"]会让所有头像共用一个身体色。

背景色的渲染在Renderer.ts的#renderBackground（第 248–256 行）：当该风格没有配置任何背景色时，返回空字符串（Gaze 因此默认透明）；配置了背景色时，则输出一个铺满画布的<rect>。Gaze 风格自身不声明background颜色组，所以只有显式设置backgroundColor才会出现底色。

backgroundColorFill/backgroundColorAngle：渐变填充

*ColorFill是枚举solid | linear | radial，*ColorAngle是范围-360 ~ 360的角度。当填充不是solid且颜色多于一个时，#resolveColorReference（第 560–574 行）会调用#buildGradientDef（第 580 行起）生成<linearGradient>或<radialGradient>，并把角度写入gradientTransform="rotate(...)"。Sunrise 预设正是这一机制的演示。

shapeVariant：变体选择

*Variant类选项由 src/js/core/src/Options.ts 的componentVariant归一化为带权重的映射，权重支持2:name这样的Prng.weightedPick语法。Geometric 预设通过把shapeVariant收窄为 7 个多边形来统一边缘风格。

scale：画布缩放

scale是范围0 ~ 10的画布级变换（见OptionsDescriptor.ts第 95 行），Close Up 预设用它把身体放大到溢出画布。

animation/animationSpeed/hopAnimation：动效

动效参数只在风格声明了声明式动画时才被广告出来（OptionsDescriptor.ts第 171–185 行）。animation是总开关，animationSpeed范围0.1 ~ 10，按动画名生成的hopAnimation可单独控制名为hop的轨道。渲染端把动画编译为@keyframes+ CSS class（Renderer.ts第 829 行起），并将所有动画 CSS 包进@media (prefers-reduced-motion: no-preference)媒体查询中（第 968–985 行）——这正是预设说明中"动画尊重 prefers-reduced-motion"的源码依据：系统开启"减少动态效果"的用户会拿到静态头像。

相关资源入口

• Gaze 风格主页：apps/docs/pages/styles/gaze/index.md
• Gaze 预设数据（本文全部选项的权威来源）：apps/docs/.vitepress/theme/presets/gaze.json
• 预设类型与加载器：apps/docs/.vitepress/theme/config/presets.ts
• 预设校验脚本：apps/docs/scripts/validate-presets.ts
• 画廊页面组件：SitePresetsPage.vue、SitePresetRow.vue
• 变化数量计算：combinationCount.ts 与 narrowDefinition.ts
• 代码示例生成：code-examples.ts 与 api.ts
• 渲染参数定义与实现：OptionsDescriptor.ts、Options.ts、Renderer.ts
• 风格在编辑器中注册：apps/editor/src/config/styles.ts
• 相关玩法：Playground（apps/docs/pages/playground/index.md）、HTTP API 集成（apps/docs/pages/integrations/http-api/index.md）

如果你想要的配色不在这 12 个预设里，也可以直接拿任意预设的 JSON 作为起点——它本质上就是一份普通的Avatar选项对象，改几个十六进制值就能得到你自己的 Gaze 风格。

• UI组件
• 后端