<!-- Source: https://dicebear.zhcndoc.com/how-to-use/go-library/ -->
<!-- Documentation for DiceBear 10.6.1. The complete docs as one file: https://dicebear.zhcndoc.com/llms-full.txt -->

# Go 头像库

Go 库提供与
[JavaScript 库](https://dicebear.zhcndoc.com/how-to-use/js-library/) 完全一致的 API。它需要 Go 1.23 或更高版本。
相同的种子和样式定义会生成与 JavaScript
参考实现字节完全一致的 SVG。

## 安装

您需要两个模块：核心库 `github.com/dicebear/dicebear-go/v10` 和头像样式定义 `github.com/dicebear/styles/v10`。模块路径包含主版本号，因此请使用带有 `/v10` 后缀的路径导入它们。

```sh
go get github.com/dicebear/dicebear-go/v10
go get github.com/dicebear/styles/v10
```

## 用法

我们在示例中使用头像样式 [lorelei](https://dicebear.zhcndoc.com/styles/lorelei/)。你可以在
[这里](https://dicebear.zhcndoc.com/styles/)找到更多头像样式。每种样式都会以原始 JSON 字符串形式导出
（例如 `styles.Lorelei`），然后传递给 `NewStyle`。

```go
package main

import (
	"fmt"

	dicebear "github.com/dicebear/dicebear-go/v10"
	"github.com/dicebear/styles/v10"
)

func main() {
	style, err := dicebear.NewStyle([]byte(styles.Lorelei))
	if err != nil {
		panic(err)
	}

	avatar, err := dicebear.NewAvatar(style, map[string]any{
		"seed": "John",
		// ... 其他选项
	})
	if err != nil {
		panic(err)
	}

	svg := avatar.SVG()
	fmt.Println(svg)
}
```

每种头像样式都带有若干选项。你可以在每个[头像样式](https://dicebear.zhcndoc.com/styles/)的详情页中找到它们。

> [!NOTE]
> 我们提供了大量来自不同创作者的头像样式。这些头像样式遵循不同的许可证，
> 创作者可以自行选择许可证。为了便于快速了解，我们为你准备了
> [许可证概览](https://dicebear.zhcndoc.com/licenses/)。

## 确定性头像

`seed` 选项是生成确定性头像的关键。相同的 seed
总是会生成相同的头像：

```go
avatar1, _ := dicebear.NewAvatar(style, map[string]any{"seed": "user-123"})
avatar2, _ := dicebear.NewAvatar(style, map[string]any{"seed": "user-123"})

// avatar1.SVG() == avatar2.SVG()
```

## 类型

### `Style`

一个经过验证、不可变的样式定义包装器。先使用
`NewStyle`（基于定义的 JSON 字节）构建一次，然后在生成多个头像时复用它。

```go
style, err := dicebear.NewStyle(definitionJSON)
if err != nil {
	panic(err)
}

avatar1, _ := dicebear.NewAvatar(style, map[string]any{"seed": "Alice"})
avatar2, _ := dicebear.NewAvatar(style, map[string]any{"seed": "Bob"})
```

### `Avatar`

生成头像的主要类型。`NewAvatar` 接收一个 `*Style` 和一个
`map[string]any` 形式的选项，并返回 `(*Avatar, error)`（无效选项和
循环颜色引用会以 `error` 形式返回）。`nil` 选项映射会被视为空映射。

```go
avatar, err := dicebear.NewAvatar(style, map[string]any{
	// ... 选项
})
```

### `OptionsDescriptor`

描述给定样式的所有有效选项。适用于构建界面或
验证用户输入。

```go
descriptor := dicebear.NewOptionsDescriptor(style).ToJSON()
```

## 方法

### `SVG()` / `String()`

**返回类型：** `string`

以 XML 格式返回 SVG 头像。`Avatar` 还实现了 `fmt.Stringer`，因此可以直接用于字符串上下文（`fmt.Println`、`fmt.Sprintf`）。

```go
avatar, _ := dicebear.NewAvatar(style, map[string]any{"seed": "Alice"})

svg := avatar.SVG()
// 或
svg = avatar.String()
```

### `JSON()`

**返回类型：** `[]byte`（包含 `svg` 和 `options` 键的 JSON）、`error`

以 JSON 格式返回 SVG 和解析后的选项。

```go
avatar, _ := dicebear.NewAvatar(style, map[string]any{"seed": "Alice"})

result, _ := avatar.JSON()

// result → {"svg":"<svg>...</svg>","options":{"flip":"none",...}}
```

解析后的选项也可以通过 `avatar.ResolvedOptions()` 直接以映射的形式访问。

### `DataURI()`

**返回类型：** `string`

以 [数据 URI](https://en.wikipedia.org/wiki/Data_URI_scheme) 的形式返回头像。

```go
avatar, _ := dicebear.NewAvatar(style, map[string]any{"seed": "Alice"})

dataURI := avatar.DataURI()

// <img src="{dataURI}" alt="头像" />
```

## 核心选项

这些选项适用于每个 DiceBear 核心。完整参考请参阅
[核心选项](https://dicebear.zhcndoc.com/guides/core-options/)。以下是 Go 语法中的选项：

```go
avatar, _ := dicebear.NewAvatar(style, map[string]any{
	"seed":                "Alice",
	"flip":                "horizontal",            // "none", "horizontal", "vertical", "both"
	"rotate":              10,                       // -360 到 360，或 [min, max] 范围
	"scale":               0.9,                      // 0 到 10（1 = 原始大小），或 [min, max] 范围
	"borderRadius":        50,                       // 0-50（50 = 圆形）
	"size":                128,
	"translateX":          0,                        // -1000 到 1000（画布宽度的百分比）
	"translateY":          0,                        // -1000 到 1000（画布高度的百分比）
	"idRandomization":     true,
	"title":               "用户头像",
	"fontFamily":          "Arial",                  // 或 []string{"Arial", "Helvetica"}
	"fontWeight":          700,                      // 1-1000
	"backgroundColor":     []string{"#b6e3f4", "#c0aede"},
	"backgroundColorFill": "solid",                  // "solid", "linear", "radial"
})
```

动态组件和颜色选项的工作方式也相同。有关所有可用模式，请参阅
[动态组件选项](https://dicebear.zhcndoc.com/guides/core-options/#dynamic-component-options)。

## 示例

### 自定义背景的头像

```go
avatar, _ := dicebear.NewAvatar(style, map[string]any{
	"seed":            "Alice",
	"backgroundColor": []string{"#b6e3f4", "#c0aede", "#d1d4f9"},
})
```

### 固定尺寸头像

```go
style, _ := dicebear.NewStyle([]byte(styles.Bottts))

avatar, _ := dicebear.NewAvatar(style, map[string]any{
	"seed":         "robot-42",
	"size":         128,
	"borderRadius": 50, // 圆形头像
})
```

### 带变换的头像

```go
style, _ := dicebear.NewStyle([]byte(styles.Avataaars))

avatar, _ := dicebear.NewAvatar(style, map[string]any{
	"seed":       "Jane",
	"flip":       "horizontal",
	"rotate":     10,
	"scale":      0.9,
	"translateY": 5,
})
```

### 同一页面上的多个头像

在同一页面渲染多个头像时，请使用 `idRandomization` 以
防止 SVG ID 冲突：

```go
style, _ := dicebear.NewStyle([]byte(styles.Lorelei))

for _, seed := range []string{"alice", "bob", "charlie"} {
	avatar, _ := dicebear.NewAvatar(style, map[string]any{
		"seed":            seed,
		"idRandomization": true,
	})
	fmt.Println(avatar.SVG())
}
```

### 加权变体选择

```go
avatar, _ := dicebear.NewAvatar(style, map[string]any{
	"seed":     "Alice",
	"topVariant": map[string]any{"short01": 2, "short02": 2, "long01": 1},
})
```