# SIA UI 组件库

一个基于 Vue 3 + TypeScript + Vite 的现代化 UI 组件库，提供丰富的数据可视化和交互组件。

## ✨ 特性

- 🎨 **丰富的组件**: 包含数据可视化、表单、布局等 30+ 个组件
- 🔧 **TypeScript**: 完整的 TypeScript 类型支持
- 📱 **响应式**: 支持移动端和桌面端
- ⚡ **性能优化**: v1.2.0+ 外部化大型依赖，包体积更小
- 🎮 **Playground**: 所有组件支持在线实时编辑预览
- 🌐 **CDN 友好**: 支持 CDN 引入，适合快速原型开发

## 📦 安装

### 基础安装

```bash
# 安装组件库
npm install sia-ui

# 安装必需的 peer 依赖
npm install vue@^3.3.0
```

### 完整安装（推荐）

如果您的项目需要使用数据可视化和高级组件：

```bash
# 安装组件库和所有依赖
npm install sia-ui vue@^3.3.0 element-plus@^2.0.0 echarts@^5.0.0

# 安装样式
# 样式已包含在 sia-ui/dist/style.css 中
```

### 依赖说明

**必需依赖（peerDependencies）**：
- `vue@^3.3.0` - 必须安装

**可选依赖（部分组件需要）**：
- `element-plus@^2.0.0` - 部分组件基于 Element Plus
- `echarts@^5.0.0` - 图表组件需要

> 💡 **为什么要单独安装依赖？**
> - ✅ 包体积更小（从 5MB+ 降至 ~500KB）
> - ✅ 避免版本冲突
> - ✅ 更好的 tree-shaking
> - ✅ 您可以选择是否需要这些依赖

## 🚀 快速开始

### 完整引入

```javascript
import { createApp } from 'vue'
import SiaUI from 'sia-ui'
import 'sia-ui/dist/style.css'
import 'element-plus/dist/index.css'  // 如果使用了 Element Plus 相关组件

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

### 按需引入（推荐）

```javascript
// 使用大写别名导入（推荐）
import { Button, Table, Charts } from 'sia-ui'
import 'sia-ui/dist/style.css'

export default {
  components: {
    Button,    // 在模板中使用 <s-button>
    Table,     // 在模板中使用 <s-table>
    Charts     // 在模板中使用 <s-chart>
  }
}
```

或使用原始命名：

```javascript
import { sButton, sTable, sChart } from 'sia-ui'

export default {
  components: {
    sButton,   // 在模板中使用 <s-button>
    sTable,    // 在模板中使用 <s-table>
    sChart     // 在模板中使用 <s-chart>
  }
}
```

## 🔧 依赖说明

### v1.2.0+ 依赖策略

从 v1.2.0 开始，我们采用更合理的依赖管理策略：

**外部化的大型依赖**（需要用户自行安装）：
- `element-plus` - Element Plus UI 组件（可选）
- `echarts` - 图表库（可选）
- `vue-echarts` - Vue ECharts 组件（可选）

**内置的工具库**（无需安装）：
- `dayjs` - 日期处理
- `lodash-debounce` - 防抖函数
- 其他轻量级工具

### 组件依赖关系

不同组件需要的依赖：

| 组件类型 | 需要的依赖 |
|---------|-----------|
| 基础组件（Button, Calendar 等） | 仅需 Vue |
| 表格组件（Table） | Element Plus |
| 图表组件（Charts, ChartMap） | ECharts |
| 特殊组件（ChatGPT, Upload） | Element Plus |

### 版本兼容性

- **Vue**: ^3.3.0 (必需)
- **Element Plus**: ^2.0.0 (可选)
- **ECharts**: ^5.0.0 (可选)
- **Node.js**: ^14.18.0 || >=16.0.0
- **浏览器**: 支持 ES2015+ 的现代浏览器

### 📦 包大小

v1.2.0+ 优化后的包体积：

- **sia-ui.js**: ~500KB (gzip 后约 150KB)
- **sia-ui.umd.cjs**: ~500KB (gzip 后约 150KB)
- **style.css**: ~100KB

> 💡 相比 v1.1.x，包体积减少了 **90%**！

## 📚 组件列表

### 数据展示
- `sTable` - 高级表格组件
- `sChart` - 图表组件
- `sChartMap` - 地图图表
- `sStatistics` - 统计数字展示
- `sSticCard` - 统计卡片

### 表单组件
- `sButton` - 按钮组件
- `sForm` - 文件上传组件
- `sLogin` - 登录注册组件
- `sCalendar` - 日历组件

### 布局组件
- `sHeader` - 页面头部
- `sFooter` - 页面底部
- `sDrawer` - 抽屉组件
- `sDraggable` - 拖拽组件
- `sCardList` - 卡片列表

### 交互组件
- `sNotification` - 通知组件
- `sStep` - 步骤条
- `sTextScroll` - 文字滚动
- `sJump` - 跳跃动画
- `sCarousel` - 轮播组件

### 特殊功能
- `sChatAI` - AI 聊天组件
- `sOfficePreview` - 办公文档预览
- `sScreen` - 数据大屏
- `sWorkMonitor` - 工作监控

## 🎯 使用示例

### 基础组件示例

```vue
<template>
  <div>
    <!-- 按钮组件 - 注意使用 kebab-case -->
    <s-button type="primary">主要按钮</s-button>
    <s-button type="success">成功按钮</s-button>
    <s-button type="danger">危险按钮</s-button>
    
    <!-- 日历组件 -->
    <s-calendar v-model="date" />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { Button, Calendar } from 'sia-ui'
import 'sia-ui/dist/style.css'

const date = ref(new Date())
</script>
```

### 图表组件示例

```vue
<template>
  <div>
    <s-chart :option="chartOption" style="height: 400px;" />
  </div>
</template>

<script setup>
import { Charts } from 'sia-ui'
import 'sia-ui/dist/style.css'

const chartOption = {
  title: { text: '销售数据' },
  xAxis: { data: ['周一', '周二', '周三', '周四', '周五'] },
  yAxis: {},
  series: [{
    data: [120, 200, 150, 80, 170],
    type: 'line',
    smooth: true
  }]
}
</script>
```

### 表格组件示例

```vue
<template>
  <div>
    <s-table :data="tableData" />
  </div>
</template>

<script setup>
import { Table } from 'sia-ui'
import 'sia-ui/dist/style.css'
import 'element-plus/dist/index.css'

const tableData = [
  { id: 1, name: '张三', age: 18, city: '北京' },
  { id: 2, name: '李四', age: 25, city: '上海' },
  { id: 3, name: '王五', age: 30, city: '深圳' }
]
</script>
```

### 💡 注意事项

1. **导入名称 vs 模板标签名**
   ```javascript
   import { Button } from 'sia-ui'  // 导入用大写
   ```
   ```vue
   <s-button>文字</s-button>  // 模板用 kebab-case
   ```

2. **样式引入**
   ```javascript
   import 'sia-ui/dist/style.css'           // 必需
   import 'element-plus/dist/index.css'      // 使用 EP 组件时需要
   ```

3. **按需加载依赖**
   - 只使用基础组件？只需安装 `vue` 和 `sia-ui`
   - 需要图表？额外安装 `echarts`
   - 需要高级表格？额外安装 `element-plus`

## 🔨 开发

```bash
# 克隆项目
git clone <repository-url>

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建库
npm run build

# 构建文档
npm run docs:build
```

## 📖 文档

完整文档和在线演示: [查看文档](./docs/)

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

[ISC](./LICENSE)