vsoft-ui 1.0.3 → 1.0.4

package/README.md

@@ -1,214 +1,240 @@
-# VSoft UI
-
-基于 Element Plus 的 Vue3 组件库，支持全局权限控制
-
-[![npm version](https://img.shields.io/npm/v/vsoft-ui.svg)](https://www.npmjs.com/package/vsoft-ui)
-[![license](https://img.shields.io/npm/l/vsoft-ui.svg)](https://github.com/your-username/vsoft-ui/blob/main/LICENSE)
-[![vue](https://img.shields.io/badge/Vue-3.3+-brightgreen.svg)](https://vuejs.org/)
-[![element-plus](https://img.shields.io/badge/Element%20Plus-2.13+-blue.svg)](https://element-plus.org/)
-
-## 简介
-
-VSoft UI 是一个基于 Vue 3 和 Element Plus 的二次封装组件库，专注于提供简单高效的权限控制解决方案。通过组件级、指令级和 Hook 级三种权限控制方式，帮助开发者快速构建具有权限管理功能的应用。
-
-## 主要特性
-
-- 📦 基于 Element Plus，提供一致的设计语言
-- 🔒 内置权限控制功能，支持三种权限控制方式
-- 🚀 零学习成本，基于 Vue 3 Composition API
-- 📝 完整的 TypeScript 支持
-- 🛠️ 丰富的示例和详细文档
-
-## 快速开始
-
-### 安装
-
-```bash
-# 使用 pnpm（推荐）
-pnpm add vsoft-ui
-
-# 或使用 npm
-npm install vsoft-ui
-
-# 或使用 yarn
-yarn add vsoft-ui
-```
-
-### 引入
-
-```typescript
-import { createApp } from 'vue'
-import ElementPlus from 'element-plus'
-import 'element-plus/dist/index.css'
-import VSoftUI from 'vsoft-ui'
-import App from './App.vue'
-
-const app = createApp(App)
-app.use(ElementPlus)
-app.use(VSoftUI)
-app.mount('#app')
-```
-
-### 设置权限
-
-在应用启动时设置用户权限：
-
-```typescript
-// main.ts
-import { permission } from 'vsoft-ui'
-
-// 设置用户权限
-permission.setPermissions(['button:add', 'button:edit', 'input:query'])
-```
-
-## 组件使用
-
-### 按钮组件
-
-```vue
-<template>
-  <!-- 基本用法 -->
-  <v-button type="primary">主要按钮</v-button>
-  
-  <!-- 权限控制 -->
-  <v-button type="success" permission="button:add">添加按钮</v-button>
-  <v-button type="warning" permission="['button:edit', 'button:update']">编辑按钮</v-button>
-  <v-button type="danger" permission="['button:delete', 'button:manage']" permission-mode="all">删除按钮</v-button>
-</template>
-```
-
-### 输入框组件
-
-```vue
-<template>
-  <!-- 基本用法 -->
-  <v-input v-model="value" placeholder="请输入内容" />
-  
-  <!-- 权限控制 -->
-  <v-input v-model="value" permission="input:query" placeholder="查询输入框" />
-</template>
-
-<script setup lang="ts">
-import { ref } from 'vue'
-
-const value = ref('')
-</script>
-```
-
-## 权限控制
-
-VSoft UI 提供三种权限控制方式：
-
-### 1. 组件级权限控制
-
-所有 VSoft UI 组件都支持 `permission` 和 `permission-mode` 属性：
-
-```vue
-<template>
-  <!-- 基本权限控制 -->
-  <v-button permission="button:add">添加按钮</v-button>
-  
-  <!-- 多权限控制（任一权限） -->
-  <v-button permission="['button:edit', 'button:update']">编辑按钮</v-button>
-  
-  <!-- 多权限控制（所有权限） -->
-  <v-button permission="['button:delete', 'button:manage']" permission-mode="all">删除按钮</v-button>
-</template>
-```
-
-### 2. 指令级权限控制
-
-使用 `v-permission` 指令对任何元素进行权限控制：
-
-```vue
-<template>
-  <!-- 基本权限控制 -->
-  <el-button v-permission="'button:delete'" type="danger">删除按钮</el-button>
-  
-  <!-- 使用 any 修饰符 -->
-  <el-button v-permission:any="['button:edit', 'button:update']" type="warning">编辑按钮</el-button>
-  
-  <!-- 使用 all 修饰符 -->
-  <el-button v-permission:all="['button:manage', 'button:admin']" type="primary">管理按钮</el-button>
-</template>
-```
-
-### 3. Hook 级权限控制
-
-使用 `usePermission` Hook 进行更灵活的权限判断：
-
-```vue
-<template>
-  <el-button v-if="canAdd" type="primary" @click="handleAdd">添加按钮</el-button>
-  <el-button v-if="canEdit" type="success" @click="handleEdit">编辑按钮</el-button>
-</template>
-
-<script setup lang="ts">
-import { usePermission } from 'vsoft-ui'
-
-const { hasPermission } = usePermission()
-
-const canAdd = hasPermission('button:add')
-const canEdit = hasPermission('button:edit')
-
-const handleAdd = () => { /* ... */ }
-const handleEdit = () => { /* ... */ }
-</script>
-```
-
-## 开发
-
-### 运行示例
-
-```bash
-pnpm dev
-```
-
-### 构建
-
-```bash
-pnpm build
-```
-
-### 文档
-
-```bash
-# 启动文档开发服务器
-pnpm dev:docs
-
-# 构建文档
-pnpm build:docs
-```
-
-## 文档
-
-- [完整文档](https://your-username.github.io/vsoft-ui/)
-- [权限控制指南](/permission/usage)
-- [组件文档](/components)
-
-## 贡献
-
-欢迎提交 Issue 和 Pull Request！
-
-## 许可证
-
-[MIT](LICENSE)
-
-## 更新日志
-
-### v1.0.2
-
-- 修复组件构建问题
-- 优化权限控制逻辑
-- 完善文档内容
-
-### v1.0.1
-
-- 修复组件级权限控制问题
-- 优化组件传参机制
-
-### v1.0.0
-
-- 初始版本发布
-- 实现 Button 和 Input 组件
-- 添加三种权限控制方式
+# 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