Vben Vxe Table在 vue-vben-admin 中用共享 API 构建可搜索数据表格【免费下载链接】vue-vben-adminA modern vue admin panel built with Vue3, Shadcn UI, Vite, TypeScript, and Monorepo. Its fast!项目地址: https://gitcode.com/GitHub_Trending/vu/vue-vben-adminVben Vxe Table是 vue-vben-admin 中对vxe-table的二次封装组件它把vxe-table与Vben Form组合在一起让开发者可以用一套共享 APIuseVbenVxeGrid同时驱动表格渲染与搜索表单快速搭建搜索 表格 分页的数据网格。本文基于 vben-vxe-table.md 展开结合仓库中 vxe-table 插件源码 与各应用的实际适配器完整讲解组件用法、GridApi、Props、Slots 及底层实现读完你可以直接在项目中落地一个带搜索表单的可查询表格。设计概览vxe-table 与 Vben Form 的组合封装在 vue-vben-admin 的 Monorepo 结构中Vben Vxe Table的核心实现位于 packages/effects/plugins/src/vxe-table对外导出一组统一的 API导出类型说明setupVbenVxeTable函数初始化配置函数useVbenVxeGrid函数表格组合式函数返回[Grid, gridApi]VbenVxeGrid组件表格组件VxeTableGridColumns类型表格列类型VxeTableGridOptions类型表格配置类型VxeGridProps类型表格 PropsVxeGridListeners类型表格事件类型该插件建立在vxe-table与vxe-pc-ui之上同时通过useVbenForm接入Vben Form因此你只需要配置一份formOptions搜索表单与表格数据请求就能联动工作。初始化setupVbenVxeTable 与自定义渲染器使用前需要在应用入口调用setupVbenVxeTable完成初始化核心代码如下完整实现见 vxe-table.tsimport { setupVbenVxeTable } from vben/plugins/vxe-table; setupVbenVxeTable({ configVxeTable: (vxeUI) { vxeUI.setConfig({ grid: { align: center, border: false, columnConfig: { resizable: true }, formConfig: { // 全局禁用 vxe-table 自身的表单配置改用 formOptions enabled: false, }, minHeight: 180, proxyConfig: { autoLoad: true, response: { result: items, total: total, list: }, showActiveMsg: true, showResponseMsg: false, }, round: true, showOverflow: true, size: small, } as VxeTableGridOptions, }); }, });关键点说明formConfig.enabled: false全局禁用 vxe-table 自带表单搜索表单统一交给Vben Form渲染这是本组件与原生 vxe-grid 最重要的差异之一proxyConfig声明远程数据请求的响应字段映射items/total配合autoLoad在表格挂载后自动加载数据configVxeTable回调中也可以注册自定义渲染器例如项目内置了CellImage、CellLink、CellTag、CellSwitch、CellOperation等见下方渲染器适配示例。文档中的 Adapter Example 展示了通过renderTableDefault(...)注册单元格渲染器的写法vxeUI.renderer.add(CellImage, { renderTableDefault(_renderOpts, params) { const { column, row } params; return h(Image, { src: row[column.field] }); }, }); vxeUI.renderer.add(CellLink, { renderTableDefault(renderOpts) { const { props } renderOpts; return h( Button, { size: small, type: link }, { default: () props?.text }, ); }, });在 playground 的适配器实现中CellImage会额外展开...propsCellLink同样基于Button渲染链接按钮除此之外还有用于展示状态的CellTag支持通过options传入标签映射、CellSwitch支持异步beforeChange钩子与行内 loading 状态、以及内置编辑/详情/删除预设操作并集成Popconfirm删除确认的CellOperation。注册渲染器之后在列配置中通过cellRender: { name: CellImage }即可使用。基本用法useVbenVxeGrid官方文档给出的最小用法如下script setup langts import { useVbenVxeGrid } from #/adapter/vxe-table; const [Grid, gridApi] useVbenVxeGrid({ gridOptions: {}, formOptions: {}, gridEvents: {}, }); /script template Grid / /templateuseVbenVxeGrid返回一个元组第一个元素Grid是渲染组件需要在模板中使用第二个元素gridApi是表格实例 API。注意这里导入的是各应用src/adapter/vxe-table.ts的封装而不是直接导入插件包——每个 web 应用如 apps/web-antd、playground都会在适配器中基于vben/plugins/vxe-table的useVbenVxeGrid做一层转发以便绑定当前应用的表单组件类型。一个完整可运行的基础示例带工具栏按钮、动态修改表格配置见 demos/vben-vxe-table/basic/index.vuescript setup langts import type { VxeGridListeners, VxeGridProps } from #/adapter/vxe-table; import { Button, message } from antdv-next; import { useVbenVxeGrid } from #/adapter/vxe-table; import { MOCK_TABLE_DATA } from ../table-data; interface RowType { address: string; age: number; id: number; name: string; nickname: string; role: string; } const gridOptions: VxeGridPropsRowType { columns: [ { title: 序号, type: seq, width: 50 }, { field: name, title: Name }, { field: age, sortable: true, title: Age }, { field: nickname, title: Nickname }, { field: role, title: Role }, { field: address, showOverflow: true, title: Address }, ], data: MOCK_TABLE_DATA, pagerConfig: { enabled: false }, sortConfig: { multiple: true }, }; const gridEvents: VxeGridListenersRowType { cellClick: ({ row }) { message.info(cell-click: ${row.name}); }, }; const [Grid, gridApi] useVbenVxeGrid({ gridEvents, gridOptions }); // 通过 useStore 读取响应式状态 const showBorder gridApi.useStore((state) state.gridOptions?.border); const showStripe gridApi.useStore((state) state.gridOptions?.stripe); function changeBorder() { gridApi.setGridOptions({ border: !showBorder.value }); } function changeStripe() { gridApi.setGridOptions({ stripe: !showStripe.value }); } function changeLoading() { gridApi.setLoading(true); setTimeout(() gridApi.setLoading(false), 2000); } /script template div classvp-raw w-full Grid template #toolbar-tools Button classmr-2 typeprimary clickchangeBorder {{ showBorder ? 隐藏 : 显示 }}边框 /Button Button classmr-2 typeprimary clickchangeLoading 显示loading /Button Button classmr-2 typeprimary clickchangeStripe {{ showStripe ? 隐藏 : 显示 }}斑马纹 /Button /template /Grid /div /template几点使用注意渲染器适配器renderer adapter负责表格单元格渲染vxe-grid本身的列配置仍写在gridOptions.columns中gridApi.useStore(selector)可以从表格内部状态仓库中读取响应式值例如state.gridOptions?.border配合setGridOptions实现运行时动态修改配置文档示例中的vp-raw类仅用于适配文档展示环境实际项目无需添加。GridApi表格实例 API 详解useVbenVxeGrid返回的gridApi是操作表格的核心入口文档给出如下方法表MethodDescriptionTypesetLoading更新加载状态(loading: boolean) voidsetGridOptions合并新的 grid options(options: PartialVxeGridProps[gridOptions]) voidreload重新加载数据并重置分页(params?: Recordstring, any) voidquery查询数据但保持当前页码(params?: Recordstring, any) voidgridvxe-grid实例VxeGridInstanceformApi搜索表单 APIFormApitoggleSearchForm切换或强制设置搜索表单可见状态(show?: boolean) boolean在源码层面这些方法由 packages/effects/plugins/src/vxe-table/api.ts 中的VxeGridApi类实现值得关注的内在逻辑reload与query内部都通过this.grid.commitProxy(reload | query, toRaw(params))交给 vxe-table 的代理proxy机制处理区别在于reload会重置分页、query保持当前页——这与 vxe-table 的commitProxy语义一致setGridOptions/setLoading通过setState写入内部Store并由mergeWithArrayOverride完成合并数组直接覆盖而不是深度合并因此可以只传部分配置增量更新toggleSearchForm(show?)不传参时取反当前showSearchForm传布尔值时强制设置并返回设置后的可见状态useStore由useVbenVxeGrid在返回的扩展 API 上注入见 use-vxe-grid.ts基于vben-core/shared/store的useStore实现响应式订阅用于在组件外部读取表格状态初始化时VxeGridApi通过bindMethods(this)绑定方法保证从解构中取出方法调用时this指向正确。Props组件属性说明PropDescriptionTypetableTitle表格标题stringtableTitleHelp表格标题的帮助文本stringclass外层容器 classstringgridClassvxe-grid节点的 classstringgridOptionsvxe-grid配置DeepPartialVxeTableGridOptionsgridEventsvxe-grid事件处理器DeepPartialVxeGridListenersformOptions搜索表单配置VbenFormPropsshowSearchForm搜索表单是否可见booleanseparator搜索表单与表格主体之间的分隔条boolean \| SeparatorOptions类型定义见 packages/effects/plugins/src/vxe-table/types.ts补充说明几个细节VxeTableGridOptions在原vxe-table的VxeGridProps基础上扩展了toolbarConfig其中新增了search?: boolean用于控制是否显示切换搜索表单的工具栏按钮separator除了布尔值外也可以传入SeparatorOptions{ show?: boolean; backgroundColor?: string }自定义分隔条样式viewedRowOptions支持布尔值或ViewedRowOptions开启后表格具备已读行能力可通过gridApi的markRowAsViewed、isRowViewed、clearViewedRows等方法来管理已读状态见 viewed-rowgridOptions、gridEvents均为DeepPartial即只传需要覆盖的字段即可其余部分与全局配置合并formOptions复用Vben Form的VbenFormProps意味着搜索表单的字段、校验规则、布局等能力与 vben-form 完全一致。Slots插槽说明SlotDescriptiontoolbar-actions工具栏左侧靠近标题位置toolbar-tools工具栏右侧位于内置工具按钮之前table-title自定义表格标题所有以form-开头的具名插槽都会被转发给搜索表单。在 use-vxe-grid.ts 中可以看到插槽类型约束toolbar-actions、toolbar-tools的插槽参数为VxeGridSlotTypes.DefaultSlotParamsTtable-title无参数其余插槽类型来自VxeGridSlots但排除了form因为搜索表单由 Vben Form 接管。结合源码的完整工作流程把上述内容串联起来一个典型的搜索 表格页面在运行时经历以下流程初始化应用入口调用setupVbenVxeTable注册全局配置、渲染器与useVbenForm创建实例组件 setup 中调用useVbenVxeGrid内部new VxeGridApi(options)生成 API 实例与响应式Store渲染挂载Grid /渲染时把api透传给VxeGrid组件组件挂载后调用api.mount(instance, formApi)将 vxe-grid 实例与搜索表单 API 存入grid/formApi数据加载proxyConfig.autoLoad为true时自动发起首次请求搜索表单提交后通过reload重置分页或query保持页码刷新数据交互更新通过gridApi.setGridOptions/setLoading/toggleSearchForm等 API 响应式更新配置与状态销毁组件卸载时调用api.unmount()重置状态处理器与已读行辅助器。对应地插件仓库还提供了响应式测试用例 use-vxe-grid.reactivity.test.ts可从中了解 API 在不同场景下的行为约定。总结Vben Vxe Table的价值在于把两套成熟的方案vxe-table 的高性能表格 Vben Form 的表单能力收敛到一个组合式函数useVbenVxeGrid之下一份gridOptions管表格、一份formOptions管搜索、一个gridApi管交互。本文覆盖了初始化、渲染器注册、基本用法、GridApi 方法、Props 与 Slots并给出了源码级实现依据更多表格能力远程数据、树形表格、单元格编辑、虚拟滚动等可参考 vben-vxe-table 演示目录 下的各示例结合 vxe-table 插件 README 进一步深入。【免费下载链接】vue-vben-adminA modern vue admin panel built with Vue3, Shadcn UI, Vite, TypeScript, and Monorepo. Its fast!项目地址: https://gitcode.com/GitHub_Trending/vu/vue-vben-admin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考