npm package: @keqi.gress/plugin-ui
Description: Gress 插件 UI 组件和样式包 - 提供统一的设计系统、通用组件和完整的样式系统
Author: Gress Team
Latest version: 1.3.0

# @keqi.gress/plugin-ui

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

## 📦 安装

```bash
npm install @keqi.gress/plugin-ui
```

## 🚀 快速开始

### 1. 导入样式

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

### 2. 使用组件

```vue
<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
页面容器组件，提供统一的页面布局。

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

#### PageContent
页面内容区域组件。

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

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

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

**Props:**
- `title` (string, required): 页面标题
- `breadcrumb` (string, optional): 面包屑文本

### 数据展示组件（3个）

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

```vue
<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
分页组件。

```vue
<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
日志查看器组件，支持过滤、主题切换和自动滚动。

```vue
<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
过滤面板组件，支持基础和高级字段。

```vue
<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
通用弹窗组件，支持多种位置和可调整大小。

```vue
<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
加载状态组件。

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

**Props:**
- `message` (string, optional): 加载提示文本

#### EmptyState
空状态组件。

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

**Props:**
- `message` (string, optional): 主要提示文本
- `description` (string, optional): 描述文本

#### ErrorState
错误状态组件。

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

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

**Events:**
- `retry`: 重试

## 🎨 样式系统

### CSS 变量

包提供了完整的 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

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

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

## 🔧 Composables

### useLoadingState

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

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

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

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

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

### useResponsive

响应式断点检测。

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

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

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

## 📖 类型支持

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

```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](./CHANGELOG_V1.3.md)
- [组件迁移计划](./COMPONENT_MIGRATION_PLAN.md)
- [样式系统集成](./STYLE_SYSTEM_INTEGRATION.md)
- [使用示例](./USAGE_EXAMPLES.md)

## 📄 License

MIT