当前位置：首页 > news >正文

【CustomPagination：基于Vue 3与Element Plus的高效二次封装分页器】

news 来源：原创 2025/5/15 9:16:39

CustomPagination：基于Vue 3与Element Plus的高效二次封装分页器

在现代Web应用开发中，分页是处理大量数据列表时不可或缺的功能。Element Plus等UI库提供了基础的分页组件，但在大型项目中，为了追求极致的用户体验和视觉统一，我们往往需要进行二次封装。本文将详细介绍我们如何基于Vue 3和Element Plus，对分页器进行二次封装，打造一个名为 CustomPagination 的组件，以满足项目特定的设计规范，并探讨其设计思路、实现细节、应用案例以及带来的益处与思考。

一、组件概述与背景

1. 组件功能定位与使用场景：

CustomPagination 是一个专为表格数据展示设计的分页控制组件。它适用于任何需要将大量数据分割成多个页面进行展示的场景，例如后台管理系统中的数据列表、用户列表、订单列表等。

2. 开发此组件的业务背景：

在我们的“能源管理平台”项目中，存在大量的数据监控和管理模块。UI设计团队对所有表格和数据展示组件都有着严格且统一的视觉要求，特别是针对分页器的外观和交互细节。

3. 现有实现的不足或待解决的问题：

Element Plus的默认分页器虽然功能强大，但在以下几个方面未能完全满足我们的特定需求：

视觉风格不统一：默认分页器的样式与项目整体暗色系、科技感的UI风格存在差异。
交互细节需定制：设计稿要求特定的交互元素和布局，如“总计：XXX”、“XX条/页”下拉框的样式、以及一个一体化的页码输入和跳转按钮。
组件复用性与维护成本：如果每个使用分页的地方都单独调整样式和逻辑，将导致代码冗余、不一致，并增加后期维护难度。

4. 组件的技术定位：

CustomPagination 定位为一个基础UI组件。它的目标是提供一个高度可复用、符合项目UI规范的标准分页解决方案，供项目内其他业务组件或页面直接调用。

二、设计目标与原则

1. 功能目标：

精确实现设计稿要求的视觉样式和交互行为。
提供总条数显示、每页条数选择、页码导航、页码输入跳转等核心分页功能。
支持禁用状态。
易于集成到现有表格或列表组件中。

2. 性能目标：

确保组件自身渲染性能高效，不引入不必要的重绘和重排。
在数据量较大时，分页切换流畅。

3. 可维护性目标：

代码结构清晰，注释完整，易于理解和修改。
逻辑内聚，分页相关的核心逻辑封装在组件内部。
提供明确的TypeScript类型定义。

4. 可扩展性目标：

虽然初期主要满足当前项目设计，但保留一定的可配置性（如 pageSizes, pagerCount）。
未来可考虑通过插槽等方式增强定制能力。

5. 设计原则：

单一职责：组件专注于分页功能本身。
Props驱动与事件通知：通过Props接收配置，通过Emits通知状态变更。
高内聚、低耦合：组件内部逻辑独立，对外部依赖最小。
开发者友好：提供简洁易懂的API和清晰的文档。

三、组件设计与API

1. 组件的对外接口/Props设计 (附TypeScript类型定义)：

interface PaginationProps {/*** 总条目数*/total: number;/*** 当前页码 (支持 .sync 或 v-model:currentPage)*/currentPage: number;/*** 每页条数 (支持 .sync 或 v-model:pageSize)*/pageSize: number;/*** 可选的每页条数数组*/pageSizes?: number[];/*** 页码按钮的数量，当总页数超过该值时会折叠*/pagerCount?: number;/*** 是否禁用分页*/disabled?: boolean;
}

2. 事件设计与处理方式：

组件通过 defineEmits 定义了以下事件：

const emit = defineEmits<{/*** 当前页码更新事件，用于 v-model:currentPage*/(e: 'update:currentPage', page: number): void;/*** 每页条数更新事件，用于 v-model:pageSize*/(e: 'update:pageSize', size: number): void;/*** 统一的分页参数变更事件，当页码或每页条数改变时触发* 建议父组件监听此事件进行数据请求*/(e: 'pagination-change', params: { page: number; size: number }): void;
}>();

update:currentPage 和 update:pageSize 主要用于支持 v-model。
pagination-change 是一个更通用的事件，当页码或每页条数发生任何有效变化后触发，父组件通常监听此事件来重新获取数据。

