Avatar Header

基础用法

张三2小时前

使用文本头像

李

李四刚刚

使用图标头像

王五5分钟前

自定义样式

赵

赵六昨天

不同尺寸

小头像1小时前

中等头像2小时前

大头像3小时前

"use client";

import { AvatarHeader } from "@/components/composed/avatar/avatar";
import { User } from "lucide-react";

export function AvatarHeaderDemo() {
  return (
    <div className="space-y-6">
      <div>
        <h3 className="mb-3 text-sm font-medium">基础用法</h3>
        <AvatarHeader
          avatar={{
            src: "https://api.dicebear.com/7.x/avataaars/svg?seed=Felix",
          }}
          name="张三"
          time="2小时前"
        />
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">使用文本头像</h3>
        <AvatarHeader
          avatar={{
            children: "李",
            style: { backgroundColor: "#1677ff", color: "white" },
          }}
          name="李四"
          time="刚刚"
        />
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">使用图标头像</h3>
        <AvatarHeader
          avatar={{
            icon: <User className="h-4 w-4" />,
            style: { backgroundColor: "#87d068" },
          }}
          name="王五"
          time="5分钟前"
        />
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">自定义样式</h3>
        <AvatarHeader
          avatar={{
            children: "赵",
            style: { backgroundColor: "#eb2f96", color: "white" },
          }}
          name="赵六"
          time="昨天"
          nameStyle={{ color: "#eb2f96", fontWeight: "bold" }}
          timeStyle={{ color: "#999" }}
        />
      </div>

      <div>
        <h3 className="mb-3 text-sm font-medium">不同尺寸</h3>
        <div className="space-y-3">
          <AvatarHeader
            avatar={{
              src: "https://api.dicebear.com/7.x/avataaars/svg?seed=Felix",
              size: "sm",
            }}
            name="小头像"
            time="1小时前"
          />
          <AvatarHeader
            avatar={{
              src: "https://api.dicebear.com/7.x/avataaars/svg?seed=Aneka",
              size: "md",
            }}
            name="中等头像"
            time="2小时前"
          />
          <AvatarHeader
            avatar={{
              src: "https://api.dicebear.com/7.x/avataaars/svg?seed=John",
              size: "lg",
            }}
            name="大头像"
            time="3小时前"
          />
        </div>
      </div>
    </div>
  );
}

Avatar Header 组件用于展示"头像 + 名称 + 时间"的一行头部信息，支持自定义图标、图片头像、多种尺寸等，适用于聊天消息、评论、用户信息展示等场景。

概述

灵活头像：支持图标、图片、自定义内容
多种尺寸：预设 small、default、large 或自定义数字
图片处理：支持图片加载错误处理和 CORS 设置
响应式：自适应不同屏幕尺寸
类型安全：完整的 TypeScript 类型定义
轻量级：基于原语组件构建

快速开始

import { AvatarHeader } from "@/registry/wuhan/composed/avatar-header/avatar-header";
import { User } from "lucide-react";

export function Example() {
  return (
    <AvatarHeader 
      icon={<User className="w-3 h-3" />}
      name="用户名" 
      time="刚刚" 
    />
  );
}

特性

多种头像类型：图标、图片 URL、自定义 ReactNode
尺寸控制：支持预设尺寸（small/default/large）和数字像素值
图片加载：自动处理图片加载失败，提供 fallback 机制
CORS 支持：可设置图片跨域属性
时间显示：可选的时间标签
可访问性：支持 alt 文本和 aria 属性

安装

pnpm dlx shadcn@latest add http://localhost:3000/r/wuhan/avatar-header.json

代码演示

基本

基础用法，展示不同的头像类型。

默认:

用户刚刚

自定义图标:

AI 助手2分钟前

图片头像:

John Doe5分钟前

仅名称:

管理员

"use client";

import { AvatarHeader } from "@/components/composed/avatar-header/avatar-header";
import { Bot, Crown } from "lucide-react";

export function AvatarHeaderDefault() {
  return (
    <div className="flex flex-col gap-4">
      <div className="flex items-center gap-2">
        <span className="text-sm text-muted-foreground w-24">默认:</span>
        <AvatarHeader name="用户" time="刚刚" />
      </div>
      <div className="flex items-center gap-2">
        <span className="text-sm text-muted-foreground w-24">自定义图标:</span>
        <AvatarHeader
          icon={<Bot className="w-3 h-3 text-blue-600" />}
          name="AI 助手"
          time="2分钟前"
        />
      </div>
      <div className="flex items-center gap-2">
        <span className="text-sm text-muted-foreground w-24">图片头像:</span>
        <AvatarHeader
          src="https://api.dicebear.com/7.x/avataaars/svg?seed=John"
          name="John Doe"
          time="5分钟前"
        />
      </div>
      <div className="flex items-center gap-2">
        <span className="text-sm text-muted-foreground w-24">仅名称:</span>
        <AvatarHeader
          icon={<Crown className="w-3 h-3 text-amber-600" />}
          name="管理员"
        />
      </div>
    </div>
  );
}

调整头像大小

不同尺寸的头像展示。

小号 (small):

小头像刚刚

