Web前端开发最佳实践

1. 页面布局规范

1.1 标题和查询条件区域

参考引航计划的布局方式，页面应包含以下区域：

<template>
  <div class="page-container">
    <!-- 页面标题 -->
    <h2>页面名称</h2>
    
    <!-- 查询条件区域 -->
    <div class="search-section">
      <h3>查询条件</h3>
      <el-form :model="queryForm" class="search-form">
        <div class="search-row">
          <el-form-item label="字段名">
            <el-input v-model="queryForm.field" placeholder="请输入..." clearable></el-input>
          </el-form-item>
          <!-- 更多查询条件 -->
          <div class="search-actions">
            <el-button type="primary" @click="query">查询</el-button>
            <el-button @click="reset">重置</el-button>
          </div>
        </div>
      </el-form>
    </div>
    
    <!-- 操作按钮区域 -->
    <div class="action-section">
      <el-button type="primary" @click="add">新增</el-button>
      <el-button type="danger" @click="deleteSelected" :disabled="selectedIds.length === 0">删除</el-button>
    </div>
    
    <!-- 表格区域 -->
    <div class="table-container">
      <el-table>...</el-table>
    </div>
  </div>
</template>

1.2 样式规范

.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 表格高度和宽度规范

<el-table
  :data="tableData"
  stripe
  border
  size="default"
  :header-cell-style="{ background: '#f5f7fa', color: '#303133', fontWeight: 'bold' }"
  style="width: calc(100vw - 331px); height: calc(100vh - 395px);">

说明：

表格宽度：calc(100vw - 331px)，确保表格宽度适应视口宽度，减去侧边栏和边距
表格高度：calc(100vh - 395px)，确保表格高度适应视口高度，减去标题、查询条件、操作按钮和分页的高度
使用size="default"确保表格使用紧凑模式

1.4 Loading状态管理

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状态应用：

<el-button type="primary" @click="getUsers" :loading="loading">查询</el-button>
<el-button @click="resetSearchForm" :loading="loading">重置</el-button>
<el-button type="danger" @click="deleteSelectedUsers" :disabled="selectedIds.length === 0" :loading="deleteLoading">删除</el-button>
<el-table v-loading="loading" :data="userList">...</el-table>

注意：

查询和重置按钮使用loading状态
删除按钮使用deleteLoading状态
表格使用loading状态
在方法开始时检查loading.value，防止重复点击
使用try-finally确保loading状态一定会被恢复

2. 表格设计规范

2.1 表格属性

<el-table
  :data="tableData"
  stripe
  border
  size="default"
  :header-cell-style="{ background: '#f5f7fa', color: '#303133', fontWeight: 'bold' }"
  :height="tableHeight"
  @selection-change="handleSelectionChange"
  @sort-change="handleSortChange">

2.2 列设计规范

序号列：宽度60px，固定居中，使用自定义模板实现连续序号
选择列：宽度55px，固定居中
操作列：宽度180px，固定右侧，使用图标按钮
状态列：宽度80px，居中显示，使用el-tag
日期时间列：宽度160px，居中显示
用户名列：宽度100px
账号列：宽度100px
用户角色列：宽度150px
企业微信账号列：宽度120px
其他文本列：使用固定宽度，支持文本溢出显示

<el-table-column type="selection" width="55" fixed align="center"></el-table-column>
<el-table-column label="序号" width="60" fixed align="center">
  <template #default="{ $index }">
    {{ (currentPage - 1) * pageSize + $index + 1 }}
  </template>
</el-table-column>
<el-table-column prop="name" label="用户名" width="100" sortable show-overflow-tooltip></el-table-column>
<el-table-column prop="loginId" label="账号" width="100" sortable show-overflow-tooltip></el-table-column>
<el-table-column prop="roleName" label="用户角色" width="150" sortable show-overflow-tooltip></el-table-column>
<el-table-column prop="weChatUserId" label="企业微信账号" width="120" sortable show-overflow-tooltip></el-table-column>
<el-table-column prop="recordStatusName" label="状态" width="80" sortable align="center">
  <template #default="scope">
    <el-tag :type="scope.row.recordStatus === 1 ? 'success' : 'info'" size="small">
      {{ scope.row.recordStatusName }}
    </el-tag>
  </template>
