Definition schema reference

每个 DiceBear 头像样式都是一个遵循 DiceBear Definition Schema 的 JSON 文件。此页面记录了样式定义的完整结构。

概览

一个样式定义描述了生成头像所需的一切：canvas 尺寸、要渲染的 SVG 元素、可随机化的组件，以及可用的颜色调色板。该定义完全是声明式的：没有代码，没有函数。渲染逻辑位于 DiceBear Core 的实现中。

顶层结构

json

{
  "$schema": "https://...",
  "$id": "https://...",
  "$comment": "可选注释",
  "meta": { ... },
  "canvas": { ... },
  "components": { ... },
  "colors": { ... },
  "attributes": { ... }
}

Property	Required	Description
`$schema`	No	用于编辑器验证的定义 schema URL
`$id`	No	此定义的规范标识符（通常为其托管地址的 URL，最多 256 个字符）
`$comment`	No	自由文本注释，例如 "Generated by Figma"（最多 4096 个字符）
`meta`	No	许可证、创建者和来源元数据
`canvas`	Yes	Canvas 尺寸和根元素树
`components`	No	命名的、可随机化的 SVG 组件（最多 512 项）
`colors`	No	用于动态着色的命名颜色调色板（最多 512 项）
`attributes`	No	根 `<svg>` 元素的全局 SVG 属性

`meta`

关于样式的元数据，用于许可证注释、CLI 横幅和文档。

json

{
  "meta": {
    "license": {
      "name": "CC0 1.0",
      "url": "https://creativecommons.org/publicdomain/zero/1.0/",
      "text": "完整许可证文本..."
    },
    "creator": {
      "name": "DiceBear",
      "url": "https://www.dicebear.com"
    },
    "source": {
      "name": "Initials",
      "url": "https://github.com/dicebear/dicebear"
    }
  }
}

`canvas`

定义 SVG 视口和根元素树。width 和 height 决定生成的 SVG 的 viewBox。

json

{
  "canvas": {
    "width": 100,
    "height": 100,
    "elements": [
      { "type": "component", "name": "background" },
      { "type": "component", "name": "face" }
    ]
  }
}

Property	Type	Required	Description
`width`	number	Yes	Canvas 宽度（像素，>= 1）
`height`	number	Yes	Canvas 高度（像素，>= 1）
`elements`	array	Yes	根元素树（最多 1024 个顶层条目）

元素

Elements 是 SVG 的构建块。支持三种类型：

`element`: SVG 标签

渲染一个 SVG 元素，例如 <circle>、<path>、<g> 等。

json

{
  "type": "element",
  "name": "circle",
  "attributes": {
    "cx": "50",
    "cy": "50",
    "r": "40",
    "fill": { "type": "color", "name": "skin" }
  },
  "children": []
}

只允许白名单中的 SVG 元素（例如 circle、path、g、rect、text、defs、filter、 linearGradient、radialGradient 等）。像 script、 foreignObject 和 a 这样的元素会因安全原因被阻止。

一个节点最多可以有 1024 个子节点。name: "defs" 的元素具有特殊语义（见下文的可重用 <defs> 条目）。

`text`: 文本内容

在 SVG 元素内渲染原始文本。支持变量引用。

json

{
  "type": "text",
  "value": "Hello"
}

或者使用变量：

json

{
  "type": "text",
  "value": { "type": "variable", "name": "initials" }
}

在文本 value 中只接受 initial 和 initials。其他变量（fontFamily、fontWeight）只在其专用属性中有效（见变量引用）。

`component`: 组件引用

引用在 components 部分定义的命名组件。DiceBear Core 会根据种子和选项选择一个变体。

json

{
  "type": "component",
  "name": "eyes"
}

组件引用可以携带自己的 attributes 映射。它们会原样写入生成的 <use> 元素，这就是你将组件实例放置到画布上的方式：

json

{
  "type": "component",
  "name": "eyes",
  "attributes": {
    "transform": "translate(10 20)"
  }
}

用户提供的 transform 会被追加在渲染器为每个组件选择的 rotate/translate/scale 之前，因此它充当外层（放置）变换。

`<style>` 元素

支持 <style>，但它是一个特殊情况。其 CSS 内容必须通过一个或多个 text 子节点提供，而不是作为单个字符串，也不能通过包含通用元素的 children 提供：