默认 (default):

默认头像1分钟前

大号 (large):

大头像5分钟前

自定义 (32px):

自定义尺寸10分钟前

"use client";

import { AvatarHeader } from "@/components/composed/avatar-header/avatar-header";

export function AvatarHeaderSizes() {
  return (
    <div className="flex flex-col gap-4">
      <div className="flex items-center gap-2">
        <span className="text-sm text-muted-foreground w-24">
          小号 (small):
        </span>
        <AvatarHeader
          size="small"
          src="https://api.dicebear.com/7.x/avataaars/svg?seed=small"
          name="小头像"
          time="刚刚"
        />
      </div>
      <div className="flex items-center gap-2">
        <span className="text-sm text-muted-foreground w-24">
          默认 (default):
        </span>
        <AvatarHeader
          size="default"
          src="https://api.dicebear.com/7.x/avataaars/svg?seed=default"
          name="默认头像"
          time="1分钟前"
        />
      </div>
      <div className="flex items-center gap-2">
        <span className="text-sm text-muted-foreground w-24">
          大号 (large):
        </span>
        <AvatarHeader
          size="large"
          src="https://api.dicebear.com/7.x/avataaars/svg?seed=large"
          name="大头像"
          time="5分钟前"
        />
      </div>
      <div className="flex items-center gap-2">
        <span className="text-sm text-muted-foreground w-24">
          自定义 (32px):
        </span>
        <AvatarHeader
          size={32}
          src="https://api.dicebear.com/7.x/avataaars/svg?seed=custom"
          name="自定义尺寸"
          time="10分钟前"
        />
      </div>
    </div>
  );
}

自定义头像元素

使用不同图标的头像。

消息助手在线

邮件通知2分钟前

电话客服离线

视频会议进行中

"use client";

import { AvatarHeader } from "@/components/composed/avatar-header/avatar-header";
import { MessageSquare, Mail, Phone, Video } from "lucide-react";

export function AvatarHeaderIcons() {
  return (
    <div className="flex flex-col gap-4">
      <AvatarHeader
        icon={<MessageSquare className="w-3 h-3 text-blue-600" />}
        name="消息助手"
        time="在线"
      />
      <AvatarHeader
        icon={<Mail className="w-3 h-3 text-green-600" />}
        name="邮件通知"
        time="2分钟前"
      />
      <AvatarHeader
        icon={<Phone className="w-3 h-3 text-purple-600" />}
        name="电话客服"
        time="离线"
      />
      <AvatarHeader
        icon={<Video className="w-3 h-3 text-red-600" />}
        name="视频会议"
        time="进行中"
      />
    </div>
  );
}

错误处理

图片加载错误处理。

正常加载:

正常用户在线

加载失败:

加载失败显示默认图标

自定义错误处理:

自定义 fallback错误次数: 0

"use client";

import { useState } from "react";
import { AvatarHeader } from "@/components/composed/avatar-header/avatar-header";
import { ImageOff } from "lucide-react";

export function AvatarHeaderError() {
  const [errorCount, setErrorCount] = useState(0);

  return (
    <div className="flex flex-col gap-4">
      <div className="flex items-center gap-2">
        <span className="text-sm text-muted-foreground w-32">正常加载:</span>
        <AvatarHeader
          src="https://api.dicebear.com/7.x/avataaars/svg?seed=valid"
          alt="正常头像"
          name="正常用户"
          time="在线"
        />
      </div>
      <div className="flex items-center gap-2">
        <span className="text-sm text-muted-foreground w-32">加载失败:</span>
        <AvatarHeader
          src="https://invalid-url.example.com/avatar.jpg"
          alt="失败头像"
          name="加载失败"
          time="显示默认图标"
        />
      </div>
      <div className="flex items-center gap-2">
        <span className="text-sm text-muted-foreground w-32">
          自定义错误处理:
        </span>
        <AvatarHeader
          src="https://invalid-url-2.example.com/avatar.jpg"
          alt="自定义错误"
          icon={<ImageOff className="w-3 h-3 text-gray-400" />}
          name="自定义 fallback"
          time={`错误次数: ${errorCount}`}
          onError={() => {
            setErrorCount((prev) => prev + 1);
            return true; // 使用默认 fallback
          }}
        />
      </div>
    </div>
  );
}

带状态指示器

结合状态标签显示用户状态。

在线用户刚刚

在线

离开用户5分钟前

离开

离线用户1小时前

离线

"use client";

import { AvatarHeader } from "@/components/composed/avatar-header/avatar-header";
import { StatusTag } from "@/components/composed/status-tag/status-tag";

export function AvatarHeaderStatus() {
  return (
    <div className="flex flex-col gap-4">
      <div className="flex items-center gap-2">
        <AvatarHeader
          src="https://api.dicebear.com/7.x/avataaars/svg?seed=Online"
          name="在线用户"
          time="刚刚"
        />
        <StatusTag status="success" text="在线" />
      </div>
      <div className="flex items-center gap-2">
        <AvatarHeader
          src="https://api.dicebear.com/7.x/avataaars/svg?seed=Away"
          name="离开用户"
          time="5分钟前"
        />
        <StatusTag status="warning" text="离开" />
      </div>
      <div className="flex items-center gap-2">
        <AvatarHeader
          src="https://api.dicebear.com/7.x/avataaars/svg?seed=Offline"
          name="离线用户"
          time="1小时前"
        />
        <StatusTag status="error" text="离线" />
      </div>
    </div>
  );
}

