radix-vue PaginationList 组件完全指南：分页项列表的渲染与控制

radix-vue PaginationList 组件完全指南分页项列表的渲染与控制【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vue本篇技术指南聚焦 radix-vue原 Radix Vue组件库中的PaginationList组件讲解它作为分页条中间列表的职责如何通过作用域插槽获取由PaginationRoot计算好的页码与省略号项目集合以及as/asChild属性如何控制渲染元素。结合源码实现你将掌握分页列表的生成算法、与PaginationListItem、PaginationEllipsis的协作方式并能直接写出可运行、无障碍友好的完整分页组件。组件定位Pagination 家族中的列表容器radix-vue 的分页能力由多个组件协作完成源码位于 packages/core/src/PaginationPaginationRoot管理当前页page、总页数pageCount等状态并通过注入上下文向子组件提供数据PaginationList本文主角一个纯展示型容器不直接渲染任何页码按钮而是通过items作用域插槽把计算好的分页项目集合交给使用者渲染PaginationListItem/PaginationEllipsis分别渲染单个页码按钮和省略号PaginationFirst/PaginationPrev/PaginationNext/PaginationLast首、上一、下一、末页跳转按钮。在典型的组合中PaginationList充当分页条的中间地带——左右两侧是跳转按钮中间则是一个由items驱动的循环渲染区。相关源码可对照 PaginationList.vue 与 PaginationRoot.vue。Props继承自 Primitive 的两个核心属性根据官方文档PaginationList.mdPaginationList的 Props 完全继承自PrimitiveProps只有两项NameDescriptionTypeRequiredDefaultas组件渲染为的元素或组件可被asChild覆盖。AsTag \| ComponentNodivasChild将默认渲染元素替换为传入的子元素并合并两者的 props 与行为。详情见官方 Composition 指南。booleanNo-从实现看PaginationList.vue 的模板即是一个Primitive包裹Primitive v-bindprops slot :itemstransformedRange / /Primitive由于PaginationListProps extends PrimitiveProps它默认渲染为div。实际使用中通常无需修改因为列表本身只负责提供插槽数据若需要语义化标签如ul可通过asul调整或在更细粒度上由PaginationListItem各自控制渲染元素。Primitive的实现位于 packages/core/src/Primitive。Slotsitems—— 分页项目集合文档中定义的本组件唯一插槽NameDescriptionTypeitems分页项目{ type: ellipsis; } \| { type: page; value: number; }items是一个可辨识联合discriminated union数组每个元素要么是页码项{ type: page; value: number }要么是省略号项{ type: ellipsis }。类型定义见 PaginationList.vue。结合 story/_Pagination.vue 的官方用法通过v-slot{ items }取出数据后通常配合v-for循环渲染PaginationList v-slot{ items } classflex items-center gap-2 PaginationFirst / PaginationPrev / template v-for(page, index) in items PaginationListItem v-ifpage.type page :keyindex :valuepage.value classborder rounded px-4 py-2>const transformedRange computed(() { return transform( getRange( rootContext.page.value, rootContext.pageCount.value, rootContext.siblingCount.value, rootContext.showEdges.value, ), ) })getRange页码窗口计算getRange(currentPage, pageCount, siblingCount, showEdges)返回(string | number)[]其中数字代表真实页码、字符串ellipsis代表省略号。其核心逻辑参考自 chakra-ui/zag 的 pagination 工具函数showEdges false默认采用滑动窗口策略。itemCount siblingCount * 2 1当总页数小于窗口大小时直接返回全部页码当前页靠近开头时返回[1..itemCount]靠近末尾时返回末尾的itemCount个页码位于中间时返回[currentPage - siblingCount .. currentPage siblingCount]。showEdges true始终保留第 1 页、最后 1 页与最多两个省略号。此时totalPageNumbers min(2 * siblingCount 5, pageCount)再通过showLeftEllipsis/showRightEllipsis的组合判断分别产生左侧省略、右侧省略、双侧省略或全量四种形态源码中有详细注释说明2 * siblingCount 5的构成两侧兄弟页 ×2、左右省略号 ×2、首尾页 ×2 与当前页 ×1。transform统一为插槽数据类型transform把(string | number)[]映射为插槽要求的联合类型——数字转{ type: page, value }字符串即ellipsis转{ type: ellipsis }。与 Root 参数的联动PaginationRoot的默认值见 PaginationRoot.vue直接决定了列表形态siblingCount默认2当前页两侧各显示 2 个页码showEdges默认false不强制显示首尾页total默认0pageCount Math.max(1, Math.ceil(total / (itemsPerPage || 1)))因此total0时总页数为 1所有跳转按钮呈禁用态。与PaginationListItem/PaginationEllipsis的分工items只是数据真正把数据渲染成可交互元素的分别是PaginationListItem.vue接收value属性内部通过computed判断isSelected当前页等于自身值并自动输出无障碍属性——aria-labelPage {value}、选中时aria-currentpage与data-selectedtrue点击时调用上下文中的onPageChange更新页码在禁用状态下点击事件被拦截!disabled rootContext.onPageChange(value)。PaginationEllipsis.vue渲染data-typeellipsis的占位元素默认内容为省略号字符#8230;。测试用例 Pagination.test.ts 验证了这些行为默认首屏第 1 页data-selectedtrue、点击下一页后选中态切换到第 2 页、showEdges开启后第 1 页与第 10 页始终存在且全部通过vitest-axe无障碍检查。完整实战示例将以上内容组合一个完整的分页条数据共 100 条、每页 10 条、共 10 页如下script setup langts import { ref } from vue import { PaginationEllipsis, PaginationFirst, PaginationLast, PaginationList, PaginationListItem, PaginationNext, PaginationPrev, PaginationRoot, } from radix-vue const page ref(1) /script template PaginationRoot v-model:pagepage :total100 :items-per-page10 PaginationList v-slot{ items } classflex items-center gap-2 PaginationFirst / PaginationPrev / template v-for(item, index) in items :keyindex PaginationListItem v-ifitem.type page :valueitem.value classborder rounded px-4 py-2 contenteditable="false">【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考