前端页面模板

# 前端页面模板

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-27
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新] [强制执行]

---

## ⚠️ 使用说明

**开发任何新页面前，必须：**
1. 阅读本文档了解标准结构
2. 参考现有同类页面（如 `src/app/tenant/employee-management/employee-list/page.tsx`）
3. 使用 AdminLayout 包装器
4. 遵循颜色、组件、主题规范

---

## &#128203; 标准页面结构模板

### 模板 1: 列表页（最常用）

```tsx
'use client';

import { useState, useEffect } from 'react';
import { useRouter } from 'next/navigation';
import {
  Card,
  Button,
  Input,
  Select,
  Table,
  Badge,
  Tag,
  Avatar,
  Space,
  Row,
  Col,
  Statistic,
  Modal,
  Form,
  App,
  Tooltip,
  Dropdown,
  Popconfirm,
} from 'antd';
import type { MenuProps, TableColumnsType } from 'antd';
import {
  SearchOutlined,
  ReloadOutlined,
  PlusOutlined,
  ExportOutlined,
  EyeOutlined,
  EditOutlined,
  DeleteOutlined,
  MoreOutlined,
} from '@ant-design/icons';

// ============================================
// 1. 类型定义
// ============================================
interface DataItem {
  id: string;
  name: string;
  status: string;
  // ... 其他字段
}

// ============================================
// 2. 主组件
// ============================================
export default function ListPage() {
  const router = useRouter();
  const { message, modal } = App.useApp();

// 数据状态
  const [data, setData] = useState<DataItem[]>([]);
  const [loading, setLoading] = useState(false);

// 统计数据
  const [stats, setStats] = useState({
    total: 0,
    active: 0,
    // ...
  });

// 筛选状态
  const [searchKeyword, setSearchKeyword] = useState('');
  const [filterStatus, setFilterStatus] = useState('all');

// 弹窗状态
  const [addModalOpen, setAddModalOpen] = useState(false);
  const [editModalOpen, setEditModalOpen] = useState(false);
  const [selectedId, setSelectedId] = useState<string | null>(null);
  const [addForm] = Form.useForm();
  const [editForm] = Form.useForm();

// ============================================
  // 3. 数据加载
  // ============================================
  const loadData = async () => {
    setLoading(true);
    try {
      const res = await fetch('/api/tenant/xxx?tenantId=tenant-001');
      const result = await res.json();
      if (result.success) {
        setData(result.data.list || []);
        setStats(result.data.stats || {});
      }
    } catch (error) {
      console.error('加载数据失败:', error);
      message.error('加载数据失败');
    } finally {
      setLoading(false);
    }
  };

useEffect(() => {
    loadData();
  }, []);

// ============================================
  // 4. 事件处理
  // ============================================
  const handleAdd = async () => {
    try {
      const values = await addForm.validateFields();
      // 调用 API
      message.success('添加成功');
      setAddModalOpen(false);
      addForm.resetFields();
      loadData();
    } catch (error) {
      console.error('添加失败:', error);
    }
  };

// ============================================
  // 5. 表格列定义
  // ============================================
  const columns: TableColumnsType<DataItem> = [
    {
      title: '名称',
      dataIndex: 'name',
      key: 'name',
    },
    {
      title: '状态',
      dataIndex: 'status',
      key: 'status',
      render: (status: string) => (
        <Badge 
          status={status === 'active' ? 'success' : 'default'} 
          text={status === 'active' ? '启用' : '禁用'} 
        />
      ),
    },
    {
      title: '操作',
      key: 'action',
      width: 150,
      render: (_, record) => (
        <Space>
          <Button 
            type="link" 
            size="small" 
            icon={<EyeOutlined />}
            onClick={() => router.push(`/tenant/xxx/${record.id}`)}
          >
            查看
          </Button>
          <Button 
            type="link" 
            size="small" 
            icon={<EditOutlined />}
            onClick={() => {
              setSelectedId(record.id);
              editForm.setFieldsValue(record);
              setEditModalOpen(true);
            }}
          >
            编辑
          </Button>
          <Popconfirm
            title="确认删除？"
            onConfirm={() => handleDelete(record.id)}
          >
            <Button type="link" size="small" danger icon={<DeleteOutlined />}>
              删除
            </Button>
          </Popconfirm>
        </Space>
      ),
    },
  ];

// ============================================
  // 6. 渲染
  // ============================================
  return (
    <div className="space-y-4">
      {/* 统计卡片 */}
      <Row gutter={16}>
        <Col span={6}>
          <Card>
            <Statistic title="总数" value={stats.total} />
          </Card>
        </Col>
        <Col span={6}>
          <Card>
            <Statistic title="启用" value={stats.active} />
          </Card>
        </Col>
      </Row>

{/* 主内容卡片 */}
      <Card>
        {/* 工具栏 */}
        <div className="flex justify-between mb-4">
          <Space>
            <Input
              placeholder="搜索..."
              prefix={<SearchOutlined />}
              value={searchKeyword}
              onChange={(e) => setSearchKeyword(e.target.value)}
              style={{ width: 200 }}
            />
            <Select
              value={filterStatus}
              onChange={setFilterStatus}
              style={{ width: 120 }}
              options={[
                { value: 'all', label: '全部状态' },
                { value: 'active', label: '启用' },
                { value: 'inactive', label: '禁用' },
              ]}
            />
            <Button icon={<ReloadOutlined />} onClick={loadData}>
              刷新
            </Button>
          </Space>
          <Space>
            <Button icon={<ExportOutlined />}>导出</Button>
            <Button type="primary" icon={<PlusOutlined />} onClick={() => setAddModalOpen(true)}>
              新增
            </Button>
          </Space>
        </div>

{/* 表格 */}
        <Table
          columns={columns}
          dataSource={data}
          rowKey="id"
          loading={loading}
          pagination={{ pageSize: 10 }}
        />
      </Card>

{/* 新增弹窗 */}
      <Modal
        title="新增"
        open={addModalOpen}
        onOk={handleAdd}
        onCancel={() => {
          setAddModalOpen(false);
          addForm.resetFields();
        }}
      >
        <Form form={addForm} layout="vertical">
          <Form.Item name="name" label="名称" rules={[{ required: true }]}>
            <Input placeholder="请输入名称" />
          </Form.Item>
        </Form>
      </Modal>

{/* 编辑弹窗 */}
      <Modal
        title="编辑"
        open={editModalOpen}
        onOk={handleEdit}
        onCancel={() => {
          setEditModalOpen(false);
          editForm.resetFields();
        }}
      >
        <Form form={editForm} layout="vertical">
          <Form.Item name="name" label="名称" rules={[{ required: true }]}>
            <Input placeholder="请输入名称" />
          </Form.Item>
        </Form>
      </Modal>
    </div>
  );
}
```

