Joy Admin Components

基于 Vue 3、Element Plus 和 VxeTable 的管理后台组件库，提供了一套完整的后台管理系统解决方案。

特性

• 基于 Vue 3 Composition API
• TypeScript 类型支持
• 开箱即用的管理后台组件
• 丰富的工具函数和 Hook
• 完整的国际化支持（中英文）
• VxeTable 自定义渲染器
• Excel 导入导出功能

依赖要求

• Vue 3.3.4+
• Element Plus 2.3.8+
• VxeTable 4.12.0+
• vue-i18n 9.10.1+
• dayjs 1.11.19+

安装

npm install joy-admin-components

或使用 yarn：

yarn add joy-admin-components

快速开始

1. 配置国际化

// main.js
import { createApp } from 'vue';
import { createI18n } from 'vue-i18n';
import { setupI18n } from 'joy-admin-components';
import App from './App.vue';

// 创建 i18n 实例
const i18n = createI18n({
  legacy: false,
  locale: 'zh_cn',
  fallbackLocale: 'zh_cn',
  messages: {
    zh_cn: {},
    en: {}
  }
});

// 初始化组件库的国际化
setupI18n(i18n);

const app = createApp(App);
app.use(i18n);
app.mount('#app');

2. 注册 VxeTable 渲染器（可选）

如果需要使用 VxeTable 的自定义渲染器：

import { registerVxeRenderers } from 'joy-admin-components';

// 注册 VxeTable 渲染器
registerVxeRenderers();

3. 使用组件

组件支持按需导入：

<template>
  <ListPage
    id="userList"
    :api="getUserList"
    :searchForm="searchForm"
  >
    <vxe-column field="name" title="用户名" />
    <vxe-column field="email" title="邮箱" />
  </ListPage>
</template>

<script setup>
import { ListPage } from 'joy-admin-components';

const searchForm = {
  items: [
    { key: 'name', type: 'input', name: '用户名', value: '' }
  ]
};

async function getUserList(params) {
  // 调用 API 获取数据
  return {
    data: [],
    total: 0
  };
}
</script>

组件列表

ListPage - 列表页面组件

一个功能完整的列表页面组件，集成了搜索、表格、分页等功能。

ListPage

主要 Props：

| 参数 | 说明 | 类型 | 必填 | 默认值 | |------|------|------|------|--------| | id | 表格唯一标识 | string | 是 | - | | api | 获取数据的 API 函数 | Function | 否 | - | | data | 静态数据（不使用 API 时） | Array | 否 | [] | | searchForm | 搜索表单配置 | Object | 是 | - | | immediate | 是否立即请求数据 | boolean | 否 | true | | loading | 加载状态 | boolean | 否 | false |

searchForm 配置：

{
  items: [
    {
      key: 'field',         // 字段名
      type: 'input',        // 类型：input/select/date/custom
      name: '字段名称',      // 显示名称
      value: '',            // 默认值
      option: {}            // 其他选项
    }
  ],
  showSearch: true,        // 是否显示搜索栏
  showPage: true,          // 是否显示分页
  showCheckBox: true,      // 是否显示复选框
  showShadow: true         // 是否显示阴影
}

插槽：

• search-bar-btn: 搜索栏按钮区域
• table-header-left: 表格头部左侧区域
• default: 表格列定义

示例：

<ListPage
  id="productList"
  :api="getProducts"
  :searchForm="{
    items: [
      { key: 'name', type: 'input', name: '产品名称', value: '' },
      { key: 'status', type: 'select', name: '状态', value: '', option: {
        options: [
          { label: '在售', value: 1 },
          { label: '下架', value: 2 }
        ]
      }}
    ]
  }"
>
  <vxe-column field="name" title="产品名称" />
  <vxe-column field="price" title="价格" />
</ListPage>

SearchBar - 搜索栏组件

独立的搜索栏组件，支持多种输入类型。

SearchBar

Props：

| 参数 | 说明 | 类型 | 必填 | |------|------|------|------| | form | 表单配置 | Object | 是 |

事件：

• confirm: 点击筛选按钮
• reset: 点击重置按钮
• visibleChange: 展开/收起状态变化

表单项类型：

• input: 文本输入框
• select: 下拉选择（使用 CmpDictionary）
• date: 日期选择器
• custom: 自定义渲染

示例：

<SearchBar
  :form="{
    items: [
      { key: 'keyword', type: 'input', name: '关键词', value: '' },
      { key: 'createTime', type: 'date', name: '创建时间', value: '', dateType: 'daterange' }
    ]
  }"
  @confirm="handleSearch"
  @reset="handleReset"
>
  <template #btn>
    <el-button>自定义按钮</el-button>
  </template>
</SearchBar>

LayOutForm - 布局表单组件

自动布局的表单组件。

LayOutForm

CmpDictionary - 字典选择器

支持静态选项和动态加载的选择器组件。

CmpDictionary

CmpIcon - 图标组件

Element Plus 图标包装组件，简化图标使用。

CmpIcon

Props：

| 参数 | 说明 | 类型 | 必填 | |------|------|------|------| | name | 图标名称 | string | 是 |

示例：

<template>
  <CmpIcon name="Edit" />
  <CmpIcon name="Delete" />
  <CmpIcon name="Search" />
</template>

<script setup>
import { CmpIcon } from 'joy-admin-components';
</script>

ConfrimButton - 确认按钮

带二次确认的操作按钮。

ConfrimButton

ImportButton - 导入按钮

Excel 文件导入按钮。

ImportButton

DownExcelTemp - 下载模板按钮

Excel 模板下载按钮。

DownExcelTemp

工具函数

验证工具

import { creatValidator } from 'joy-admin-components';

// 创建表单验证器
const validator = creatValidator(rules);

Excel 工具