</el-table-column>
<el-table-column prop="createTime" label="创建时间" width="160" sortable align="center" show-overflow-tooltip>
  <template #default="scope">
    {{ formatDateTime(scope.row.createTime) }}
  </template>
</el-table-column>
<el-table-column prop="modifyTime" label="修改时间" width="160" sortable align="center" show-overflow-tooltip>
  <template #default="scope">
    {{ formatDateTime(scope.row.modifyTime) }}
  </template>
</el-table-column>
<el-table-column label="操作" width="180" align="center" fixed="right">
  <template #default="{ row }">
    <el-tooltip content="编辑" placement="top">
      <el-button type="primary" :icon="Edit" circle size="small" @click="edit(row)"></el-button>
    </el-tooltip>
    <el-tooltip content="删除" placement="top">
      <el-button type="danger" :icon="Delete" circle size="small" @click="delete(row.id)"></el-button>
    </el-tooltip>
  </template>
</el-table-column>

重要说明：

使用固定宽度（width）而不是最小宽度（min-width）可以避免标题栏分行
序号列使用自定义模板实现连续序号，公式为(currentPage - 1) * pageSize + $index + 1，确保分页时序号连续
序号列宽度使用60px，比原来的50px更合适，可以显示更大的页码
操作列使用180px，足够容纳3个图标按钮
状态列使用80px，足够显示状态标签
用户名和账号列使用100px，适合大多数情况
用户角色列使用150px，可以容纳多个角色名称（用逗号分隔）
企业微信账号列使用120px，适合大多数微信号长度
日期时间列使用160px，可以完整显示日期时间格式

2.4 图标按钮使用规范

操作列应使用图标按钮，而不是文字按钮，使界面更加简洁美观。

2.4.1 图标按钮示例

<el-table-column label="操作" width="180" align="center" fixed="right">
  <template #default="{ row }">
    <el-tooltip content="编辑" placement="top">
      <el-button type="primary" :icon="Edit" circle size="small" @click="edit(row)"></el-button>
    </el-tooltip>
    <el-tooltip content="删除" placement="top">
      <el-button type="danger" :icon="Delete" circle size="small" @click="delete(row.id)"></el-button>
    </el-tooltip>
  </template>
</el-table-column>

2.4.2 图标导入和使用

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为图标按钮提供功能提示：

<el-tooltip content="编辑" placement="top">
  <el-button type="primary" :icon="Edit" circle size="small" @click="edit(row)"></el-button>
</el-tooltip>

Tooltip属性：

content：提示文本
placement：提示位置，可选值：top、bottom、left、right

2.3 日期时间格式化

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 删除确认对话框

所有删除操作都必须显示确认对话框，防止误操作。

单个删除

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('删除用户失败')
    }
  }
}

批量删除

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 后端删除逻辑

删除主表数据时，必须先删除关联表数据。

@Transactional
public void deleteUsers(List<String> userIds) {
    for (String userId : userIds) {
        // 先删除关联表数据
        sysUserRoleRepository.deleteByUserId(userId);
        // 再删除主表数据
        userRepository.deleteById(userId);
    }
}

4. 排序功能

4.1 前端排序

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 后端排序

public Page<User> 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工具，自动处理认证和错误。

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 错误处理

try {
  await request.post('/api/endpoint', data)
  ElMessage.success('操作成功')
} catch (error) {
  console.error('操作失败:', error)
  ElMessage.error('操作失败，请稍后重试')
}

6. 表单验证

6.1 前端验证

<el-form :model="form" :rules="rules" ref="formRef">
  <el-form-item label="用户名" prop="name">
    <el-input v-model="form.name" placeholder="请输入用户名"></el-input>
  </el-form-item>
</el-form>

<script>
const rules = {
  name: [
    { required: true, message: '请输入用户名', trigger: 'blur' },
    { min: 2, max: 50, message: '长度在 2 到 50 个字符', trigger: 'blur' }
  ]
}
</script>

6.2 后端验证

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 注释规范

/**
 * 获取用户列表
 */
const getUsers = async () => {
  // 实现代码
}

