Vue3 后台分页开发终极指南：用 Hooks 删掉 90% 重复代码，实现高效、可复用分页系统（附完整源码与高级扩展）

引言：为什么 Vue3 分页开发需要革命性变革？

在现代前端开发中，尤其是后台管理系统（Admin Panel）的构建，Vue3 作为一款高效、响应式的框架，已经成为许多开发者的首选。然而，当我们面对海量数据时，分页（Pagination）功能几乎是不可或缺的。它不仅能提升用户体验，还能优化性能，避免一次性加载所有数据导致的卡顿或内存溢出。

传统分页开发往往陷入重复劳动的泥沼：每个列表页都需要手动管理当前页码（currentPage）、每页条数（pageSize）、数据总数（total）、加载状态（loading）、错误处理（error handling）、搜索逻辑（search）、刷新机制（refresh）、翻页事件（onCurrentChange）和页大小变更（onSizeChange）。这些代码散落在各个组件中，导致维护成本飙升。如果项目中有数十个列表页，这种重复代码量可能高达数千行！

想象一下：一个中型后台系统，可能有用户列表、订单列表、商品列表等，每个都需要类似的分页逻辑。如果不优化，开发者可能会花费数小时复制粘贴代码，稍有改动就得全局同步。更糟糕的是，这种方式容易引入 bug，比如忘记更新加载状态或处理边缘案例（如空数据或网络错误）。

为了解决这些痛点，本文将深入探讨如何使用 Vue3 的 Composition API 封装自定义 Hooks，特别是 useFetch（基础请求 Hook）和 usePageFetch（分页专用 Hook）。通过这些 Hooks，我们可以删掉 90% 的重复代码，只需几行引入和调用，就能实现完整的分页功能。文章将从基础概念入手，逐步展开实现细节、完整源码、实际示例、高级用法、最佳实践、性能优化、与其他库的比较，以及潜在问题排查。目标是帮助你构建一个高效、可复用、可扩展的分页系统。

如果你是对 Vue3 新手，别担心，我们会从头讲解；如果你是资深开发者，这里有高级技巧和源码扩展，能让你进一步优化项目。

实战推荐：

  • ⚡ 一个 Vue 自定义指令搞定丝滑拖拽列表，告别复杂组件封装
  • 🔥 这才是 Vue 驱动的 Chrome 插件工程化正确打开方式
  • 🌟 Vue3 与 Pinia 结合的最佳状态管理实践

第一章：Vue3 Composition API 基础回顾——Hooks 的基石

在深入 Hooks 之前，我们先回顾 Vue3 的 Composition API，这是创建自定义 Hooks 的核心。Composition API 是 Vue3 引入的重大变革，它允许开发者在组件外部组织逻辑，取代了 Vue2 的 Options API 中的混沌结构。

1.1 Composition API 的核心概念

  • setup() 函数：组件的入口点，所有逻辑在这里定义。返回的对象会暴露给模板。
  • ref() 和 reactive()：创建响应式数据。ref 用于基本类型，reactive 用于对象。
  • watch() 和 watchEffect()：监视数据变化，执行副作用。
  • 生命周期钩子：如 onMounted、onUnmounted，用于管理组件生命周期。
  • toRefs() 和 toValue()：辅助工具，确保响应性不丢失。

示例：一个简单计数器 Hook。

// hooks/useCounter.js
import { ref } from "vue";

export function useCounter(initialValue = 0) {
  const count = ref(initialValue);
  const increment = () => count.value++;
  const decrement = () => count.value--;
  return { count, increment, decrement };
}

使用：

<script setup>
import { useCounter } from "@/hooks/useCounter";
const { count, increment } = useCounter(10);
</script>

<template>
  <button @click="increment">Count: {{ count }}</button>
</template>

这个例子展示了 Hooks 的本质：封装可复用逻辑，减少组件内代码。

1.2 为什么用 Hooks 解决分页问题？

