@keqi.gress/plugin-ui

Gress 插件 UI 组件和样式包 - 提供统一的设计系统、通用组件和完整的样式系统。

📦 安装

npm install @keqi.gress/plugin-ui

🚀 快速开始

1. 导入样式

// main.ts
import '@keqi.gress/plugin-ui/dist/style.css'

2. 使用组件

<template>
  <PageContainer>
    <PageHeader title="我的页面" breadcrumb="首页 / 我的页面" />
    <PageContent>
      <CardList>
        <div class="card">卡片内容</div>
      </CardList>
    </PageContent>
  </PageContainer>
</template>

<script setup lang="ts">
import { PageContainer, PageHeader, PageContent, CardList } from '@keqi.gress/plugin-ui'
</script>

📚 组件列表

布局组件（3个）

PageContainer

页面容器组件，提供统一的页面布局。

<PageContainer>
  <!-- 页面内容 -->
</PageContainer>

PageContent

页面内容区域组件。

<PageContent>
  <!-- 内容 -->
</PageContent>

PageHeader

页面头部组件，显示标题和面包屑。

<PageHeader 
  title="页面标题" 
  breadcrumb="首页 / 当前页" 
/>

Props:

• title (string, required): 页面标题
• breadcrumb (string, optional): 面包屑文本

数据展示组件（3个）

CardList

卡片列表容器，自动响应式布局。

<CardList size="medium" min-width="300px">
  <div class="card">卡片1</div>
  <div class="card">卡片2</div>
</CardList>

Props:

• size ('small' | 'medium' | 'large', optional): 卡片尺寸
• minWidth (string, optional): 最小宽度

PagePagination

分页组件。

<PagePagination
  v-model:page="currentPage"
  v-model:page-size="pageSize"
  :total="total"
  :page-sizes="[10, 20, 50, 100]"
  :show-size-picker="true"
/>

Props:

• page (number, required): 当前页码
• pageSize (number, required): 每页条数
• total (number, required): 总条数
• pageSizes (number[], optional): 每页条数选项
• showSizePicker (boolean, optional): 是否显示每页条数选择器

Events:

• update:page: 页码变化
• update:pageSize: 每页条数变化

LogViewer

日志查看器组件，支持过滤、主题切换和自动滚动。

<LogViewer
  :logs="logs"
  :loading="loading"
  :auto-scroll="true"
  default-theme="light"
  @refresh="handleRefresh"
  @clear="handleClear"
/>

Props:

• logs (LogItem[], required): 日志列表
• loading (boolean, optional): 是否加载中
• autoScroll (boolean, optional): 是否自动滚动到底部
• defaultTheme ('light' | 'dark', optional): 默认主题

Events:

• refresh: 刷新日志
• clear: 清空日志

交互组件（2个）

FilterPanel

过滤面板组件，支持基础和高级字段。

<FilterPanel
  v-model:filters="filters"
  v-model:show-advanced="showAdvanced"
  :basic-fields="basicFields"
  :advanced-fields="advancedFields"
  @search="handleSearch"
  @reset="handleReset"
/>

Props:

• filters (Record<string, unknown>, required): 过滤器值对象
• basicFields (FilterFieldConfig[], required): 基础字段配置
• advancedFields (FilterFieldConfig[], optional): 高级字段配置
• showAdvanced (boolean, optional): 是否展开高级字段
• searchText (string, optional): 搜索按钮文本
• resetText (string, optional): 重置按钮文本

Events:

• update:filters: 过滤器值变化
• update:showAdvanced: 展开状态变化
• search: 搜索
• reset: 重置

UniversalModal

通用弹窗组件，支持多种位置和可调整大小。

<UniversalModal
  v-model:show="showModal"
  title="弹窗标题"
  subtitle="副标题"
  position="right"
  width="600px"
  :show-mask="true"
  :resizable="true"
  :show-fullscreen="true"
  @confirm="handleConfirm"
