zyc
b4108961fa
All checks were successful
Build and Deploy Web / build-and-deploy (push) Successful in 1m38s
648 lines
18 KiB
Markdown
648 lines
18 KiB
Markdown
# RTC Web 前端设计规范
|
||
|
||
> 本文档定义 rtc_web 管理后台的 UI 设计规范。所有新页面和组件必须遵循此规范，确保视觉一致性。
|
||
|
||
---
|
||
|
||
## 1. 技术栈
|
||
|
||
| 技术 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| React | 19.x | UI 框架 |
|
||
| TypeScript | 5.9+ | 类型安全 |
|
||
| Ant Design | 5.x | 组件库 |
|
||
| @ant-design/pro-components | 2.x | ProTable 等高级组件 |
|
||
| @ant-design/charts | 2.x | 图表 (Pie, Column 等) |
|
||
| Zustand | 5.x | 状态管理 |
|
||
| Vite | 7.x | 构建工具 |
|
||
|
||
---
|
||
|
||
## 2. 色彩体系
|
||
|
||
### 2.1 主题色
|
||
|
||
主题色通过 `src/theme/tokens.ts` 统一配置，由 Ant Design 的 `ConfigProvider` 全局应用。
|
||
|
||
| 语义 | 色值 | 用途 |
|
||
|------|------|------|
|
||
| **Primary** | `#6366f1` | 主操作按钮、链接、选中态、品牌色 |
|
||
| Success | `#10b981` | 成功状态、已绑定、完成 |
|
||
| Warning | `#f59e0b` | 警告、未导入、待处理 |
|
||
| Error | `#ef4444` | 错误、删除、禁用 |
|
||
| Info | `#3b82f6` | 信息提示、只读状态 |
|
||
|
||
### 2.2 统计卡片专用色（`statColors`）
|
||
|
||
从 `src/theme/tokens.ts` 中导入 `statColors`：
|
||
|
||
```typescript
|
||
import { statColors } from '../../theme/tokens';
|
||
|
||
// 可用颜色:
|
||
statColors.primary // #6366f1 - 紫蓝
|
||
statColors.success // #10b981 - 绿
|
||
statColors.warning // #f59e0b - 橙
|
||
statColors.error // #ef4444 - 红
|
||
statColors.info // #3b82f6 - 蓝
|
||
statColors.purple // #8b5cf6 - 紫
|
||
statColors.cyan // #06b6d4 - 青
|
||
statColors.pink // #ec4899 - 粉
|
||
```
|
||
|
||
### 2.3 中性色
|
||
|
||
| 用途 | 色值 |
|
||
|------|------|
|
||
| 正文标题 | `#1f2937` |
|
||
| 正文内容 | `#374151` |
|
||
| 辅助文字 | `#6b7280` |
|
||
| 占位/禁用 | `#9ca3af` |
|
||
| 边框 | `#e5e7eb` |
|
||
| 浅背景 | `#f5f5f7` (Layout 背景) |
|
||
| 白色容器 | `#ffffff` |
|
||
|
||
### 2.4 CSS 变量
|
||
|
||
全局 CSS 变量定义在 `src/index.css` 的 `:root` 中，可在任何 CSS 文件中使用：
|
||
|
||
```css
|
||
var(--color-primary) /* #6366f1 */
|
||
var(--color-primary-light) /* #818cf8 */
|
||
var(--color-primary-dark) /* #4f46e5 */
|
||
var(--color-bg-base) /* #f5f5f7 */
|
||
var(--color-bg-elevated) /* #ffffff */
|
||
var(--color-border) /* #e5e7eb */
|
||
var(--shadow-sm) /* 微弱阴影 */
|
||
var(--shadow-md) /* 中等阴影 */
|
||
var(--shadow-lg) /* 强阴影 */
|
||
var(--transition-fast) /* 150ms */
|
||
var(--transition-base) /* 200ms */
|
||
var(--transition-slow) /* 300ms */
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 圆角规范
|
||
|
||
| 场景 | 值 | 说明 |
|
||
|------|------|------|
|
||
| 小组件 (Tag) | `6px` | `borderRadiusSM` |
|
||
| 标准组件 (Button, Input) | `8px` | `borderRadius` |
|
||
| 大容器 (Card, Modal) | `12px` | `borderRadiusLG` |
|
||
| 特殊场景 (登录卡片) | `16-20px` | 仅限全屏独立页面 |
|
||
| 图标背景 | `12px` | 统计卡片图标容器 |
|
||
|
||
---
|
||
|
||
## 4. 间距规范
|
||
|
||
基于 **8px** 网格系统：
|
||
|
||
| 场景 | 值 |
|
||
|------|------|
|
||
| 紧凑间距 | `8px` |
|
||
| 小间距 | `12px` |
|
||
| 标准间距 | `16px` |
|
||
| 中等间距 | `24px` (内容区 padding、页面级 margin) |
|
||
| 宽松间距 | `32px` |
|
||
|
||
**常见用法：**
|
||
|
||
```tsx
|
||
// 页面标题与内容
|
||
<Title level={4} style={{ marginBottom: 24 }}>页面标题</Title>
|
||
|
||
// Row 间距
|
||
<Row gutter={[16, 16]}>
|
||
|
||
// Card body padding
|
||
<Card styles={{ body: { padding: '20px' } }}>
|
||
|
||
// 区块间距
|
||
<Card style={{ marginBottom: 16 }}>
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 阴影规范
|
||
|
||
```
|
||
轻微: 0 1px 2px rgba(0,0,0,0.03) → 内容区、Card 默认
|
||
中等: 0 1px 3px rgba(0,0,0,0.06) → Header
|
||
悬停: var(--shadow-md) → Card:hover (全局自动)
|
||
强调: 0 25px 50px rgba(99,102,241,0.25) → 登录卡片
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 页面结构模板
|
||
|
||
### 6.1 列表页（ProTable 页面）
|
||
|
||
这是最常见的页面类型，用于设备类型、批次、用户、管理员等管理页面。
|
||
|
||
```tsx
|
||
import React, { useState, useRef } from 'react';
|
||
import { Button, message, Modal, Form, Input, Space, Tag, Popconfirm } from 'antd';
|
||
import { PlusOutlined, EditOutlined, DeleteOutlined } from '@ant-design/icons';
|
||
import { ProTable } from '@ant-design/pro-components';
|
||
import type { ProColumns, ActionType } from '@ant-design/pro-components';
|
||
import { getItems, createItem, updateItem, deleteItem } from '../../api/xxx';
|
||
import type { Item } from '../../api/xxx';
|
||
|
||
const XxxPage: React.FC = () => {
|
||
const actionRef = useRef<ActionType>(null);
|
||
const [modalVisible, setModalVisible] = useState(false);
|
||
const [editingRecord, setEditingRecord] = useState<Item | null>(null);
|
||
const [form] = Form.useForm();
|
||
const [loading, setLoading] = useState(false);
|
||
|
||
// --- CRUD handlers ---
|
||
const handleAdd = () => {
|
||
setEditingRecord(null);
|
||
form.resetFields();
|
||
setModalVisible(true);
|
||
};
|
||
|
||
const handleEdit = (record: Item) => {
|
||
setEditingRecord(record);
|
||
form.setFieldsValue(record);
|
||
setModalVisible(true);
|
||
};
|
||
|
||
const handleDelete = async (id: number) => {
|
||
try {
|
||
await deleteItem(id);
|
||
message.success('删除成功');
|
||
actionRef.current?.reload();
|
||
} catch (error) {
|
||
message.error(error instanceof Error ? error.message : '删除失败');
|
||
}
|
||
};
|
||
|
||
const handleSubmit = async () => {
|
||
try {
|
||
const values = await form.validateFields();
|
||
setLoading(true);
|
||
if (editingRecord) {
|
||
await updateItem(editingRecord.id, values);
|
||
message.success('更新成功');
|
||
} else {
|
||
await createItem(values);
|
||
message.success('创建成功');
|
||
}
|
||
setModalVisible(false);
|
||
form.resetFields();
|
||
actionRef.current?.reload();
|
||
} catch (error) {
|
||
if (error instanceof Error) {
|
||
message.error(error.message);
|
||
}
|
||
} finally {
|
||
setLoading(false);
|
||
}
|
||
};
|
||
|
||
// --- Column definitions ---
|
||
const columns: ProColumns<Item>[] = [
|
||
{
|
||
title: 'ID',
|
||
dataIndex: 'id',
|
||
width: 80,
|
||
search: false,
|
||
},
|
||
{
|
||
title: '名称',
|
||
dataIndex: 'name',
|
||
ellipsis: true,
|
||
},
|
||
{
|
||
title: '状态',
|
||
dataIndex: 'is_active',
|
||
width: 80,
|
||
search: false,
|
||
render: (_, record) => (
|
||
<Tag color={record.is_active ? 'green' : 'red'}>
|
||
{record.is_active ? '正常' : '禁用'}
|
||
</Tag>
|
||
),
|
||
},
|
||
{
|
||
title: '创建时间',
|
||
dataIndex: 'created_at',
|
||
valueType: 'dateTime',
|
||
width: 180,
|
||
search: false,
|
||
},
|
||
{
|
||
title: '操作',
|
||
width: 150,
|
||
search: false,
|
||
render: (_, record) => (
|
||
<Space>
|
||
<Button type="link" size="small" icon={<EditOutlined />}
|
||
onClick={() => handleEdit(record)}>
|
||
编辑
|
||
</Button>
|
||
<Popconfirm title="确定删除吗？" onConfirm={() => handleDelete(record.id)}>
|
||
<Button type="link" size="small" danger icon={<DeleteOutlined />}>
|
||
删除
|
||
</Button>
|
||
</Popconfirm>
|
||
</Space>
|
||
),
|
||
},
|
||
];
|
||
|
||
return (
|
||
<div>
|
||
{/* ✅ 必须加 cardBordered */}
|
||
<ProTable<Item>
|
||
headerTitle="Xxx 管理"
|
||
rowKey="id"
|
||
actionRef={actionRef}
|
||
columns={columns}
|
||
cardBordered
|
||
request={async (params) => {
|
||
try {
|
||
const res = await getItems({
|
||
page: params.current,
|
||
page_size: params.pageSize,
|
||
});
|
||
return {
|
||
data: res.data.items,
|
||
total: res.data.total,
|
||
success: true,
|
||
};
|
||
} catch (error) {
|
||
message.error('获取数据失败');
|
||
return { data: [], total: 0, success: false };
|
||
}
|
||
}}
|
||
toolBarRender={() => [
|
||
<Button key="add" type="primary" icon={<PlusOutlined />} onClick={handleAdd}>
|
||
新增
|
||
</Button>,
|
||
]}
|
||
pagination={{
|
||
defaultPageSize: 10,
|
||
showSizeChanger: true,
|
||
}}
|
||
/>
|
||
|
||
{/* Modal - 统一 layout="vertical" + marginTop 24 */}
|
||
<Modal
|
||
title={editingRecord ? '编辑' : '新增'}
|
||
open={modalVisible}
|
||
onOk={handleSubmit}
|
||
onCancel={() => setModalVisible(false)}
|
||
confirmLoading={loading}
|
||
destroyOnClose
|
||
>
|
||
<Form form={form} layout="vertical" style={{ marginTop: 24 }}>
|
||
<Form.Item name="name" label="名称"
|
||
rules={[{ required: true, message: '请输入名称' }]}>
|
||
<Input placeholder="请输入名称" />
|
||
</Form.Item>
|
||
</Form>
|
||
</Modal>
|
||
</div>
|
||
);
|
||
};
|
||
|
||
export default XxxPage;
|
||
```
|
||
|
||
**关键规则：**
|
||
|
||
1. ProTable 必须添加 `cardBordered` 属性
|
||
2. Modal 内 Form 统一 `layout="vertical"` + `style={{ marginTop: 24 }}`
|
||
3. 删除操作必须用 `Popconfirm` 确认
|
||
4. ID 列：`width: 80, search: false`
|
||
5. 时间列：`valueType: 'dateTime', width: 180, search: false`
|
||
6. 操作列：`search: false`，按钮用 `type="link" size="small"`
|
||
7. 分页统一：`defaultPageSize: 10, showSizeChanger: true`
|
||
|
||
### 6.2 详情页
|
||
|
||
```tsx
|
||
import { statColors } from '../../theme/tokens';
|
||
|
||
// 页头：返回按钮 + 标题
|
||
<Space style={{ marginBottom: 24 }} align="center">
|
||
<Button icon={<ArrowLeftOutlined />} onClick={() => navigate('/xxx')}
|
||
type="text" style={{ color: '#6b7280' }}>
|
||
返回
|
||
</Button>
|
||
<Title level={4} style={{ margin: 0, color: '#1f2937' }}>
|
||
详情 - {record.name}
|
||
</Title>
|
||
</Space>
|
||
|
||
// 信息卡片
|
||
<Card style={{ marginBottom: 16 }}>
|
||
<Descriptions column={{ xs: 1, sm: 2, md: 3 }}>
|
||
<Descriptions.Item label="字段名">值</Descriptions.Item>
|
||
</Descriptions>
|
||
</Card>
|
||
|
||
// 统计数据
|
||
<Row gutter={[16, 16]} style={{ marginBottom: 16 }}>
|
||
<Col xs={12} sm={6}>
|
||
<Card styles={{ body: { padding: '16px 20px' } }}>
|
||
<Statistic title="标题" value={100}
|
||
valueStyle={{ color: statColors.primary, fontWeight: 600 }} />
|
||
</Card>
|
||
</Col>
|
||
</Row>
|
||
|
||
// 子表格
|
||
<ProTable cardBordered search={false} ... />
|
||
```
|
||
|
||
### 6.3 统计卡片
|
||
|
||
Dashboard 风格的统计卡片模板：
|
||
|
||
```tsx
|
||
import { statColors } from '../../theme/tokens';
|
||
|
||
<Card hoverable styles={{ body: { padding: '20px' } }}>
|
||
<div style={{ display: 'flex', alignItems: 'center', gap: 14 }}>
|
||
{/* 图标容器 */}
|
||
<div style={{
|
||
width: 44, height: 44,
|
||
borderRadius: 12,
|
||
background: 'rgba(99, 102, 241, 0.08)', // 主色 8% 透明度
|
||
display: 'flex', alignItems: 'center', justifyContent: 'center',
|
||
fontSize: 20,
|
||
color: statColors.primary,
|
||
flexShrink: 0,
|
||
}}>
|
||
<UserOutlined />
|
||
</div>
|
||
{/* 数值区 */}
|
||
<div>
|
||
<div style={{ fontSize: 12, color: '#6b7280', marginBottom: 2 }}>
|
||
标题
|
||
</div>
|
||
<div style={{ fontSize: 24, fontWeight: 700, color: '#1f2937', lineHeight: 1.2 }}>
|
||
{value.toLocaleString()}
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</Card>
|
||
```
|
||
|
||
**图标背景色规则：** 使用对应 statColor 的 8% 透明度作为背景。
|
||
|
||
```
|
||
rgba(99, 102, 241, 0.08) → primary 背景
|
||
rgba(16, 185, 129, 0.08) → success 背景
|
||
rgba(139, 92, 246, 0.08) → purple 背景
|
||
rgba(245, 158, 11, 0.08) → warning 背景
|
||
rgba(6, 182, 212, 0.08) → cyan 背景
|
||
rgba(236, 72, 153, 0.08) → pink 背景
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 图表规范
|
||
|
||
使用 `@ant-design/charts`，导入方式：
|
||
|
||
```typescript
|
||
import { Pie, Column, Line, Area } from '@ant-design/charts';
|
||
```
|
||
|
||
### 7.1 饼图
|
||
|
||
```tsx
|
||
const pieConfig = {
|
||
data: [{ type: '类别', value: 100 }],
|
||
angleField: 'value',
|
||
colorField: 'type',
|
||
radius: 0.85,
|
||
innerRadius: 0.6, // 环形图
|
||
color: [statColors.primary, statColors.success, statColors.warning],
|
||
label: {
|
||
text: (d) => `${d.type}\n${d.value}`,
|
||
style: { fontSize: 12, fontWeight: 500 },
|
||
},
|
||
legend: {
|
||
color: {
|
||
position: 'bottom' as const,
|
||
layout: { justifyContent: 'center' as const },
|
||
},
|
||
},
|
||
};
|
||
<Pie {...pieConfig} />
|
||
```
|
||
|
||
### 7.2 柱状图
|
||
|
||
```tsx
|
||
const columnConfig = {
|
||
data: [{ name: '类别', value: 100 }],
|
||
xField: 'name',
|
||
yField: 'value',
|
||
style: {
|
||
radiusTopLeft: 6,
|
||
radiusTopRight: 6,
|
||
fill: statColors.primary,
|
||
fillOpacity: 0.85,
|
||
},
|
||
label: {
|
||
text: (d) => `${d.value}`,
|
||
textBaseline: 'bottom' as const,
|
||
style: { dy: -4, fontSize: 12 },
|
||
},
|
||
axis: {
|
||
y: { title: false },
|
||
x: { title: false },
|
||
},
|
||
};
|
||
<Column {...columnConfig} />
|
||
```
|
||
|
||
### 7.3 图表容器
|
||
|
||
```tsx
|
||
<Card title="图表标题" styles={{ body: { padding: '16px 24px' } }}>
|
||
<div style={{ height: 320 }}>
|
||
<ChartComponent {...config} />
|
||
</div>
|
||
</Card>
|
||
```
|
||
|
||
- 图表容器高度统一 `320px`
|
||
- 空数据时显示居中灰色提示文字
|
||
- 图表颜色优先使用 `statColors` 中的色值
|
||
|
||
---
|
||
|
||
## 8. Tag 状态映射
|
||
|
||
### 8.1 通用状态
|
||
|
||
```tsx
|
||
// 启用/禁用
|
||
<Tag color={record.is_active ? 'green' : 'red'}>
|
||
{record.is_active ? '正常' : '禁用'}
|
||
</Tag>
|
||
|
||
// 设备状态
|
||
const statusMap = {
|
||
in_stock: { color: 'default', text: '库存中' },
|
||
bound: { color: 'green', text: '已绑定' },
|
||
offline: { color: 'red', text: '离线' },
|
||
};
|
||
|
||
// 布尔属性
|
||
<Tag color={value ? 'purple' : 'default'}>{value ? '是' : '否'}</Tag>
|
||
|
||
// 缺失数据
|
||
record.field || <Tag color="orange">未导入</Tag>
|
||
```
|
||
|
||
### 8.2 角色
|
||
|
||
```tsx
|
||
const roleMap = {
|
||
super_admin: { text: '超级管理员', color: 'red' },
|
||
admin: { text: '管理员', color: 'blue' },
|
||
operator: { text: '操作员', color: 'default' },
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 响应式断点
|
||
|
||
基于 Ant Design Grid 的断点系统：
|
||
|
||
```tsx
|
||
// 统计卡片 (6列网格)
|
||
<Col xs={24} sm={12} lg={8} xl={4}>
|
||
|
||
// 图表区域 (2列)
|
||
<Col xs={24} lg={12}>
|
||
|
||
// 详情页统计 (4列)
|
||
<Col xs={12} sm={6}>
|
||
|
||
// Descriptions 响应式列数
|
||
<Descriptions column={{ xs: 1, sm: 2, md: 3 }}>
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 样式规则
|
||
|
||
### 10.1 使用优先级
|
||
|
||
1. **Ant Design Theme Token** → 优先使用 `theme.useToken()` 获取的值
|
||
2. **statColors** → 统计、图表颜色用 `statColors`
|
||
3. **CSS 变量** → 阴影、过渡动画用 `var(--xxx)`
|
||
4. **内联 style** → 布局、间距等用内联样式
|
||
5. **全局 CSS** → 仅用于 Ant Design 组件覆盖（已有的 CSS 文件）
|
||
|
||
### 10.2 禁止事项
|
||
|
||
- **不要** 硬编码 `#1890ff`（旧主题色），使用 `themeToken.colorPrimary` 或 `statColors.primary`
|
||
- **不要** 创建 `.module.css` 文件，保持现有内联样式模式
|
||
- **不要** 在页面组件中直接引用 CSS 文件，全局 CSS 已在 `App.tsx` 统一导入
|
||
- **不要** 使用 `style={{ color: '#999' }}`，用 `#6b7280` 或 `#9ca3af` 代替
|
||
- **不要** 遗漏 ProTable 的 `cardBordered` 属性
|
||
|
||
### 10.3 获取主题 Token
|
||
|
||
```tsx
|
||
import { theme } from 'antd';
|
||
|
||
const MyComponent: React.FC = () => {
|
||
const { token: themeToken } = theme.useToken();
|
||
|
||
return (
|
||
<div style={{
|
||
background: themeToken.colorBgContainer,
|
||
borderRadius: themeToken.borderRadiusLG,
|
||
color: themeToken.colorPrimary,
|
||
}}>
|
||
...
|
||
</div>
|
||
);
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 文件结构
|
||
|
||
```
|
||
src/
|
||
├── theme/
|
||
│ ├── tokens.ts # 主题配置 (themeConfig + statColors)
|
||
│ └── sidebar.css # 侧边栏样式
|
||
├── styles/
|
||
│ └── protable-theme.css # ProTable 全局样式
|
||
├── components/
|
||
│ └── Layout/
|
||
│ └── index.tsx # 主布局 (侧边栏 + 头部 + Content)
|
||
├── pages/
|
||
│ ├── Login/index.tsx # 登录页 (独立布局)
|
||
│ ├── Dashboard/index.tsx
|
||
│ ├── [Module]/
|
||
│ │ ├── index.tsx # 列表页
|
||
│ │ └── Detail.tsx # 详情页 (如有)
|
||
├── api/ # API 层
|
||
├── store/ # Zustand 状态
|
||
├── routes/index.tsx # 路由配置
|
||
├── App.tsx # 根组件 (ConfigProvider + 主题)
|
||
└── index.css # CSS 变量 + 全局基础样式
|
||
```
|
||
|
||
---
|
||
|
||
## 12. 新增页面检查清单
|
||
|
||
新开发一个页面时，逐项检查：
|
||
|
||
- [ ] ProTable 添加了 `cardBordered`
|
||
- [ ] 使用 `statColors` 而非硬编码颜色
|
||
- [ ] Tag 状态映射与已有页面一致
|
||
- [ ] Modal Form 使用 `layout="vertical"` + `style={{ marginTop: 24 }}`
|
||
- [ ] 删除操作使用 `Popconfirm`
|
||
- [ ] 时间列使用 `valueType: 'dateTime'`
|
||
- [ ] 页面标题 `<Title level={4}>` + `marginBottom: 24`
|
||
- [ ] 响应式布局使用 `Row/Col` + 正确断点
|
||
- [ ] 详情页有返回按钮 (`type="text"`)
|
||
- [ ] 空状态文字颜色使用 `#9ca3af`
|
||
- [ ] 图表容器高度 `320px`
|
||
- [ ] 分页配置 `defaultPageSize: 10, showSizeChanger: true`
|
||
|
||
---
|
||
|
||
## 13. 新增路由步骤
|
||
|
||
1. 在 `src/pages/` 下创建页面组件
|
||
2. 在 `src/routes/index.tsx` 的 `children` 数组中添加路由
|
||
3. 在 `src/components/Layout/index.tsx` 的 `menuItems` 中添加菜单项
|
||
4. 在 `src/api/` 下创建对应的 API 文件
|
||
|
||
```tsx
|
||
// routes/index.tsx
|
||
{
|
||
path: 'new-page',
|
||
element: <NewPage />,
|
||
}
|
||
|
||
// Layout/index.tsx menuItems
|
||
{
|
||
key: '/new-page',
|
||
icon: <SomeOutlined />,
|
||
label: '新页面',
|
||
}
|
||
```
|