# Web前端开发最佳实践
## 1. 页面布局规范
### 1.1 标题和查询条件区域
参考引航计划的布局方式，页面应包含以下区域：
```vue
```
### 1.2 样式规范
```css
.page-container {
padding: 15px;
height: 100vh;
overflow-y: auto;
}
.page-container h2 {
margin: 0 0 15px 0;
font-size: 18px;
color: #303133;
}
.search-section {
background: #fff;
padding: 15px;
margin-bottom: 15px;
border-radius: 4px;
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}
.search-section h3 {
margin: 0 0 12px 0;
font-size: 15px;
color: #606266;
}
.search-form {
display: flex;
flex-direction: column;
gap: 12px;
}
.search-row {
display: flex;
flex-wrap: wrap;
gap: 12px;
align-items: center;
}
.search-row .el-form-item {
margin-bottom: 0;
min-width: 200px;
}
.search-actions {
display: flex;
gap: 8px;
margin-left: auto;
}
.action-section {
margin-bottom: 15px;
display: flex;
gap: 8px;
}
.table-container {
background: #fff;
padding: 15px;
border-radius: 4px;
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
flex: 1;
display: flex;
flex-direction: column;
}
.pagination {
margin-top: 15px;
display: flex;
justify-content: center;
}
.dialog-footer {
display: flex;
justify-content: flex-end;
gap: 8px;
}
```
**关键间距说明：**
- 页面容器padding：15px
- 标题h2：font-size: 18px，margin-bottom: 15px
- 查询条件区域padding：15px，margin-bottom: 15px
- 标题h3：font-size: 15px，margin-bottom: 12px
- search-row gap：12px
- search-actions gap：8px
- 操作按钮区域margin-bottom：15px
- 表格容器padding：15px
- 分页margin-top：15px
- 对话框按钮gap：8px
**注意：** 所有间距都应保持紧凑，避免过大的空白区域，确保界面紧凑、专业。
### 1.3 表格高度和宽度规范
```vue
```
**说明：**
- 表格宽度：`calc(100vw - 331px)`，确保表格宽度适应视口宽度，减去侧边栏和边距
- 表格高度：`calc(100vh - 395px)`，确保表格高度适应视口高度，减去标题、查询条件、操作按钮和分页的高度
- 使用`size="default"`确保表格使用紧凑模式
### 1.4 Loading状态管理
```javascript
const loading = ref(false)
const deleteLoading = ref(false)
const getUsers = async () => {
if (loading.value) return
loading.value = true
try {
const response = await request.get('/user/list', {
params: {
...queryForm,
page: currentPage.value,
pageSize: pageSize.value,
sortBy: sortMap.value.sortBy,
sortOrder: sortMap.value.sortOrder
}
})
userList.value = response.data.content
total.value = response.data.totalElements
} catch (error) {
console.error('获取用户列表失败:', error)
ElMessage.error('获取用户列表失败')
} finally {
loading.value = false
}
}
```
**Loading状态应用：**
```vue
查询
重置
删除
...
```
**注意：**
- 查询和重置按钮使用`loading`状态
- 删除按钮使用`deleteLoading`状态
- 表格使用`loading`状态
- 在方法开始时检查`loading.value`，防止重复点击
- 使用`try-finally`确保loading状态一定会被恢复
## 2. 表格设计规范
### 2.1 表格属性
```vue
```
### 2.2 列设计规范
- **序号列**：宽度60px，固定居中，使用自定义模板实现连续序号
- **选择列**：宽度55px，固定居中
- **操作列**：宽度180px，固定右侧，使用图标按钮
- **状态列**：宽度80px，居中显示，使用el-tag
- **日期时间列**：宽度160px，居中显示
- **用户名列**：宽度100px
- **账号列**：宽度100px
- **用户角色列**：宽度150px
- **企业微信账号列**：宽度120px
- **其他文本列**：使用固定宽度，支持文本溢出显示
```vue
{{ (currentPage - 1) * pageSize + $index + 1 }}
{{ scope.row.recordStatusName }}
{{ formatDateTime(scope.row.createTime) }}
{{ formatDateTime(scope.row.modifyTime) }}
```
**重要说明：**
- 使用固定宽度（width）而不是最小宽度（min-width）可以避免标题栏分行
- 序号列使用自定义模板实现连续序号，公式为`(currentPage - 1) * pageSize + $index + 1`，确保分页时序号连续
- 序号列宽度使用60px，比原来的50px更合适，可以显示更大的页码
- 操作列使用180px，足够容纳3个图标按钮
- 状态列使用80px，足够显示状态标签
- 用户名和账号列使用100px，适合大多数情况
- 用户角色列使用150px，可以容纳多个角色名称（用逗号分隔）
- 企业微信账号列使用120px，适合大多数微信号长度
- 日期时间列使用160px，可以完整显示日期时间格式
### 2.4 图标按钮使用规范
操作列应使用图标按钮，而不是文字按钮，使界面更加简洁美观。
#### 2.4.1 图标按钮示例
```vue
```
#### 2.4.2 图标导入和使用
```javascript
import { Edit, Delete, User, Lock, Search } from '@element-plus/icons-vue'
export default {
components: {
Edit,
Delete,
User,
Lock,
Search
}
}
```
#### 2.4.3 常用图标说明
| 图标 | 名称 | 用途 |
|------|------|------|
| `Edit` | 编辑 | 修改数据 |
| `Delete` | 删除 | 删除数据 |
| `User` | 用户 | 用户/人员管理 |
| `Lock` | 锁定 | 锁定/重置密码 |
| `Search` | 搜索 | 搜索/查询 |
| `Plus` | 加号 | 新增 |
| `View` | 查看 | 查看详情 |
| `Download` | 下载 | 下载文件 |
| `Upload` | 上传 | 上传文件 |
| `Refresh` | 刷新 | 刷新数据 |
#### 2.4.4 图标按钮属性说明
- `type`：按钮类型，如`primary`、`success`、`warning`、`danger`、`info`
- `:icon`：图标组件，如`:icon="Edit"`
- `circle`：圆形按钮
- `size`：按钮尺寸，推荐使用`small`
- `@click`：点击事件
#### 2.4.5 Tooltip使用
使用`el-tooltip`为图标按钮提供功能提示：
```vue
```
**Tooltip属性：**
- `content`：提示文本
- `placement`：提示位置，可选值：`top`、`bottom`、`left`、`right`
### 2.3 日期时间格式化
```javascript
const formatDateTime = (dateStr) => {
if (!dateStr) return ''
const date = new Date(dateStr)
const year = date.getFullYear()
const month = String(date.getMonth() + 1).padStart(2, '0')
const day = String(date.getDate()).padStart(2, '0')
const hours = String(date.getHours()).padStart(2, '0')
const minutes = String(date.getMinutes()).padStart(2, '0')
const seconds = String(date.getSeconds()).padStart(2, '0')
return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`
}
```
## 3. 删除操作规范
### 3.1 删除确认对话框
所有删除操作都必须显示确认对话框，防止误操作。
#### 单个删除
```javascript
const deleteUser = async (id) => {
try {
await ElMessageBox.confirm(
'确定要删除该用户吗？删除后用户及其角色关联将被永久删除，不可恢复。',
'删除确认',
{
confirmButtonText: '确定',
cancelButtonText: '取消',
type: 'warning'
}
)
await request.delete(`/user/delete/${id}`)
ElMessage.success('删除成功')
getUsers()
} catch (error) {
if (error !== 'cancel') {
console.error('删除用户失败:', error)
ElMessage.error('删除用户失败')
}
}
}
```
#### 批量删除
```javascript
const deleteSelectedUsers = async () => {
if (selectedUserIds.value.length === 0) {
return
}
try {
await ElMessageBox.confirm(
`确定要删除选中的 ${selectedUserIds.value.length} 个用户吗？删除后用户及其角色关联将被永久删除，不可恢复。`,
'删除确认',
{
confirmButtonText: '确定',
cancelButtonText: '取消',
type: 'warning'
}
)
await request.delete('/user/delete', {
data: selectedUserIds.value
})
ElMessage.success('删除成功')
selectedUserIds.value = []
getUsers()
} catch (error) {
if (error !== 'cancel') {
console.error('删除用户失败:', error)
ElMessage.error('删除用户失败')
}
}
}
```
### 3.2 后端删除逻辑
删除主表数据时，必须先删除关联表数据。
```java
@Transactional
public void deleteUsers(List userIds) {
for (String userId : userIds) {
// 先删除关联表数据
sysUserRoleRepository.deleteByUserId(userId);
// 再删除主表数据
userRepository.deleteById(userId);
}
}
```
## 4. 排序功能
### 4.1 前端排序
```javascript
const handleSortChange = ({ prop, order }) => {
if (order) {
queryForm.value.sortBy = prop
queryForm.value.sortOrder = order === 'ascending' ? 'asc' : 'desc'
} else {
queryForm.value.sortBy = null
queryForm.value.sortOrder = null
}
getUsers()
}
```
### 4.2 后端排序
```java
public Page queryUsers(UserQuery query, Pageable pageable) {
Sort sort = pageable.getSort();
if (query.getSortBy() != null && query.getSortOrder() != null) {
sort = Sort.by(
"asc".equalsIgnoreCase(query.getSortOrder()) ? Sort.Direction.ASC : Sort.Direction.DESC,
query.getSortBy()
);
}
return userRepository.findAll(pageable.withSort(sort));
}
```
## 5. API请求规范
### 5.1 使用request.js
所有API请求都应该使用统一的request工具，自动处理认证和错误。
```javascript
import request from '@/utils/request'
export const getUsers = (params) => {
return request.get('/user/list', { params })
}
export const createUser = (data) => {
return request.post('/user/create', data)
}
export const deleteUser = (data) => {
return request.delete('/user/delete', { data })
}
```
### 5.2 错误处理
```javascript
try {
await request.post('/api/endpoint', data)
ElMessage.success('操作成功')
} catch (error) {
console.error('操作失败:', error)
ElMessage.error('操作失败，请稍后重试')
}
```
## 6. 表单验证
### 6.1 前端验证
```vue
```
### 6.2 后端验证
```java
public class UserCreateDTO {
@NotBlank(message = "用户名不能为空")
@Size(min = 2, max = 50, message = "用户名长度必须在2-50之间")
private String name;
@NotBlank(message = "账号不能为空")
private String loginId;
@NotBlank(message = "密码不能为空")
@Size(min = 6, message = "密码长度不能少于6位")
private String password;
}
```
## 7. 代码规范
### 7.1 命名规范
- 组件名：使用PascalCase，如`UserManagement.vue`
- 方法名：使用camelCase，如`getUsers`、`handleSortChange`
- 变量名：使用camelCase，如`userList`、`selectedIds`
- 常量名：使用UPPER_SNAKE_CASE，如`MAX_PAGE_SIZE`
### 7.2 注释规范
```javascript
/**
* 获取用户列表
*/
const getUsers = async () => {
// 实现代码
}
/**
* 处理排序变化
* @param {Object} param - 排序参数
* @param {String} param.prop - 排序字段
* @param {String} param.order - 排序方向
*/
const handleSortChange = ({ prop, order }) => {
// 实现代码
}
```
## 8. 性能优化
### 8.1 防抖和节流
```javascript
import { debounce } from 'lodash-es'
const search = debounce(() => {
getUsers()
}, 300)
```
### 8.2 虚拟滚动
对于大量数据，使用虚拟滚动提高性能。
```vue
```
## 9. 安全规范
### 9.1 XSS防护
使用Vue的插值表达式，避免直接使用v-html。
```vue
{{ user.name }}
```
### 9.2 CSRF防护
所有POST、PUT、DELETE请求都应该携带CSRF token。
```javascript
import request from '@/utils/request'
request.interceptors.request.use(config => {
const token = localStorage.getItem('csrf_token')
if (token) {
config.headers['X-CSRF-TOKEN'] = token
}
return config
})
```
## 10. 可访问性
### 10.1 语义化HTML
```vue
页面标题
```
### 10.2 键盘导航
确保所有交互元素都可以通过键盘访问。
```vue
点击
```
## 11. 搜索下拉框规范
### 11.1 适用场景
对于选项数量较多的下拉选择框（如船公司、代理公司、港口等），应使用可搜索的下拉框，并实现远程搜索和分页加载功能。
### 11.2 搜索下拉框实现
#### 11.2.1 模板部分
```vue
```
#### 11.2.2 数据属性
```javascript
data() {
return {
searchForm: {
shipownerId: ''
},
shipCompanyList: [],
shipCompanyQuery: '',
shipCompanyPage: 1,
shipCompanyPageSize: 10,
shipCompanyLoading: false,
shipCompanyHasMore: true
}
}
```
#### 11.2.3 方法实现
```javascript
methods: {
getShipCompanyList() {
this.getShipCompanyListByPage('', 1);
},
getShipCompanyListByPage(query, page) {
this.shipCompanyLoading = true;
this.$axios.get('/api/ship-company/list', {
params: {
companyName: query,
page: page,
pageSize: this.shipCompanyPageSize
}
})
.then(response => {
if (page === 1) {
this.shipCompanyList = response.data.content || [];
} else {
this.shipCompanyList = [...this.shipCompanyList, ...(response.data.content || [])];
}
this.shipCompanyHasMore = response.data.content && response.data.content.length >= this.shipCompanyPageSize;
})
.catch(error => {
console.error('获取船公司列表失败:', error);
this.$message.error('获取船公司列表失败，请稍后重试');
})
.finally(() => {
this.shipCompanyLoading = false;
});
},
searchShipCompany(query) {
this.shipCompanyQuery = query || '';
this.shipCompanyPage = 1;
this.getShipCompanyListByPage(this.shipCompanyQuery, this.shipCompanyPage);
},
handleShipCompanyVisibleChange(visible) {
if (visible && !this.shipCompanyQuery) {
this.shipCompanyPage = 1;
this.getShipCompanyListByPage('', this.shipCompanyPage);
}
},
handleShipCompanyScroll() {
if (this.shipCompanyHasMore && !this.shipCompanyLoading) {
this.shipCompanyPage++;
this.getShipCompanyListByPage(this.shipCompanyQuery, this.shipCompanyPage);
}
}
}
```
### 11.3 后端API规范
#### 11.3.1 Controller实现
```java
@GetMapping("/list")
public Page list(
@RequestParam(required = false) String companyName,
@RequestParam(defaultValue = "1") int page,
@RequestParam(defaultValue = "10") int pageSize
) {
Pageable pageable = PageRequest.of(page - 1, pageSize, Sort.by("companyName").ascending());
return shipCompanyService.searchCompanies(companyName, pageable);
}
```
#### 11.3.2 Service实现
```java
@Service
public class ShipCompanyService {
@Autowired
private ShipCompanyRepository shipCompanyRepository;
public Page searchCompanies(String companyName, Pageable pageable) {
Specification spec = (root, query, cb) -> {
List predicates = new ArrayList<>();
if (companyName != null && !companyName.isEmpty()) {
predicates.add(cb.like(root.get("companyName"), "%" + companyName + "%"));
}
predicates.add(cb.equal(root.get("recordStatus"), 1));
return cb.and(predicates.toArray(new Predicate[0]));
};
Page companies = shipCompanyRepository.findAll(spec, pageable);
return companies.map(ShipCompanyDTO::fromEntity);
}
}
```
### 11.4 关键属性说明
| 属性 | 说明 |
|------|------|
| filterable | 启用本地过滤功能 |
| remote | 启用远程搜索 |
| remote-method | 远程搜索方法，当用户输入时触发 |
| loading | 加载状态，用于显示加载动画 |
| visible-change | 下拉框显示/隐藏时触发 |
| scroll | 下拉列表滚动时触发，用于实现瀑布加载 |
### 11.5 注意事项
1. **分页大小**：建议每页加载10-20条记录
2. **防抖处理**：远程搜索建议添加防抖，避免频繁请求
3. **错误处理**：必须添加错误处理和用户提示
4. **加载状态**：必须显示加载状态，提升用户体验
5. **清空处理**：清空搜索条件时，应重置分页和列表
6. **首次加载**：下拉框首次打开时，应加载第一页数据
7. **前后端数据结构不一致处理**：当前后端数据结构不一致时，应优先修改前端代码来适应后端返回的数据格式，因为后端的方法可能被多个地方调用，修改后端可能影响其他功能。前端可以通过以下方式适应后端：
- 使用本地过滤和分页：如果后端返回全部数据，前端可以在本地进行过滤和分页
- 数据转换：在前端对后端返回的数据进行必要的转换
- 兼容性处理：使用可选链操作符（`?.`）和默认值处理可能的字段缺失