>
  <div>弹窗内容</div>
</UniversalModal>

Props:

• show (boolean, required): 是否显示弹窗
• title (string, optional): 标题
• subtitle (string, optional): 副标题
• position ('center' | 'left' | 'right' | 'top' | 'bottom', optional): 位置
• width (string | number, optional): 宽度
• height (string | number, optional): 高度
• showMask (boolean, optional): 是否显示遮罩
• maskClosable (boolean, optional): 点击遮罩是否关闭
• resizable (boolean, optional): 是否可调整大小
• showFullscreen (boolean, optional): 显示全屏按钮

Events:

• update:show: 显示状态变化
• close: 关闭
• cancel: 取消
• confirm: 确认

Slots:

• header: 自定义头部
• default: 内容区域
• footer: 自定义底部

反馈组件（3个）

LoadingState

加载状态组件。

<LoadingState message="加载中..." />

Props:

• message (string, optional): 加载提示文本

EmptyState

空状态组件。

<EmptyState 
  message="暂无数据" 
  description="请尝试其他筛选条件"
/>

Props:

• message (string, optional): 主要提示文本
• description (string, optional): 描述文本

ErrorState

错误状态组件。

<ErrorState 
  message="加载失败" 
  :error="error"
  @retry="handleRetry"
/>

Props:

• message (string, optional): 错误提示文本
• error (Error | string, optional): 错误对象或消息

Events:

• retry: 重试

🎨 样式系统

CSS 变量

包提供了完整的 CSS 变量系统，支持运行时主题定制：

:root {
  /* 主色 */
  --primary-color: #18a058;
  --primary-hover: #36ad6a;
  --primary-pressed: #0c7a43;
  
  /* 背景色 */
  --body-color: #f5f5f5;
  --card-color: #ffffff;
  
  /* 文字色 */
  --text-color: #333333;
  --text-color-secondary: #666666;
  
  /* 边框 */
  --border-color: #e0e0e6;
  --border-radius: 4px;
  
  /* 间距 */
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
  --spacing-xl: 32px;
}

SCSS Mixins

// 在组件中使用
<style lang="scss" scoped>
@import "@/styles/variables.scss";
@import "@/styles/mixins.scss";

.my-component {
  @include card-shadow;
  @include custom-scrollbar;
}
</style>

🔧 Composables

useLoadingState

管理加载状态的组合式函数。

import { useLoadingState } from '@keqi.gress/plugin-ui'

const { isLoading, startLoading, stopLoading, withLoading } = useLoadingState()

// 手动控制
startLoading()
// ... 异步操作
stopLoading()

// 自动包装
await withLoading(async () => {
  await fetchData()
})

useResponsive

响应式断点检测。

import { useResponsive, breakpoints } from '@keqi.gress/plugin-ui'

const { isMobile, isTablet, isDesktop, currentBreakpoint } = useResponsive()

console.log(breakpoints) // { mobile: 768, tablet: 1024, desktop: 1280 }

📖 类型支持

包提供完整的 TypeScript 类型定义：

import type {
  PageHeaderProps,
  CardListProps,
  PagePaginationProps,
  LogItem,
  LogViewerProps,
  FilterFieldConfig,
  UniversalModalProps,
  PositionType
} from '@keqi.gress/plugin-ui'

🎯 设计原则

1. 零依赖设计 - 不强制依赖 Naive UI 或其他 UI 库
2. 插槽优先 - 支持自定义渲染
3. CSS 变量 - 支持运行时主题定制
4. TypeScript - 完整的类型支持
5. 响应式 - 移动端友好

📦 包信息

• 版本: 1.3.0
• 大小: 63.23 kB (未压缩) / 9.21 kB (gzip)
• 组件数量: 11 个
• 依赖: Vue 3.3+

🔗 相关链接

• CHANGELOG
• 组件迁移计划
• 样式系统集成
• 使用示例

📄 License

MIT