组合式函数

概述

Naive Admin Max 提供了一系列组合式函数（Composables），集中在 src/composables/ 目录下，用于封装常见的业务逻辑模式。这些函数遵循 Vue 3 Composition API 风格，可直接在 <script setup> 中使用。

useRowActions — 表格操作列

声明式配置表格操作列按钮，支持内联按钮和「更多」下拉菜单，自动集成权限判断和确认弹窗。

基本用法

import { useRowActions } from '@/composables/useRowActions'

const rowActions = useRowActions<UserRow>({
  inline: [
    {
      label: '编辑',
      type: 'primary',
      auth: 'update',
      onClick: (row) => saveRef.value?.open(row),
    },
    {
      label: '删除',
      type: 'error',
      auth: 'delete',
      confirm: '确认删除吗？删除后将无法恢复，是否继续？',
      onClick: async (row) => {
        await deleteApi(row.id)
        await queryList()
      },
    },
  ],
  more: [
    {
      label: '重置密码',
      auth: 'update',
      onClick: (row) => resetPwd(row),
    },
  ],
})

// 在列定义中使用
const columns = [
  // ... 其他列
  { title: '操作', key: 'operate', render: (row) => rowActions.render(row) },
]

配置项

属性	类型	说明
label	string	按钮文字
type	'primary' | 'error' | 'warning' | ...	按钮类型
auth	string	权限码（同 v-auth）
confirm	string	确认弹窗文案（非空时点击自动弹确认框）
onClick	(row) => void | Promise<void>	点击回调
show	(row) => boolean	动态显隐
disabled	(row) => boolean	动态禁用

• inline：平铺为文字按钮
• more：收进「更多」下拉菜单

useConfirm — 确认弹窗

封装 Naive UI 的 dialog.warning，提供便捷的确认/取消操作：

import { useConfirm } from '@/composables/useConfirm'

const { confirmDelete, confirmCustom } = useConfirm()

// 删除确认
await confirmDelete('确认删除该用户吗？')
await deleteApi(userId)

// 自定义确认
await confirmCustom({
  title: '批量操作',
  content: '确认批量启用选中的 10 条记录吗？',
})

useBatchOptions — 批量操作

处理分批批量操作（如批量删除、批量启用），自动分批发送请求并显示进度：

import { useBatchOptions } from '@/composables/useBatchOptions'

const { batchProcess } = useBatchOptions()

// 批量删除（自动分批，每批 10 条）
await batchProcess({
  ids: selectedIds,
  batchSize: 10,
  processFn: async (batchIds) => {
    await batchDeleteApi(batchIds)
  },
  onSuccess: () => {
    queryList()
    tableRef.value?.clearSelection()
  },
})

useExport — 分页导出

支持大数据量分页导出为 Excel 文件，自动处理分页请求和进度展示：

import { useExport } from '@/composables/useExport'

const { exportData, exportProgress } = useExport()

// 分页导出
await exportData({
  filename: '用户列表',
  columns: exportColumns,
  fetchFn: async (page, pageSize) => {
    const { list, total } = await queryListApi({ page, pageSize })
    return { data: list, total }
  },
  pageSize: 500, // 每次请求 500 条
})

exportProgress 为响应式进度值（0-100），可用于显示进度条。

useResultModal — 结果弹窗

操作完成后展示结果表格弹窗，支持成功/失败明细展示：

import { useResultModal } from '@/composables/useResultModal'

const { showResult } = useResultModal()

// 批量操作后展示结果
showResult({
  title: '批量导入结果',
  successCount: 95,
  failCount: 5,
  failDetails: [
    { row: '第 3 行', reason: '用户名重复' },
    { row: '第 7 行', reason: '邮箱格式错误' },
    // ...
  ],
})

最佳实践

• 操作列配置使用 useRowActions，不要在 render 里手写 h(NDropdown/NButton)
• 删除确认交给操作项的 confirm 字段（内部走 useConfirm）
• 列表页外的零散确认场景直接使用 useConfirm()