base-on-ui

base-on-ui 是基于 Vue 3 与 Element Plus 的通用业务组件库，面向中后台管理场景，当前提供表格与搜索、分页与弹窗、配置化表单引擎、上传、图标与 Cron 选择、文件预览（Word/Excel/PDF）、Markdown 渲染与编辑（含 KaTeX 公式）以及 v-copy 指令等能力，帮助你更快搭建 CRUD 页面与配置化表单界面。

说明：本仓库是已发布到 npm 的组件库包 base-on-ui 的源码仓库，npm 上安装使用的就是由此仓库打包构建生成的产物。

功能概览

当前组件库主要包含以下内容（均在 src/components 下）：

• BaseTable

  • 基于 el-table 的二次封装，支持：
  • 可配置列信息（tableHeader），支持对齐方式、宽度、formatter、自定义插槽等
  • 可选多选列（isSelection）
  • 与 BasePagination 组合使用，内置分页事件回调
  • 可选右侧列显隐工具栏（RightToolbar，通过 showToolbar 控制）

• BaseSearch

  • 配置化搜索表单组件，支持：
  • 通过 searchList 配置每一项的 type、label、prop 等
  • 内置 input / select / rangeDate / rangeDateTime / treeSelect 等常用类型
  • 超过 4 项时支持「展开/收起」
  • 点击「搜索」时会过滤空值，只将有意义的查询条件通过 handleSearch 事件回传
  • 支持「重置」功能

• BaseFormMini

  • 通过 config.formItems 配置项驱动的「迷你表单引擎」，支持：
  • 各种常见组件类型：input / textarea / select / cascader / date / number / radio / checkbox / switch / color / rate / slider / tags / divider / upload / list / object 等
  • 支持查看模式（isView）、编辑模式切换
  • 支持「分组锚点导航」（showMenu），自动高亮当前分组
  • 支持复杂嵌套结构（list、object），并提供字段打平 + 还原能力
  • 对 checkbox / upload 等特殊类型做了单独的值解析处理

• BaseFormJson

  • 基于 JSON 配置渲染表单 / 配置界面的组件集合：
  • JsonItem、TreeItem、StatsConfig 等子组件
  • 可用于构建可视化表单配置器或复杂 JSON 配置编辑界面

• BaseDialog

  • 基于 el-dialog 的业务弹窗封装：
  • 支持插槽扩展
  • 便于与 BaseFormMini 等表单组件配合使用

• BasePagination

  • 基于 Element Plus 分页器的封装：
  • 通过 pagination（如 pageNum、pageSize）与 total 控制分页
  • 通过 handlePagination 事件向外抛出分页变化

• BaseUpload

  • 基于上传组件的封装，便于在表单 / 弹窗中统一使用

• BaseFilePreview

  • 基于 @vue-office/docx、@vue-office/excel、@vue-office/pdf 的文件预览组件
  • 支持 Word（doc/docx）、Excel（xls/xlsx）、PDF，可传入远程 url 或本地二进制（File / Blob / ArrayBuffer），并通过 suffix 或 mimeType 指定类型
  • 依赖已随 base-on-ui 一起打包，业务项目 无需再单独安装 vue-office

• BaseIconSelect

  • 图标选择组件：
  • 内部维护可选图标列表（iconSelect.js）
  • 提供统一的图标选择交互

• BaseCronSelect

  • Cron 表达式选择组件：
  • 适用于定时任务、调度策略等场景

• ParentView

  • 一般用于路由嵌套场景的中间视图容器

• 指令：v-copy

  • 在 src/directives/copy.js 中实现，并在入口中通过 app.directive('copy', copy) 全局注册
  • 用法：v-copy="要复制的文本"，点击或触发时即可将文本复制到剪贴板

安装与使用

注意：以下为 npm 包使用方式，本仓库本身是 base-on-ui 的源码，你可以将它作为依赖使用，也可以 fork 后在此基础上二次开发。

安装

npm install base-on-ui
# 或
yarn add base-on-ui

全局注册

在你的 Vue 3 项目入口（例如 main.js）中：

import { createApp } from 'vue'
import App from './App.vue'

import BaseOnUI from 'base-on-ui'
import 'base-on-ui/style.css'

const app = createApp(App)

app.use(BaseOnUI)

app.mount('#app')

src/index.js 中导出了一个 install 方法，会：

• 批量注册所有组件（BaseCronSelect、BaseDialog、BaseFormJson、BaseFormMini、BaseFilePreview、BaseIconSelect、BasePagination、BaseSearch、BaseTable、BaseUpload）
• 注册全局指令 v-copy

你也可以按需导入单个组件使用：

import { BaseTable, BaseSearch } from 'base-on-ui'

BaseFilePreview 示例

<template>
  <BaseFilePreview
    src="https://example.com/files/demo.docx"
    suffix=".docx"
  />
</template>

若使用本地文件二进制，可传入 file（File / Blob / ArrayBuffer）并配合 suffix；组件会将二进制转为 ArrayBuffer 后交给 @vue-office/* 渲染。

典型使用示例（列表页）

下面是一个组合使用 BaseSearch + BaseTable + BasePagination 的典型列表页逻辑思路（仅作说明，非完整代码）：

<template>
  <BaseSearch
    :form="searchForm"
    :search-list="searchList"
    @handleSearch="handleSearch"
  />

  <BaseTable
    :table-header="tableHeader"
    :data-list="tableData"
    :pagination="pagination"
    :total="total"
    :loading="loading"
    :is-selection="true"
    :show-toolbar="true"
    @handleSelection="handleSelection"
    @handlePagination="handlePagination"
  />
</template>

项目结构简要说明

• src/index.js：组件库入口文件，导出 install 方法和各个组件的命名导出。
• src/components：所有业务组件的源码目录。
• src/directives/copy.js：全局复制指令实现。
• package.json
  • name: "base-on-ui"：npm 包名称。
  • main / module / exports：打包后 UMD / ES 模块入口以及样式导出。
  • peerDependencies：依赖的外部环境（如 vue、element-plus 等），在使用时需要由宿主项目自行安装。
  • scripts：dev 用于本地开发调试，build 使用 Vite 进行组件库打包。

开发与构建

如果你克隆了本源码仓库，想要本地调试或修改：

# 安装依赖
npm install

# 本地开发（基于 Vite）
npm run dev

# 构建组件库
npm run build

构建后的产物会输出到 dist 目录，并通过 package.json 中的 files 字段（如 dist 和 components）对外发布到 npm。

版权与许可

当前 package.json 中的 license 字段为 UNLICENSED，如需在生产环境或商业项目中使用、二次分发或修改本组件库，请根据实际情况自行确认和调整许可证信息。