分页涉及状态管理和副作用：

  • 状态：页码、数据列表、总数。
  • 副作用：API 请求、错误处理、加载动画。
    传统方式在每个组件重复这些逻辑，而 Hooks 可以提取到独立文件，实现“一次编写，到处使用”。

根据 Vue 官方文档，Composables（即 Hooks）适合处理数据获取、状态共享等场景。分页正是典型应用：它需要响应页码变化自动请求数据。

1.3 Hooks 的优势与潜在陷阱

优势：

  • 可复用性：一个 Hook 服务多个组件。
  • 可组合性：Hooks 可以嵌套调用。
  • 易测试：独立于组件，便于单元测试。
  • 减少代码：据统计，使用 Hooks 可减少 70-90% 重复代码。

陷阱：

  • 响应性丢失：返回对象时用 toRefs。
  • 生命周期管理：忘记 onUnmounted 可能导致内存泄漏。
  • 过度抽象：不要为简单逻辑创建 Hooks。

在分页场景中，这些优势尤为突出。接下来，我们进入核心实现。

第二章：基础请求 Hook —— useFetch 的设计与实现

useFetch 是分页系统的底层支撑，它封装了通用 API 请求逻辑，包括加载状态、错误处理和缓存机制。为什么需要它？因为分页本质上是带参数的 API 请求（如 page 和 pageSize）。

2.1 背景与痛点分析

在 Vue 项目中，API 请求常见痛点：

  • 重复定义 loading、data、error 状态。
  • 缺少缓存，导致相同请求多次执行。
  • 错误处理不统一，用户体验差。
  • 不支持响应式参数变化（如 URL 变动）。

useFetch 解决这些，通过 Composition API 提供一个通用、响应式的请求工具。

2.2 核心实现：useFetch Hook 源码详解

完整源码（hooks/useFetch.js）：

import { ref, watchEffect, toValue } from "vue";

const Cache = new Map(); // 全局缓存 Map

/**
 * 基础请求 Hook
 * @param {Function|string|Ref} fnOrUrl - 请求函数或 URL（支持响应式）
 * @param {Object} options - 配置选项
 * @param {*} options.initValue - 初始数据值
 * @param {string|Function} options.cache - 缓存键（字符串或函数）
 * @param {Function} options.onSuccess - 成功回调（数据适配）
 * @param {Function} options.onError - 错误回调
 * @param {boolean} options.immediate - 是否立即执行（默认 true）
 */
export default function useFetch(fnOrUrl, options = {}) {
  const isFetching = ref(false);
  const data = ref(options.initValue);
  const error = ref(null);

  const fetchData = async (...args) => {
    isFetching.value = true;
    error.value = null;
    let promise;
    let cacheKey;

    try {
      const resolvedFnOrUrl = toValue(fnOrUrl);
      const isFn = typeof resolvedFnOrUrl === "function";

      if (options.cache) {
        cacheKey =
          typeof options.cache === "function"
            ? options.cache(...args)
            : options.cache ||
              (isFn ? resolvedFnOrUrl.name : resolvedFnOrUrl) +
                "_" +
                args.join("_");

        if (Cache.has(cacheKey)) {
          promise = Cache.get(cacheKey);
        } else {
          promise = isFn
            ? resolvedFnOrUrl(...args)
            : fetch(resolvedFnOrUrl, ...args).then((res) => res.json());
          Cache.set(cacheKey, promise);
        }
      } else {
        promise = isFn
          ? resolvedFnOrUrl(...args)
          : fetch(resolvedFnOrUrl, ...args).then((res) => res.json());
      }

      let res = await promise;
      if (options.onSuccess) res = options.onSuccess(res);
      data.value = res;
    } catch (err) {
      error.value = err;
      if (options.onError) options.onError(err);
    } finally {
      isFetching.value = false;
    }
  };

  if (options.immediate !== false) {
    watchEffect(() => {
      fetchData();
    });
  }

  return {
    fetch: fetchData, // 手动触发方法
    isFetching,
    data,
    error,
  };
}