3. 插槽设计与定制能力：

当前版本的 CustomPagination 主要通过Props进行配置，未设计复杂的插槽。其主要定制能力体现在对Element Plus组件的样式覆盖和结构重组上，以达到设计稿要求。未来如果需要更灵活的UI片段替换，可以考虑引入具名插槽。

4. 组件内部结构：

组件模板主要由以下几部分构成：

总条数显示区域 (.total-info)。
每页条数选择下拉框 (.pagesize-dropdown-wrapper，使用 el-dropdown 实现)。
核心页码导航区域 (基于简化的 el-pagination)。
页码输入和跳转区域 (.jumper-container，使用 el-input 和自定义按钮实现一体化效果)。

这些元素通过Flexbox进行布局和对齐。

四、实现细节

1. 组件结构与核心代码：

为了更清晰地展示实现细节，我们来看一下 CustomPagination 组件的核心代码片段。

(1.1) 组件模板 (<template>)

<!-- src/components/custom-pagination/index.vue -->
<template><div class="common-pagination-container" v-if="total > 0"><div class="pagination-inner-container"><!-- 总计信息 --><div class="total-info">总计: {{ total }}</div><!-- 每页条数选择 (使用el-dropdown定制) --><div class="pagesize-dropdown-wrapper"><el-dropdown trigger="click" @command="handleSizeChange"><div class="el-dropdown-link">{{ pageSize }} 条/页<i class="el-icon-arrow-down el-icon--right"></i> {/* 自定义箭头样式 */}</div><template #dropdown><el-dropdown-menu><el-dropdown-item v-for="size in pageSizes" :key="size" :command="size">{{ size }} 条/页</el-dropdown-item></el-dropdown-menu></template></el-dropdown></div><!-- Element Plus基础分页 (只保留核心导航) --><el-paginationbackgroundlayout="prev, pager, next" {/* 精简布局，只保留翻页和页码 */}:total="total":current-page="internalCurrentPage" {/* 注意这里绑定的是内部状态 */}:page-size="internalPageSize"     {/* 同上 */}:pager-count="pagerCount"@current-change="handlePageChange"class="custom-pagination" {/* 自定义样式类，用于:deep选择器 */}/><!-- 一体化跳转功能 --><div class="jumper-container"><div class="jump-input-wrapper"><el-input v-model="jumpPage" class="jump-page-input" @keyup.enter="handleJumpPage"/><div class="jumper-button" @click="handleJumpPage">跳转</div></div></div></div></div>
</template>

整体布局：使用 Flexbox (pagination-inner-container) 进行右对齐布局。
每页条数选择：通过 el-dropdown 实现高度自定义的下拉选择。
核心页码导航：借用 el-pagination 的 prev, pager, next 布局。
一体化跳转：将 el-input 和自定义按钮组合，并通过CSS调整边框和圆角实现视觉连接。@keyup.enter 添加了回车跳转功能。

(1.2) 组件逻辑 (<script setup lang="ts">)

// src/components/custom-pagination/index.vue
import { ref, watch } from 'vue';// Props 定义 (同上节)
// Emits 定义 (同上节)// 内部状态
const internalCurrentPage = ref(props.currentPage);
const internalPageSize = ref(props.pageSize);
const jumpPage = ref<string | number>('');// 监听外部props变化，同步内部状态
watch(() => props.currentPage, (val) => {if (val !== internalCurrentPage.value) internalCurrentPage.value = val;
});
watch(() => props.pageSize, (val) => {if (val !== internalPageSize.value) internalPageSize.value = val;
});// 事件处理函数
function handlePageChange(page: number) { // el-pagination的@current-changeif (props.disabled) return;internalCurrentPage.value = page;emit('update:currentPage', page);emit('pagination-change', { page, size: internalPageSize.value });
}function handleSizeChange(size: number) { // el-dropdown的@commandif (props.disabled) return;internalPageSize.value = size;internalCurrentPage.value = 1; // 切换条数时，重置到第一页emit('update:pageSize', size);emit('update:currentPage', 1);emit('pagination-change', { page: 1, size });
}function handleJumpPage() { // 跳转按钮点击或回车if (props.disabled || !jumpPage.value) return;let page = parseInt(jumpPage.value as string);if (isNaN(page) || page < 1) {page = 1;} else {const maxPage = Math.ceil(props.total / internalPageSize.value);page = Math.min(page, maxPage); // 确保页码在有效范围内}internalCurrentPage.value = page;emit('update:currentPage', page);emit('pagination-change', { page, size: internalPageSize.value });jumpPage.value = '';
}// defineExpose (同上节)

