跳到正文

PersonAvatar 人物像素头像

要用人在 Raft 头像编辑器里捏出来的像素头像来表示这个人、并且和在 Raft 里看起来一样时,用 PersonAvatar。agent 的头像请用 PixelAvatar;上传的图片或名字缩写,请用 Avatar。

使用前须知

从它单独的入口引入;@pika-lab/react 里没有导出它:

tsx
import { PersonAvatar } from "@pika-lab/react/person-avatar";

PersonAvatar 画出人的像素头像,也就是 Raft 头像编辑器捏出来的那一张:由 recipe 里的七项选择(背景、肤色、发型、发色、表情、头饰、眼镜)组合出的 112×112 画像。同一个 recipe 在这里和在 Raft 里画出来完全一样。

它和 PixelAvatar 用同一套外框:size、round、bordered、alt,也能放进 AvatarGroup 叠放。画像数据约 230 KB(gzip 后不到 6 KB),所以有单独的入口,不显示人物头像的应用不会加载它。

演示

基础用法

recipe 里没给的字段用 Raft 的默认值:黄色背景、鸭舌帽、黑色短发、眨眼。

编辑器

personAvatarOptions 按编辑器的顺序列出每个字段的选项,randomPersonAvatarRecipe 和 Raft 一样随机搭配。toRaftPersonAvatar 给出 Raft 存储的值。

Raft 头像

readRaftPersonAvatar 按 Raft 的方式读取人的 avatarUrl(pixel-human:v1:…):不认识的字段画默认值;不是人物头像时返回 null,交给 PixelAvatar 画。

Props

名称类型默认值说明版本
recipePartial<PersonAvatarRecipe>{}外观。缺少或不认识的字段画 Raft 的默认值。未发布
sizesmall | medium | large | numbermedium控件高度档位,或以 px 为单位的边长。未发布
roundbooleanfalse画成圆形,而不是主题默认形状。未发布
borderedbooleantrue主题外框。未发布
altstringundefined无障碍名称。不传时头像是装饰性的(aria-hidden)。未发布

其余 props 传给根节点 <span>。size、round、bordered 可以通过 ConfigProvider 的 componentOptions.PersonAvatar 统一设置。

工具函数

名称说明
personAvatarOptions每个字段的选项 id,按编辑器顺序。
defaultPersonAvatarRecipeRaft 的默认外观。
randomPersonAvatarRecipe(random?)随机外观:一半戴头饰,约三分之一戴眼镜。
readRaftPersonAvatar(value)Raft pixel-human: 值里的 recipe,不是则为 null。
toRaftPersonAvatar(recipe)recipe 在 Raft 里的存储值。

画像数据用 pnpm --filter @pika-lab/scripts sync:raft-avatars <Raft 仓库目录> 从 Raft 同步,personAvatarArtVersion 是它的版本。