@yxhl/specter-pui-vtk 1.0.41 → 1.0.43

package/README.md

@@ -1,72 +1,548 @@
-# @yxhl/specter-pui
+# @yxhl/specter-pui-vtk
 
-雅心互联 Vue 3 + Vuetify 3 智能组件库
+> 雅心互联 Vue 3 + Vuetify 3 智能组件库
 
-## 📦 安装
+基于 Vuetify 3 的企业级 Vue 3 组件库，提供丰富的业务组件和工具函数。
+
+## 📋 目录
+
+- [快速开始](#快速开始)
+- [安装配置](#安装配置)
+- [组件文档](#组件文档)
+- [公用方法](#公用方法)
+- [配置选项](#配置选项)
+- [更新迭代](#更新迭代)
+- [常见问题](#常见问题)
+
+---
+
+## 快速开始
+
+### 1. 安装组件库
 
 ```bash
 npm install @yxhl/specter-pui-vtk
 ```
 
-## 🚀 快速开始
+### 2. 引入组件库
 
-### 完整引入
+在 `src/main.js` 或 `src/main.ts` 中：
 
 ```javascript
 import { createApp } from 'vue'
 import App from './App.vue'
-import SpecterPuiVtk from '@yxhl/specter-pui'
-import '@yxhl/specter-pui/dist/specter-pui.css'
+import SpecterPuiVtk from '@yxhl/specter-pui-vtk'
+import '@yxhl/specter-pui-vtk/dist/specter-pui-vtk.css'
 
 const app = createApp(App)
+
+// 配置组件库（可选）
+window.VTK_CONFIG = {
+  storageKeys: {
+    user: import.meta.env.VITE_MIS_USERS || '_mis_acis_users',
+    token: import.meta.env.VITE_MIS_TOKEN || '_mis_acis_token'
+  }
+}
+
+// 配置 API 地址（可选）
+window.VITE_APP_API_URL = import.meta.env.VITE_APP_API_URL
+
 app.use(SpecterPuiVtk)
 app.mount('#app')
 ```
 
-### 按需引入
+### 3. 使用组件
+
+```vue
+<template>
+  <VtkStepper :el="currentStep" list="步骤1,步骤2,步骤3" />
+  <VtkPage v-model="page" :total="total" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const currentStep = ref(1)
+const page = ref({ pageno: 1, limit: 10 })
+const total = ref(100)
+</script>
+```
+
+---
+
+## 安装配置
+
+### 环境要求
+
+- Vue 3.x
+- Vuetify 3.x
+- Node.js >= 16
+
+### 完整配置示例
 
 ```javascript
-import { VtkStepper, VtkPage, storage } from '@yxhl/specter-pui'
+// main.js
+import { createApp } from 'vue'
+import App from './App.vue'
+import SpecterPuiVtk from '@yxhl/specter-pui-vtk'
+import '@yxhl/specter-pui-vtk/dist/specter-pui-vtk.css'
 
-export default {
-  components: {
-    VtkStepper,
-    VtkPage
-  },
-  setup() {
-    // 使用工具函数
-    storage.set('key', 'value')
+const app = createApp(App)
+
+// 1. 配置存储键名（可选）
+window.VTK_CONFIG = {
+  storageKeys: {
+    user: import.meta.env.VITE_MIS_USERS || '_mis_acis_users',
+    token: import.meta.env.VITE_MIS_TOKEN || '_mis_acis_token'
   }
 }
+
+// 2. 配置 API 基础地址（可选）
+window.VITE_APP_API_URL = import.meta.env.VITE_APP_API_URL
+
+// 3. 注册组件库
+app.use(SpecterPuiVtk)
+
+// 4. 添加消息组件到模板（必需）
+// 在 App.vue 中添加：
+// <template>
+//   <v-app>
+//     <router-view />
+//     <vtk-message />
+//   </v-app>
+// </template>
+
+app.mount('#app')
 ```
 
-## 📚 组件列表
+### 环境变量配置
+
+在项目根目录创建 `.env` 文件：
+
+```env
+# API 基础地址
+VITE_APP_API_URL=https://api.example.com
+
+# 存储键名（可选）
+VITE_MIS_USERS=my_user_key
+VITE_MIS_TOKEN=my_token_key
+```
+
+---
+
+## 组件文档
 
 ### 基础组件
-- **VtkArea** - 地区选择组件
-- **VtkCheckbox** - 复选框组件
-- **VtkCount** - 计数器组件
-- **VtkDatePicker** - 日期选择器
-- **VtkEmpty** - 空状态组件
-- **VtkFab** - 浮动按钮
-- **VtkFormItem** - 表单项组件
-- **VtkImg** - 图片组件
-- **VtkPage** - 分页组件
-- **VtkPdf** - PDF 查看器
-- **VtkProj** - 项目组件
-- **VtkRadio** - 单选框组件
-- **VtkSearch** - 搜索组件
-- **VtkSelect** - 下拉选择组件
-- **VtkStepper** - 步骤条组件
+
+#### VtkArea - 地区选择组件
+
+地区选择下拉组件，支持省市区三级联动。
+
+**Props:**
+- `modelValue` (String): 绑定值，地区代码
+- `placeholder` (String): 占位文本，默认 "请选择地区"
+
+**Events:**
+- `update:modelValue`: 值变化时触发
+- `change`: 选择变化时触发
+
+**使用示例:**
+```vue
+<VtkArea v-model="areaCode" placeholder="选择地区" @change="handleChange" />
+```
+
+---
+
+#### VtkAreaTabs - 地区选择组件（Tab 版）
+
+带 Tab 切换的地区选择组件，支持多级地区选择。
+
+**Props:**
+- `modelValue` (String): 绑定值，地区代码
+- `minArea` (Number): 最小地区级别（2=省，4=市，6=区县，9=街镇，12=村社）
+- `areaNode` (Number): 显示的地区节点数量
+
+**Events:**
+- `update:modelValue`: 值变化时触发
+- `change`: 选择变化时触发
+
+**使用示例:**
+```vue
+<!-- 基础使用 -->
+<VtkAreaTabs v-model="areaCode" @change="handleChange" />
+
+<!-- 限制到区县级别 -->
+<VtkAreaTabs v-model="areaCode" :min-area="6" />
+
+<!-- 只显示最后2级地区名称 -->
+<VtkAreaTabs v-model="areaCode" :area-node="2" />
+```
+
+---
+
+#### VtkDept - 人员选择组件
+
+地区-部门-人员三级联动选择组件，支持单选和多选。
+
+**Props:**
+- `multiple` (Boolean): 是否多选，默认 false
+
+**Events:**
+- `selected`: 选择完成时触发，参数为选中的人员数组
+
+**Methods:**
+- `add()`: 打开选择对话框
+- `close()`: 关闭选择对话框
+
+**使用示例:**
+```vue
+<template>
+  <VBtn @click="openDept">选择人员</VBtn>
+  <VtkDept
+    ref="deptRef"
+    :multiple="true"
+    @selected="handleSelected"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const deptRef = ref(null)
+
+const openDept = () => {
+  deptRef.value?.add()
+}
+
+const handleSelected = (persons) => {
+  console.log('选中的人员:', persons)
+}
+</script>
+```
+
+---
+
+#### VtkBreadcrumb - 面包屑导航
+
+面包屑导航组件，支持自定义返回路径。
+
+**Props:**
+- `items` (Array): 面包屑项数组，格式：`[{ title: '首页', to: '/home' }]`
+- `showBack` (Boolean): 是否显示返回按钮，默认 true
+- `backTo` (String): 返回路径
+- `backText` (String): 返回按钮文本，默认 "返回"
+
+**Events:**
+- `back`: 点击返回按钮时触发
+
+**使用示例:**
+```vue
+<VtkBreadcrumb
+  :items="[
+    { title: '首页', to: '/home' },
+    { title: '用户管理', to: '/users' },
+    { title: '用户详情' }
+  ]"
+  back-to="/home"
+  @back="handleBack"
+/>
+```
+
+---
+
+#### VtkStepper - 步骤条组件
+
+步骤条组件，用于展示多步骤流程。
+
+**Props:**
+- `el` (Number): 当前步骤，从 1 开始
+- `list` (String): 步骤列表，逗号分隔，如 "步骤1,步骤2,步骤3"
+
+**Slots:**
+- `1`, `2`, `3`...: 各步骤的内容插槽
+
+**使用示例:**
+```vue
+<VtkStepper :el="currentStep" list="基础信息,详细信息,完成">
+  <template #1>
+    <div>步骤1的内容</div>
+  </template>
+  <template #2>
+    <div>步骤2的内容</div>
+  </template>
+  <template #3>
+    <div>步骤3的内容</div>
+  </template>
+</VtkStepper>
+```
+
+---
+
+#### VtkPage - 分页组件
+
+分页组件，支持页码和每页数量选择。
+
+**Props:**
+- `modelValue` (Object): 绑定值，格式：`{ pageno: 1, pageCount: 10, rowCount: 100, limit: 10 }`
+
+**Events:**
+- `update:modelValue`: 分页变化时触发
+- `change`: 分页变化时触发
+
+**使用示例:**
+```vue
+<VtkPage v-model="pageData" @change="loadData" />
+
+<script setup>
+const pageData = ref({
+  pageno: 1,      // 当前页
+  pageCount: 10,  // 总页数
+  rowCount: 100,  // 总记录数
+  limit: 10       // 每页数量
+})
+</script>
+```
+
+---
+
+#### VtkFormItem - 表单项组件
+
+表单项组件，提供标签和帮助文本。
+
+**Props:**
+- `label` (String): 标签文本
+- `must` (Boolean): 是否必填，显示红色星号
+- `left` (Boolean): 标签左对齐
+- `help` (String): 帮助文本，支持 HTML
+
+**Slots:**
+- `default`: 表单控件插槽
+
+**使用示例:**
+```vue
+<VtkFormItem
+  label="用户名："
+  must
+  left
+  help="请输入4-20位字符"
+>
+  <VTextField v-model="username" />
+</VtkFormItem>
+```
+
+---
+
+#### VtkSelect - 下拉选择组件
+
+下拉选择组件，支持字符串格式的选项列表。
+
+**Props:**
+- `modelValue`: 绑定值
+- `list` (String): 选项列表，格式：`"value1:label1/value2:label2"`
+- `placeholder` (String): 占位文本
+- 其他 Vuetify VSelect 的 props
+
+**使用示例:**
+```vue
+<VtkSelect
+  v-model="selected"
+  list="1:选项1/2:选项2/3:选项3"
+  placeholder="请选择"
+/>
+```
+
+---
+
+#### VtkCheckbox - 复选框组件
+
+复选框组件，支持字符串格式的选项列表。
+
+**Props:**
+- `modelValue`: 绑定值
+- `list` (String): 选项列表，格式：`"value1:label1/value2:label2"`
+
+**使用示例:**
+```vue
+<VtkCheckbox
+  v-model="selected"
+  list="1:选项1/2:选项2/3:选项3"
+/>
+```
+
+---
+
+#### VtkRadio - 单选框组件
+
+单选框组件，支持字符串格式的选项列表。
+
+**Props:**
+- `modelValue`: 绑定值
+- `list` (String): 选项列表，格式：`"value1:label1/value2:label2"`
+
+**使用示例:**
+```vue
+<VtkRadio
+  v-model="selected"
+  list="1:选项1/2:选项2/3:选项3"
+/>
+```
+
+---
+
+#### VtkDatePicker - 日期选择器
+
+日期选择器组件。
+
+**Props:**
+- `modelValue`: 绑定值
+- `placeholder` (String): 占位文本
+
+**使用示例:**
+```vue
+<VtkDatePicker v-model="date" placeholder="选择日期" />
+```
+
+---
+
+#### VtkImg - 图片组件
+
+图片展示组件，支持预览和列表展示。
+
+**Props:**
+- `list` (Array): 图片列表，格式：`[{ url: '', title: '', description: '' }]`
+
+**使用示例:**
+```vue
+<VtkImg :list="imageList" />
+```
+
+---
+
+#### VtkPdf - PDF 查看器
+
+PDF 文件查看组件。
+
+**Props:**
+- `list` (Array): PDF 列表，格式：`[{ url: '', title: '', description: '' }]`
+
+**使用示例:**
+```vue
+<VtkPdf :list="pdfList" />
+```
+
+---
+
+#### VtkEmpty - 空状态组件
+
+空状态展示组件。
+
+**Props:**
+- `text` (String): 提示文本，默认 "暂无数据"
+
+**使用示例:**
+```vue
+<VtkEmpty text="暂无内容" />
+```
+
+---
+
+#### VtkFab - 浮动按钮
+
+浮动操作按钮组件。
+
+**使用示例:**
+```vue
+<VtkFab />
+```
+
+---
 
 ### 消息组件
-- **vtkMessage** - 全局消息提示
 
-## 🛠️ 工具函数
+#### vtkMessage - 全局消息
+
+全局消息提示组件，需要在 App.vue 中添加 `<vtk-message />` 组件。
+
+**方法:**
+
+```javascript
+// 在组件中使用
+const { proxy } = getCurrentInstance()
+
+// 成功提示
+proxy.$vtk.message.success('操作成功')
+
+// 错误提示
+proxy.$vtk.message.error('操作失败')
+
+// 警告提示
+proxy.$vtk.message.warning('警告信息')
+
+// 信息提示
+proxy.$vtk.message.info('提示信息')
+
+// Toast 提示
+proxy.$vtk.message.toast('提示文本', { color: 'primary' })
+
+// 确认对话框
+proxy.$vtk.message.confirm({
+  title: '提示',
+  text: '确认删除吗？',
+  onConfirm: () => {
+    console.log('确认')
+  },
+  onCancel: () => {
+    console.log('取消')
+  }
+})
+
+// Alert 对话框
+proxy.$vtk.message.alert({
+  title: '提示',
+  text: '操作成功',
+  onConfirm: () => {
+    console.log('确认')
+  }
+})
+
+// Loading 加载
+proxy.$vtk.message.loading.show()
+proxy.$vtk.message.loading.hide()
+```
+
+---
+
+## 公用方法
+
+### 1. Storage - 本地存储
+
+封装的本地存储工具，支持 localStorage 和 sessionStorage。
+
+**使用方式:**
+
+```javascript
+import { getCurrentInstance } from 'vue'
+
+const { proxy } = getCurrentInstance()
+
+// 设置值
+proxy.$vtk.storage.set('key', 'value')
+proxy.$vtk.storage.set('key', { name: 'test' }) // 自动序列化对象
+
+// 获取值
+const value = proxy.$vtk.storage.get('key')
+
+// 删除值
+proxy.$vtk.storage.remove('key')
+
+// 清空所有
+proxy.$vtk.storage.clear()
+```
+
+**或者直接导入:**
 
-### storage - 本地存储
 ```javascript
-import { storage } from '@yxhl/specter-pui'
+import { storage } from '@yxhl/specter-pui-vtk'
 
 storage.set('key', 'value')
 storage.get('key')
@@ -74,49 +550,351 @@ storage.remove('key')
 storage.clear()
 ```
 
-### request - HTTP 请求
+---
+
+### 2. Request - HTTP 请求
+
+封装的 Axios 请求工具，自动处理 token 和错误。
+
+**使用方式:**
+
 ```javascript
-import { request } from '@yxhl/specter-pui'
+const { proxy } = getCurrentInstance()
+
+// GET 请求（表单格式）
+proxy.$vtk.request.getForm('/api/user', { id: 1 })
+
+// POST 请求（表单格式）
+proxy.$vtk.request.postForm('/api/user', { name: 'test' })
+
+// GET 请求（JSON 格式）
+proxy.$vtk.request.getJson('/api/user', { id: 1 })
 
-request.get('/api/data')
-request.post('/api/data', { data })
+// POST 请求（JSON 格式）
+proxy.$vtk.request.postJson('/api/user', { name: 'test' })
+
+// 文件上传
+proxy.$vtk.request.imp('/api/upload', formData)
+
+// 文件下载
+proxy.$vtk.request.exp('/api/download', { id: 1 })
+
+// 自定义请求
+proxy.$vtk.request.http(
+  '/api/data',
+  { key: 'value' },
+  'POST',
+  { 'content-type': 'application/json' },
+  null
+)
 ```
 
-### themes - 主题管理
+**或者直接导入:**
+
 ```javascript
-import { themes } from '@yxhl/specter-pui'
+import { request } from '@yxhl/specter-pui-vtk'
+
+request.getForm('/api/user')
+request.postJson('/api/user', { name: 'test' })
+```
+
+---
+
+### 3. Filters - 过滤器方法
+
+提供常用的数据格式化方法。
+
+**字典过滤:**
+
+```javascript
+const { proxy } = getCurrentInstance()
+
+// 字典转换
+proxy.$vtk.filters.dict('1', 'status') // 根据字典类型转换值
+
+// 分析类型
+proxy.$vtk.filters.analyType('type_code')
 
-themes.toggle() // 切换主题
+// 分析级别
+proxy.$vtk.filters.analyLevel('level_code')
 ```
 
-### Composables
+**脱敏方法:**
+
+```javascript
+// 手机号脱敏
+proxy.$vtk.filters.mobile('13812345678') // 138****5678
+
+// 身份证脱敏
+proxy.$vtk.filters.idcard('110101199001011234') // 110101********1234
+```
+
+**格式化方法:**
+
+```javascript
+// 日期格式化
+proxy.$vtk.filters.date('2024-01-01', 'YYYY-MM-DD')
+
+// 数字格式化
+proxy.$vtk.filters.num(1234.56, 2) // 1,234.56
+
+// 年龄计算
+proxy.$vtk.filters.age('1990-01-01') // 34
+
+// 文本截取
+proxy.$vtk.filters.txt('很长的文本...', 10) // 很长的文本...
+
+// 绝对值
+proxy.$vtk.filters.abs(-123) // 123
+```
+
+---
+
+### 4. Validation - 表单验证
+
+提供常用的表单验证规则。
+
+**使用方式:**
+
+```javascript
+const { proxy } = getCurrentInstance()
+
+// 必填验证
+const rules = [
+  proxy.$vtk.Validation.required('用户名不能为空')
+]
+
+// 邮箱验证
+const emailRules = [
+  proxy.$vtk.Validation.email('请输入正确的邮箱')
+]
+
+// 手机号验证
+const mobileRules = [
+  proxy.$vtk.Validation.mobile('请输入正确的手机号')
+]
+
+// 自定义验证
+const customRules = [
+  (v) => !!v || '不能为空',
+  (v) => v.length >= 6 || '至少6个字符'
+]
+```
+
+---
+
+
+
+## 配置选项
+
+### 存储键名配置
+
+组件库使用 localStorage 存储用户信息和 token，可以通过配置自定义键名。
+
+**配置方式:**
+
+```javascript
+// main.js
+window.VTK_CONFIG = {
+  storageKeys: {
+    user: import.meta.env.VITE_MIS_USERS || '_mis_acis_users',
+    token: import.meta.env.VITE_MIS_TOKEN || '_mis_acis_token'
+  }
+}
+```
+
+**默认值:**
+- `user`: `_mis_acis_users`
+- `token`: `_mis_acis_token`
+
+---
+
+### API 基础地址配置
+
+配置 HTTP 请求的基础地址。
+
+**配置方式:**
+
 ```javascript
-import { usePage, useVtk } from '@yxhl/specter-pui'
+// main.js
+window.VITE_APP_API_URL = import.meta.env.VITE_APP_API_URL
+```
+
+**或在 .env 文件中:**
+
+```env
+VITE_APP_API_URL=https://api.example.com
+```
+
+---
+
+## 更新迭代
+
+### 组件库维护者
 
-// 分页功能
-const { page, pageSize, total } = usePage()
+#### 1. 修改组件
 
-// 访问全局对象
-const vtk = useVtk()
-vtk.message.success('操作成功')
+在 `pui-vtks/src/` 目录下修改组件代码。
+
+#### 2. 构建组件库
+
+```bash
+cd pui-vtks
+npm run build
 ```
 
-## 🔄 更新组件库
+#### 3. 更新版本号
+
+```bash
+# 补丁版本 (1.0.0 -> 1.0.1)
+npm version patch
+
+# 小版本 (1.0.0 -> 1.1.0)
+npm version minor
+
+# 大版本 (1.0.0 -> 2.0.0)
+npm version major
+```
 
-当组件库发布新版本后,在你的项目中运行:
+#### 4. 发布到 npm
+
+```bash
+npm config set //registry.npmjs.org/:_authToken=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
+npm publish --access public
+```
+
+---
+
+### 项目使用者
+
+#### 更新组件库
 
 ```bash
 # 更新到最新版本
-npm update @yxhl/specter-pui
+npm update @yxhl/specter-pui-vtk
 
 # 或指定版本
-npm install @yxhl/specter-pui@latest
+npm install @yxhl/specter-pui-vtk@1.0.5
+
+# 强制重新安装
+rm -rf node_modules package-lock.json
+npm install
+```
+
+#### 查看当前版本
+
+```bash
+npm list @yxhl/specter-pui-vtk
+```
+
+---
+
+## 常见问题
+
+### 1. 组件未定义
+
+**问题:** 使用组件时提示组件未定义
+
+**解决:**
+- 确保在 main.js 中正确引入并注册了组件库
+- 确保引入了 CSS 文件
+
+```javascript
+import SpecterPuiVtk from '@yxhl/specter-pui-vtk'
+import '@yxhl/specter-pui-vtk/dist/specter-pui-vtk.css'
+
+app.use(SpecterPuiVtk)
 ```
 
-## 📄 License
+---
 
-MIT
+### 2. 消息组件不显示
 
-## 👥 Author
+**问题:** 调用 `proxy.$vtk.message` 方法后没有显示
+
+**解决:**
+- 确保在 App.vue 中添加了 `<vtk-message />` 组件
+
+```vue
+<template>
+  <v-app>
+    <router-view />
+    <vtk-message />
+  </v-app>
+</template>
+```
+
+---
+
+### 3. API 请求 baseURL 为 undefined
+
+**问题:** HTTP 请求的 baseURL 是 undefined
+
+**解决:**
+- 在 main.js 中配置 API 地址
+
+```javascript
+window.VITE_APP_API_URL = import.meta.env.VITE_APP_API_URL
+```
+
+- 或在 .env 文件中配置
+
+```env
+VITE_APP_API_URL=https://api.example.com
+```
+
+---
+
+### 4. 用户信息获取失败
+
+**问题:** 组件无法获取用户信息
+
+**解决:**
+- 确保在 localStorage 中存储了用户信息
+- 如果使用自定义键名，需要配置 `window.VTK_CONFIG`
+
+```javascript
+window.VTK_CONFIG = {
+  storageKeys: {
+    user: 'my_custom_user_key'
+  }
+}
+```
+
+---
+
+### 5. 组件样式异常
+
+**问题:** 组件样式显示不正常
+
+**解决:**
+- 确保引入了 CSS 文件
+- 确保 Vuetify 已正确配置
+- 检查是否有样式冲突
+
+```javascript
+import '@yxhl/specter-pui-vtk/dist/specter-pui-vtk.css'
+```
+
+---
+
+## 版本历史
+
+### v1.0.0
+- 初始版本发布
+- 包含基础组件和工具函数
+
+---
+
+## 许可证
+
+MIT License
+
+## 作者
 
 yxhl <17363318852@139.com>
+
+## 链接
+
+- [npm 包](https://www.npmjs.com/package/@yxhl/specter-pui-vtk)
+- [问题反馈](https://gitee.com/liangthink/specter-core-vue/issues)