---

### 模板 2: 详情页

```tsx
'use client';

import { useState, useEffect } from 'react';
import { useParams, useRouter } from 'next/navigation';
import {
  Card,
  Button,
  Descriptions,
  Avatar,
  Tag,
  Space,
  Spin,
  App,
} from 'antd';
import {
  ArrowLeftOutlined,
  EditOutlined,
  DeleteOutlined,
} from '@ant-design/icons';

interface DetailData {
  id: string;
  name: string;
  // ...
}

export default function DetailPage() {
  const params = useParams();
  const router = useRouter();
  const { message } = App.useApp();

const [data, setData] = useState<DetailData | null>(null);
  const [loading, setLoading] = useState(true);

const id = params.id as string;

useEffect(() => {
    loadData();
  }, [id]);

if (loading) {
    return (
      <div className="flex justify-center items-center h-64">
        <Spin size="large" />
      </div>
    );
  }

if (!data) {
    return <div>数据不存在</div>;
  }

return (
    <div className="space-y-4">
      {/* 头部操作栏 */}
      <Card>
        <div className="flex justify-between items-center">
          <Button icon={<ArrowLeftOutlined />} onClick={() => router.back()}>
            返回
          </Button>
          <Space>
            <Button icon={<EditOutlined />}>编辑</Button>
            <Button danger icon={<DeleteOutlined />}>删除</Button>
          </Space>
        </div>
      </Card>

{/* 基本信息卡片 */}
      <Card title="基本信息">
        <Descriptions column={2}>
          <Descriptions.Item label="名称">{data.name}</Descriptions.Item>
          {/* 更多字段... */}
        </Descriptions>
      </Card>
    </div>
  );
}
```

---

## &#128203; 常用导入清单

### Ant Design 组件（按需导入）