Props 和 Emits：如上节所述，支持 v-model 和统一的 pagination-change 事件。
内部状态管理：通过 internalCurrentPage 和 internalPageSize 与 el-pagination 交互，并响应外部 props 的变化。
输入校验：handleJumpPage 中对跳转页码进行严格校验。

2. 样式实现与响应式处理 (<style lang="less" scoped>)

// src/components/custom-pagination/index.vue
.common-pagination-container {.pagination-inner-container {display: flex;justify-content: flex-end; align-items: center;}.total-info { /* ... */ }.pagesize-dropdown-wrapper {.el-dropdown-link { /* ... */ i { /* 自定义CSS箭头 */border-top: 12px solid #fff; /* ... */}}}:deep(.el-pagination) { /* 深度定制el-pagination样式 *//* ... 通过CSS变量和直接覆盖内部类名调整样式 ... */}.jumper-container {.jump-input-wrapper {.jump-page-input :deep(.el-input__wrapper) {border-right: none; border-top-right-radius: 0;border-bottom-right-radius: 0;}.jumper-button {border-left: none;border-top-left-radius: 0;border-bottom-left-radius: 0;&::before { /* 中间竖线 */content: ''; position: absolute; left: 0; top: 0px; bottom: 0px; width: 1px; background-color: #3b86bf;}}}}
}
:deep(.el-dropdown-menu) { /* 下拉菜单样式 *//* ... */
}

Scoped CSS 与 :deep()：确保样式局部化，同时能修改子组件内部样式。
CSS变量与直接覆盖：结合使用Element Plus提供的CSS变量和直接覆盖内部类名的方式进行样式定制。
一体化输入框：通过调整相邻元素的 border 和 border-radius，并用伪元素 ::before 绘制分割线，实现视觉上的无缝连接。

3. 性能优化点：

组件本身逻辑不复杂，主要渲染开销在Element Plus子组件。我们通过简化 el-pagination 的 layout，只渲染必要部分。
v-if="total > 0" 避免了在没有数据时渲染整个分页器。
事件处理函数中增加了 props.disabled 判断，避免不必要的操作。

五、优化与性能

1. 渲染性能：

组件结构相对简单，主要依赖Element Plus组件。通过按需渲染（v-if）和简化内部el-pagination的layout，减少了不必要的DOM节点。

2. 用户体验优化点：

视觉一致性：严格遵循设计稿，提供统一的视觉体验。
交互明确：自定义的下拉箭头和一体化跳转按钮，交互更直观。
输入容错：跳转页码输入时，对无效输入（非数字、超出范围）进行了处理，自动校正到有效页码。
回车跳转：为跳转输入框添加了回车事件，提升操作效率。

六、应用案例

1. 基础用法案例 (v-model绑定)：

<template><div><!-- 假设这里有一个表格 --><div class="table-placeholder">表格数据展示区域</div><CustomPaginationv-model:current-page="paginationState.currentPage"v-model:page-size="paginationState.pageSize":total="paginationState.total"@pagination-change="handleDataFetch"/></div>
</template><script setup lang="ts">
import { reactive } from 'vue';
import CustomPagination from '@/components/custom-pagination/index.vue'; // 确保路径正确const paginationState = reactive({currentPage: 1,pageSize: 10,total: 0, // 通常由API返回
});// 模拟数据获取
async function fetchData(page: number, size: number) {console.log(`Fetching data for page: ${page}, size: ${size}`);// 实际项目中，这里会调用API// 假设API返回了155条数据paginationState.total = 155; // 更新表格数据...
}function handleDataFetch(params: { page: number; size: number }) {fetchData(params.page, params.size);
}// 初始化加载第一页数据
fetchData(paginationState.currentPage, paginationState.pageSize);
</script><style scoped>
.table-placeholder {height: 200px;border: 1px dashed #ccc;display: flex;align-items: center;justify-content: center;margin-bottom: 20px;color: #888;
}
</style>

2. 在弹窗内表格中的应用 (如 charging-facility-dialog.vue)：

<!-- charging-facility-dialog.vue -->
<template><CustomerDialog v-model:visible="newVisible"><!-- ... dialog title and search ... --><div class="common-table-container" v-loading="isLoading"><table class="common-data-table" v-if="filteredTableData.length > 0"><!-- ... table head and body ... --></table><div class="common-empty-container" v-else><NoData /></div><!-- 使用自定义分页器 --><div v-if="filteredTableData.length > 0"><CustomPagination:total="total"v-model:current-page="currentPage"v-model:page-size="pageSize"@pagination-change="onPaginationChange" /></div></div></CustomerDialog>
</template><script setup lang="ts">
import CustomPagination from '@/components/custom-pagination/index.vue';
// ... 其他 imports 和 setup逻辑 ...const currentPage = ref(1);
const pageSize = ref(10);
const total = ref(0);
// ... tableData, isLoading 等 ...// 父组件（弹窗）的数据获取逻辑
async function fetchData() {isLoading.value = true;// 构造请求参数，包含 currentPage.value 和 pageSize.valueconst params = { /* ...其他筛选条件... */__page: currentPage.value, __pagesize: pageSize.value };try {// const res = await Api.getEquipmentInfo(params);// tableData.value = res.pageData;// total.value = res.itemCount;} finally {isLoading.value = false;}
}// CustomPagination的事件回调
function onPaginationChange(params: { page: number; size: number }) {// currentPage 和 pageSize 已经通过 v-model 更新fetchData(); // 直接调用数据获取
}// 初始化或弹窗显示时加载数据
// watch(() => props.visible, (isVisible) => { if(isVisible) fetchData() } );
</script>

截图效果：(此处可以配上组件在项目中实际应用的截图，展示其与整体UI的融合效果)

七、重构与迭代

本组件是在项目初期对Element Plus分页器进行样式调整的基础上，逐步演化而来的。

重构前：分散在各个Vue文件中的 :deep() 样式覆盖和零散的 el-pagination 配置。
重构思路：
1. 统一需求：收集所有分页场景下的设计稿要求，确定统一的视觉和交互标准。
2. 提取共性：将共同的样式和布局抽象出来。
3. 组件化封装：创建一个独立的 .vue 文件，将模板、逻辑和样式封装在一起。
4. 定义清晰API：设计Props和Emits，确保易用性和灵活性。
重构后效果：显著减少了代码冗余，提高了开发效率，保证了UI一致性，降低了维护成本。

八、学习与收获

技术决策：选择基于Element Plus进行二次封装而非完全造轮子，是在项目时间和成熟度之间做的权衡。我们利用了Element Plus的稳定性和核心逻辑，同时通过深度定制满足了UI需求。
挑战与解决：
- 样式覆盖：Element Plus组件内部DOM结构复杂，精确覆盖特定元素的样式需要耐心调试 :deep() 选择器，并理解其权重。
- 交互细节模拟：如一体化跳转按钮的实现，需要巧妙运用CSS技巧（如负margin、边框处理、伪元素）。
设计模式应用：组件本身遵循了良好的封装和单一职责原则。通过Props和Emits实现了父子组件的单向数据流和事件通信。

九、未来规划

待解决的问题或限制：
- 目前对Element Plus版本有一定依赖，升级时需注意兼容性。
- 国际化支持：当前文案（如“总计”、“条/页”、“跳转”）是硬编码的，未来可考虑通过i18n方案实现多语言。
计划中的新功能：
- 更灵活的布局选项：例如允许将总条数、每页条数选择器等放置在分页器的不同位置。
- 提供更多插槽：允许用户自定义分页器的某些部分，如页码按钮的渲染。
性能优化方向：对于超大数据总量（百万级以上）且页数极多的情况，可以研究 el-pagination 内部的页码渲染策略，看是否有进一步优化的空间（尽管通常后端API会限制最大查询页数）。

十、设计资源与代码

组件完整代码：src/components/custom-pagination/index.vue (如前文所示)
使用示例文档：src/components/custom-pagination/example.vue 和 src/components/custom-pagination/README.md
设计稿/原型链接：(此处可链接到项目的UI设计稿或原型中关于分页器的具体页面)

通过这次二次封装，我们不仅得到了一个满足项目需求的自定义分页组件，也在组件化开发、CSS深度定制以及Vue 3组合式API的应用上获得了宝贵的经验。希望这些分享能对您有所启发。