# cimos7-vue3-common 使用文档

## 概述

cimos7-vue3-common 是一个基于 Vue 3 的通用组件库，提供了丰富的 UI 组件和工具类，帮助开发者快速构建企业级应用。

---

## 目录

1. [安装](#安装)
2. [快速开始](#快速开始)
3. [样式工具类](#样式工具类)
4. [组件列表](#组件列表)
5. [工具方法](#工具方法)

---

## 安装

### NPM

```bash
npm install cimos7-vue3-common
```

### Yarn

```bash
yarn add cimos7-vue3-common
```

---

## 快速开始

### 引入样式

在项目入口文件中引入样式：

```javascript
import 'cimos7-vue3-common/lib/styles/cimos7-vue3-common.css'
```

### 全局注册组件

```javascript
import { createApp } from 'vue'
import App from './App.vue'
import { ZyButton, ZyInput } from 'cimos7-vue3-common'

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

### 按需引入

```vue
<template>
  <div>
    <ZyButton type="primary">按钮</ZyButton>
  </div>
</template>

<script setup>
import { ZyButton } from 'cimos7-vue3-common'
</script>
```

---

## 样式工具类

### Flex 布局工具类

| 类名 | 描述 |
|------|------|
| `.flex-box` | 水平两端对齐，垂直居中 |
| `.flex-box-top` | 水平两端对齐，垂直顶部对齐 |
| `.flex-center` | 水平居中，垂直居中，允许换行 |
| `.flex-center-top` | 水平居中，垂直顶部对齐 |
| `.flex-top` | 水平居中，垂直顶部对齐 |
| `.flex-left` | 水平左对齐，垂直居中，允许换行 |
| `.flex-left-nowrap` | 水平左对齐，垂直居中，不换行 |
| `.flex-left-top` | 水平左对齐，垂直顶部对齐 |
| `.flex-right` | 水平右对齐，垂直居中 |
| `.flex-right-top` | 水平右对齐，垂直顶部对齐 |
| `.flex-around` | 水平均匀分布，垂直居中 |
| `.flex-around-top` | 水平均匀分布，垂直顶部对齐 |
| `.item-center` | 垂直方向居中 |
| `.item-top` | 垂直方向顶部对齐 |
| `.item-center-all` | 垂直水平都居中 |
| `.item-box` | 垂直方向两端对齐 |

### 间距工具类 (Padding & Margin)

**Padding 尺寸：12px, 16px, 24px, 32px**

| 类名 | 描述 |
|------|------|
| `.p-{size}` | 四周内边距 (p-12, p-16, p-24, p-32) |
| `.pl-{size}` | 左侧内边距 (pl-12, pl-16, pl-24, pl-32) |
| `.pr-{size}` | 右侧内边距 (pr-12, pr-16, pr-24, pr-32) |
| `.pt-{size}` | 顶部内边距 (pt-12, pt-16, pt-24, pt-32) |
| `.pb-{size}` | 底部内边距 (pb-12, pb-16, pb-24, pb-32) |

**Margin 尺寸：12px, 16px, 24px, 32px**

| 类名 | 描述 |
|------|------|
| `.m-{size}` | 四周外边距 (m-12, m-16, m-24, m-32) |
| `.ml-{size}` | 左侧外边距 (ml-12, ml-16, ml-24, ml-32) |
| `.mr-{size}` | 右侧外边距 (mr-12, mr-16, mr-24, mr-32) |
| `.mt-{size}` | 顶部外边距 (mt-12, mt-16, mt-24, mt-32) |
| `.mb-{size}` | 底部外边距 (mb-12, mb-16, mb-24, mb-32) |

### 尺寸工具类

| 类名 | 描述 |
|------|------|
| `.w-100` | 宽度 100% |
| `.w-50` | 宽度 50% |
| `.w-auto` | 宽度自适应 |
| `.h-100` | 高度 100% |
| `.h-auto` | 高度自适应 |

### 文本工具类

| 类名 | 描述 |
|------|------|
| `.text-left` | 左对齐 |
| `.text-center` | 居中对齐 |
| `.text-right` | 右对齐 |
| `.font-12` | 12px |
| `.font-14` | 14px |
| `.font-16` | 16px |
| `.font-18` | 18px |
| `.font-20` | 20px |
| `.font-bold` | 粗体 |
| `.font-normal` | 正常 |
| `.text-ellipsis` | 单行溢出省略 |

### 颜色工具类

| 类名 | 描述 |
|------|------|
| `.text-primary` | 主题色 |
| `.text-success` | 成功色 |
| `.text-warning` | 警告色 |
| `.text-danger` | 危险/错误色 |
| `.text-info` | 信息色（主标题） |
| `.text-secondary` | 次要色（副标题） |

### 显示工具类

| 类名 | 描述 |
|------|------|
| `.d-block` | 块级显示 |
| `.d-inline-block` | 行内块显示 |
| `.d-none` | 隐藏 |
| `.d-flex` | flex 显示 |

### 其他工具类

| 类名 | 描述 |
|------|------|
| `.overflow-hidden` | 溢出隐藏 |
| `.overflow-auto` | 溢出滚动 |
| `.position-relative` | 相对定位 |
| `.position-absolute` | 绝对定位 |
| `.position-fixed` | 固定定位 |
| `.border-radius-4` | 4px 圆角 |
| `.border-radius-8` | 8px 圆角 |
| `.border-radius-50` | 50% 圆角（圆形） |
| `.border` | 四周边框 |
| `.border-top` | 顶部边框 |
| `.border-bottom` | 底部边框 |
| `.border-left` | 左侧边框 |
| `.border-right` | 右侧边框 |
| `.cursor-pointer` | 手型光标 |
| `.cursor-not-allowed` | 禁止光标 |
| `.cursor-default` | 默认光标 |
| `.user-select-none` | 禁止选择 |
| `.user-select-auto` | 允许选择 |
| `.box-shadow` | 盒子阴影 |
| `.bg-primary` | 主题色背景 |
| `.bg-white` | 白色背景 |
| `.bg-gray` | 灰色背景 |

### 滚动条样式类

| 类名 | 描述 |
|------|------|
| `.innerBox` | 纵向滚动条样式（必须设置高度或最大高度） |
| `.innerBox-x` | 横向滚动条样式 |

**滚动条样式使用示例：**

```html
<!-- 纵向滚动条 -->
<div class="innerBox h-100">
  <div>内容...</div>
</div>

<!-- 横向滚动条 -->
<div class="innerBox-x w-100">
  <div>内容1</div>
  <div>内容2</div>
  <div>内容3</div>
</div>
```

### 工具类使用示例

```html
<div class="flex-box p-24">
  <div class="text-left">左侧内容</div>
  <div class="text-right">右侧内容</div>
</div>

<div class="flex-center h-100">
  <div>垂直水平居中的内容</div>
</div>

<div class="p-16 border border-radius-8 box-shadow bg-white">
  <h3 class="font-16 font-bold text-primary">标题</h3>
  <p class="mt-12 text-secondary">内容描述</p>
</div>
```

---

## 组件列表

### 布局组件

- **AppLayout**: 应用主布局
- **AppHeader**: 应用头部
- **LeftMenu**: 左侧菜单
- **PageLayout**: 页面布局
- **WrapperPage**: 分页包装器
- **WrapperSearch**: 搜索包装器

### 表单组件

- **FormItem**: 表单项
- **FormTitle**: 表单标题
- **ButtonTest**: 按钮测试组件
- **DeptSelect**: 部门选择器
- **UserSelectDialog**: 用户选择对话框

### 数据展示组件

- **FieldList**: 字段列表
- **FileList**: 文件列表
- **ImageList**: 图片列表
- **TableBtns**: 表格按钮组
- **MultiTip**: 多选提示
- **Avatar**: 头像组件
- **Photo**: 照片组件

### 功能组件

- **Editor**: 富文本编辑器
- **ZyPage**: 分页组件
- **ZyNavigator**: 导航栏组件

---

## 工具方法

### Ajax 请求

```javascript
import { Ajax, SuccessAjax } from 'cimos7-vue3-common'

// 基础请求
Ajax(url, params, options)
  .then(res => console.log(res))
  .catch(err => console.error(err))

// 带业务码处理的请求
SuccessAjax(url, params, options)
  .then(({ data }) => console.log(data))
  .catch(err => console.error(err))
```

### 存储

```javascript
import { Storage, LocalStorage, SessionStorage } from 'cimos7-vue3-common'

// 通用存储（默认 sessionStorage）
Storage.set('key', 'value')  // 存储 session  localStorage
Storage.get('key') // 取sessionStorage
Storage.remove('key')  // 移除指定key
Storage.clearAll() // 清空全部

// localStorage
LocalStorage.set('key', 'value')
LocalStorage.get('key')
LocalStorage.remove('key')
LocalStorage.clearAll()
// sessionStorage
SessionStorage.set('key', 'value')
SessionStorage.get('key')
SessionStorage.remove('key')
SessionStorage.clearAll()
```

### Token 管理

```javascript
import { GetToken, GetLoginInfo } from 'cimos7-vue3-common'

const token = GetToken()
const loginInfo = GetLoginInfo()
```

### 加载状态

```javascript
import { Loading } from 'cimos7-vue3-common'

Loading.ShowLoading()
Loading.HidenLoading()
```

### 其他工具

```javascript
import { ExitLogin, GoHome } from 'cimos7-vue3-common'

ExitLogin() // 退出登录
GoHome()    // 返回首页
```

---

## 主题定制

### CSS 变量

在项目中覆盖 CSS 变量即可定制主题：

```css
:root {
  --main-color: #1890ff; /* 主色调 */
  --main-color-hover: #40a9ff; /* 主色调悬浮 */
  --success-color: #52c41a; /* 成功色 */
  --warning-color: #faad14; /* 警告色 */
  --danger-color: #ff4d4f; /* 危险色 */
}
```

---

## 注意事项

1. 确保已安装 Vue 3 和 Element Plus
2. 样式工具类可以组合使用
3. 组件默认使用中文，如需国际化请配置 Element Plus
4. 建议在项目中使用按需引入以减小打包体积

---

## 更新日志

### v0.3.0
- 添加滚动条样式类 (.innerBox, .innerBox-x)
- 完善CSS使用文档
- 优化滚动条样式，支持Chrome、Edge、Firefox浏览器

### v0.2.9
- 完善 baseCommon.less 工具类
- 修复 CSS 变量问题
- 优化组件样式

---

## 许可证

MIT License
