@minte-ui/core

Minte UI（薄荷） 核心组件库，基于 Vue 3 构建，提供框架无关的模态框、抽屉、表单、数据表格四大组件，通过 API 驱动的方式统一管理组件状态。

特性

• API 驱动：所有组件均通过 useXxx Hook 返回的 API 对象控制状态，无需关心组件内部细节
• Schema 表单：声明式 JSON 驱动，支持动态联动、Zod 校验、字段依赖
• VXE 表格：基于 vxe-table 封装，内置查询表单、工具栏、分页
• UI 框架无关：核心逻辑与 UI 框架解耦，通过适配层（adapter）接入 Element Plus / Ant Design Vue 等
• TypeScript：完整类型声明，开箱即用

安装

npm install @minte-ui/core
# 或
pnpm add @minte-ui/core

注意：本包为核心层，不包含 UI 组件实现。实际使用时请安装对应 UI 框架的适配包：

• Element Plus：@minte-ui/adapter-element-plus
• Ant Design Vue：@minte-ui/adapter-ant-design-vue

快速上手

1. 全局初始化（以 Element Plus 为例）

// main.ts
import { createApp } from 'vue';
import ElementPlus from 'element-plus';
import 'element-plus/dist/index.css';
import '@minte-ui/core/dist/core.css';
import { setupMinteForm, setupMinteVxeTable } from '@minte-ui/adapter-element-plus';
import App from './App.vue';

const app = createApp(App);
app.use(ElementPlus);

// 注册表单组件
setupMinteForm();
// 注册表格组件（可选）
setupMinteVxeTable();

app.mount('#app');

模态框（Modal）

API

| 函数 | 说明 | |---|---| | useMinteModal(options?) | 创建模态框，返回 [ModalComponent, modalApi] | | setDefaultModalProps(props) | 设置全局默认 Modal 属性 | | provideMinteModalContainer() | 将 Modal 挂载到自定义容器 |

基础用法

<template>
  <!-- 直接使用组件（带自定义内容） -->
  <MyModal>
    <template #default>弹窗内容</template>
  </MyModal>
  <button @click="modalApi.open()">打开</button>
</template>

<script setup lang="ts">
import { useMinteModal } from '@minte-ui/core';

const [MyModal, modalApi] = useMinteModal({
  title: '提示',
  onConfirm() {
    console.log('确认');
    modalApi.close();
  },
  onCancel() {
    modalApi.close();
  },
});
</script>

ModalProps 配置项

| 属性 | 类型 | 默认值 | 说明 | |---|---|---|---| | title | string | — | 标题 | | description | string | — | 描述文本 | | width | string \| number | 520 | 宽度 | | fullscreen | boolean | false | 全屏 | | draggable | boolean | false | 可拖拽 | | centered | boolean | false | 垂直居中 | | loading | boolean | false | 确认按钮加载态 | | showFooter | boolean | true | 显示底部操作区 | | showConfirmButton | boolean | true | 显示确认按钮 | | showCancelButton | boolean | true | 显示取消按钮 | | confirmText | string | '确认' | 确认按钮文字 | | cancelText | string | '取消' | 取消按钮文字 | | onConfirm | () => void | — | 点击确认回调 | | onCancel | () => void | — | 点击取消回调 | | onClosed | () => void | — | 关闭动画结束回调 | | appendToMain | boolean | false | 挂载到主内容区而非 body |

ModalApi 方法

modalApi.open()           // 打开
modalApi.close()          // 关闭
modalApi.setState(state)  // 更新属性（支持函数形式）
modalApi.useStore()       // 获取响应式状态（ComputedRef）

抽屉（Drawer）

API

| 函数 | 说明 | |---|---| | useMinteDrawer(options?) | 创建抽屉，返回 [DrawerComponent, drawerApi] | | setDefaultDrawerProps(props) | 设置全局默认 Drawer 属性 | | provideMinteDrawerContainer() | 将 Drawer 挂载到自定义容器 |

基础用法

<template>
  <MyDrawer>
    <p>抽屉内容</p>
  </MyDrawer>
  <button @click="drawerApi.open()">打开抽屉</button>
</template>

<script setup lang="ts">
import { useMinteDrawer } from '@minte-ui/core';

const [MyDrawer, drawerApi] = useMinteDrawer({
  title: '详情',
  placement: 'right',
  width: 480,
});
</script>

DrawerProps 配置项

| 属性 | 类型 | 默认值 | 说明 | |---|---|---|---| | title | string | — | 标题 | | placement | 'left' \| 'right' \| 'top' \| 'bottom' | 'right' | 弹出方向 | | width | string \| number | 'auto' | 宽度（left/right 时有效）| | height | string \| number | 'auto' | 高度（top/bottom 时有效）| | showFooter | boolean | true | 显示底部 | | showConfirmButton | boolean | true | 显示确认按钮 | | confirmText | string | '确认' | 确认文字 | | cancelText | string | '取消' | 取消文字 | | loading | boolean | false | 加载态 | | onConfirm | () => void | — | 确认回调 | | onCancel | () => void | — | 取消回调 | | appendToMain | boolean | false | 挂载到主内容区 |

DrawerApi 方法

drawerApi.open()
drawerApi.close()
drawerApi.setState(state)
drawerApi.useStore()

表单（Form）

Schema 驱动的动态表单，基于 vee-validate + zod 实现校验。

API

| 函数 | 说明 | |---|---| | useMinteForm(options) | 创建表单，返回 [FormComponent, formApi] | | setupMinteForm(options) | 注册表单组件（在 main.ts 调用一次） | | z | 重导出的 Zod，用于编写校验规则 |

基础用法

<template>
  <MyForm />
</template>

<script setup lang="ts">
import { useMinteForm, z } from '@minte-ui/core';

