utop-ui-lib

Utop UI

基于 Element Plus 的企业级 Vue 3 组件库

安装

npm install utop-ui-lib
# 或
yarn add utop-ui-lib
# 或
pnpm add utop-ui-lib

使用

完整引入

// main.ts
import { createApp } from 'vue'
import UtopUI from 'utop-ui-lib'
import 'utop-ui-lib/dist/style.css'
import App from './App.vue'

const app = createApp(App)

app.use(UtopUI)
app.mount('#app')

按需引入

<template>
  <UtopDialogContainer v-model="visible" title="对话框">
    内容
  </UtopDialogContainer>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { UtopDialogContainer } from 'utop-ui-lib'

const visible = ref(false)
</script>

组件列表

基础组件

DialogContainer 对话框容器

统一的对话框容器组件，提供标准化的对话框样式和行为

<template>
  <UtopDialogContainer
    v-model="visible"
    title="标题"
    width="600px"
    :show-cancel="true"
    :show-confirm="true"
    @confirm="handleConfirm"
  >
    对话框内容
  </UtopDialogContainer>
</template>

Props

• title - 对话框标题
• width - 对话框宽度，默认 '50%'
• modelValue - 控制对话框显示隐藏
• showCancel - 是否显示取消按钮，默认 true
• showConfirm - 是否显示确认按钮，默认 true
• cancelText - 取消按钮文本，默认 '取消'
• confirmText - 确认按钮文本，默认 '确定'
• loading - 确认按钮加载状态
• scroll - 内容是否可滚动，默认 true

Events

• @update:modelValue - 显示状态改变
• @cancel - 取消按钮点击
• @confirm - 确认按钮点击

SectionTitle 区块标题

带装饰线的标题组件

<template>
  <UtopSectionTitle title="基本信息" :border="true">
    <template #right>
      <el-button type="primary">编辑</el-button>
    </template>
  </UtopSectionTitle>
</template>

Props

• title - 标题文本
• border - 是否显示左边装饰线，默认 true
• prefixIcon - 前缀图标组件

表单组件

FormPlus 增强表单

动态表单生成器，支持多种输入类型

<template>
  <UtopFormPlus
    v-model="formData"
    :items="formItems"
    :rules="rules"
    label-width="120px"
    @field-change="handleFieldChange"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { FormItem } from 'utop-ui-lib'

const formData = ref({
  name: '',
  age: '',
  gender: '',
  desc: ''
})

const formItems: FormItem[] = [
  {
    type: 'input',
    label: '姓名',
    prop: 'name',
    required: true,
    placeholder: '请输入姓名'
  },
  {
    type: 'select',
    label: '性别',
    prop: 'gender',
    options: [
      { label: '男', value: 'male' },
      { label: '女', value: 'female' }
    ]
  },
  {
    type: 'textarea',
    label: '描述',
    prop: 'desc',
    rows: 3
  }
]

const rules = {
  name: [
    { required: true, message: '请输入姓名', trigger: 'blur' }
  ]
}
</script>

支持的表单项类型

• input - 输入框
• textarea - 文本域
• select - 选择器
• radio - 单选框
• checkbox - 复选框
• date / datetime - 日期选择器
• number - 数字输入框
• switch - 开关
• slider - 滑块
• transfer - 穿梭框
• slot - 自定义插槽

DictSelect 字典选择器

支持动态加载字典数据的选择器

<template>
  <UtopDictSelect
    v-model="value"
    dict-type="gender"
    :api-method="loadDict"
    placeholder="请选择性别"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { DictOption } from 'utop-ui-lib'

const value = ref('')

const loadDict = async (dictType: string): Promise<DictOption[]> => {
  // 模拟API调用
  const dictData: Record<string, DictOption[]> = {
    gender: [
      { label: '男', value: 'male' },
      { label: '女', value: 'female' }
    ]
  }
  return dictData[dictType] || []
}
</script>

Props

• dictType - 字典类型
• apiMethod - 加载字典数据的方法
• options - 静态选项数据（优先于字典加载）
• labelKey - 选项标签字段名，默认 'label'
• valueKey - 选项值字段名，默认 'value'

表格组件

TablePlus 增强表格

功能强大的表格组件

<template>
  <UtopTablePlus
    :data="tableData"
    :columns="columns"
    :loading="loading"
    :show-selection="true"
    :show-index="true"
    :show-pagination="true"
    :total="total"
    v-model:page="currentPage"
    v-model:page-size="pageSize"
    @selection-change="handleSelectionChange"
    @button-click="handleButtonClick"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { TableColumn } from 'utop-ui-lib'

const tableData = ref([])
const loading = ref(false)
const total = ref(0)
const currentPage = ref(1)
const pageSize = ref(10)

const columns: TableColumn[] = [
  {
    type: 'button',
    label: '操作',
    buttons: [
      { label: '编辑', type: 'primary', onClick: (row) => edit(row) },
      { label: '删除', type: 'danger', onClick: (row) => del(row) }
    ]
  },
  {
    prop: 'name',
    label: '姓名',
    sortable: true
  },
  {
    prop: 'status',
    label: '状态',
    type: 'tag',
    tagTypes: {
      active: 'success',
      inactive: 'info'
    }
  }
]
</script>

特殊列类型

• button - 按钮列
• switch - 开关列
• tag - 标签列
• image - 图片列
• link - 链接列
• operation - 操作列

展示组件

Empty 空状态

空状态展示组件

<template>
  <UtopEmpty description="暂无数据">
    <el-button type="primary">创建</el-button>
  </UtopEmpty>
</template>

Props

• image - 自定义图片地址
• description - 描述文本，默认 '暂无数据'
• imageStyle - 图片样式

工具函数

import { utils } from 'utop-ui-lib'

// 格式化
utils.formatFileSize(1024) // 1 KB
utils.formatAmount(1234.56) // ¥1,234.56
utils.formatPhone('13800138000') // 138-0013-8000

// 验证
utils.isPhone('13800138000') // true
utils.isEmail('[e-mail]') // true
utils.isIdCard('110101199001011234') // true

// DOM操作
utils.scrollToElement(element, 100)
utils.copyToClipboard('复制的文本')
utils.debounce(fn, 300)

主题定制

通过 CSS 变量自定义主题：

:root {
  --utop-color-primary: #1890ff;
  --utop-color-success: #52c41a;
  --utop-color-warning: #faad14;
  --utop-color-danger: #ff4d4f;
}

开发

# 安装依赖
pnpm install

# 开发
pnpm dev

# 构建
pnpm build

# 类型检查
pnpm type-check

# 代码检查
pnpm lint

许可证

MIT