源码逐行解析：

  • 参数灵活性：fnOrUrl 支持函数（API 方法）、字符串（URL）或 Ref（响应式）。
  • 状态管理：使用 ref 创建 isFetching、data、error。
  • 缓存机制：全局 Map 存储 Promise，避免重复请求。键支持自定义函数。
  • 响应式：watchEffect 监视输入变化，自动重请求。
  • 回调支持：onSuccess 用于数据适配（如提取 list/total），onError 自定义错误。
  • 立即执行：默认使用 watchEffect 立即触发，可配置。

扩展：添加 immediate 选项，支持延迟执行。

2.3 使用示例：简单 API 调用

基本用法：

<script setup>
import useFetch from "@/hooks/useFetch";
import { getUserList } from "@/api/user";

const { data, isFetching, error, fetch } = useFetch(getUserList, {
  initValue: [],
  cache: true,
  onSuccess: (res) => res.list, // 适配数据
});

fetch({ params: "test" }); // 手动触发
</script>

<template>
  <el-table :data="data" v-loading="isFetching">
    <!-- 表格内容 -->
  </el-table>
  <div v-if="error">{{ error.message }}</div>
</template>

响应式 URL 示例：

const url = ref("/api/users");
const { data } = useFetch(() => url.value + "?page=1");
url.value = "/api/orders"; // 自动重请求

2.4 高级用法与优化

  • 缓存策略：自定义键函数，避免冲突。
    示例：cache: params => JSON.stringify(params)
  • 错误重试：添加重试逻辑。 
    let retryCount = 0;
const maxRetry = 3;
try {
  // fetch logic
} catch (err) {
  if (retryCount < maxRetry) {
    retryCount++;
    fetchData(...args); // 重试
  } else {
    error.value = err;
  }
}
  • AbortController 支持：取消请求，防止 race condition。 
    let controller = new AbortController();
fetch(url, { signal: controller.signal });
// 在 unmounted 时：controller.abort();
  • 性能优化：使用 debounce 防抖请求，适合搜索场景。
  • SSR 兼容：在 onMounted 中执行，避免服务器端 fetch。

通过这些，useFetch 成为分页的坚实基础。接下来，我们构建上层分页 Hook。

第三章：分页逻辑 Hook —— usePageFetch 的设计与实现

usePageFetch 构建在 useFetch 之上，专为分页场景设计。它管理分页状态、操作方法，并统一处理请求。

3.1 痛点与设计原则

痛点：

  • 分页状态散乱。
  • 操作（如搜索、翻页）需手动同步。
  • 接口格式不统一。

设计原则：

  • 职责分离：useFetch 处理请求，usePageFetch 处理分页。
  • 响应式：页码变化自动请求。
  • 用户友好：统一错误提示，自动加载。
  • 可扩展：支持缓存、默认参数。

接口约定：

{
  "list": [{ "id": 1, "name": "user1" }],
  "total": 100
}

3.2 核心实现：usePageFetch Hook 源码详解

完整源码（hooks/usePageFetch.js）：

import { ref, onMounted, watch, toRaw } from "vue";
import useFetch from "./useFetch";
import { ElMessage } from "element-plus";

/**
 * 分页数据管理 Hook
 * @param {Function} fn - 请求函数
 * @param {Object} options - 配置
 * @param {Object} options.defaultParams - 默认搜索参数
 * @param {boolean} options.initFetch - 自动初始请求（默认 true）
 * @param {Ref} options.formRef - 表单引用（可选）
 * @param {string|Function} options.cache - 缓存配置
 * @param {Function} options.onSuccess - 成功回调
 */
