@lacunist/ucui

UcUI

一套代码，双端渲染的 Vue 3 组件库。统一 API 之下按需驱动 element-plus 或 ant-design-vue 渲染，运行时可切换，无需改一行业务代码。

• 86 个组件统一 API（Uc 前缀），覆盖基础输入、表单容器、数据展示、反馈弹层、导航、布局
• 全量 TypeScript 类型声明（props / emits / expose 实例方法 / 全局属性）
• 完整双端契约测试（1400+ 用例），行为逐一对齐
• 服务式 API：$message / $notification / $messageBox 双端语义归一

安装

npm install @lacunist/ucui vue element-plus
# 或
npm install @lacunist/ucui vue ant-design-vue

element-plus / ant-design-vue 为可选 peer 依赖：一个项目只需安装你使用的那一套（也都安装则以 lib 选项为准）。

快速开始

从子入口安装，产物里只会包含你实际使用的那一端：

import { createApp } from 'vue'
import UcElement from '@lacunist/ucui/element'   // antd 端换成 '@lacunist/ucui/antd'
import 'element-plus/dist/index.css'             // 底层库样式由你引入
import App from './App.vue'

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

主入口 @lacunist/ucui 只含核心层（注册表 + 安装逻辑），不再内置适配器： 早期版本主入口同时 import 两套适配器，只用 element-plus 的项目也会被未安装的 ant-design-vue 拦在构建阶段。需要切库时见双端切换。

模板里直接使用统一组件：

<template>
  <UcButton type="primary" @click="submit">提交</UcButton>
  <UcInput v-model="name" placeholder="姓名" clearable />
  <UcSelect v-model="city" :options="options" />
</template>

双端切换

两端都要先注册，applyLib 才能切换（已渲染组件需配合子树 :key 重新渲染）：

import { applyLib } from '@lacunist/ucui'
import UcElement from '@lacunist/ucui/element'
import UcAntd from '@lacunist/ucui/antd'

app.use(UcElement)
app.use(UcAntd)          // 两端适配器都注册进核心层

applyLib(app, 'element') // 切回 element-plus
applyLib(app, 'antd')    // 切到 ant-design-vue

按需引入

子入口本身就是单端产物，也可只引单个组件，配合打包器 tree-shaking：

import { UcButton, UcInput } from '@lacunist/ucui/element'
import { UcButton, UcList } from '@lacunist/ucui/antd'   // antd 端

服务式 API

// 任意组件内（app.use 之后）
proxy.$message.success('已保存')
proxy.$notification.warning('磁盘告警', '可用空间不足 10%')
await proxy.$messageBox.confirm('确认删除？', '提示')   // Promise<'confirm'> / reject 'cancel'

TypeScript

• 所有组件的 props / emits 类型齐全，SFC 模板内 <UcButton type="primary" /> 自动补全（GlobalComponents）
• expose 实例方法：ref<InstanceType<typeof UcForm>>() 后 formRef.value?.validate() 有完整签名
• 服务式 API 类型经 ComponentCustomProperties 全局生效
• 公共类型从主入口导出：import type { UcOption, UcTableColumn } from '@lacunist/ucui'
• 子入口同样带类型：UcMessage / UcNotification / UcMessageBox 在 @lacunist/ucui/element、@lacunist/ucui/antd 上都有声明，不需要 as unknown as 绕过

从 0.1.x 升级

• 主入口不再内置适配器：app.use(UcUI, { lib }) 前要先 app.use(UcElement) / app.use(UcAntd)（或 registerAdapter），否则会抛出带用法提示的错误
• 服务式 API 的全局属性名修正为 $messageBox（旧版本实际挂成了 $messagebox，与类型声明和文档不一致）
• UcTable 的列支持 width / minWidth / align / fixed 等字段；render 产出的内容也吃得到父组件的 scoped 样式

组件清单（86 个）

完整 API 与示例见文档站（npm run docs:dev 本地启动）。

开发

npm install
npm run dev              # playground（双端切换 + 全组件演示）
npm run test:run         # 全量双端测试
npm run build            # 库构建（dist/）
npm run build:playground # playground 构建
npm run docs:dev         # 文档站

License

MIT