# biancd-vale

**Repository Path**: anthonyjhon/biancd-vale

## Basic Information

- **Project Name**: biancd-vale
- **Description**: 基于 Element Plus 的 Vue 3 功能组件库，提供命令式表单弹窗（useFormPopup）、通用表格（useAbTable）、标签页管理（useTabManager）、倒计时轮询（useCountdownPolling）和 HTTP 请求封装（request）等开箱即用的 Hook 和工具函数。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-09
- **Last Updated**: 2026-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# @biancd/vale

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

## 安装

```bash
npm install @biancd/vale
```

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

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

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

```ts
// 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](./docs/form-popup.md) |
| `useAbTable` | 基于 Element Plus 的通用表格 Hook，分页/排序/搜索/表单弹窗开箱即用 | [docs/table.md](./docs/table.md) |
| `useTabManager` | 基于 useStorage 的持久化标签页管理 Hook | 见下方快速开始 |
| `useCountdownPolling` | 倒计时轮询 Hook，支持异步回调 | 见下方快速开始 |
| `request` | 基于 axios 的通用 HTTP 请求封装，支持全局配置 | 见下方快速开始 |

## 快速开始

### 表单弹窗

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

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

```vue
<!-- 任意 .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>
```

### 通用表格

```vue
<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>
```

### 标签页管理

```vue
<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>
```

### 倒计时轮询

```vue
<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 请求

```ts
// 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
// 任意 .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' })
```

## 开发

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