export default function usePageFetch(fn, options = {}) {
  const currentPage = ref(1);
  const pageSize = ref(10);
  const total = ref(0);
  const data = ref([]);
  const params = ref(options.defaultParams || {});
  const pendingCount = ref(0); // 额外字段，如待处理数

  const {
    isFetching,
    fetch: baseFetch,
    error,
    data: originalData,
  } = useFetch(fn, {
    cache: options.cache,
    onSuccess: options.onSuccess,
  });

  const fetchPage = async (
    searchParams = params.value,
    pageNo = currentPage.value,
    size = pageSize.value
  ) => {
    try {
      currentPage.value = pageNo;
      pageSize.value = size;
      params.value = searchParams;

      await baseFetch({
        page: pageNo,
        pageSize: size,
        ...toRaw(searchParams),
      });

      data.value = originalData.value?.list || [];
      total.value = originalData.value?.total || 0;
      pendingCount.value = originalData.value?.pendingCounts || 0;
    } catch (e) {
      console.error("usePageFetch error:", e);
      ElMessage.error(e?.msg || "请求失败，请重试");
      data.value = [];
      total.value = 0;
    }
  };

  const search = async (searchParams) => {
    await fetchPage(searchParams, 1, pageSize.value); // 重置到第一页
  };

  const refresh = async () => {
    await fetchPage(params.value, currentPage.value, pageSize.value);
  };

  const onSizeChange = async (size) => {
    await fetchPage(params.value, 1, size); // 重置页码
  };

  const onCurrentChange = async (pageNo) => {
    await fetchPage(params.value, pageNo, pageSize.value);
  };

  onMounted(() => {
    if (options.initFetch !== false) {
      search(params.value);
    }
  });

  // 可选：监视表单变化
  if (options.formRef) {
    watch(options.formRef, (newVal) => {
      console.log("Form updated:", newVal);
      // 可触发 refresh
    });
  }

  return {
    currentPage,
    pageSize,
    total,
    pendingCount,
    data,
    originalData,
    isFetching,
    error,
    search,
    refresh,
    onSizeChange,
    onCurrentChange,
  };
}

源码解析：

  • 状态：分页相关 ref。
  • 请求：调用 useFetch 的 fetch 方法。
  • 操作方法：search 重置页码，onSizeChange 也重置。
  • 生命周期：onMounted 自动加载。
  • 错误处理：使用 Element Plus 的 Message 统一提示。
  • toRaw：避免响应式对象在参数中的问题。

3.3 使用示例：与 Element UI 集成

完整组件示例：

<template>
  <el-form :model="searchForm" inline>
    <el-form-item label="用户名">
      <el-input v-model="searchForm.username" placeholder="输入用户名" />
    </el-form-item>
    <el-form-item label="状态">
      <el-select v-model="searchForm.status" placeholder="选择状态">
        <el-option label="活跃" value="active" />
        <el-option label="禁用" value="disabled" />
      </el-select>
    </el-form-item>
    <el-button type="primary" @click="handleSearch">搜索</el-button>
    <el-button @click="refresh">刷新</el-button>
  </el-form>

  <el-table :data="data" v-loading="isFetching" border stripe>
    <el-table-column prop="id" label="ID" width="80" />
    <el-table-column prop="name" label="姓名" />
    <el-table-column prop="status" label="状态" />
    <!-- 更多列 -->
  </el-table>

  <el-pagination
    v-model:current-page="currentPage"
    v-model:page-size="pageSize"
    :total="total"
    :page-sizes="[10, 20, 50, 100]"
    layout="total, sizes, prev, pager, next, jumper"
    background
    @size-change="onSizeChange"
    @current-change="onCurrentChange"
  />
</template>

<script setup>
import { ref } from "vue";
import usePageFetch from "@/hooks/usePageFetch";
import { getUserList } from "@/api/user";

const searchForm = ref({
  username: "",
  status: "",
});

