UI组件后端【免费下载链接】dicebearDiceBear is an avatar library for designers and developers. 项目地址https://gitcode.com/gh_mirrors/di/dicebear点击查看免费下载dicebear/core是 DiceBear 头像库的官方 JavaScript 实现负责把「样式定义style definition 一个 seed 字符串」确定性地产出 SVG 头像。它既能在 Node.js 22 中作为服务端工具运行也能在现代浏览器中以原生 ESM 模块方式使用同一 seed、样式与选项在所有语言实现中都会得到逐字节一致的 SVG 输出。读完本文你将掌握Avatar/Style两个核心类的正确用法、全部可配置选项的取值范围与默认值以及dicebear/core/lite轻量入口的取舍边界。一、包定位与核心概念DiceBear 的核心设计是确定性头像不是随机生成的而是由输入seed、样式、选项通过固定算法计算出来的。dicebear/core封装了这条完整的计算管线文档在 README 中将其描述为JavaScript implementation of the DiceBear avatar library. Generates deterministic SVG avatars from style definitions and a seed string.DiceBear 提供了多语言实现仓库中可见 C#、Dart、Go、PHP、Python、Rust 等端口所有实现共享同一套 PRNG 与渲染管线因此在同一 seed、样式、选项下无论使用哪种语言产出的 SVG 输出完全一致。这种跨语言一致性由共享的确定性算法保证并由 Parity.test.js 及仓库根的 parity fixtures 加以验证。两个需要先理解的角色样式定义style definition一段描述如何画头像的 JSON声明画布尺寸、组件眼睛、嘴巴、身体……及其变体、颜色、动画等。官方预置样式由dicebear/styles包提供如lorelei.json也可以通过仓库文档了解如何从零创建样式或编辑既有样式。seed一个字符串通常来自用户名、邮箱或任意 id是头像唯一性或者说确定性多样性的来源。同一 seed 永远生成同一头像。二、安装与运行环境npm install dicebear/core根据 package.json包版本为11.0.0-rc.2遵循 MIT 许可证type: module产物为原生 ESM 模块exports暴露两个入口.主入口带校验与./lite轻量入口无校验sideEffects: false可被打包工具安全地进行 tree-shakingengines要求node 22.0.0README 同时说明也可在任何现代浏览器中运行。三、快速上手生成第一个头像README 给出了最小可运行示例从dicebear/styles引入一个样式定义配合 seed 与 size 选项创建头像然后导出为 SVG 字符串或 data URI。import { Avatar, Style } from dicebear/core; // 从样式定义创建此处来自 dicebear/styles 包 import definition from dicebear/styles/lorelei.json with { type: json }; const avatar new Avatar(new Style(definition), { seed: John, size: 128, }); avatar.toString(); // SVG 字符串 avatar.toDataUri(); // data:image/svgxml;charsetutf-8,...注意几个容易踩坑的细节Avatar必须接收Style实例而非裸的 definition 对象。构造函数会做 instanceof 检查传入原始对象会抛出TypeError。这一行为在 Avatar.ts 中实现并由 Avatar.test.js 的用例「should reject a raw style definition」覆盖验证。JSON 导入语法示例使用with { type: json }这是 ESM 的 JSON 模块导入方式需要 Node.js 22 支持。解析发生在构造时new Avatar(...)一旦创建就立即完成选项解析与 SVG 渲染见 Avatar.ts后续所有输出方法只是对同一份结果的序列化不会重复计算。四、复用 Style 实例与三种输出方法复用 Style一份样式定义可以反复使用Style在构造时完成校验并深拷贝存储定义structuredClone后续每个Avatar直接复用无需重新校验。import { Style, Avatar } from dicebear/core; const style new Style(definition); // 同一 Style 创建多个头像 const avatar1 new Avatar(style, { seed: Alice }); const avatar2 new Avatar(style, { seed: Bob });从源码看Style.tsStyle会在构造时执行两类 JSON Schema 无法覆盖的补充校验组件别名校验#validateAliases检查每个通过extends声明的组件别名都指向真实存在且非别名的组件禁止别名链alias chains违例抛出StyleValidationError动画关键帧校验#validateAnimations遍历所有元素确保每条动画轨道的关键帧at值严格递增阶梯跳变应使用hold缓动表达而不是重复位置。其余视图meta()、canvas()、components()、colors()等均采用惰性分解lazy decomposition首次访问才构建并缓存避免为每个头像重复解析整个定义。三种输出方法方法返回说明toString()string原始 SVG 标记toDataUri()stringdata:image/svgxml;charsetutf-8, URL 编码后的 SVG可直接放入img srctoJSON(){ svg, options }JSON 可序列化对象包含 SVG 与完全解析后的选项快照toJSON()有两个值得注意的设计Avatar.ts返回的options是通过structuredClone克隆的深拷贝调用方随意修改不会污染内部缓存测试用例「should return a deep copy of options」验证快照中刻意不包含原始 seedResolver.ts 明确注释 seed 是唯一不进快照的输入避免序列化头像时泄露用户标识需要复现同一头像时应保留原始 seed 与用户选项。五、选项详解类型、取值范围与默认值选项通过 StyleOptions.ts 的类型系统定义当传入的样式定义携带字面量键时TypeScript 能推导出精确的组件/颜色名提供完整自动补全当定义为泛型时则退化为索引签名。Options类Options.ts负责校验并规范化用户输入。全局基础选项选项类型默认值说明seedstring确定性种子唯一决定头像内容sizenumber画布原始尺寸输出 SVG 的width/height范围 1–4096idRandomizationbooleanfalse为渲染附加随机后缀避免同一页内多个相同头像的id冲突titlestring无设置title与aria-label提升可访问性flipnone \| horizontal \| vertical \| both可数组none水平/垂直翻转fontFamilystring可数组system-ui文本元素的字体fontWeightnumber可数组1–1000400字重scalenumber或[min, max]1围绕画布中心缩放0–10borderRadiusnumber或[min, max]0圆角百分比0–50按画布宽高折算为rx/ryrotatenumber或[min, max]0围绕画布中心旋转-360–360translateX/translateYnumber或[min, max]0平移按画布尺寸的百分比计算-1000–1000tagsstring或数组无过滤变体标签过滤详见下文animationbooleanfalse动画总开关不参与 PRNGanimationSpeednumber或[min, max]1全局动画速度倍率0.1–10animationDelaynumber或[min, max]0全局动画起始偏移秒-3600–3600上述取值范围与字段描述来自 OptionsDescriptor.ts该描述器同样供编辑器类工具动态生成表单控件。按组件动态键${name}Variant与${name}Probability样式中的每个组件都有一对动态选项${name}Variant指定变体约束。接受单个变体名、变体名数组或变体名 → 权重对象加权随机选择。未设置时遵循全局tags过滤两者都未设置时从该组件全部变体中选取。${name}Probability组件出现概率0–100。该值影响#isVisible的 PRNG 判断Resolver.ts。注意若某组件是通过extends声明的别名则它不暴露自己的选项键其行为完全继承源组件StyleOptions.ts中IsAlias类型会把这些键过滤掉。按颜色动态键${name}Color系列每个颜色含恒有的background都有五个动态选项${name}Color候选颜色列表十六进制可数组。未设置时返回undefined使解析器回落到样式定义中的颜色值Options.ts 注释明确说明这一不对称设计。${name}ColorFill填充方式solid | linear | radial默认solid多颜色 非 solid 时渲染器会生成linearGradient/radialGradient并注册进defsRenderer.ts。${name}ColorFillStops渐变阶数范围 ≥2。${name}ColorAngle渐变旋转角-360–360。${name}ColorOrderrandom | fixed控制候选颜色是经 PRNG 洗牌还是保持给定顺序fixed时跳过洗牌与对比度排序Resolver.ts。范围Range选项的归一化语义所有接受number | [number, number]的选项都会在Options层被归一化为内部{ min, max }结构Options.ts裸数字n或单元素数组[n]→{ min: n, max: n }固定值双元素数组取其中较小/较大者为 min/max容忍逆序空数组视为未设置让解析器应用默认值而不是得到NaN。归一化后PRNG 会在该区间内做确定性抽取float/integer见下文。tags标签过滤语法tags是控制变体筛选的高级语法可传入字符串或数组每项支持三种形式category:value正向允许同类别内多个值按 OR 组合不同类别按 AND 组合裸category要求该类别存在标签!category/!category:value排除总是优先生效。Options会把原始 token 解析为{ category, value?, negated }结构Options.tsResolver再按允许/要求/排除三组规则对每个组件的变体做单遍过滤Resolver.ts。当用户给某组件设置了显式${name}Variant时该组件的tags过滤被完全忽略${name}Variant优先级更高。六、确定性原理PRNG 与渲染管线键控 PRNGFNV-1a Mulberry32确定性输出由 Prng.ts 提供核心思路是键控key-based伪随机每个取值操作都带一个 key如flip、eyesVariant、backgroundColor对seed:key做 FNV-1a 哈希Fnv1a.ts再用结果播种 Mulberry32Mulberry32.ts并取nextFloat()因此同 seed 同 key 永远得到同值且与调用顺序无关Prng.ts。Prng提供pick等概率选取先按码点排序去重、weightedPick按权重选取、bool按概率 0–100 返回布尔、float/integer区间内取值与shuffleFisher-Yates带链式 Mulberry32 状态等原语。排序比较统一按字符串的 UTF-16 码元进行以保证各语言端口行为一致。解析管线ResolverResolver.ts 把三个输入——Style、校验后的Options、由 seed 播种的Prng——捆绑在一起为每个选项暴露确定性取值访问器。每个访问器都会**记忆化memoize**其结果#memo保证多次调用不漂移这些记忆条目同时构成resolved()的信息快照seed 除外。变体选取variant、颜色解析#resolveColor含对比度排序、notEqualTo排除、循环引用检测CircularColorReferenceError都发生在此层。渲染管线RendererRenderer.ts 将元素树转换为最终 SVG其包装顺序是确定的Renderer.ts渲染背景rect若配置了background颜色渲染画布元素树依次施加scale→flip→rotate→translate变换顺序与注释明确先缩放与翻转、再旋转、最后平移用clipPath按borderRadius计算rx/ry裁剪防止变换内容溢出画布。此外有若干工程细节值得注意组件去重组件变体以defs条目 use href方式输出相同组件被引用多次时只产生一份定义Renderer.ts稳定 ID 哈希defs条目 id 由「样式源名称 seed」的 FNV-1a 哈希派生#hashSeed避免同页内不同样式、同 seed 的头像互相抢用defsRenderer.tsidRandomization启用后为所有id声明与引用附加 6 位随机十六进制后缀解决同 seed 头像在共享文档中的 id 冲突该随机值有意使用Math.random()因为 PRNG 派生值会对同 seed 重复Renderer.ts声明式动画样式定义中可声明动画轨道translateX/Y、rotate、scaleX/Y、opacity固定外层→内层顺序渲染器生成去重后的keyframes与类规则并整体包裹在media (prefers-reduced-motion: no-preference)中尊重用户的减少动态偏好Renderer.ts。七、lite 入口跳过校验的轻量包包的约一半体积来自两个 Schema 校验器样式校验与选项校验。dicebear/core/lite暴露完全相同的 API只是不做校验gzip 后约14 kB而主入口约30 kB。import { Style, Avatar } from dicebear/core/lite;README 对此有明确的安全警告校验正是把脚本、事件处理器、外部引用等不安全内容挡在 SVG 之外、并把错误选项变成报错而非异常输出的机制lite 入口渲染什么就给什么。因此仅当样式定义与选项来自你自己编写或生成的代码时才使用 lite绝不用于来自上传、URL 或其他不受你控制的来源。实现层面lite.ts直接导出未包一层校验的Style/Avatar基类。测试 Lite.test.js 验证了lite 与主入口对同一合法输入产出完全一致的 SVG含未知键的定义/越界选项在主入口抛错、在 lite 中照常通过并且 lite 入口的静态导入图中不包含任何校验器否则会进入所有基于它的打包产物。# 打包体积对照gzip dicebear/core ~30 kB # 带完整校验安全 dicebear/core/lite ~14 kB # 无校验仅限可信输入八、校验器与安全边界主入口的校验器由 Validator/README.md 说明目录中的.js文件由scripts/compile-schema.mjs从dicebear/schema自动生成使用exodus/schemasafe的toModule()输出对应.d.ts手工维护。如需重新生成在包根目录运行npm run prebuild两个校验器index.ts在构造时介入StyleValidator对样式定义做严格 schema 校验元素名与属性名采用严格白名单 schema从根上排除script、事件处理器等不安全内容Renderer.ts 的注释印证了这一点OptionsValidator对用户传入的选项做 schema 校验把错误选项变成明确的OptionsValidationError。安全策略总结默认路径主入口保证非白名单即拒绝需要性能与体积时必须自行承担输入可信度责任。九、常见问题与实战要点头像不唯一检查是否复用了同一 seed相同 seed 相同样式 相同选项必然产生相同 SVG这是特性而非缺陷为不同用户换用不同 seed 即可。要自定义样式仓库提供了完整的样式定义 schema、编辑指南与从零创建指南定义以 JSON 形式传给new Style(definition)即可。服务端使用Node.js 22 环境可直接运行结合 converter 可进一步把 SVG 转为 PNG/JPEG。与其他语言实现对齐JS 端口与 Go、Rust、Python 等共享同一 PRNG 与渲染管线跨语言产出一致由 Parity.test.js 与 parity fixtures 保障多端如前后端异构部署时无需担心头像不一致。可访问性传入title时渲染器会输出title与aria-label并设置roleimg未传时设置aria-hiddentrueRenderer.ts默认对装饰性头像友好。在浏览器中交互式体验各样式效果可参考文档站的 Playground 页面官方 JavaScript 集成文档 则覆盖了 React、Vue、Angular 等框架的接入方式。dicebear/core本身则始终是这些集成背后的渲染引擎——理解它的确定性模型、选项归一化规则与校验边界就掌握了整个生态的行为基础。赞分享UI组件后端【免费下载链接】dicebearDiceBear is an avatar library for designers and developers. 项目地址https://gitcode.com/gh_mirrors/di/dicebear点击查看免费下载相关推荐DiceBear CoreC开发指南用 .NET 生成确定性 SVG 头像DiceBear CoreC 开发指南用 .NET 生成确定性 SVG 头像 本篇技术指南围绕当前仓库中 src/csharp/core/README.mUI组件后端DiceBear CoreRust使用 Rust 生成确定性 SVG 头像的完整指南DiceBear CoreRust使用 Rust 生成确定性 SVG 头像的完整指南 DiceBear Core 的 Rust 实现将「样式定义stylUI组件后端DiceBear 头像生成原理从 seed 到 SVG 的确定性渲染流水线DiceBear 头像生成原理从 seed 到 SVG 的确定性渲染流水线 导读 本指南深入剖析 DiceBear 的核心渲染机制——一个头像如何在请求时由UI组件后端上一篇History.js状态恢复终极指南页面刷新后数据保持的完整解决方案下一篇ant-design-vue-pro与GraphQL现代API在企业应用中的实践指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考