@biancd/vale

基于 Element Plus 的 Vue 3 功能组件库，提供命令式表单弹窗（useFormPopup）、通用表格（useAbTable）、标签页管理（useTabManager）、倒计时轮询（useCountdownPolling）和 HTTP 请求封装（request）等开箱即用的 Hook 和工具函数。

安装

npm install @biancd/vale

本包依赖以下 peer dependencies，使用前请确保项目中已安装：

npm install vue element-plus @form-create/element-ui @element-plus/icons-vue @vueuse/core axios

另外需要在项目中全局引入 Element Plus 以及本包的样式：

// main.ts
import 'element-plus/dist/index.css'
import '@biancd/vale/vale.css'

vale.css 是 Vite 库模式构建时从 SFC 的 <style scoped> 中提取的组件样式。库模式下 CSS 无法内联到 JS 中，因此需要单独引入。

组件

| 组件 | 说明 | 文档 | |------|------|------| | useFormPopup | 基于 Element Plus + form-create 的命令式表单弹窗 Hook | docs/form-popup.md | | useAbTable | 基于 Element Plus 的通用表格 Hook，分页/排序/搜索/表单弹窗开箱即用 | docs/table.md | | useTabManager | 基于 useStorage 的持久化标签页管理 Hook | 见下方快速开始 | | useCountdownPolling | 倒计时轮询 Hook，支持异步回调 | 见下方快速开始 | | request | 基于 axios 的通用 HTTP 请求封装，支持全局配置 | 见下方快速开始 |

快速开始

表单弹窗

// main.ts — 全局配置（可选，在应用入口调用一次）
import { configureFormPopup } from '@biancd/vale'

configureFormPopup({
  uploadHeaders: { Authorization: 'Bearer xxx' },
  uploadAction: '/api/upload',
})

<!-- 任意 .vue 组件中 -->
<script setup>
import { useFormPopup } from '@biancd/vale'

const popup = useFormPopup({
  rules: [
    { type: 'input', field: 'name', title: '名称', validate: [{ required: true }] },
  ],
  addService: (data) => api.create(data),
  editService: (data) => api.update(data),
})
</script>

<template>
  <el-button @click="popup.addShow()">新增</el-button>
  <el-button @click="popup.editShow(row)">编辑</el-button>
</template>

通用表格

<script setup>
import { useAbTable, AbTable, defaultOptButtons } from '@biancd/vale'
import type { CoTable } from '@biancd/vale'
import * as userApi from '@/api/user'

const options: CoTable = {
  column: [
    { type: 'selection' },
    { prop: 'name', label: '姓名', width: 120 },
    { prop: 'status', label: '状态', render: 'tag',
      replaceValue: { 1: '启用', 0: '禁用' },
      custom: { 1: 'success', 0: 'info' },
    },
    {
      render: 'buttons', label: '操作', width: 180,
      fixed: 'right', buttons: defaultOptButtons(),
    },
  ],
  formRules: [
    { type: 'input', field: 'name', title: '姓名', validate: [{ required: true }] },
  ],
}

const { table } = useAbTable(userApi, options)
</script>

<template>
  <AbTable />
</template>

标签页管理

<script setup>
import { useTabManager } from '@biancd/vale'
import ComponentA from './ComponentA.vue'
import ComponentB from './ComponentB.vue'

const { activeId, options, currentComponent } = useTabManager('my-tabs', [
  { label: '标签 A', value: 1, component: ComponentA },
  { label: '标签 B', value: 2, component: ComponentB },
])
</script>

<template>
  <el-segmented v-model="activeId" :options="options" />
  <component :is="currentComponent" />
</template>

倒计时轮询

<script setup>
import { useCountdownPolling } from '@biancd/vale'

const { countdown, running, start, stop, reset } = useCountdownPolling(
  30, // 每 30 秒轮询一次
  async () => {
    await fetchData() // 异步请求完成后才重置倒计时
  },
  (count) => {
    console.log(`剩余 ${count} 秒`)
  },
)
</script>

<template>
  <div>
    <span>倒计时: {{ countdown }}s</span>
    <el-button @click="start" :disabled="running">开始</el-button>
    <el-button @click="stop">停止</el-button>
    <el-button @click="reset">重置</el-button>
  </div>
</template>

HTTP 请求

// main.ts — 全局配置
import { configureRequest } from '@biancd/vale'

configureRequest({
  baseURL: import.meta.env.VITE_API_BASE,
  tokenGetter: () => useUserinfo().token,
  onUnauthorized: () => {
    useUserinfo().logout()
    window.location.hash = '/login'
  },
})

// 任意 .ts 文件中使用
import { request } from '@biancd/vale'

const users = await request<User[]>('/api/users')
await request('/api/user', { name: 'Alice' }, 'post', '创建成功')

// 创建独立配置的请求函数
import { createRequest } from '@biancd/vale'
const upload = createRequest({ baseURL: 'https://cdn.example.com' })

开发

npm install        # 安装依赖
npm run dev        # 开发模式（watch 构建）
npm run play       # 启动 playground，在真实环境中调试组件
npm run build      # 生产构建
npm test           # 运行测试
npm run test:watch # 监听模式测试