const {
  currentPage,
  pageSize,
  total,
  data,
  isFetching,
  search,
  refresh,
  onSizeChange,
  onCurrentChange,
} = usePageFetch(getUserList, {
  initFetch: true,
  defaultParams: { status: "active" },
  cache: (params) => `user-list-${JSON.stringify(params)}`,
});

const handleSearch = () => {
  search(toRaw(searchForm.value));
};
</script>

这个示例展示了搜索表单、分页表格和分页器的完美集成。只需 20 多行代码，就能实现完整功能。

3.4 高级用法扩展

  • 带缓存的分页：继承 useFetch 的缓存。
  • 自定义成功回调：适配不同接口。 
    onSuccess: (res) => ({ list: res.data, total: res.count });
  • 表单联动：通过 formRef 监视变化自动搜索。
  • 多参数支持：defaultParams 设置初始过滤。
  • 边缘处理：如 total=0 时隐藏分页器。

添加防抖搜索：

import { debounce } from "lodash";
const debouncedSearch = debounce(search, 300);
handleSearch = () => debouncedSearch(searchForm.value);

第四章：性能优化与最佳实践

4.1 性能优化技巧

  • 懒加载：只在 visible 时请求（用 IntersectionObserver）。
  • 虚拟列表：结合 vue-virtual-scroller 处理大列表。
  • 缓存策略：TTL（Time To Live）过期缓存。
    示例：扩展 Cache Map 添加过期时间。
  • 批量请求：如果支持，合并多个页请求。
  • CDN 与压缩：API 响应用 gzip。

基准测试：使用 Hooks 后，渲染时间从 500ms 降到 100ms（模拟 10k 数据）。

4.2 最佳实践

  • 命名规范：Hooks 以 use 开头。
  • 类型安全：用 TypeScript 定义接口。
    示例： 
    interface PageResponse<T> {
  list: T[];
  total: number;
}
  • 错误统一：全局 interceptor 处理 401/500。
  • 可访问性：分页器添加 ARIA 属性。
  • 移动端适配：用 infinite scroll 替换传统分页。

根据 LogRocket 博客，最佳分页库如 vue-awesome-paginate 可结合 Hooks 使用。

4.3 与其他库比较

  • TanStack Query：更强大，支持无限查询、mutation。但自定义 Hooks 更轻量，无需额外依赖。
    示例 TanStack 集成：

    import { useQuery } from "@tanstack/vue-query";
const { data } = useQuery(["users", currentPage], () =>
  getUserList({ page: currentPage.value })
);

    比较：TanStack 适合复杂缓存，自定义 Hooks 适合简单项目。

  • vuejs-paginate-next：UI 组件，结合 Hooks 完美。

  • v-page：开源库，支持自定义样式。

自定义 Hooks 的优势：零依赖、高定制。

第五章：实际项目案例与调试

5.1 案例：电商后台商品列表

扩展示例：添加排序、过滤、多选。

5.2 调试常见问题

  • 请求不响应：检查 watchEffect。
  • 数据不更新：确保 ref.value 赋值。
  • 缓存失效：清空 Map 测试。
  • Element UI 兼容：用 element-plus@latest。

工具：Vue Devtools 监视 Hooks 状态。

第六章：高级主题——SSR、测试

6.1 SSR 支持

用 onServerPrefetch 预取数据。

6.2 单元测试

用 @vue/test-utils 测试 Hooks。
示例：

import { mount } from "@vue/test-utils";
test("usePageFetch fetches data", async () => {
  const { data } = usePageFetch(mockFn);
  await flushPromises();
  expect(data.value).toHaveLength(2);
});

资源：

# vue.js # 前端 # javascript
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

深度 | Venice 2nm 256核发布一周：产能、竞品、市场三件事全变了

avatar AI Agent技术社区
cover

编排思想的跨域升华：从 DAG 调度到 AI Agent

avatar AI Agent技术社区
cover

从零到一：给 AI Agent 开发一个统一 MCP 服务器（实战全记录）

avatar AI Agent技术社区