响应式尺寸

响应式尺寸适配不同屏幕。

响应式尺寸:

响应式头像刚刚

提示：调整浏览器窗口大小可以看到头像尺寸的变化

"use client";

import { AvatarHeader } from "@/components/composed/avatar-header/avatar-header";

export function AvatarHeaderResponsive() {
  return (
    <div className="flex flex-col gap-4">
      <div className="flex items-center gap-2">
        <span className="text-sm text-muted-foreground w-32">响应式尺寸:</span>
        <AvatarHeader
          size={{ xs: 20, sm: 24, md: 32, lg: 40 }}
          name="响应式头像"
          time="刚刚"
        />
      </div>
      <div className="text-xs text-muted-foreground">
        提示：调整浏览器窗口大小可以看到头像尺寸的变化
      </div>
    </div>
  );
}

API

AvatarHeader

主头像组件，支持图标、图片和自定义内容。

Props

Prop	Type	Default	Description
`alt`	`string`	-	图像无法显示时的替代文本
`icon`	`React.ReactNode`	-	设置头像的自定义图标
`size`	`AvatarSize`	`"default"`	设置头像的大小
`src`	`string \| React.ReactNode`	-	图片类头像的资源地址或者图片元素
`crossOrigin`	`CrossOrigin`	-	CORS 属性设置
`onError`	`() => boolean`	-	图片加载失败的事件，返回 false 会关闭组件默认的 fallback 行为
`name`	`React.ReactNode`	-	头像标签
`time`	`React.ReactNode`	-	时间标签
`className`	`string`	-	自定义样式类名

Example

import { AvatarHeader } from "@/registry/wuhan/composed/avatar-header/avatar-header";
import { Bot } from "lucide-react";

function UserHeader() {
  return (
    <div className="flex flex-col gap-2">
      {/* 使用图标 */}
      <AvatarHeader 
        icon={<Bot className="w-3 h-3 text-blue-600" />}
        name="AI 助手"
        time="在线"
      />
      
      {/* 使用图片 */}
      <AvatarHeader 
        src="https://example.com/avatar.jpg"
        alt="用户头像"
        name="张三"
        time="5分钟前"
        size="large"
      />
      
      {/* 错误处理 */}
      <AvatarHeader 
        src="https://invalid-url.com/avatar.jpg"
        name="加载失败"
        time="显示默认图标"
        onError={() => {
          console.log("图片加载失败");
          return true; // 使用默认 fallback
        }}
      />
    </div>
  );
}

AvatarSize

头像尺寸类型定义。

type AvatarSize = 
  | number                    // 自定义像素值
  | "large"                   // 40px
  | "small"                   // 20px
  | "default"                 // 24px
  | {                         // 响应式尺寸
      xs?: number;
      sm?: number;
      md?: number;
      lg?: number;
      xl?: number;
      xxl?: number;
    };

CrossOrigin

CORS 属性类型定义。

type CrossOrigin = "anonymous" | "use-credentials" | "";

预设尺寸

Size	Pixels	Description
`small`	20px	小号头像
`default`	24px	默认尺寸
`large`	40px	大号头像

使用场景

聊天消息：显示发送者头像、名称和时间
评论系统：展示评论者信息
用户列表：显示用户基本信息
通知中心：显示通知来源
社交动态：展示动态发布者
AI 对话：区分 AI 和用户消息

最佳实践

图标使用：为不同类型的用户使用不同的图标（如 Bot、User、Admin）
图片优化：使用适当尺寸的图片，避免加载过大的图片
错误处理：为图片加载失败提供合理的 fallback
可访问性：为图片提供有意义的 alt 文本
尺寸统一：在同一场景中保持尺寸一致性
时间格式：使用相对时间（如"刚刚"、"5分钟前"）提升用户体验

注意事项

使用 src 时，组件会自动处理图片加载错误
onError 返回 false 可以禁用默认的 fallback 行为
size 支持响应式对象，但默认会取 md/sm/lg 中的第一个有效值
icon 和 src 同时存在时，优先显示 src（除非加载失败）
图片加载失败后会自动显示 icon 或默认图标

原语组件

Avatar Header 基于以下原语组件构建：

AvatarHeaderPrimitive - 头像栏容器
AvatarPrimitive - 头像样式
AvatarNamePrimitive - 名称样式
AvatarTimePrimitive - 时间样式

这些原语可以在 registry/wuhan/blocks/avatar-header/avatar-header-01.tsx 中找到。

样式定制

组件使用 Tailwind CSS 和 CSS 变量，可以通过以下方式定制：

// 自定义头像大小
<AvatarHeader 
  size={48}
  className="gap-4"
/>

// 自定义样式
<AvatarHeader 
  name="用户"
  className="p-2 bg-gray-50 rounded-lg"
/>