DiceBear Notionists Neutral 预设（Presets）全解：11 组开箱即用的纸墨配色与缩放方案-平芜编程栈

UI组件
后端

【免费下载链接】dicebear

DiceBear is an avatar library for designers and developers. 🌍

项目地址：https://gitcode.com/gh_mirrors/di/dicebear

Notionists Neutral 是 DiceBear 中一个「只有脸部」的手绘风格——眼睛、鼻子和嘴巴以松散的黑色线条绘制在纯色背景上，没有头部、头发和身体。本篇文章围绕该风格的官方预设（Presets）页面展开，完整拆解预设的数据结构、11 组预设各自的参数含义，以及「复制代码 / Playground 打开 / HTTP API 直用」三条实战路径。读完你将能读懂任意预设的 JSON 配置，并能基于自己的常用配色快速拼出新的预设。

Notionists Neutral 风格速览

在进入预设之前，先明确该风格的定位。根据风格主页的描述：

The Notionists face on its own: eyes, nose and mouth in loose black lines on a plain background, without head, hair or body.

也就是说，Notionists Neutral 是完整版 Notionists 的「中性剥离版」——没有头发、衣服、头型等组件，画面只保留五官线条与背景。正因为没有头部形状来承载填充色，背景色就成了整个画面最大的视觉变量，这也是预设中backgroundColor（背景）、inkColor（墨线）、paperColor（纸张）三个颜色组反复出现的原因。

该风格在文档站中属于Characters分类（见 styleCategories.ts），其预览种子（seed）表由脚本自动生成并维护在 previewRowSeeds.ts，共 8 个种子：Dahlia、Ilse、Casper、Emil、Boris、Ezra、Anja、Rita。

什么是 DiceBear 预设：一份普普通通的渲染选项

预设页面的正文只有一句话，却点出了预设的本质：

A preset is an ordinary set of render options. Pick one, read its code or open it in the Playground and keep tuning. Options a preset leaves alone keep varying with the seed, so each row lists how many distinct avatars it still gives you.

即：预设就是一个普通的渲染选项（options）集合。它在文档仓库中的实现说明（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.

这意味着预设完全位于「文档层」，与 JS / PHP / Go / Rust / Python / C# / Dart 七套核心实现无关。任何核心渲染时都只是在处理{ seed, ...preset.options }这样的普通参数对象，预设文件本身只是theme/presets/<style>.json下的纯 JSON。

每个预设的字段结构定义在 presets.ts：

字段	说明
`id`	稳定的小写 kebab-case 标识，用于`?preset=`形式的 Playground 链接
`name`	展示名称
`summary`	一句话摘要，显示在头像旁边
`description`	更长的设计说明，展开卡片时展示，以 Markdown 编写并允许引用`code`形式的选项名
`options`	真正的渲染选项对象，与传给`Avatar`的选项完全同构

11 组官方预设逐一拆解

Notionists Neutral 是目前少数自带预设的风格之一，其全部预设数据保存在 theme/presets/notionists-neutral.json。文档页会据此自动生成标题「Eleven Notionists Neutral starting points」（见 SitePresetsPage.vue）。

总体一览：

id	名称	一句话摘要	设置的选项数
`bare`	Bare	白底黑线，不加任何东西	1
`sepia`	Sepia	牛皮纸上的棕色墨水	3
`greyscale`	Greyscale	浅灰背景上的炭笔线条	3
`duotone`	Duotone	深青配薄荷，全图仅两种颜色	3
`inverted`	Inverted	近黑底上的白色线条，如同粉笔	3
`muted`	Muted	六个灰调底色共用同一组线条	3
`electric`	Electric	黑线配六种酸性高饱和底色	3
`pastel-wall`	Pastel Wall	五种柔和底色	1
`bold-pop`	Bold Pop	五种高饱和底色	1
`sunrise`	Sunrise	渐变背景下的暖色日出	3
`close-up`	Close Up	放大到五官特写	4

Bare —— 全风格的基准线

{ "id": "bare", "name": "Bare", "summary": "Black on white, nothing added.", "description": "The style at its plainest: the face drawn in black on a white ground. The baseline the rest of these presets move away from.", "options": { "backgroundColor": ["ffffff"] } }

它只固定了背景为纯白，不碰墨线与纸张颜色，是其余所有预设的「出发点」。注意backgroundColor是数组形式——即使只填一个值也用数组表达，与多值随机选择的语法保持一致。

Sepia —— 暖色纸墨

"options": { "backgroundColor": ["e3d2b4"], "inkColor": ["4a3526"], "paperColor": ["f5ead6"] }

同时调整三个颜色组：牛皮纸色背景e3d2b4、深棕墨线4a3526、浅黄纸张f5ead6。其设计说明指出：由于没有头部形状可填充，背景就是「纸」，墨线就是「画」，整个画面被统一的暖色贯穿。

Greyscale —— 中性灰

"options": { "backgroundColor": ["ececed"], "inkColor": ["3b3d42"], "paperColor": ["fafafa"] }

