Angular 头像组件 | ng-hub-ui-avatar
Angular 头像组件，支持首字母、备用图片、在线状态徽标和 CSS 变量，用于可复用的用户身份界面。
最后更新 2026年8月18日
概览
团队为何搜索这个库
当你需要稳健的用户身份界面，并支持备用方案、首字母、多个图片来源以及对设计系统友好的样式钩子时，请选择这个 Angular 头像组件。
安装
npm install ng-hub-ui-avatar跳转到
适用于
- 用户菜单
- 团队列表
- 动态信息流
- 个人资料卡片
关于 avatar
ng-hub-ui-avatar 帮助 Angular 应用在菜单、个人资料卡片和协作界面中一致地展示用户。它覆盖了常见的边界情况，例如图片缺失、首字母生成、状态指示器和共享的尺寸规则。
功能指南
头像来源
可从社交资料、自定义图片、名称首字母或自定义值解析头像，并提供自动回退。
示例:
Facebook 资料
Facebook 资料
Gravatar
Gravatar
GitHub 资料
GitHub 资料
自定义图片来源
自定义图片来源
姓名首字母
姓名首字母
值显示
值显示
回退系统
会优雅地逐一降级遍历每个已配置的来源，直到显示出一个有意义的表示。
示例:
回退系统
回退系统
Showing GitHub source (Facebook ID invalid)
尺寸
可控制头像尺寸、文字与尺寸的比例以及渲染多少个首字母。
示例:
自定义尺寸
自定义尺寸
文字大小比例
文字大小比例
首字母数量限制
首字母数量限制
样式
形状、圆角半径、颜色、边框和任意内联样式——全部由输入和 CSS 变量驱动。
示例:
圆形头像
圆形头像
圆角半径
圆角半径
背景色和前景色
背景色和前景色
--hub-avatar-bg-color ([autoColor]="false")边框颜色
边框颜色
自定义样式
自定义样式
交互性
通过头像点击事件对用户交互做出响应。
示例:
点击事件处理器
点击事件处理器
分组与徽标
将头像堆叠为分组，并在角落叠加徽标——状态圆点或计数——使用语义色板着色。
示例:
头像组显示
头像组显示
徽标（圆点与计数）
徽标（圆点与计数）
自定义内容
可将任意图标、内联 SVG、图片或表情符号投影到头像内。它会居中、留白并按头像形状裁剪，以不依赖类型的方式调整大小（字体图标缩放，SVG/图片填充），并通过常规的 bgColor / fgColor 输入进行主题化。
示例:
自定义内容（图标、SVG）
自定义内容（图标、SVG）
核心特性
最近更改
Version 22.9.1 - 8/8/26, 12:00 AM
fixed: Documentation links now point at the canonical localized URLs. The README linked to https://hubui.dev/<path> with no locale prefix and no trailing slash, and both forms are 301-redirected, so every reader arriving from npm or GitHub landed on a redirect instead of the canonical page.
Version 22.9.0 - 7/28/26, 12:00 AM
changed: Accent resolution now imports the canonical resolveHubAccent from ng-hub-ui-utils. The private copy under src/lib/shared/resolve-hub-accent.ts has been deleted in favour of the single, tested implementation shared family-wide. Behaviour is identical (the copy had not diverged): a bareword resolves to var(--hub-sys-color-<name>, <name>), a literal colour passes through unchanged, an empty value yields null.
added: NEW peer dependency: ng-hub-ui-utils >=22.7.0. Consumers must have ng-hub-ui-utils installed alongside this library (it is where resolveHubAccent lives). Users installing via ng add ng-hub-ui-installer get it automatically; manual installs need npm i ng-hub-ui-utils.
Version 22.8.0 - 7/28/26, 12:00 AM
added: interactive input: exposes role=button, focusability and Enter/Space activation for avatars that bind (clickOnAvatar) — the click target used to be mouse-only.
Version 22.6.0 - 7/7/26, 12:00 AM
added: autoColor input — set [autoColor]="false" on an initials avatar to suppress the inline hash background so it can be themed via the --hub-avatar-bg-color CSS variable (no !important). Defaults to true; an explicit bgColor still wins.
Version 22.5.0 - 6/30/26, 12:00 AM
added: Standalone AvatarComponent — import it directly (no NgModule) and configure with the new provideAvatar() environment provider.
deprecated: AvatarModule / AvatarModule.forRoot() — kept for backward compatibility (now re-exporting the standalone component); use AvatarComponent + provideAvatar() instead.