const [MyForm, formApi] = useMinteForm({
  wrapperClass: 'grid-cols-2',
  schema: [
    {
      fieldName: 'username',
      label: '用户名',
      component: 'Input',
      rules: 'required',
      componentProps: { placeholder: '请输入用户名' },
    },
    {
      fieldName: 'email',
      label: '邮箱',
      component: 'Input',
      required: true,
      rules: z.string().email('请输入正确的邮箱格式'),
      componentProps: { placeholder: '请输入邮箱' },
    },
  ],
  showDefaultActions: true,
  onSubmit(values) {
    console.log(values);
  },
});
</script>

FormSchema 字段配置

| 属性 | 类型 | 说明 | |---|---|---| | fieldName | string | 字段名（必填）| | label | string | 标签 | | component | string \| Component | 使用的组件（需在 setupMinteForm 中注册）| | componentProps | object \| function | 组件 props，支持函数动态返回 | | rules | 'required' \| 'selectRequired' \| ZodSchema \| null | 校验规则 | | required | boolean | 是否显示必填星号（不影响校验） | | defaultValue | any | 默认值 | | disabled | boolean | 是否禁用 | | hide | boolean | 是否隐藏（v-if）| | colSpan | number | 占据列数（基于 24 列）| | formItemClass | string | 表单项 class（支持 col-span-* 布局）| | dependencies | FormItemDependencies | 动态联动配置 | | renderComponentContent | function | 渲染组件内部 slot | | suffix / prefix | () => VNode | 控件前后缀 | | description | string | 字段描述 | | help | string \| () => VNode | 帮助提示 | | fieldMappingTime | [string, [string, string], string?] | 时间范围字段拆分映射 |

动态联动（dependencies）

{
  fieldName: 'city',
  component: 'Select',
  dependencies: {
    triggerFields: ['province'],          // 监听 province 变化
    if: (values) => !!values.province,   // DOM 级显隐（v-if）
    show: (values) => ...,               // CSS 级显隐（v-show）
    disabled: (values) => ...,           // 动态禁用
    required: (values) => ...,           // 动态必填
    rules: (values) => ...,              // 动态校验规则
    componentProps: (values) => ({ options: [...] }), // 动态 props
    trigger: (values, formApi) => { ... }, // 自由联动副作用
  },
}

FormApi 方法

formApi.validate()                          // 触发校验，返回 Promise<values | false>
formApi.resetValidate()                     // 清除校验错误
formApi.getValues()                         // 获取当前值
formApi.setValues(values)                   // 批量设值
formApi.setFieldValue(field, value, shouldValidate?)         // 单字段设值
formApi.setState(state | (prev) => state)   // 更新表单配置
formApi.updateSchema(partialSchemas[])      // 更新指定字段 schema
formApi.removeSchemaByFields(fields[])      // 删除字段
formApi.merge(otherApi).submitAllForm()     // 合并多个表单一起提交
formApi.useStore(selector?)                 // 获取响应式状态

MinteFormProps 主要配置

| 属性 | 类型 | 默认值 | 说明 | |---|---|---|---| | schema | FormSchema[] | — | 字段定义 | | layout | 'horizontal' \| 'vertical' \| 'inline' | 'horizontal' | 布局方式 | | wrapperClass | string | — | 表单容器 class（如 grid-cols-2）| | commonConfig | FormCommonConfig | — | 公共配置（labelWidth、disabled 等）| | showDefaultActions | boolean | false | 显示默认提交/重置按钮 | | collapsed | boolean | false | 初始折叠（查询表单）| | collapsedRows | number | 1 | 折叠时显示行数 | | showCollapseButton | boolean | false | 显示折叠按钮 | | submitButtonOptions | object | — | 提交按钮配置（text/disabled/loading/show）| | resetButtonOptions | object | — | 重置按钮配置 | | actionPosition | 'left' \| 'center' \| 'right' | 'left' | 操作按钮对齐 | | fieldMappingTime | array | — | 全局时间范围字段映射 | | handleSubmit / onSubmit | (values) => void | — | 提交回调（二者等价）| | onReset | () => void | — | 重置回调 |

数据表格（Table）

基于 vxe-table 封装，内置与 Minte 表单的联动（查询 + 分页 + 工具栏）。

API

| 函数 | 说明 | |---|---| | useMinteVxeGrid(options) | 创建表格，返回 [GridComponent, gridApi] | | setupMinteVxeTable(options) | 注册 VXE 组件（在 main.ts 调用一次）|

基础用法

<template>
  <MyTable />
</template>

<script setup lang="ts">
import { useMinteVxeGrid } from '@minte-ui/core';

const [MyTable, tableApi] = useMinteVxeGrid({
  columns: [
    { field: 'name', title: '姓名', width: 120 },
    { field: 'age',  title: '年龄', width: 80 },
    { field: 'email', title: '邮箱' },
  ],
  proxyConfig: {
    ajax: {
      async query({ page }) {
        const res = await fetchList({ page: page.currentPage, pageSize: page.pageSize });
        return { result: res.data, total: res.total };
      },
    },
  },
  pagerConfig: { enabled: true },
  toolbarConfig: { refresh: true },
});
</script>

VxeGridApi 方法

tableApi.reload(params?)   // 刷新数据
tableApi.query(params?)    // 查询（重置到第1页）
tableApi.getGrid()         // 获取 vxe-grid 实例
tableApi.setState(state)   // 更新配置
tableApi.useStore()        // 获取响应式状态

自定义 CSS 变量

在项目中覆盖以下 CSS 变量可快速调整主题：

:root {
  --minte-primary: #409eff;
  --minte-border-radius: 4px;
  --minte-modal-z-index: 1000;
}

License

MIT © 2024 Minte UI