设计上是最安静的一组，适合管理后台表格或评论区——头像仅作为「标记」而非「图片」出现，不与页面上的其他内容争抢注意力。

Duotone —— 严格双色

"options": { "backgroundColor": ["dff0eb"], "inkColor": ["0f3d38"], "paperColor": ["eefaf6"] }

墨线用深青0f3d38，底色用薄荷dff0eb与近乎白的纸色eefaf6，整张图只有青与薄荷两种色系。

Inverted —— 粉笔黑板

"options": { "backgroundColor": ["111113"], "inkColor": ["f2f2f4"], "paperColor": ["1c1c20"] }

将颜色整体反转：近黑背景111113、白色墨线f2f2f4。其描述提到该风格的 fill（填充）是独立的颜色组，会随底色一起变暗，因此画面读起来是「黑板上的粉笔字」，而不是「浅色线条在暗底上溶解」。

Muted —— 六种灰调底色

"options": { "backgroundColor": ["6b705c", "a5a58d", "b98b73", "7c9082", "8e9aaf", "9c6b58"], "inkColor": ["1f1f22"], "paperColor": ["f0efe9"] }

只改变底色，且是「离开白色」而非「走向更亮」。六种灰绿色系底色共用一个深灰墨线与近白纸色——由于backgroundColor是含 6 个值的数组，每次渲染会按种子随机抽取一个底色，因此这一组预设保留了可观的多样性。

Electric —— 六种酸性底色

"options": { "backgroundColor": ["ff2e88", "00e5ff", "ffe600", "7cff00", "ff6a00", "b400ff"], "inkColor": ["101216"], "paperColor": ["ffffff"] }

与 Muted 相反的方向：六种超出风格默认范围的荧光底色（粉红、青、黄、绿、橙、紫），墨线保持近黑以保证在任何底色上都清晰。

Pastel Wall 与 Bold Pop —— 底色调色板

两者都只设置多值backgroundColor，前者是五种柔和底色ffe3ea / e3edff / e2f5e9 / fdf1d4 / efe6ff，后者是五种高饱和底色ff5d8f / ffb703 / 43aa8b / 4d96ff / b57bff。它们的共同思路是：通过一组同调性底色让整套头像看起来「属于同一个系列」，同时数组多值保留了种子带来的随机变化。

Sunrise —— 渐变背景示例

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

这是唯一演示渐变背景参数的预设：两个颜色值、linear（线性）填充、135 度固定角度。对应到渲染选项上，backgroundColorFill的取值范围为solid | linear | radial（定义于 StyleOptions.ts）。

Close Up —— 用缩放替代配色

"options": { "backgroundColor": ["f4f1ea"], "scale": 1.3, "inkColor": ["2f2a24"], "paperColor": ["fffdf9"] }

这是唯一改动几何参数的预设：scale: 1.3将画面放大到五官特写。其设计说明解释了动机——这类风格在图形周围留了大量空白，裁切放大可以把这些留白「买回来」。

预设背后的选项体系：颜色组与几何参数

所有预设用到的键都来自 StyleOptions.ts 中定义的选项类型。全局基础选项包括：

seed（字符串）：决定随机序列，同一种子永远渲染同一头像；
scale：数值或[min, max]区间，控制整体缩放；
flip、rotate、translateX、translateY：翻转与位移；
size：输出尺寸；
title、fontFamily、fontWeight：SVG 元信息；
tags：标签过滤语法。

而颜色类选项是按「颜色组」成组生成的（StyleOptions.ts），每个颜色组C自动获得五个键：

键	类型	预设中的实际用法
`CColor`	`string \\| string[]`	本组颜色，多值为按种子随机抽取
`CColorFill`	`solid \\| linear \\| radial`	填充方式（Sunrise 使用了`linear`）
`CColorFillStops`	`number \\| [number, number]`	渐变停靠位置
`CColorAngle`	`number \\| [number, number]`	渐变角度（Sunrise 使用了`135`）
`CColorOrder`	`random \\| fixed`	颜色顺序（预设校验会对它发出 HTTP API 警告，见下文）

Notionists Neutral 的预设实际使用了三个颜色组：background（背景）、ink（墨线）、paper（纸张）。颜色值一律为不含#前缀的 6 位十六进制。

预设页面是怎么工作的

presets/index.md 本身只是一层薄壳，挂载SitePresetsPage组件并传入styleName="notionists-neutral"。该组件（SitePresetsPage.vue）负责渲染整页：

固定三列种子：取getPreviewRowSeeds的前 3 个种子（即Dahlia、Ilse、Casper）作为每一行的公共种子（第 48 行），这样所有预设在同一组种子上横向对比，差异全部来自预设参数；
侧栏精选：从预设列表中「均匀取样」4 个作为侧栏缩略图（第 95-102 行），以保证颜色视觉上有所变化；
行内信息：每个预设一行，由 SitePresetRow.vue 渲染，展示「N options · X distinct avatars」并给出Code与Playground两个按钮；
对话框：点击 Code 后由 StylePresetDialog.vue 展开完整种子行、设计说明与选项代码。

