feat(navigation): add NavigationUserCard component

[JustKanade]

NavigationUserCard - 导航用户信息卡片组件

为 PyQt-Fluent-Widgets 的导航组件添加用户信息卡片功能，支持显示头像/图标、标题和副标题信息。

2025-11-1721-24-27-ezgif.com-gif-maker.mp4

演示

功能特性

• 双状态显示

  • 紧凑模式：24×24px 圆形头像图标
  • 展开模式：64×64px 头像 + 用户名 + 副标题

• 过渡动画

  • 头像尺寸缩放动画（250ms，OutCubic 缓动）
  • 文本透明度渐变动画（200ms，InOutQuad 缓动）

• 行为

  • EXPAND: 紧凑模式下展开导航栏（默认）
  • CALLBACK: 触发自定义回调函数
  • EXPAND_AND_CALLBACK: 同时展开并触发回调

• 自定义选项

  • 头像：支持图片路径、QPixmap、QImage 或 FluentIcon
  • 字体大小：可调节标题（14px）和副标题（12px）字体
  • 背景颜色：可自定义头像背景色（浅色/深色主题）
  • 放置位置：支持放置在菜单按钮上方/下方

主要改动

• navigation_user_card.py: 新增 NavigationUserCard 组件

  • 新增 NavigationUserCard 类：用户信息卡片组件
  • 新增 NavigationUserCardClickBehavior 枚举：点击行为配置
  • setCompacted(): 响应紧凑/展开模式切换
  • mouseReleaseEvent(): 根据配置处理点击行为
  • _drawAvatar(): 绘制圆形头像（支持图片裁剪和图标）
  • _drawText(): 绘制标题和副标题（支持透明度渐变）
  • 属性方法：setAvatar(), setTitle(), setSubtitle(), setCompactClickBehavior()

• navigation_interface.py: 添加用户卡片支持

  • addUserCard(): 添加用户卡片到导航面板
  • 支持 aboveMenuButton 参数控制卡片位置

API

NavigationInterface.addUserCard()

def addUserCard(
    routeKey: str, 
    avatar: Union[str, QIcon, FluentIconBase] = None,
    title: str = '', 
    subtitle: str = '', 
    onClick=None, 
    position=NavigationItemPosition.TOP,
    aboveMenuButton: bool = False
) -> NavigationUserCard

• routeKey: 用户卡片的唯一标识
• avatar: 头像图片路径、QIcon 或 FluentIconBase
• title: 用户名或主标题文字
• subtitle: 副标题文字（如邮箱、状态）
• onClick: 点击回调函数
• position: 添加位置（TOP/SCROLL/BOTTOM）
• aboveMenuButton: 是否放置在菜单按钮上方

NavigationUserCard 方法

# 设置内容
card.setAvatar(avatar: Union[str, QPixmap, QImage])
card.setAvatarIcon(icon: FluentIconBase)
card.setTitle(title: str)
card.setSubtitle(subtitle: str)

# 自定义样式
card.setTitleFontSize(size: int)
card.setSubtitleFontSize(size: int)
card.setAnimationDuration(duration: int)
card.setAvatarBackgroundColor(lightColor: QColor, darkColor: QColor)

# 行为配置
card.setCompactClickBehavior(behavior: NavigationUserCardClickBehavior)

NavigationUserCardClickBehavior 枚举

from qfluentwidgets import NavigationUserCardClickBehavior

# 点击行为选项
NavigationUserCardClickBehavior.EXPAND                # 展开导航栏
NavigationUserCardClickBehavior.CALLBACK              # 触发回调
NavigationUserCardClickBehavior.EXPAND_AND_CALLBACK   # 两者都执行

完整的演示代码位于 examples/navigation/navigation_user_card/demo.py