file-starter/.claude/commands/shadcn-管理页面开发.md

---

description: "Shadcn-ui 管理页开发指令"

概述

基于 src/client/admin/pages/Users.tsx 中用户管理页的实现，提取可复用的开发模式和最佳实践，适用于基于 Shadcn-ui 的管理后台页面开发。

页面结构规范

1. 文件位置

• 管理后台页面: src/client/admin/pages/[EntityName].tsx

2. 页面组件结构

// 1. 类型导入和定义
type CreateRequest = InferRequestType<typeof client.$post>['json'];
type UpdateRequest = InferRequestType<typeof client[':id']['$put']>['json'];
type EntityResponse = InferResponseType<typeof client.$get, 200>['data'][0];

// 2. 表单Schema直接使用后端定义
const createFormSchema = CreateEntityDto;
const updateFormSchema = UpdateEntityDto;

// 3. 主页面组件
export const EntityPage = () => {
  // 状态管理
  const [searchParams, setSearchParams] = useState({ page: 1, limit: 10, search: '' });
  const [isModalOpen, setIsModalOpen] = useState(false);
  const [editingEntity, setEditingEntity] = useState<any>(null);
  const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);
  const [entityToDelete, setEntityToDelete] = useState<number | null>(null);
  
  // 表单实例
  const createForm = useForm<CreateRequest>({...});
  const updateForm = useForm<UpdateRequest>({...});
  
  // 数据查询
  const { data, isLoading, refetch } = useQuery({...});
  
  // 业务逻辑函数
  const handleSearch = () => {...};
  const handleCreateEntity = () => {...};
  const handleEditEntity = () => {...};
  const handleDeleteEntity = () => {...};
  
  // 渲染
  return (...);
};

核心开发模式

1. 类型驱动的开发

• RPC类型提取: 使用 InferRequestType 和 InferResponseType 从后端API自动提取类型
• Schema复用: 直接使用后端定义的Zod Schema作为表单验证
• 类型安全: 所有API调用都有完整的TypeScript类型支持

2. 状态管理模式

// 分页和搜索参数
const [searchParams, setSearchParams] = useState({
  page: 1,
  limit: 10,
  search: '',
  // 其他筛选条件...
});

// 模态框状态
const [isModalOpen, setIsModalOpen] = useState(false);
const [editingEntity, setEditingEntity] = useState<any>(null);
const [isCreateForm, setIsCreateForm] = useState(true);

3. 数据获取模式

const { data, isLoading, refetch } = useQuery({
  queryKey: ['entities', searchParams],
  queryFn: async () => {
    const res = await entityClient.$get({
      query: {
        page: searchParams.page,
        pageSize: searchParams.limit,
        keyword: searchParams.search,
        // 其他查询参数...
      }
    });
    if (res.status !== 200) throw new Error('获取列表失败');
    return await res.json();
  }
});

页面布局规范

1. 页面标题区域

<div className="flex justify-between items-center">
  <h1 className="text-2xl font-bold">页面标题</h1>
  <Button onClick={handleCreateEntity}>
    <Plus className="mr-2 h-4 w-4" />
    创建实体
  </Button>
</div>

2. 搜索区域

<Card>
  <CardHeader>
    <CardTitle>列表标题</CardTitle>
    <CardDescription>列表描述信息</CardDescription>
  </CardHeader>
  <CardContent>
    <div className="mb-4">
      <form onSubmit={handleSearch} className="flex gap-2">
        <div className="relative flex-1 max-w-sm">
          <Search className="absolute left-2 top-2.5 h-4 w-4 text-muted-foreground" />
          <Input
            placeholder="搜索提示..."
            value={searchParams.search}
            onChange={(e) => setSearchParams(prev => ({ ...prev, search: e.target.value }))}
            className="pl-8"
          />
        </div>
        <Button type="submit" variant="outline">
          搜索
        </Button>
      </form>
    </div>
  </CardContent>
</Card>

3. 数据表格

<div className="rounded-md border">
  <Table>
    <TableHeader>
      <TableRow>
        <TableHead>列标题1</TableHead>
        <TableHead>列标题2</TableHead>
        <TableHead className="text-right">操作</TableHead>
      </TableRow>
    </TableHeader>
    <TableBody>
      {data.map((item) => (
        <TableRow key={item.id}>
          <TableCell>{item.field1}</TableCell>
          <TableCell>{item.field2}</TableCell>
          <TableCell className="text-right">
            <div className="flex justify-end gap-2">
              <Button variant="ghost" size="icon" onClick={() => handleEdit(item)}>
                <Edit className="h-4 w-4" />
              </Button>
              <Button variant="ghost" size="icon" onClick={() => handleDelete(item.id)}>
                <Trash2 className="h-4 w-4" />
              </Button>
            </div>
          </TableCell>
        </TableRow>
      ))}
    </TableBody>
  </Table>