```tsx
// 基础组件
import {
  Button,
  Input,
  Select,
  Checkbox,
  Radio,
  Switch,
  DatePicker,
  TimePicker,
  Upload,
} from 'antd';

// 数据展示
import {
  Table,
  List,
  Card,
  Descriptions,
  Statistic,
  Tag,
  Badge,
  Avatar,
  Tooltip,
  Typography,
  Empty,
} from 'antd';

// 反馈组件
import {
  Modal,
  Drawer,
  Message,
  Notification,
  Popconfirm,
  Popover,
  Progress,
  Spin,
} from 'antd';

// 布局组件
import {
  Layout,
  Space,
  Row,
  Col,
  Divider,
  Tabs,
  Breadcrumb,
  Menu,
} from 'antd';

// 表单组件
import {
  Form,
  FormItem,
  InputNumber,
  Cascader,
  TreeSelect,
  Rate,
  Slider,
} from 'antd';

// 类型
import type { MenuProps, TableColumnsType } from 'antd';
```

### Ant Design 图标（按需导入）

```tsx
import {
  // 操作图标
  PlusOutlined,
  EditOutlined,
  DeleteOutlined,
  SearchOutlined,
  ReloadOutlined,
  ExportOutlined,
  ImportOutlined,
  SettingOutlined,
  
  // 状态图标
  CheckCircleOutlined,
  CloseCircleOutlined,
  ExclamationCircleOutlined,
  InfoCircleOutlined,
  LoadingOutlined,
  
  // 用户图标
  UserOutlined,
  TeamOutlined,
  UserAddOutlined,
  
  // 文件图标
  FileOutlined,
  FolderOutlined,
  FileTextOutlined,
  
  // 其他常用
  MoreOutlined,
  EyeOutlined,
  QuestionCircleOutlined,
  ArrowLeftOutlined,
  ArrowRightOutlined,
} from '@ant-design/icons';
```

---

## &#128203; 状态管理模式

### 列表页状态

```tsx
// 数据状态
const [data, setData] = useState<DataItem[]>([]);
const [loading, setLoading] = useState(false);

// 统计数据
const [stats, setStats] = useState({ total: 0, active: 0 });

// 筛选状态
const [searchKeyword, setSearchKeyword] = useState('');
const [filterStatus, setFilterStatus] = useState('all');
const [filterDepartment, setFilterDepartment] = useState('all');

// 分页状态
const [pagination, setPagination] = useState({ current: 1, pageSize: 10, total: 0 });

// 弹窗状态
const [addModalOpen, setAddModalOpen] = useState(false);
const [editModalOpen, setEditModalOpen] = useState(false);
const [detailDrawerOpen, setDetailDrawerOpen] = useState(false);

// 表单实例
const [addForm] = Form.useForm();
const [editForm] = Form.useForm();

// 选中项
const [selectedId, setSelectedId] = useState<string | null>(null);
const [selectedRowKeys, setSelectedRowKeys] = useState<React.Key[]>([]);
```

---

## &#128203; 数据加载模式

### 标准 API 调用

```tsx
// 列表数据
const loadData = async () => {
  setLoading(true);
  try {
    const res = await fetch('/api/tenant/xxx?tenantId=tenant-001');
    const result = await res.json();
    if (result.success) {
      setData(result.data.list || []);
    }
  } catch (error) {
    console.error('加载数据失败:', error);
    message.error('加载数据失败');
  } finally {
    setLoading(false);
  }
};

// 详情数据
const loadDetail = async (id: string) => {
  setLoading(true);
  try {
    const res = await fetch(`/api/tenant/xxx/${id}?tenantId=tenant-001`);
    const result = await res.json();
    if (result.success) {
      setData(result.data);
    }
  } catch (error) {
    console.error('加载数据失败:', error);
  } finally {
    setLoading(false);
  }
};

// 新增数据
const handleAdd = async () => {
  try {
    const values = await addForm.validateFields();
    const res = await fetch('/api/tenant/xxx', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ ...values, tenantId: 'tenant-001' }),
    });
    const result = await res.json();
    if (result.success) {
      message.success('添加成功');
      setAddModalOpen(false);
      addForm.resetFields();
      loadData();
    } else {
      message.error(result.error || '添加失败');
    }
  } catch (error) {
    console.error('添加失败:', error);
    message.error('添加失败');
  }
};
```

---

## &#128218; 相关文档

- [前端布局规范](./前端布局规范.md) - 布局结构、导航配置
- [前端颜色与组件规范](./前端颜色与组件规范.md) - 颜色、组件、主题规范
- [开发安全规范](../开发安全规范.md) - 防破坏性开发规则
- [项目摘要](../../压缩摘要.md) - 核心红线规则