json

{
  "type": "element",
  "name": "style",
  "children": [
    {
      "type": "text",
      "value": ".dark { fill: #000; }"
    }
  ]
}

一个 <style> 元素最多可以包含 64 个文本子节点。CSS 内容的清理比普通属性值更严格：

已知危险的 @ 规则（@import、@font-face、@document、@charset）会被拒绝。其他 @ 规则（@media、@keyframes、@supports、@layer、 …）是允许的，但其内容仍会通过下面描述的通用过滤器。

以下内容会在每个 CSS 内容和每个属性值中被拒绝（共享的 filteredString 注入过滤器）：

外部 url(...) 引用（本地 url(#id) 没问题）
expression(...)、behavior:、-moz-binding
javascript: 和 vbscript: URI scheme
反斜杠转义序列

这是一个纵深防御过滤器，不是 CSS 验证器：子字符串匹配会拒绝那些恰好包含被阻止标记的、原本无害的字符串（例如在纯文本中出现的字面量单词 javascript:）。

可重用的 `<defs>` 条目

<defs> 被列入白名单，作为普通元素可以使用，但渲染器会特殊处理它：树中任何名为 defs 的元素的每个子元素，都会被提升到整个文档范围的 <defs> 块中，与生成的渐变、裁剪路径和组件主体一起。这样既能让渲染后的 SVG 只保留一个 <defs> 元素，又允许样式作者提供可重用片段（过滤器、渐变、蒙版等）并在树中的其他位置引用它们。

`components`

头像中可命名、可随机化的部分。每个组件定义了一组 PRNG 可以选择的变体。

json

{
  "components": {
    "eyes": {
      "width": 80,
      "height": 40,
      "probability": 100,
      "rotate": { "min": -10, "max": 10 },
      "scale": { "min": 0.9, "max": 1.1 },
      "translate": {
        "x": { "min": 0, "max": 0 },
        "y": { "min": -5, "max": 5 }
      },
      "variants": {
        "happy": {
          "weight": 1,
          "elements": [...]
        },
        "surprised": {
          "weight": 1,
          "elements": [...]
        }
      }
    }
  }
}

Property	Type	Description
`width`	number	Required. 组件画布宽度（像素，>= 1）
`height`	number	Required. 组件画布高度（像素，>= 1）
`probability`	number	可选。组件出现的概率，0 到 100（默认 `100`）
`rotate`	object	可选。旋转范围，见范围
`scale`	object	可选。围绕组件中心的缩放范围，见范围
`translate`	object	可选。以组件自身 `width` / `height` 的百分比表示的 `{ x?: Range, y?: Range }` 偏移，见范围
`variants`	object	Required. 命名的变体定义（最多 512 个）

translate.x 和 translate.y 以组件自身 width 和 height 的百分比表示。值为 100 表示将组件按其完整宽度或高度平移；0 表示保持原位。上面的示例（y: { min: -5, max: 5 }）因此表示“将组件在垂直方向上最多平移其高度的 5%，且可向任一方向”。

范围

rotate、scale、translate.x 和 translate.y 都使用相同的范围对象：

json

{ "min": -10, "max": 10, "step": 5 }

Property	Type	Description
`min`	number	Required. 范围下限
`max`	number	Required. 范围上限
`step`	number	可选。将范围量化为 `min + i × step` 的正值

对于固定值，将 min === max。使用 step 时，PRNG 会从 { min + i × step | 0 ≤ i ≤ ⌊(max − min) / step⌋ } 中采样，因此当 (max − min) 不是 step 的整数倍时，max 本身不可达。没有 step 时，范围是连续的。

数值域因字段而异：rotate 和内部 step 值以度为单位（-360 到 360，step ≤ 720），scale 为 0 到 10（step ≤ 10），而 translate.x / translate.y 为 -1000 到 1000 的百分比（step ≤ 2000）。

组件别名

可以使用 extends 将一个组件设置为另一个组件的别名。别名没有自己的尺寸或变体：它继承被引用组件的一切，但会作为一个独立的、单独随机化的实例进行渲染。这在你希望同一个视觉组件出现两次时很有用（例如左右耳环），并且希望每次出现都选择自己的变体。

json

{
  "components": {
    "earring": {
      "width": 20,
      "height": 20,
      "variants": {
        "stud": { "elements": [...] },
        "hoop": { "elements": [...] }
      }
    },
    "earringLeft":  { "extends": "earring" },
    "earringRight": { "extends": "earring" }
  }
}

别名是严格引用：extends 是它唯一允许的属性。它必须指向同一个 components 映射中定义的基础组件（不能是另一个别名）。宽度、高度、概率、rotate、scale、translate 和 variants 都从源组件继承。别名不会暴露自己的 ${aliasName}Variant 或 ${aliasName}Probability 用户选项。两者都通过 ${sourceName}Variant 和 ${sourceName}Probability 与源组件共享。渲染器仍会对每个别名单独运行 PRNG，因此每次出现都会在共享约束内选择自己的变体。详见实现指南了解详情。

变体

每个变体包含一个元素树和一个可选的权重：

Property	Type	Default	Description
`elements`	array	—	Required. 此变体的 SVG 元素树（最多 1024 个）
`weight`	number	`1`	PRNG 的选择权重（0 到 1,000,000）

更高的权重会使某个变体更有可能被选中。权重为 0 会完全排除该变体，除非每个变体的权重都为 0，在这种情况下 PRNG 会退回到在所有变体中进行不加权选择。

`colors`

命名颜色调色板。PRNG 会根据种子从调色板中选择一种颜色。

json

{
  "colors": {
    "skin": {
      "values": ["#f5d6c3", "#d4a889", "#a67c5b", "#614335"]
    },
    "text": {
      "values": ["#ffffff", "#000000"],
      "contrastTo": "skin"
    },
    "hair": {
      "values": ["#2c1b18", "#b58143", "#d6b370", "#724133"],
      "notEqualTo": ["skin"]
    }
  }
}

属性	类型	描述
`values`	string[]	必需。形如 `#RGB`、`#RGBA`、`#RRGGBB` 或 `#RRGGBBAA` 的十六进制颜色（1 到 128 项）
`contrastTo`	string	可选。选择与该组所选颜色对比度最高的颜色
`notEqualTo`	string[]	可选。过滤掉这些组已经选中的颜色（最多 64 个引用）

一个定义最多可以声明 512 个颜色组。

颜色约束

contrastTo 会绕过随机选择。相反，候选颜色会根据相对于引用颜色的 WCAG 2.1 对比度进行排序，并选取对比度最高的颜色。这对于确保文本可读性很有用。

notEqualTo 会过滤掉在所引用颜色组中已经被选中的颜色。这可以防止相邻部分使用相同的颜色。比较基于 RGB 十六进制值（去除 alpha）；如果过滤后候选列表为空，渲染器会回退到未过滤的列表。

该 schema 不会检测循环（a ⇄ b 约束）。渲染器会按照定义顺序解析调色板，并在渲染时检测到循环后抛出错误。

属性中的颜色引用

颜色属性（fill、stroke、stop-color、color、 flood-color、lighting-color）既可以接受字面量 CSS 颜色字符串（命名颜色、十六进制、rgb()、oklch()、color-mix()、本地 paint server 引用，如 url(#id) 等），也可以接受命名调色板的引用：

json

{
  "fill": { "type": "color", "name": "skin" }
}

调色板引用会在渲染时解析为 PRNG 为 skin 组选中的颜色。字面量字符串不会按 CSS 语法进行验证（语法无效是浏览器的问题），但共享注入过滤器仍然适用（不允许 javascript:，不允许外部 url(...)，等等）。

变量引用

少数属性支持用 { "type": "variable", "name": "…" } 对象替代字面量字符串。每个变量只在特定位置有效。schema 会拒绝不匹配的放置方式。

变量	允许使用于	解析为
`initial`	`text` 元素的 `value`	基于种子生成的首字母
`initials`	`text` 元素的 `value`	基于种子生成的完整首字母缩写（1 到 2 个字符）
`fontFamily`	`font-family` 属性	解析后的 `fontFamily` 用户选项（默认值为 `system-ui`）
`fontWeight`	`font-weight` 属性	解析后的 `fontWeight` 用户选项（默认值为 `400`）

json

{
  "type": "text",
  "value": { "type": "variable", "name": "initials" }
}

json

{
  "attributes": {
    "font-family": { "type": "variable", "name": "fontFamily" },
    "font-weight": { "type": "variable", "name": "fontWeight" }
  }
}

`attributes`

应用于根 <svg> 元素的全局 SVG 表现属性。

json

{
  "attributes": {
    "fill": "none",
    "shape-rendering": "auto"
  }
}

只允许安全的 SVG 表现属性；事件处理器（onclick，等等）和带命名空间的属性（xlink:href，等等）会被拒绝。完整白名单请参见 schema 源码。

有两个属性有特别的额外规则：

href 仅接受本地片段引用（#id）和编码为 data:image/{png|gif|jpeg|webp|avif};base64,… 的嵌入式栅格图像。远程 URL （http(s)://…）以及 <script>/xlink:href 模式都会被拒绝。
style 会作为 CSS 字符串进行净化：适用更严格的 <style> 元素规则集（参见 The <style> element）。

示例：最小样式定义

一个完整但最小的定义，渲染一个有颜色的圆形：

json

{
  "$schema": "https://cdn.hopjs.net/npm/@dicebear/schema@1.0.0/dist/definition.min.json",
  "canvas": {
    "width": 100,
    "height": 100,
    "elements": [
      {
        "type": "element",
        "name": "circle",
        "attributes": {
          "cx": "50",
          "cy": "50",
          "r": "45",
          "fill": { "type": "color", "name": "background" }
        }
      },
      {
        "type": "component",
        "name": "face"
      }
    ]
  },
  "components": {
    "face": {
      "width": 100,
      "height": 100,
      "variants": {
        "smile": {
          "elements": [
            {
              "type": "element",
              "name": "path",
              "attributes": {
                "d": "M 30 60 Q 50 80 70 60",
                "stroke": "#000000",
                "stroke-width": "3",
                "fill": "none"
              }
            }
          ]
        },
        "neutral": {
          "elements": [
            {
              "type": "element",
              "name": "line",
              "attributes": {
                "x1": "35",
                "y1": "65",
                "x2": "65",
                "y2": "65",
                "stroke": "#000000",
                "stroke-width": "3"
              }
            }
          ]
        }
      }
    }
  },
  "colors": {
    "background": {
      "values": ["#f9c74f", "#90be6d", "#43aa8b", "#577590", "#f94144"]
    }
  }
}

Schema 包

这些 schema 位于 @dicebear/schema 中，并提供两个文件（均为 JSON Schema draft-07）：

definition.json：验证样式定义
options.json：验证传递给 Avatar 的用户选项

可通过你的包管理器安装：

生态系统	安装
npm	`npm install @dicebear/schema`
Composer	`composer require dicebear/schema`
PyPI	`pip install dicebear-schema`
Cargo	`cargo add dicebear-schema`
Go	`go get github.com/dicebear/schema`

或者直接从 CDN 引用 schema，这对样式定义的 $schema 字段很方便，这样像 VS Code 这样的编辑器就能提供自动补全和内联验证：

https://cdn.hopjs.net/npm/@dicebear/schema@1.0.0/dist/definition.min.json
https://cdn.hopjs.net/npm/@dicebear/schema@1.0.0/dist/options.min.json

DiceBear 随附的第三方样式定义位于单独的包中： npm 上的 @dicebear/styles 和 Packagist 上的 dicebear/styles。

CDN sponsored by

Definition schema reference ​

概览 ​

顶层结构 ​

meta ​

canvas ​

元素 ​

element: SVG 标签 ​

text: 文本内容 ​

component: 组件引用 ​

<style> 元素 ​

可重用的 <defs> 条目 ​

components ​

范围 ​

组件别名 ​

变体 ​

colors ​

颜色约束 ​

属性中的颜色引用 ​

变量引用 ​

attributes ​

示例：最小样式定义 ​

Schema 包 ​

Definition schema reference

概览

顶层结构

`meta`

`canvas`

元素

`element`: SVG 标签

`text`: 文本内容

`component`: 组件引用

`<style>` 元素

可重用的 `<defs>` 条目

`components`

范围

组件别名

变体

`colors`

颜色约束

属性中的颜色引用

变量引用

`attributes`

示例：最小样式定义

Schema 包