此外，样式页（notionists-neutral/index.md）本身也通过组件内嵌渲染了预设的导览区块，读者在进入完整选项列表（## Options）之前就能先看到现成效果。

把预设用到你的项目里：三条实战路径

路径一：复制为 JavaScript 代码

预设的options与@dicebear/core的渲染选项完全同构，直接搬进Avatar即可。参考 JavaScript 库文档的用法，以 Sepia 为例：

import { Style, Avatar } from '@dicebear/core'; import notionistsNeutral from '@dicebear/styles/notionists-neutral.json' with { type: 'json' }; const style = new Style(notionistsNeutral); const avatar = new Avatar(style, { seed: 'Dahlia', backgroundColor: ['e3d2b4'], inkColor: ['4a3526'], paperColor: ['f5ead6'], }); const svg = avatar.toString();

路径二：在 Playground 中打开并继续调参

预设页每一行都带Playground按钮，链接格式为/playground/?style=<styleName>&preset=<presetId>（见 SitePresetRow.vue）。PlaygroundApp.vue 读取这两个查询参数：先切换到对应风格，再按需加载预设文件并通过store.applyPreset(preset)应用其选项。也就是说，你可以直接打开：

/playground/?style=notionists-neutral&preset=close-up

在界面里继续拖拽调整，直到得到满意的效果再回填代码。

路径三：通过 HTTP API 直用

由于预设就是普通选项，它们可以直接作为 HTTP API 的查询参数使用（这正是 presets.ts 注释中明确声明的能力）。参照 HTTP API 文档的 URL 模板，Notionists Neutral 的地址格式为：

https://api.dicebear.com/11.x/notionists-neutral/svg?seed=Dahlia&backgroundColor=e3d2b4&inkColor=4a3526&paperColor=f5ead6

数组型参数（如 Muted 的六色背景）在 URL 中无法表达随机抽取语义，因此 HTTP API 场景更适合固定单值的预设。

「每一行还剩多少个头像」是怎么算出来的

预设行中显示的 distinct avatars 数字并非拍脑袋，而是由文档站的组合计数工具实时计算：

narrowDefinition.ts 先把风格定义按预设选项「收窄」——固定了哪些颜色组、锁定了哪些组件变体；
computeCount 再对收窄后的定义做组合计数，遍历每个组件结果数、可见颜色组联合计数，并乘上首字母文本的基数，最终输出{ display, log10 }。

这正是「Options a preset leaves alone keep varying with the seed」的量化体现：一个预设固定越多选项（例如 Close Up 同时固定 4 项），剩余组合数就越少；而 Muted、Electric 这类多值颜色数组的预设，会因每次按种子随机选色而保留更多多样性。对「不同种子到底能产生多少不同头像」更底层的解释，可参考 how-many-unique-avatars。

预设如何被校验、同步与保鲜

预设是冻结的选项集，会随风格迭代「安静地腐烂」——某个组件被改名后，旧预设里的xxxVariant选项将不再匹配任何东西。为此文档仓库提供了两个配套脚本：

校验脚本 validate-presets.ts（用法node scripts/validate-presets.ts）会对每个预设做多项检查：

字段完整性：id / name / summary / description非空，id必须 kebab-case 且不得重复；
选项合法性：对照@dicebear/styles中当前风格定义（通过OptionsDescriptor）逐项校验，不认识的键、不存在的枚举变体都会报错；
真实渲染：用 6 个探测种子（Felix / Aneka / Milo / Luna / Dara / Erik）实际跑一遍new Avatar(style, { seed, ...preset.options }).toString()，并要求输出中包含<use元素，从而捕获「概率/变体选项把所有内容都删掉」导致的空头像；
HTTP API 一致性警告：对*ColorOrder以及idRandomization / fontFamily / fontWeight / title等 API 不支持的选项发出警告，避免画廊与线上 API 渲染不一致。

同步脚本 sync-preset-pages.ts（用法node scripts/sync-preset-pages.ts，可加--check）则负责把 JSON 数据接进文档站：为每个带预设的风格生成presets/index.md画廊页（Notionists Neutral 的这一页就是它生成的模板），并在风格主页的## Options之前插入预设导览区块。它同时是幂等的，新增预设后重跑即可。

扩展与自定义：把常用配置做成预设

正如页面底部注释所说：Presets exist for every style that ships them. The files are plain JSON in the docs repository.预设文件的存储与加载由 presets.ts 中的懒加载 glob 完成——theme/presets/*.json下每多一个文件就多一个风格的预设，无需改任何组件代码；加载方式特意设计为按风格拆分的懒加载 chunk，避免所有预设被内联成一个 214 KB 的大包拖慢每个页面。

如果你在项目中积累了自己偏爱的配色组合，完全可以参照 notionists-neutral.json 的格式，为其他风格编写自己的预设 JSON，再让validate-presets.ts帮你验证其选项是否与当前风格定义兼容。这一套「纯 JSON 数据 + 懒加载 + 自动校验」的机制，就是 DiceBear 预设体系的完整工作方式。