vsoft-ui 1.0.2 → 1.0.4

package/README.md

@@ -0,0 +1,240 @@
+# VSoft UI
+
+基于 Element Plus 的二次封装组件库，包含全局权限控制功能。
+
+## 特性
+
+- 📦 基于 Element Plus 二次封装
+- 🔒 内置全局权限控制功能
+- 🚀 支持 Vue 3 + TypeScript
+- 📖 完整的类型定义
+- 💪 组件化开发，易于维护和扩展
+- 📱 响应式设计，适配各种设备
+
+## 安装
+
+使用 pnpm 安装：
+
+```bash
+pnpm add vsoft-ui
+```
+
+## 快速开始
+
+### 1. 引入组件库
+
+在 main.ts 中引入并安装组件库，组件库会自动安装 Element Plus 和注册所有图标：
+
+```typescript
+import { createApp } from 'vue'
+import App from './App.vue'
+import VSoftUI from 'vsoft-ui'
+
+const app = createApp(App)
+
+// 安装 VSoft UI 组件库（自动安装 Element Plus 和注册所有图标）
+app.use(VSoftUI)
+
+app.mount('#app')
+```
+
+### 2. 初始化权限
+
+在应用初始化时设置权限列表：
+
+```typescript
+import { usePermission } from 'vsoft-ui'
+
+const { setPermissions } = usePermission()
+
+// 设置权限列表
+setPermissions(['user:view', 'user:edit', 'button:click'])
+```
+
+### 3. 使用图标
+
+组件库自动注册了所有 Element Plus 图标，您可以在封装组件中直接使用：
+
+```vue
+<!-- 在封装组件中直接使用图标名称 -->
+<v-button type="primary" icon="Plus">添加</v-button>
+
+<!-- 在封装组件中使用图标组件 -->
+<v-button type="success">
+  <el-icon><Edit /></el-icon>
+  编辑
+</v-button>
+```
+
+## 全局权限控制
+
+### 1. 权限控制指令 `v-permission`
+
+**基本用法：**
+
+```vue
+<!-- 单个权限 -->
+<v-button v-permission="'user:view'" type="primary">查看用户</v-button>
+
+<!-- any模式（默认）- 满足任一权限 -->
+<v-button v-permission="['user:view', 'user:edit']" type="success">编辑用户</v-button>
+
+<!-- all模式 - 需要所有权限 -->
+<v-button v-permission:all="['user:view', 'user:edit']" type="warning">需要查看和编辑权限</v-button>
+
+<!-- 黑名单模式（无此权限时显示） -->
+<v-button v-permission:blacklist="'user:delete'" type="danger">删除用户</v-button>
+
+<!-- 黑名单 + all模式 -->
+<v-button v-permission:blacklist.all="['user:delete', 'user:update']" type="info">无删除和更新权限时显示</v-button>
+```
+
+### 2. 权限控制组合式函数 `usePermission`
+
+**基本用法：**
+
+```vue
+<script setup lang="ts">
+import { usePermission } from 'vsoft-ui'
+
+const { hasPermission, hasAllPermissions, setPermissions, getPermissions, clearPermissions } = usePermission()
+
+// 检查单个权限
+const canView = hasPermission('user:view')
+
+// 检查多个权限（满足任一即可）
+const canEditOrDelete = hasPermission(['user:edit', 'user:delete'])
+
+// 检查所有权限（必须全部满足）
+const hasAll = hasAllPermissions(['user:view', 'user:edit'])
+
+// 设置权限
+setPermissions(['user:view', 'user:edit'])
+
+// 获取权限列表
+const permissions = getPermissions()
+
+// 清除权限
+clearPermissions()
+</script>
+```
+
+## 示例组件
+
+### VButton 组件
+
+基于 Element Plus Button 二次封装，内置权限控制功能。
+
+**基本用法：**
+
+```vue
+<!-- 有权限的按钮 -->
+<v-button permission="button:click" type="primary">点击按钮</v-button>
+
+<!-- 无权限的按钮（自动禁用） -->
+<v-button permission="button:disabled" type="success">禁用按钮</v-button>
+
+<!-- 多权限按钮 -->
+<v-button permission="['user:view', 'button:click']" type="warning">多权限按钮</v-button>
+
+<!-- 黑名单模式 -->
+<v-button permission="user:delete" permission-mode="blacklist" type="danger">黑名单按钮</v-button>
+```
+
+**Props：**
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| permission | `string  string[]` | `undefined` | 按钮所需权限 |
+| permission-mode | `'whitelist'  'blacklist'` | `'whitelist'` | 权限模式 |
+| 其他属性 | - | - | 继承 Element Plus Button 的所有属性 |
+
+## 构建和发布
+
+### 构建组件库
+
+```bash
+# 构建组件库
+pnpm run build
+
+# 生成类型声明文件
+pnpm run build:types
+```
+
+### 开发模式
+
+```bash
+# 启动开发服务器
+pnpm run dev
+```
+
+### 代码检查
+
+```bash
+# 运行 ESLint 检查
+pnpm run lint
+```
+
+## 目录结构
+
+```
+├── src/
+│   ├── components/          # 组件目录
+│   │   └── VButton/         # VButton 组件
+│   ├── directives/          # 指令目录
+│   │   └── permission.ts    # 权限控制指令
+│   ├── composables/         # 组合式函数目录
+│   │   └── usePermission.ts # 权限控制组合式函数
+│   ├── utils/               # 工具函数目录
+│   │   └── permission.ts    # 权限管理工具
+│   ├── styles/              # 样式目录
+│   └── index.ts             # 入口文件
+├── examples/                # 示例应用
+├── types/                   # 类型定义
+├── vite.config.ts           # Vite 配置
+├── tsconfig.json            # TypeScript 配置
+└── package.json             # 项目配置
+```
+
+## 开发指南
+
+### 1. 创建新组件
+
+在 `src/components` 目录下创建新组件目录，包含 `index.vue` 和 `index.ts` 文件：
+
+```bash
+mkdir -p src/components/NewComponent
+```
+
+### 2. 编写组件代码
+
+在 `index.vue` 中编写组件逻辑，在 `index.ts` 中导出组件：
+
+```typescript
+// src/components/NewComponent/index.ts
+import NewComponent from './index.vue'
+
+export { NewComponent }
+export default NewComponent
+```
+
+### 3. 导出组件
+
+在 `src/index.ts` 中导出新组件：
+
+```typescript
+// src/index.ts
+export * from './components/NewComponent'
+
+// 在 install 函数中注册组件
+export const install = (app: App) => {
+  // 已有的组件注册
+  app.component('VButton', VButton)
+  // 新组件注册
+  app.component('NewComponent', NewComponent)
+}
+```
+
+## 许可证
+
+MIT