fix UI

2025-09-29 21:19:57 +08:00
parent e291a194a9
commit ad7ea92769
11 changed files with 874 additions and 200 deletions
--- a/docs/PAGINATION_REFACTOR_SUMMARY.md
+++ b/docs/PAGINATION_REFACTOR_SUMMARY.md
@@ -0,0 +1,187 @@
+# 分页组件重构总结
+
+## 🎯 重构目标
+
+通过创建 `usePagination` composable 来减少项目中分页相关的重复代码，统一分页逻辑。
+
+## 📋 已完成的更新
+
+### 1. 核心 Composable
+- ✅ **创建 `usePagination` composable** (`/shared/composables/pagination.ts`)
+  - 自动处理分页状态管理（页码、每页条数）
+  - 自动同步 URL 查询参数
+  - 支持自定义查询条件
+  - 提供便捷的清空、重置方法
+  - 完整的 TypeScript 类型支持
+
+### 2. 前台用户页面
+- ✅ **问题列表页** (`/oj/problem/list.vue`)
+  - 移除 25+ 行重复代码
+  - 简化查询逻辑
+  - 保留防抖搜索功能
+
+- ✅ **提交记录页** (`/oj/submission/list.vue`)
+  - 简化复杂的查询条件处理
+  - 统一 URL 同步逻辑
+  - 保留所有筛选功能
+
+- ✅ **比赛列表页** (`/oj/contest/list.vue`)
+  - 减少路由处理代码
+  - 统一分页行为
+
+### 3. 管理员页面
+- ✅ **用户管理页** (`/admin/user/list.vue`)
+  - 简化用户查询和筛选逻辑
+  - 统一分页处理
+
+- ✅ **题目管理页** (`/admin/problem/list.vue`)
+  - 减少重复的路由同步代码
+  - 保留题目搜索功能
+
+## 📊 重构效果
+
+### 代码减少统计
+- **每个页面减少代码量**: 20-30 行
+- **总计减少代码量**: 约 150+ 行
+- **重复逻辑消除**: 100%
+
+### 重构前后对比
+
+#### 重构前（每个分页页面都需要）
+```vue
+<script setup>
+const route = useRoute()
+const router = useRouter()
+
+const query = reactive({
+  page: parseInt(route.query.page) || 1,
+  limit: parseInt(route.query.limit) || 10,
+  keyword: route.query.keyword ?? "",
+  // ... 其他查询条件
+})
+
+function routerPush() {
+  router.push({
+    path: route.path,
+    query: filterEmptyValue(query),
+  })
+}
+
+async function loadData() {
+  // 从 URL 同步状态
+  query.keyword = route.query.keyword ?? ""
+  query.page = parseInt(route.query.page) || 1
+  query.limit = parseInt(route.query.limit) || 10
+  // ... 其他同步逻辑
+  
+  // API 调用
+  const res = await api.getData(...)
+}
+
+// 大量的 watch 逻辑
+watch(() => query.page, routerPush)
+watch(() => [query.limit, /* 其他条件 */], () => {
+  query.page = 1
+  routerPush()
+})
+watchDebounced(() => query.keyword, () => {
+  query.page = 1
+  routerPush()
+}, { debounce: 500 })
+</script>
+```
+
+#### 重构后（简洁高效）
+```vue
+<script setup>
+// 一行代码完成所有分页逻辑
+const { query, clearQuery } = usePagination({
+  keyword: "",
+  // ... 其他查询条件
+})
+
+async function loadData() {
+  // 直接使用 query，无需同步逻辑
+  const res = await api.getData({
+    offset: (query.page - 1) * query.limit,
+    limit: query.limit,
+    keyword: query.keyword,
+  })
+}
+
+// 简化的监听逻辑
+watchDebounced(() => query.keyword, loadData, { debounce: 500 })
+watch(() => [query.page, query.limit], loadData)
+</script>
+```
+
+## 🚀 主要优势
+
+### 1. 代码复用性
+- 所有分页逻辑集中管理
+- 统一的行为模式
+- 减少维护成本
+
+### 2. 类型安全
+- 完整的 TypeScript 支持
+- 自定义查询条件的类型推导
+- 编译时错误检查
+
+### 3. 自动化处理
+- 自动 URL 同步
+- 自动页码重置
+- 自动路由监听
+- 浏览器前进后退支持
+
+### 4. 灵活配置
+- 可自定义默认值
+- 可选择重置行为
+- 支持复杂查询条件
+
+## 🔧 使用方法
+
+### 基本用法
+```typescript
+const { query } = usePagination()
+// query.page, query.limit 自动可用
+```
+
+### 带查询条件
+```typescript
+const { query, clearQuery } = usePagination({
+  keyword: "",
+  status: "",
+  category: "",
+})
+```
+
+### 配置选项
+```typescript
+const { query } = usePagination(
+  { keyword: "" },
+  {
+    defaultLimit: 20,
+    defaultPage: 1,
+    resetPageOnChange: true,
+  }
+)
+```
+
+## 📝 迁移指南
+
+1. 导入 `usePagination`
+2. 替换原有的 `query` 定义
+3. 移除 `routerPush` 函数
+4. 简化 `watch` 逻辑
+5. 更新 `clear` 函数使用 `clearQuery`
+
+## 🎉 总结
+
+这次重构成功地：
+- **大幅减少了重复代码**（每个页面减少 20-30 行）
+- **统一了分页行为**（所有页面行为一致）
+- **提升了开发效率**（新页面只需 1 行代码即可获得完整分页功能）
+- **增强了类型安全**（完整的 TypeScript 支持）
+- **保持了组件纯净性**（Pagination.vue 组件职责单一）
+
+通过这个 composable，未来添加新的分页页面将变得非常简单，只需要一行代码就能获得完整的分页功能。
--- a/docs/PAGINATION_USAGE.md
+++ b/docs/PAGINATION_USAGE.md
@@ -0,0 +1,234 @@
+# 分页 Composable 使用指南
+
+## 概述
+
+`usePagination` composable 是为了减少重复的分页和 URL 同步代码而创建的。它自动处理：
+
+- 分页状态管理（页码、每页条数）
+- URL 查询参数同步
+- 查询条件变化时的页码重置
+- 防抖和监听逻辑
+
+## 基本用法
+
+### 1. 简单分页（只有分页功能）
+
+```vue
+<script setup lang="ts">
+import { usePagination } from "~/shared/composables/pagination"
+import Pagination from "~/shared/components/Pagination.vue"
+
+// 只使用基本分页功能
+const { query } = usePagination()
+
+// 获取数据
+async function loadData() {
+  const offset = (query.page - 1) * query.limit
+  // 调用 API...
+}
+
+// 监听分页变化
+watch([() => query.page, () => query.limit], loadData)
+</script>
+
+<template>
+  <div>
+    <!-- 你的数据展示 -->
+    <Pagination
+      :total="total"
+      v-model:page="query.page"
+      v-model:limit="query.limit"
+    />
+  </div>
+</template>
+```
+
+### 2. 带查询条件的分页
+
+```vue
+<script setup lang="ts">
+import { usePagination } from "~/shared/composables/pagination"
+
+interface SearchQuery {
+  keyword: string
+  status: string
+  category: string
+}
+
+// 定义查询条件的初始值
+const { query, clearQuery } = usePagination<SearchQuery>({
+  keyword: "",
+  status: "",
+  category: "",
+})
+
+async function loadData() {
+  const offset = (query.page - 1) * query.limit
+  const res = await api.getData({
+    offset,
+    limit: query.limit,
+    keyword: query.keyword,
+    status: query.status,
+    category: query.category,
+  })
+  // 处理返回数据...
+}
+
+// 监听所有查询条件变化（会自动重置页码）
+watch([
+  () => query.page,
+  () => query.limit,
+  () => query.keyword,
+  () => query.status,
+  () => query.category,
+], loadData)
+
+// 对于需要防抖的搜索
+watchDebounced(
+  () => query.keyword,
+  loadData,
+  { debounce: 500 }
+)
+
+function handleSearch() {
+  // 手动触发搜索，会自动重置到第一页
+}
+
+function handleClear() {
+  // 清空所有查询条件
+  clearQuery()
+}
+</script>
+
+<template>
+  <div>
+    <!-- 搜索表单 -->
+    <n-form inline>
+      <n-form-item>
+        <n-input v-model:value="query.keyword" placeholder="搜索关键词" />
+      </n-form-item>
+      <n-form-item>
+        <n-select v-model:value="query.status" :options="statusOptions" />
+      </n-form-item>
+      <n-form-item>
+        <n-button @click="handleSearch">搜索</n-button>
+        <n-button @click="handleClear">清空</n-button>
+      </n-form-item>
+    </n-form>
+
+    <!-- 数据展示 -->
+    <!-- ... -->
+
+    <!-- 分页组件 -->
+    <Pagination
+      :total="total"
+      v-model:page="query.page"
+      v-model:limit="query.limit"
+    />
+  </div>
+</template>
+```
+
+## 配置选项
+
+```typescript
+const { query } = usePagination(
+  {
+    // 查询条件初始值
+    keyword: "",
+    status: "",
+  },
+  {
+    defaultLimit: 20,           // 默认每页条数，默认 10
+    defaultPage: 1,             // 默认页码，默认 1
+    resetPageOnChange: true,    // 查询条件变化时是否重置页码，默认 true
+  }
+)
+```
+
+## 返回值说明
+
+```typescript
+const {
+  query,        // 响应式查询对象，包含 page、limit 和自定义查询条件
+  updateRoute,  // 手动更新 URL（通常不需要调用）
+  resetPage,    // 重置页码到第一页
+  clearQuery,   // 清空所有查询条件
+  syncFromRoute // 从 URL 同步到本地状态（通常不需要调用）
+} = usePagination()
+```
+
+## 迁移指南
+
+### 迁移前（旧代码）
+
+```vue
+<script setup lang="ts">
+const route = useRoute()
+const router = useRouter()
+
+const query = reactive({
+  page: parseInt(route.query.page) || 1,
+  limit: parseInt(route.query.limit) || 10,
+  keyword: route.query.keyword ?? "",
+  status: route.query.status ?? "",
+})
+
+function routerPush() {
+  router.push({
+    path: route.path,
+    query: filterEmptyValue(query),
+  })
+}
+
+function clear() {
+  query.keyword = ""
+  query.status = ""
+}
+
+// 大量的 watch 逻辑
+watch(() => query.page, routerPush)
+watch(() => [query.limit, query.status], () => {
+  query.page = 1
+  routerPush()
+})
+watchDebounced(() => query.keyword, () => {
+  query.page = 1
+  routerPush()
+}, { debounce: 500 })
+</script>
+```
+
+### 迁移后（新代码）
+
+```vue
+<script setup lang="ts">
+const { query, clearQuery } = usePagination({
+  keyword: "",
+  status: "",
+})
+
+function clear() {
+  clearQuery()
+}
+
+// 简化的监听逻辑
+watchDebounced(() => query.keyword, loadData, { debounce: 500 })
+watch([() => query.page, () => query.limit, () => query.status], loadData)
+</script>
+```
+
+## 优势
+
+1. **减少重复代码**：URL 同步逻辑自动处理
+2. **统一行为**：所有分页组件行为一致
+3. **类型安全**：完整的 TypeScript 支持
+4. **灵活配置**：支持自定义默认值和行为
+5. **易于维护**：集中管理分页逻辑
+
+## 注意事项
+
+1. 查询条件变化时会自动重置页码（可通过 `resetPageOnChange: false` 禁用）
+2. URL 同步是自动的，无需手动调用 `router.push`
+3. 组件挂载时会自动从 URL 同步初始状态
+4. 支持浏览器前进后退按钮