/**
 * 处理排序变化
 * @param {Object} param - 排序参数
 * @param {String} param.prop - 排序字段
 * @param {String} param.order - 排序方向
 */
const handleSortChange = ({ prop, order }) => {
  // 实现代码
}

8. 性能优化

8.1 防抖和节流

import { debounce } from 'lodash-es'

const search = debounce(() => {
  getUsers()
}, 300)

8.2 虚拟滚动

对于大量数据，使用虚拟滚动提高性能。

<el-table
  :data="tableData"
  height="600"
  v-loading="loading">
</el-table>

9. 安全规范

9.1 XSS防护

使用Vue的插值表达式，避免直接使用v-html。

<!-- 正确 -->
<div>{{ user.name }}</div>

<!-- 错误 -->
<div v-html="user.name"></div>

9.2 CSRF防护

所有POST、PUT、DELETE请求都应该携带CSRF token。

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

<nav>...</nav>
<main>
  <h1>页面标题</h1>
  <section class="search-section">...</section>
  <section class="table-section">...</section>
</main>
<footer>...</footer>

10.2 键盘导航

确保所有交互元素都可以通过键盘访问。

<el-button @click="handleClick" @keyup.enter="handleClick">
  点击
</el-button>

11. 搜索下拉框规范

11.1 适用场景

对于选项数量较多的下拉选择框（如船公司、代理公司、港口等），应使用可搜索的下拉框，并实现远程搜索和分页加载功能。

11.2 搜索下拉框实现

11.2.1 模板部分

<el-form-item label="船公司">
  <el-select
    v-model="searchForm.shipownerId"
    placeholder="请选择"
    style="width: 180px"
    clearable
    filterable
    remote
    :remote-method="searchShipCompany"
    :loading="shipCompanyLoading"
    @visible-change="handleShipCompanyVisibleChange"
    @scroll="handleShipCompanyScroll"
  >
    <el-option
      v-for="company in shipCompanyList"
      :key="company.companyId"
      :label="company.companyName"
      :value="company.companyId">
    </el-option>
  </el-select>
</el-form-item>

11.2.2 数据属性

data() {
  return {
    searchForm: {
      shipownerId: ''
    },
    shipCompanyList: [],
    shipCompanyQuery: '',
    shipCompanyPage: 1,
    shipCompanyPageSize: 10,
    shipCompanyLoading: false,
    shipCompanyHasMore: true
  }
}

11.2.3 方法实现

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实现

@GetMapping("/list")
public Page<ShipCompanyDTO> 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实现

@Service
public class ShipCompanyService {
    
    @Autowired
    private ShipCompanyRepository shipCompanyRepository;
    
    public Page<ShipCompanyDTO> searchCompanies(String companyName, Pageable pageable) {
        Specification<ShipCompany> spec = (root, query, cb) -> {
            List<Predicate> 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<ShipCompany> companies = shipCompanyRepository.findAll(spec, pageable);
        return companies.map(ShipCompanyDTO::fromEntity);
    }
}

11.4 关键属性说明

属性	说明
filterable	启用本地过滤功能
remote	启用远程搜索
remote-method	远程搜索方法，当用户输入时触发
loading	加载状态，用于显示加载动画
visible-change	下拉框显示/隐藏时触发
scroll	下拉列表滚动时触发，用于实现瀑布加载

11.5 注意事项

分页大小：建议每页加载10-20条记录
防抖处理：远程搜索建议添加防抖，避免频繁请求
错误处理：必须添加错误处理和用户提示
加载状态：必须显示加载状态，提升用户体验
清空处理：清空搜索条件时，应重置分页和列表
首次加载：下拉框首次打开时，应加载第一页数据
前后端数据结构不一致处理：当前后端数据结构不一致时，应优先修改前端代码来适应后端返回的数据格式，因为后端的方法可能被多个地方调用，修改后端可能影响其他功能。前端可以通过以下方式适应后端：
- 使用本地过滤和分页：如果后端返回全部数据，前端可以在本地进行过滤和分页
- 数据转换：在前端对后端返回的数据进行必要的转换
- 兼容性处理：使用可选链操作符（?.）和默认值处理可能的字段缺失

web-dev-best-practices.md 22 KB Historia Czysty