</div>

{data?.data.length === 0 && !isLoading && (
  <div className="text-center py-8">
    <p className="text-muted-foreground">暂无数据</p>
  </div>
)}

<DataTablePagination
  currentPage={searchParams.page}
  pageSize={searchParams.limit}
  totalCount={data?.pagination.total || 0}
  onPageChange={(page, limit) => setSearchParams(prev => ({ ...prev, page, limit }))}
/>

表单开发模式

1. 表单组件结构

// 创建表单
const createForm = useForm<CreateRequest>({
  resolver: zodResolver(createFormSchema),
  defaultValues: {
    // 默认值设置
  },
});

// 更新表单
const updateForm = useForm<UpdateRequest>({
  resolver: zodResolver(updateFormSchema),
  defaultValues: {
    // 更新时默认值
  },
});

2. 模态框表单（创建/编辑分离模式）

将 创建/编辑表单分离 不要 要
{isCreateForm ? ( // 创建表单（独立渲染） ) : ( // 编辑表单（独立渲染） )}

<Dialog open={isModalOpen} onOpenChange={setIsModalOpen}>
  <DialogContent className="sm:max-w-[500px] max-h-[90vh] overflow-y-auto">
    <DialogHeader>
      <DialogTitle>{isCreateForm ? '创建实体' : '编辑实体'}</DialogTitle>
      <DialogDescription>
        {isCreateForm ? '创建一个新的实体' : '编辑现有实体信息'}
      </DialogDescription>
    </DialogHeader>
    
    {isCreateForm ? (
      // 创建表单（独立渲染）
      <Form {...createForm}>
        <form onSubmit={createForm.handleSubmit(handleCreateSubmit)} className="space-y-4">
          {/* 创建专用字段 */}
          <DialogFooter>
            <Button type="button" variant="outline" onClick={() => setIsModalOpen(false)}>
              取消
            </Button>
            <Button type="submit">创建</Button>
          </DialogFooter>
        </form>
      </Form>
    ) : (
      // 编辑表单（独立渲染）
      <Form {...updateForm}>
        <form onSubmit={updateForm.handleSubmit(handleUpdateSubmit)} className="space-y-4">
          {/* 编辑专用字段 */}
          <DialogFooter>
            <Button type="button" variant="outline" onClick={() => setIsModalOpen(false)}>
              取消
            </Button>
            <Button type="submit">更新</Button>
          </DialogFooter>
        </form>
      </Form>
    )}
  </DialogContent>
</Dialog>

3. 表单字段模式

<FormField
  control={form.control}
  name="fieldName"
  render={({ field }) => (
    <FormItem>
      <FormLabel className="flex items-center">
        字段标签
        {isRequired && <span className="text-red-500 ml-1">*</span>}
      </FormLabel>
      <FormControl>
        <Input placeholder="请输入..." {...field} />
      </FormControl>
      <FormDescription>字段描述信息</FormDescription>
      <FormMessage />
    </FormItem>
  )}
/>

图片上传集成

1. ImageSelector组件使用

import { ImageSelector } from '@/client/admin/components/ImageSelector';

<FormField
  control={form.control}
  name="avatarFileId"
  render={({ field }) => (
    <FormItem>
      <FormLabel>头像</FormLabel>
      <FormControl>
        <ImageSelector
          value={field.value || undefined}
          onChange={(value) => field.onChange(value)}
          maxSize={2} // MB
          uploadPath="/avatars"
          uploadButtonText="上传头像"
          previewSize="medium"
          placeholder="选择头像"
        />
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>

文件上传集成

1. FileSelector组件使用

import { FileSelector } from '@/client/admin/components/FileSelector';

<FormField
  control={form.control}
  name="avatarFileId"
  render={({ field }) => (
    <FormItem>
      <FormLabel>头像</FormLabel>
      <FormControl>
        <FileSelector
          value={field.value || undefined}
          onChange={(value) => field.onChange(value)}
          maxSize={2} // MB
          uploadPath="/avatars"
          uploadButtonText="上传头像"
          previewSize="medium"
          placeholder="选择头像"
        />
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>

状态管理最佳实践

1. 状态提升策略

• 表单状态: 使用React Hook Form管理
• UI状态: 使用useState管理模态框、加载状态等
• 服务器状态: 使用React Query管理数据获取和缓存

2. 数据刷新策略

// 操作成功后刷新数据
const handleCreateSubmit = async (data: CreateRequest) => {
  try {
    const res = await entityClient.$post({ json: data });
    if (res.status !== 201) throw new Error('创建失败');
    toast.success('创建成功');
    setIsModalOpen(false);
    refetch(); // 刷新数据
  } catch (error) {
    toast.error('操作失败，请重试');
  }
};

加载状态处理

1. 骨架屏模式

1.1 导入依赖

import { Skeleton } from '@/client/components/ui/skeleton';

1.2 完整骨架屏实现

if (isLoading) {
  return (
    <div className="space-y-4">
      {/* 标题区域骨架 */}
      <div className="flex justify-between items-center">
        <Skeleton className="h-8 w-48" />
        <Skeleton className="h-10 w-32" />
      </div>
      
      {/* 搜索区域骨架 */}
      <Card>
        <CardHeader>
          <Skeleton className="h-6 w-1/4" />
        </CardHeader>
        <CardContent>
          <Skeleton className="h-10 w-full max-w-sm" />
        </CardContent>
      </Card>
      
      {/* 表格骨架 */}
      <Card>
        <CardHeader>
          <Skeleton className="h-6 w-1/3" />
        </CardHeader>
        <CardContent>
          <Table>
            <TableHeader>
              <TableRow>
                {[...Array(5)].map((_, i) => (
                  <TableHead key={i}>
                    <Skeleton className="h-4 w-full" />
                  </TableHead>
                ))}
              </TableRow>
            </TableHeader>
            <TableBody>
              {[...Array(5)].map((_, i) => (
                <TableRow key={i}>
                  {[...Array(5)].map((_, j) => (
                    <TableCell key={j}>
                      <Skeleton className="h-4 w-full" />
                    </TableCell>
                  ))}
                </TableRow>
              ))}
            </TableBody>
          </Table>
        </CardContent>
      </Card>
    </div>
  );
}

1.3 简化骨架屏（推荐）

if (isLoading) {
  return (
    <div className="space-y-4">
      <div className="flex justify-between items-center">
        <Skeleton className="h-8 w-48" />
        <Skeleton className="h-10 w-32" />
      </div>
      
      <Card>
        <CardContent className="pt-6">
          <div className="space-y-3">
            {[...Array(5)].map((_, i) => (
              <div key={i} className="flex gap-4">
                <Skeleton className="h-10 flex-1" />
                <Skeleton className="h-10 flex-1" />
                <Skeleton className="h-10 flex-1" />
                <Skeleton className="h-10 w-20" />
              </div>
            ))}
          </div>
        </CardContent>
      </Card>
    </div>
  );
}

2. 空数据状态

{users.length === 0 && !isLoading && (
  <div className="text-center py-8">
    <p className="text-muted-foreground">暂无数据</p>
  </div>
)}

错误处理模式

1. API错误处理

try {
  const res = await entityClient.$post({ json: data });
  if (res.status !== 201) throw new Error('操作失败');
  toast.success('操作成功');
} catch (error) {
  console.error('操作失败:', error);
  toast.error('操作失败，请重试');
}

2. 删除确认模式

const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);
const [entityToDelete, setEntityToDelete] = useState<number | null>(null);

// 删除确认对话框
<Dialog open={deleteDialogOpen} onOpenChange={setDeleteDialogOpen}>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>确认删除</DialogTitle>
      <DialogDescription>
        确定要删除这个实体吗？此操作无法撤销。
      </DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <Button variant="outline" onClick={() => setDeleteDialogOpen(false)}>
        取消
      </Button>
      <Button variant="destructive" onClick={confirmDelete}>
        删除
      </Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

// 删除成功状态码为204
const confirmDelete = async () => {
  if (!entityToDelete) return;
  
  try {
    const res = await entityClient[':id']['$delete']({
      param: { id: entityToDelete.toString() }
    });
    
    if (res.status === 204) {
      toast.success('删除成功');
      setDeleteDialogOpen(false);
      refetch(); // 刷新数据
    } else {
      throw new Error('删除失败');
    }
  } catch (error) {
    toast.error('删除失败，请重试');
  }
};

样式规范

1. 间距系统

• 页面标题区域: space-y-4
• 卡片内容: space-y-4
• 表单字段: space-y-4
• 按钮组: gap-2

2. 响应式设计

• 模态框最大宽度: sm:max-w-[500px]
• 模态框最大高度: max-h-[90vh]
• 搜索输入框: max-w-sm

3. 视觉层次

• 标题: text-2xl font-bold
• 卡片标题: text-lg font-semibold
• 描述文字: text-sm text-muted-foreground

开发流程

1. 创建新管理页面

1. 复制 Users.tsx 作为模板
2. 替换以下部分：
   • API客户端导入
   • 类型定义
   • 表单Schema引用
   • 页面标题和描述
   • 表格列定义
   • 表单字段定义
3. 根据业务需求调整字段和逻辑

2. 字段映射规范

• 文本字段: 使用 Input
• 长文本: 使用 Textarea
• 选择字段: 使用 Select
• 开关字段: 使用 Switch
• 日期字段: 使用 DatePicker
• 图片字段: 使用 ImageSelector

3. 业务逻辑复用

• 保持相同的CRUD操作模式
• 复用分页、搜索、排序逻辑
• 统一的状态管理模式
• 一致的表单验证和错误处理

高级组件集成

1. DataTablePagination 分页组件

1.1 使用方式

import { DataTablePagination } from '@/client/admin/components/DataTablePagination';

<DataTablePagination
  currentPage={searchParams.page}
  pageSize={searchParams.limit}
  totalCount={data?.pagination.total || 0}
  onPageChange={(page, limit) => setSearchParams(prev => ({ ...prev, page, limit }))}
/>

1.2 参数说明

参数	类型	描述
currentPage	number	当前页码
pageSize	number	每页显示条数
totalCount	number	总记录数
onPageChange	function	页码变化回调函数

1.3 集成到状态管理

const [searchParams, setSearchParams] = useState({
  page: 1,
  limit: 10,
  search: ''
});

// 在数据查询中
const { data } = useQuery({
  queryKey: ['entities', searchParams],
  queryFn: async () => {
    const res = await client.$get({
      query: {
        page: searchParams.page,
        pageSize: searchParams.limit,
        keyword: searchParams.search
      }
    });
    return await res.json();
  }
});

2. 关联实体Selector组件

2.1 AdvertisementTypeSelector 示例

import AdvertisementTypeSelector from '@/client/admin/components/AdvertisementTypeSelector';

<FormField
  control={form.control}
  name="typeId"
  render={({ field }) => (
    <FormItem>
      <FormLabel>广告类型</FormLabel>
      <FormControl>
        <AdvertisementTypeSelector
          value={field.value}
          onChange={field.onChange}
          placeholder="请选择广告类型"
        />
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>

2.2 自定义Selector开发模式

// 通用Selector接口设计
interface EntitySelectorProps {
  value?: number;
  onChange?: (value: number) => void;
  placeholder?: string;
  disabled?: boolean;
}

// 实现模式
const EntitySelector: React.FC<EntitySelectorProps> = ({
  value,
  onChange,
  placeholder = "请选择",
  disabled
}) => {
  const { data } = useQuery({
    queryKey: ['entities'],
    queryFn: async () => {
      const res = await entityClient.$get();
      return await res.json();
    }
  });

  return (
    <Select value={value?.toString()} onValueChange={(v) => onChange?.(parseInt(v))}>
      <SelectTrigger disabled={disabled}>
        <SelectValue placeholder={placeholder} />
      </SelectTrigger>
      <SelectContent>
        {data?.data.map((item) => (
          <SelectItem key={item.id} value={item.id.toString()}>
            {item.name}
          </SelectItem>
        ))}
      </SelectContent>
    </Select>
  );
};

2.3 图片选择器集成

import ImageSelector from '@/client/admin/components/ImageSelector';

<FormField
  control={form.control}
  name="imageFileId"
  render={({ field }) => (
    <FormItem>
      <FormLabel>广告图片</FormLabel>
      <FormControl>
        <ImageSelector
          value={field.value || undefined}
          onChange={field.onChange}
          maxSize={2} // MB
          uploadPath="/advertisements"
          uploadButtonText="上传广告图片"
          previewSize="medium"
          placeholder="选择广告图片"
          title="选择广告图片"
          description="上传新图片或从已有图片中选择"
        />
      </FormControl>
      <FormDescription>推荐尺寸：1200x400px，支持jpg、png格式</FormDescription>
      <FormMessage />
    </FormItem>
  )}
/>

3. 复杂字段展示模式

3.1 关联实体字段展示

<TableCell>
  {advertisement.advertisementType?.name || '-'}
</TableCell>

3.2 状态字段展示

<TableCell>
  <Badge variant={advertisement.status === 1 ? 'default' : 'secondary'}>
    {advertisement.status === 1 ? '启用' : '禁用'}
  </Badge>
</TableCell>

3.3 图片字段展示

<TableCell>
  {advertisement.imageFile?.fullUrl ? (
    <img
      src={advertisement.imageFile.fullUrl}
      alt={advertisement.title || '图片'}
      className="w-16 h-10 object-cover rounded"
      onError={(e) => {
        e.currentTarget.src = '/placeholder.png';
      }}
    />
  ) : (
    <span className="text-muted-foreground text-xs">无图片</span>
  )}
</TableCell>

4. 表单字段类型映射

4.1 标准字段映射

字段类型	组件	示例
文本输入	Input	<Input placeholder="请输入标题" {...field} />
长文本	Textarea	<Textarea placeholder="请输入描述" {...field} />
选择器	Select	<Select value={field.value} onValueChange={field.onChange}>
数字输入	Input	<Input type="number" {...field} />
日期选择	DatePicker	<DatePicker selected={field.value} onChange={field.onChange} />
开关	Switch	<Switch checked={field.value} onCheckedChange={field.onChange} />
文件上传	ImageSelector	<ImageSelector value={field.value} onChange={field.onChange} />

4.2 关联实体选择

// 直接使用Selector组件
<FormField
  control={form.control}
  name="typeId"
  render={({ field }) => (
    <FormItem>
      <FormLabel>广告类型</FormLabel>
      <FormControl>
        <AdvertisementTypeSelector {...field} />
      </FormControl>
    </FormItem>
  )}
/>

4.3 日期格式化规范

4.3.1 导入依赖

import { format } from 'date-fns';

4.3.2 日期显示格式

// 标准日期时间格式：yyyy-MM-dd HH:mm
<TableCell>
  {user.createdAt ? format(new Date(user.createdAt), 'yyyy-MM-dd HH:mm') : '-'}
</TableCell>

// 仅日期格式：yyyy-MM-dd
<TableCell>
  {user.birthday ? format(new Date(user.birthday), 'yyyy-MM-dd') : '-'}
</TableCell>

// 完整时间格式：yyyy-MM-dd HH:mm:ss
<TableCell>
  {user.updatedAt ? format(new Date(user.updatedAt), 'yyyy-MM-dd HH:mm:ss') : '-'}
</TableCell>

4.3.3 日期输入格式

// 在表单中使用日期选择器
<FormField
  control={form.control}
  name="startDate"
  render={({ field }) => (
    <FormItem>
      <FormLabel>开始日期</FormLabel>
      <FormControl>
        <Input
          type="date"
          {...field}
          value={field.value ? format(new Date(field.value), 'yyyy-MM-dd') : ''}
          onChange={(e) => field.onChange(e.target.value)}
        />
      </FormControl>
    </FormItem>
  )}
/>

4.3.4 相对时间显示（可选）

import { formatDistanceToNow } from 'date-fns';
import { zhCN } from 'date-fns/locale';

// 相对时间显示
<TableCell>
  {user.createdAt ? formatDistanceToNow(new Date(user.createdAt), { addSuffix: true, locale: zhCN }) : '-'}
</TableCell>

4.4 消息通知规范

4.4.1 导入依赖

import { toast } from 'sonner';

4.4.2 使用规范

// 成功通知
toast.success('操作成功');
toast.success('用户创建成功');

// 错误通知
toast.error('操作失败');
toast.error('创建用户失败，请重试');

// 警告通知
toast.warning('请确认操作');
toast.warning('该操作将删除所有相关数据');

// 信息通知
toast.info('操作提示');
toast.info('正在处理中，请稍候...');

4.4.3 与API响应集成

try {
  const res = await entityClient.$post({ json: data });
  if (res.status === 201) {
    toast.success('创建成功');
    setIsModalOpen(false);
    refetch();
  } else {
    const error = await res.json();
    toast.error(error.message || '操作失败');
  }
} catch (error) {
  console.error('操作失败:', error);
  toast.error('网络错误，请重试');
}