import { importExcel, exportExcel } from 'joy-admin-components';

// 导入 Excel
const data = await importExcel(file);

// 导出 Excel
exportExcel(data, 'filename.xlsx');

通用工具函数

import {
  sleep,                  // 延迟执行
  _toRaw,                // 转换为原始对象
  arrayToTree,           // 数组转树形结构
  stringToArray,         // 字符串转数组
  StatusMap,             // 状态映射类
  arrToStatusMap,        // 数组转状态映射
  stripHtmlTags,         // 移除 HTML 标签
  unicode2Str,           // Unicode 转字符串
  checkFileSize,         // 检查文件大小
  createListPageId,      // 创建列表页 ID
  createImportFields,    // 创建导入字段配置
  getValueBykey          // 根据 key 获取值
} from 'joy-admin-components';

Hook 函数

import {
  useRequest,            // 请求 Hook
  useDatePicker,         // 日期选择器 Hook
  _typeOf,               // 类型判断
  useI18nReState,        // 国际化响应式状态
  getLocaleValue,        // 获取本地化值
  useState,              // Vuex state Hook
  useGetters,            // Vuex getters Hook
  useActions             // Vuex actions Hook
} from 'joy-admin-components';

VxeTable 渲染器

registerVxeRenderers 提供了 5 种常用的 VxeTable 自定义渲染器，简化数据展示逻辑。

注册渲染器

在应用入口文件中注册：

import { registerVxeRenderers } from 'joy-admin-components';

// 注册 VxeTable 渲染器
registerVxeRenderers();

内置渲染器

| 渲染器 | 说明 | 使用场景 | |--------|------|----------| | Enum | 枚举值渲染器 | 状态、类型等枚举数据，支持彩色标签 | | InputNumber | 数字输入渲染器 | 表格内直接编辑数字 | | TrueFalse | 布尔值渲染器 | 是/否、真/假等布尔值，自动国际化 | | I18n | 国际化渲染器 | 根据语言环境自动切换字段 | | Link | 跳转链接渲染器 | 可点击跳转的链接，支持多个链接 |

详细文档

每个渲染器的详细参数、配置选项和高级用法，请查看：

📖 VxeTable 渲染器完整文档

国际化

组件库内置完整的国际化支持，详细使用说明请查看：国际化文档

快速配置：

import { createI18n } from 'vue-i18n';
import { setupI18n } from 'joy-admin-components';

const i18n = createI18n({
  legacy: false,
  locale: 'zh_cn',
  messages: { zh_cn: {}, en: {} }
});

setupI18n(i18n);

切换语言：

import { useI18n } from 'vue-i18n';

const { locale } = useI18n();
locale.value = 'en'; // 切换为英文

TypeScript 支持

所有组件和函数都包含 TypeScript 类型定义：

import type { SearchFormConfig } from 'joy-admin-components';

const searchForm: SearchFormConfig = {
  items: [
    { key: 'name', type: 'input', name: '名称', value: '' }
  ]
};

完整示例

<template>
  <div class="page">
    <ListPage
      id="userManagement"
      :api="getUserList"
      :searchForm="searchForm"
      @selection-change="handleSelectionChange"
    >
      <template #search-bar-btn>
        <el-button type="primary" @click="handleAdd">新增用户</el-button>
        <ImportButton :api="importUsers" @success="refresh" />
        <DownExcelTemp :template="userTemplate" />
      </template>

      <vxe-column field="id" title="ID" width="80" />

      <vxe-column
        field="name"
        title="用户名"
        cell-render="I18n"
        :cell-render-data="{ fieldEn: 'nameEn' }"
      />

      <vxe-column
        field="status"
        title="状态"
        cell-render="Enum"
        :cell-render-data="{ enum: statusEnum }"
      />

      <vxe-column
        field="isActive"
        title="是否激活"
        cell-render="TrueFalse"
      />

      <vxe-column title="操作" width="150">
        <template #default="{ row }">
          <el-button text @click="handleEdit(row)">编辑</el-button>
          <ConfrimButton
            text
            type="danger"
            @confirm="handleDelete(row.id)"
          >
            删除
          </ConfrimButton>
        </template>
      </vxe-column>
    </ListPage>
  </div>
</template>

<script setup>
import {
  ListPage,
  ImportButton,
  DownExcelTemp,
  ConfrimButton,
  registerVxeRenderers
} from 'joy-admin-components';
import { ref } from 'vue';

// 注册 VxeTable 渲染器
registerVxeRenderers();

// 搜索表单配置
const searchForm = {
  items: [
    { key: 'name', type: 'input', name: '用户名', value: '' },
    { key: 'status', type: 'select', name: '状态', value: '', option: {
      options: [
        { label: '启用', value: 1 },
        { label: '禁用', value: 2 }
      ]
    }},
    { key: 'createTime', type: 'date', name: '创建时间', value: '', dateType: 'daterange' }
  ]
};

// 状态枚举
const statusEnum = {
  getName: (value) => ({ 1: '启用', 2: '禁用' }[value] || '-'),
  getTag: (value) => ({ 1: 'success', 2: 'danger' }[value] || 'info')
};

// API 函数
async function getUserList(params) {
  const response = await fetch('/api/users', {
    method: 'POST',
    body: JSON.stringify(params)
  });
  return response.json();
}

// 事件处理
function handleSelectionChange(selection) {
  console.log('选中的数据：', selection);
}

function handleAdd() {
  // 新增用户逻辑
}

function handleEdit(row) {
  // 编辑用户逻辑
}

function handleDelete(id) {
  // 删除用户逻辑
}
</script>

浏览器支持

• Chrome >= 87
• Firefox >= 78
• Safari >= 14
• Edge >= 88

更多文档

• 国际化使用说明
• VxeTable 渲染器文档

License

MIT