API 参考

这里是 avatar 的完整契约：你可以绑定、监听、投影和设置主题的一切，都集中在一处。接入你需要的部分，自定义你想要的样式——它是 standalone 的，且对 signal 友好。

输入

通过 19 个输入项精细调校 avatar。像绑定任意 Angular @Input 一样绑定它们。

名称	类型	默认值	描述
`size`	`string \| number`	`50`	头像尺寸（像素）
`name`	`string`	—	当图片来源失败时用于生成首字母缩写的用户名
`src`	`string \| SafeUrl`	—	头像的主要自定义图片来源 URL
`alt`	`string`	—	头像图片的替代文本，用于无障碍访问
`round`	`boolean`	`true`	头像是否为圆形（true），或遵循 cornerRadius
`bgColor`	`string`	—	文字头像的背景颜色。若未提供则自动生成
`fgColor`	`string`	`#FFF`	文本 avatar 中首字母的文本颜色
`borderColor`	`string`	—	头像周围的边框颜色
`cornerRadius`	`string \| number`	`0`	当 round 为 false 时的圆角半径
`textSizeRatio`	`number`	`3`	根据头像尺寸计算文字大小的比例（size / textSizeRatio）
`initialsSize`	`string \| number`	`0`	限制显示的首字母数量（0 = 不限制）
`facebookId`	`string`	—	用于获取头像的 Facebook 用户 ID（尽力而为，可能受 API 限制）
`githubId`	`string`	—	用于获取头像的 GitHub 用户名
`gravatarId`	`string`	—	用于获取头像的 Gravatar 邮箱或 MD5 哈希值
`value`	`string`	—	将自定义值显示为头像（例如 "75%"、"+5"）
`style`	`Partial<CSSStyleDeclaration>`	—	应用于头像根元素的自定义样式
`referrerpolicy`	`string`	—	头像图片的 referrer 策略（例如 "no-referrer"）
`badge`	`string \| number \| boolean \| null`	—	角标叠加：`badge` / `[badge]="true"` → 圆点；`badge="4k"` → 文字徽标；null / 缺省 → 无。
`badgeColor`	`HubAvatarBadgeColor \| string \| null`	—	徽标的语义颜色（primary · secondary · success · danger · warning · info · light · dark）→ `--hub-sys-color-*`。

输出

响应 avatar 的行为——有 1 个事件可供你挂接逻辑。

名称	类型	描述
`clickOnAvatar`	`Source`	当头像被点击时触发，返回当前活动的来源对象

模板

尚未记录任何模板。

CSS 变量

用 11 个 CSS 变量为每一个像素设置主题。在 :root 处覆盖它们，或将其限定到某个容器范围内。

尺寸与布局

控制 avatar 的尺寸和间距

变量	默认值	类型	描述
`--hub-avatar-size`	`50px`	length	未指定尺寸时的默认 avatar 大小 `24px40px64px96px`
`--hub-avatar-border-radius`	`50%`	length	avatar 容器的边框半径 `04px8px50%`

颜色与外观

自定义 avatar 的颜色和视觉外观

变量	默认值	类型	描述
`--hub-avatar-bg-color`	`var(--hub-sys-color-primary)`	color	文本 avatar 的背景颜色 `#007bff#28a745#dc3545#6f42c1`
`--hub-avatar-text-color`	`#ffffff`	color	文本 avatar 中首字母的文本颜色 `#000000#ffffff#6c757d`
`--hub-avatar-border-color`	`transparent`	color	avatar 周围的边框颜色 `#dee2e6#007bff#28a745`
`--hub-avatar-border-width`	`0`	length	avatar 周围的边框宽度 `1px2px3px`

排版

控制 avatar 首字母的文本外观

变量	默认值	类型	描述
`--hub-avatar-font-family`	`Helvetica, Arial, sans-serif`	string	avatar 首字母的字体族 `Inter, sans-serifRoboto, sans-serifsystem-ui`
`--hub-avatar-font-weight`	`normal`	string	avatar 首字母的字重 `400500600bold`
`--hub-avatar-text-transform`	`uppercase`	string	首字母的文本转换 `noneuppercaselowercasecapitalize`

自定义内容

投影到头像中的内容的尺寸。背景与前景来自头像自身的令牌。

变量	默认值	类型	描述
`--hub-avatar-content-padding`	`calc(var(--hub-avatar-size) * 0.2)`	length	投影内容与头像边缘之间的内边距。 `8px15%calc(var(--hub-avatar-size) * 0.25)`
`--hub-avatar-content-icon-size`	`calc(var(--hub-avatar-size) * 0.55)`	length	投影的字体图标 / 表情符号的字号（由字形继承）。 `1.5remcalc(var(--hub-avatar-size) * 0.6)`

样式与主题

尚未记录任何样式示例。本节将包含自定义方案和主题示例。