知识库首页模版 credits-balance-card.tsx.md

credits balance card.tsx

本地来源：模版/template/raphael-starterkit-v1-main/analysis/05-组件系统/credits-balance-card.tsx.md

积分余额卡片组件 (components/dashboard/credits-balance-card.tsx) 逐行分析

文件概述

这是一个显示用户积分余额和最近积分活动历史的卡片组件。它提供了简洁的积分信息展示和交易历史查看功能。

导入语句分析

"use client";

指示这是客户端组件
支持交互功能和状态管理

import { Coins } from "lucide-react";
import { CreditTransaction } from "@/types/creem";

Coins: 硬币图标，用于积分展示
CreditTransaction: 积分交易类型定义

类型定义分析

type CreditsBalanceCardProps = {
  credits: number;
  recentHistory: CreditTransaction[];
};

Props 字段说明

credits: 当前积分余额数量
recentHistory: 最近的积分交易历史数组

设计特点

简洁的 Props 接口
明确的数据类型
易于使用和理解

组件结构分析

主容器

<div className="rounded-xl border bg-card p-6">

与其他仪表板卡片保持一致的样式
圆角设计
卡片背景色
统一的内边距

头部区域

<div className="flex items-center gap-4">
  <div className="p-2 bg-primary/10 rounded-lg">
    <Coins className="h-6 w-6 text-primary" />
  </div>
  <div>
    <p className="text-sm text-muted-foreground">Available Credits</p>
    <h3 className="text-2xl font-bold mt-1">{credits}</h3>
  </div>
</div>

图标设计

<div className="p-2 bg-primary/10 rounded-lg">
  <Coins className="h-6 w-6 text-primary" />
</div>

使用 Coins 图标表示积分
主题色背景（10%透明度）
圆角容器
标准化的图标尺寸

积分信息显示

<div>
  <p className="text-sm text-muted-foreground">Available Credits</p>
  <h3 className="text-2xl font-bold mt-1">{credits}</h3>
</div>

标签说明："Available Credits"
大字体显示积分数量
使用加粗字体突出重要信息
合适的颜色对比

历史活动区域

<div className="mt-4 space-y-2">
  <p className="text-sm text-muted-foreground">Recent Activity</p>
  <div className="space-y-1">
    {recentHistory.map((history, index) => (
      // 历史记录项
    ))}
  </div>
</div>

区域标题

<p className="text-sm text-muted-foreground">Recent Activity</p>

清晰的区域标识
使用次要颜色
统一的文字样式

历史记录列表

<div className="space-y-1">
  {recentHistory.map((history, index) => (
    <div
      key={index}
      className="flex items-center justify-between text-sm"
    >
      <span
        className={
          history.type === "add" ? "text-primary" : "text-destructive"
        }
      >
        {history.type === "add" ? "+" : "-"}
        {history.amount}
      </span>
      <span className="text-muted-foreground">
        {new Date(history.created_at).toLocaleDateString()}
      </span>
    </div>
  ))}
</div>

列表项结构

使用 Flexbox 布局
左右对齐设计
紧凑的行间距

积分变动显示

<span
  className={
    history.type === "add" ? "text-primary" : "text-destructive"
  }
>
  {history.type === "add" ? "+" : "-"}
  {history.amount}
</span>

动态颜色：增加用主题色，减少用警告色
符号标识：+ 表示增加，- 表示减少
数量显示：清晰的数值展示

日期显示

<span className="text-muted-foreground">
  {new Date(history.created_at).toLocaleDateString()}
</span>

本地化日期格式
使用次要颜色
右对齐显示

数据处理分析

日期格式化

new Date(history.created_at).toLocaleDateString()

将ISO日期字符串转换为本地日期
自动适应用户的地区设置
简洁的日期显示

交易类型处理

history.type === "add" ? "text-primary" : "text-destructive"
history.type === "add" ? "+" : "-"

根据交易类型显示不同颜色和符号
直观的视觉区分
语义化的色彩使用

设计模式分析

展示型组件模式

纯展示组件，不包含业务逻辑
通过 Props 接收数据
专注于UI渲染

条件渲染模式

根据交易类型条件渲染不同样式
动态类名和符号
保持代码简洁

列表渲染模式

使用 map 函数渲染历史记录
适当的 key 值设置
统一的列表项样式

用户体验设计

视觉层次

主要信息：积分余额（大字体、突出显示）
次要信息：标签和区域标题（小字体、次要颜色）
详细信息：交易历史（适中字体、条件颜色）

信息密度

合理的信息密度
清晰的信息分组
舒适的阅读体验

交互反馈

颜色编码的交易类型
直观的符号表示
清晰的时间信息

可扩展性考虑

历史记录扩展

// 可以轻松扩展显示更多信息
{recentHistory.map((history, index) => (
  <div key={index}>
    {/* 可添加更多字段 */}
    <span>{history.description}</span>
    <span>{history.source}</span>
  </div>
))}

样式扩展

一致的CSS类名结构
易于主题化
支持自定义样式

最佳实践总结

组件设计：单一职责，专注积分展示
类型安全：完整的TypeScript类型定义
视觉设计：一致的颜色和间距系统
用户体验：直观的信息层次和视觉反馈
代码质量：简洁清晰的实现
可维护性：易于理解和修改
性能优化：轻量级组件，高效渲染

使用示例

// 基本使用
<CreditsBalanceCard 
  credits={1500}
  recentHistory={[
    {
      amount: 100,
      type: "add",
      created_at: "2024-01-15T10:30:00Z",
      description: "购买积分包"
    },
    {
      amount: 50,
      type: "subtract", 
      created_at: "2024-01-14T14:20:00Z",
      description: "生成图片"
    }
  ]}
/>

// 空历史记录
<CreditsBalanceCard 
  credits={0}
  recentHistory={[]}
/>

改进建议

加载状态：添加积分余额的加载状态
空状态：为空历史记录提供占位内容
交互功能：添加查看完整历史的链接
格式化：考虑大数值的格式化显示
国际化：支持多语言文字和日期格式

这个组件提供了简洁而有效的积分信息展示功能，通过清晰的视觉设计和直观的交互反馈，为用户提供了良好的积分管理体验。

本文档为站内渲染。原始文件本地路径：saas/source/templates/模版-template-raphael-starterkit-v1-main-analysis-05-组件系统-cred-4ece65.md（仅本地保留，不入库不部署）