@upcloudx/ui

UpCloudX 通用业务 UI 组件库 & Hooks，基于 Vue 3 + Radix Vue，适用于中后台管理系统。

安装

pnpm add @upcloudx/ui

peerDependencies：

pnpm add vue dayjs

使用

<script setup lang="ts">
import { DataTable, SearchBar, StatusTag, useServerPagination } from '@upcloudx/ui';
</script>

样式随组件自动注入，无需手动引入 CSS 文件。

组件

组件	说明
PageHeader	带返回按钮的页面标题
SectionTitle	带左侧色块装饰的分区标题
StatusTag	业务状态标签，支持内置预设和自定义映射
ActionButtons	表格操作列按钮组，超出自动收纳到下拉菜单
CopyText	带一键复制功能的文本展示
EmptyState	统一空状态占位（默认/搜索无结果/加载失败）
DataTable	封装分页、加载状态、空状态的业务数据表格
SearchBar	列表页搜索/筛选栏，支持 input/select/date-range/date-picker
DetailCard	支持只读/编辑切换的详情信息卡片
FormModal	封装表单的新增/编辑弹窗
StepForm	多步骤向导表单
StatCard	统计数据卡片，支持趋势箭头和骨架屏
CurrencyDisplay	货币格式化展示，支持正负值着色
TabsPage	带 Tab 切换的页面容器，支持 sessionStorage 持久化

Hooks

Hook	说明
useConfirmAction	二次确认弹窗（删除/停用等危险操作）
useConfirm / confirmDelete	快捷确认/删除确认
useListSearch	列表页搜索/重置联动
useServerPagination	服务端分页状态管理
useModalForm	表单弹窗生命周期管理（打开回显/关闭重置/提交验证）
useStatusMapper	状态码到文本/颜色的映射工具
useProviderType	厂商类型格式化（aws→AWS, cloudflare→Cloudflare）
useDictData	字典数据加载
useUtcTime	UTC 时间格式化为本地时间
useUserOptions	用户列表 Select options
useCustomerOptions	客户列表 Select options + Map 查找
useDomainOptions	域名列表 Select options
usePagination	前端分页

组件示例

DataTable + SearchBar

<template>
  <SearchBar
    :fields="[
      { key: 'name', label: '名称', type: 'input', placeholder: '请输入名称' },
      { key: 'status', label: '状态', type: 'select', options: statusOptions },
    ]"
    :loading="loading"
    @search="handleSearch"
    @reset="handleReset"
  />
  <DataTable
    :columns="columns"
    :data-source="list"
    :loading="loading"
    :total="total"
    :page-num="currentPage"
    :page-size="pageSize"
    @page-change="handlePageChange"
  >
    <template #bodyCell="{ column, record }">
      <StatusTag v-if="column.key === 'status'" :status="record.status" preset="domain" />
      <ActionButtons
        v-if="column.key === 'action'"
        :actions="[
          { label: '编辑', onClick: () => handleEdit(record) },
          { label: '删除', onClick: () => handleDelete(record), danger: true },
        ]"
      />
    </template>
  </DataTable>
</template>

useServerPagination + useListSearch

import { useServerPagination, useListSearch, useConfirmAction } from '@upcloudx/ui';

const { currentPage, pageSize, total, paginationConfig, resetPage, setTotal } =
  useServerPagination({ loadFn: loadData });

const { handleSearch, handleReset } = useListSearch({
  formRef,
  resetPage,
  loadFn: loadData,
});

const { confirmDelete } = useConfirmAction();

StatusTag 预设

<!-- 域名状态 -->
<StatusTag :status="4" preset="domain" />

<!-- 证书状态 -->
<StatusTag :status="2" preset="certificate" />

<!-- 自定义映射 -->
<StatusTag
  :status="record.status"
  :status-map="{ 0: { text: '待审核', color: 'processing' }, 1: { text: '已通过', color: 'success' } }"
/>

迁移说明（v0.4.0）

从 v0.3.x 升级时，ant-design-vue 不再是 peerDependency，可以从项目中移除（如果没有其他地方使用）。

组件 API 保持不变，无需修改业务代码。

Vite 插件

// vite.config.ts
import { vitePreauthLoadingPlugin } from '@upcloudx/ui/vite';

export default defineConfig({
  plugins: [vitePreauthLoadingPlugin()],
});

注入预认证 Loading Screen 到 index.html，配合 createPreAuth 使用。

开发

# 安装依赖
pnpm install

# 构建
pnpm build

# 监听模式
pnpm dev

发布

推送 tag 自动触发 GitHub Actions 发布到 npm：

# 修改 package.json 中的 version
git add -A && git commit -m "release: v0.x.x"
git tag v0.x.x
git push origin main --tags

License

MIT