@yxhl/specter-pui-vtk 1.0.67 → 1.0.69

package/README.md

@@ -1,1226 +1,450 @@
-# @yxhl/specter-pui-vtk
-
-> 雅心互联 Vue 3 + Vuetify 3 智能组件库
-
-基于 Vuetify 3 的企业级 Vue 3 组件库，提供丰富的业务组件和工具函数。
-
-## 📋 目录
-
-- [快速开始](#快速开始)
-- [安装配置](#安装配置)
-- [组件文档](#组件文档)
-  - [VtkUpload - 文件上传组件](#vtkupload---文件上传组件)
-- [公用方法](#公用方法)
-- [配置选项](#配置选项)
-- [更新迭代](#更新迭代)
-- [常见问题](#常见问题)
-
----
-
-## 快速开始
-
-### 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-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
-// 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'
-
-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 - 地区选择组件
-
-地区选择下拉组件，支持省市区三级联动。
-
-**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="选择日期" />
-```
-
----
-
-#### VtkDateSelector - 高级日期选择器
-
-功能强大的日期选择器组件，支持日期、周、月、年的单选和范围选择，适配 Vuetify 3 主题（亮色/暗色）。
-
-**Props:**
-- `modelValue` (String | Array): 绑定值
-  - 单选模式：字符串，如 `"2024-01-01"`
-  - 范围模式：数组，如 `["2024-01-01", "2024-01-31"]`
-- `displayMode` (String): 显示模式，可选值：`'day'` | `'week'` | `'month'` | `'year'`，默认 `'day'`
-- `mode` (String): 选择模式，可选值：`'single'` | `'range'`，默认 `'single'`
-- `placeholder` (String): 占位文本，默认 `'请选择日期'`
-- `disabled` (Boolean): 是否禁用，默认 `false`
-- `format` (String): 日期格式，默认 `'YYYY-MM-DD'`
-- `separator` (String): 范围分隔符，默认 `' 至 '`
-- `inline` (Boolean): 内联模式，直接显示选择器，不需要点击输入框，默认 `false`
-- `singlePanel` (Boolean): 单面板模式，范围选择时只显示一个面板，默认 `false`
-- `disableFuture` (Boolean): 禁用未来日期，大于当前日期的都置灰不可选，默认 `false`
-- `onCancel` (Function): 自定义取消方法
-- `onConfirm` (Function): 自定义确认方法
-- `disableFuture` (Boolean): 是否禁用超出日期，默认 `false`
-
-**Events:**
-- `update:modelValue`: 值变化时触发
-- `change`: 选择变化时触发
-- `cancel`: 点击取消按钮时触发（未提供 onCancel 时）
-- `confirm`: 点击确认按钮时触发（未提供 onConfirm 时）
-
-**使用示例:**
-
-```vue
-<template>
-  <!-- 基础使用：单选日期 -->
-  <VtkDateSelector v-model="date" placeholder="选择日期" />
-
-  <!-- 日期范围选择 -->
-  <VtkDateSelector
-    v-model="dateRange"
-    mode="range"
-    displayMode="day"
-    placeholder="选择日期范围"
-  />
-
-  <!-- 月份范围选择 -->
-  <VtkDateSelector
-    v-model="monthRange"
-    mode="range"
-    displayMode="month"
-    placeholder="选择月份范围"
-  />
-
-  <!-- 年份范围选择 -->
-  <VtkDateSelector
-    v-model="yearRange"
-    mode="range"
-    displayMode="year"
-    placeholder="选择年份范围"
-  />
-
-  <!-- 周范围选择 -->
-  <VtkDateSelector
-    v-model="weekRange"
-    mode="range"
-    displayMode="week"
-    placeholder="选择周范围"
-  />
-
-  <!-- 内联模式：直接显示选择器 -->
-  <VtkDateSelector
-    v-model="date"
-    mode="range"
-    displayMode="month"
-    inline
-  />
-
-  <!-- 单面板模式：范围选择时只显示一个面板 -->
-  <VtkDateSelector
-    v-model="dateRange"
-    mode="range"
-    displayMode="day"
-    singlePanel
-  />
-
-  <!-- 禁用未来日期：只能选择今天及之前的日期 -->
-  <VtkDateSelector
-    v-model="date"
-    displayMode="month"
-    :disableFuture="true"
-    placeholder="选择月份（不能选未来）"
-  />
-
-  <!-- 自定义取消和确认方法 -->
-  <VtkDateSelector
-    v-model="date"
-    :onCancel="handleCancel"
-    :onConfirm="handleConfirm"
-  />
-
-  <!-- 监听事件 -->
-  <VtkDateSelector
-    v-model="date"
-    @cancel="handleCancel"
-    @confirm="handleConfirm"
-    @change="handleChange"
-  />
-</template>
-
-<script setup>
-import { ref } from 'vue'
-
-// 单选日期
-const date = ref('2024-01-01')
-
-// 日期范围
-const dateRange = ref(['2024-01-01', '2024-01-31'])
-
-// 月份范围
-const monthRange = ref(['2024-01', '2024-12'])
-
-// 年份范围
-const yearRange = ref(['2023', '2024'])
-
-// 周范围
-const weekRange = ref(['2024-W01', '2024-W10'])
-
-// 自定义处理方法
-const handleCancel = () => {
-  console.log('取消选择')
-}
-
-const handleConfirm = (value) => {
-  console.log('确认选择:', value)
-  // 执行自定义逻辑
-}
-
-const handleChange = (value) => {
-  console.log('值变化:', value)
-}
-</script>
-```
-
-**特性说明:**
-
-1. **多种显示模式**
-   - `day`: 日期选择（显示日历）
-   - `month`: 月份选择（显示月份网格）
-   - `year`: 年份选择（显示年份网格）
-   - `week`: 周选择（显示周列表）
-
-2. **单选和范围选择**
-   - `single`: 单选模式，返回单个值
-   - `range`: 范围模式，返回数组 `[开始, 结束]`
-
-3. **内联模式**
-   - 设置 `inline="true"` 后，选择器直接显示，无需点击输入框
-   - 选择后立即赋值，无需点击确认按钮
-   - 适合嵌入表单或页面中
-
-4. **单面板模式**
-   - 设置 `singlePanel="true"` 后，范围选择时只显示一个面板
-   - 通过导航按钮切换月份/年份
-   - 适合空间受限的场景
-
-5. **主题适配**
-   - 自动适配 Vuetify 3 的亮色和暗色主题
-   - 使用 Vuetify 主题变量，无需额外配置
-
-6. **禁用未来日期**
-   - 设置 `disableFuture="true"` 后，大于当前日期的所有日期、月份、年份都会置灰
-   - 禁用的项目无法点击选择
-   - 适用于生日选择、历史数据查询等场景
-
-7. **自定义操作**
-   - 可通过 `onCancel` 和 `onConfirm` props 自定义取消和确认逻辑
-   - 或通过 `@cancel` 和 `@confirm` 事件监听
-
----
-
-#### 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" />
-```
-
----
-
-#### VtkUpload - 文件上传组件
-
-文件上传组件，参考 Element Plus `el-upload` 设计，支持拖拽上传、多种列表展示模式、图片预览、PDF 新窗口预览、Excel Online 查看器等功能。
-
-**Props:**
-
-| 属性 | 类型 | 默认值 | 说明 |
-|---|---|---|---|
-| `modelValue` | `Array` | `[]` | 文件列表（v-model 双向绑定） |
-| `action` | `String` | `''` | 上传接口地址 |
-| `accept` | `String` | `''` | 接受的文件类型，同原生 `accept` 属性，如 `image/*`、`.pdf,.xlsx` |
-| `multiple` | `Boolean` | `false` | 是否允许多文件同时选择 |
-| `limit` | `Number` | `0` | 最大可上传文件数量，`0` 表示不限制 |
-| `maxSize` | `Number` | `0` | 单个文件最大体积（MB），`0` 表示不限制 |
-| `listType` | `String` | `'text'` | 文件列表展示类型：`text` \| `picture` \| `picture-card` |
-| `showFileList` | `Boolean` | `true` | 是否显示文件列表 |
-| `autoUpload` | `Boolean` | `true` | 选择文件后是否自动上传 |
-| `disabled` | `Boolean` | `false` | 是否禁用 |
-| `headers` | `Object` | `{}` | 附加的请求头 |
-| `data` | `Object` | `{}` | 上传时附加的表单数据 |
-| `name` | `String` | `'file'` | 上传文件的字段名 |
-| `tip` | `String` | `''` | 拖拽区底部的提示文字 |
-| `beforeUpload` | `Function` | `null` | 上传前的钩子函数，接收 `(rawFile)` 参数，返回 `false` 或 rejected Promise 则停止上传 |
-| `beforeRemove` | `Function` | `null` | 移除文件前的钩子函数，接收 `(file, fileList)` 参数，返回 `false` 则阻止移除 |
-
-**Events:**
-
-| 事件 | 参数 | 说明 |
-|---|---|---|
-| `update:modelValue` | `fileList` | 文件列表变化时触发（v-model） |
-| `change` | `(file, fileList)` | 文件添加、上传成功/失败时触发 |
-| `success` | `(response, file, fileList)` | 文件上传成功时触发 |
-| `error` | `(error, file, fileList)` | 文件上传失败时触发 |
-| `remove` | `(file, fileList)` | 文件被移除时触发 |
-| `exceed` | `(files, fileList)` | 超出文件数量限制时触发 |
-| `preview` | `(file)` | 点击文件预览时触发 |
-
-**Methods（通过 ref 调用）:**
-
-| 方法 | 说明 |
-|---|---|
-| `submit()` | 手动触发所有 `ready` 状态文件的上传（`autoUpload: false` 时使用） |
-| `clearFiles()` | 清空文件列表 |
-| `remove(file)` | 手动移除指定文件 |
-
-**文件预览策略:**
-
-| 文件类型 | 有服务端 URL | 仅本地（未上传） |
-|---|---|---|
-| 图片 | Dialog 内嵌预览 | Dialog 显示 base64 预览 |
-| PDF | 新标签页直接打开 | 生成 Blob URL 新标签页打开 |
-| xlsx / xls | Microsoft Office Online 查看器（需公网地址） | Dialog 提示无法预览 |
-| 其他 | Dialog 内嵌展示 | Dialog 内嵌展示 |
-
-> Office Online 查看器要求文件 URL 必须是**公网可访问的 https 地址**。
-
-**Slots:**
-
-| 插槽 | 说明 |
-|---|---|
-| `default` | 自定义拖拽区域内容（仅 `text` / `picture` 模式生效） |
-
-**使用示例:**
-
-```vue
-<template>
-  <!-- 1. 基础文本列表模式 -->
-  <VtkUpload
-    v-model="files"
-    action="/api/upload"
-    tip="支持 jpg / png / pdf，单个文件不超过 5MB"
-  />
-
-  <!-- 2. 图片缩略图列表模式 -->
-  <VtkUpload
-    v-model="files"
-    action="/api/upload"
-    list-type="picture"
-    accept="image/*"
-    :max-size="2"
-  />
-
-  <!-- 3. 图片卡片模式（最多 5 张） -->
-  <VtkUpload
-    v-model="files"
-    action="/api/upload"
-    list-type="picture-card"
-    accept="image/*"
-    :limit="5"
-    :max-size="2"
-    tip="只能上传 jpg/png，不超过 2MB"
-  />
-
-  <!-- 4. 手动上传 -->
-  <VtkUpload
-    ref="uploadRef"
-    v-model="files"
-    action="/api/upload"
-    :auto-upload="false"
-    @change="handleChange"
-  />
-  <VBtn @click="uploadRef.submit()">开始上传</VBtn>
-
-  <!-- 5. 上传前校验 -->
-  <VtkUpload
-    v-model="files"
-    action="/api/upload"
-    :before-upload="beforeUpload"
-    :before-remove="beforeRemove"
-  />
-
-  <!-- 6. 附加数据 / 自定义请求头 -->
-  <VtkUpload
-    v-model="files"
-    action="/api/upload"
-    :data="{ bizType: 'avatar' }"
-    :headers="{ 'X-Custom': 'value' }"
-  />
-</template>
-
-<script setup>
-import { ref } from 'vue'
-
-const files = ref([])
-const uploadRef = ref(null)
-
-// 上传前校验示例
-const beforeUpload = (rawFile) => {
-  if (rawFile.size / 1024 / 1024 > 5) {
-    alert('文件大小不能超过 5MB')
-    return false
-  }
-  return true
-}
-
-// 移除前确认示例
-const beforeRemove = (file) => {
-  return window.confirm(`确认移除 ${file.name}？`)
-}
-
-const handleChange = (file, fileList) => {
-  console.log('文件变化:', file, fileList)
-}
-</script>
-```
-
----
-
-#### VtkEmpty - 空状态组件
-
-空状态展示组件。
-
-**Props:**
-- `text` (String): 提示文本，默认 "暂无数据"
-
-**使用示例:**
-```vue
-<VtkEmpty text="暂无内容" />
-```
-
----
-
-#### VtkFab - 浮动按钮
-
-浮动操作按钮组件。
-
-**使用示例:**
-```vue
-<VtkFab />
-```
-
----
-
-### 消息组件
-
-#### 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()
-```
-
-**或者直接导入:**
-
-```javascript
-import { storage } from '@yxhl/specter-pui-vtk'
-
-storage.set('key', 'value')
-storage.get('key')
-storage.remove('key')
-storage.clear()
-```
-
----
-
-### 2. Request - HTTP 请求
-
-封装的 Axios 请求工具，自动处理 token 和错误。
-
-**使用方式:**
-
-```javascript
-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 })
-
-// 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
-)
-```
-
-**或者直接导入:**
-
-```javascript
-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')
-
-// 分析级别
-proxy.$vtk.filters.analyLevel('level_code')
-```
-
-**脱敏方法:**
-
-```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
-// main.js
-window.VITE_APP_API_URL = import.meta.env.VITE_APP_API_URL
-```
-
-**或在 .env 文件中:**
-
-```env
-VITE_APP_API_URL=https://api.example.com
-```
-
----
-
-## 更新迭代
-
-### 组件库维护者
-
-#### 1. 修改组件
-
-在 `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-vtk
-
-# 或指定版本
-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)
-```
-
----
-
-### 2. 消息组件不显示
-
-**问题:** 调用 `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)
+# @yxhl/specter-pui-vtk
+
+基于 Vue 3 + Vuetify 3 的业务组件库，内置常用业务组件、消息能力、请求封装、存储工具和格式化方法。
+
+## 目录
+
+- [安装](#安装)
+- [快速开始](#快速开始)
+- [全局能力](#全局能力)
+- [组件使用](#组件使用)
+- [工具方法](#工具方法)
+- [配置说明](#配置说明)
+- [开发与发布](#开发与发布)
+- [常见问题](#常见问题)
+
+## 安装
+
+```bash
+npm install @yxhl/specter-pui-vtk
+```
+
+适用环境：
+
+- Vue 3.x
+- Vuetify 3.x
+- Node.js >= 16
+
+## 快速开始
+
+### 1. 在 `main.js` 中注册组件库
+
+```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";
+
+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"
+  }
+};
+
+window.VITE_APP_API_URL = import.meta.env.VITE_APP_API_URL;
+
+app.use(SpecterPuiVtk);
+app.mount("#app");
+```
+
+### 2. 在根组件挂载消息组件
+
+`proxy.$vtk.message` 依赖全局消息组件，建议在 `App.vue` 中加入：
+
+```vue
+<template>
+  <v-app>
+    <router-view />
+    <vtk-message />
+  </v-app>
+</template>
+```
+
+### 3. 基础使用示例
+
+```vue
+<template>
+  <VtkStepper :el="step" list="基础信息,详细信息,完成" />
+  <VtkPage v-model="pageData" @change="loadData" />
+</template>
+
+<script setup>
+import { ref } from "vue";
+
+const step = ref(1);
+const pageData = ref({
+  pageno: 1,
+  pageCount: 1,
+  rowCount: 0,
+  limit: 10
+});
+
+const loadData = () => {
+  console.log("分页变化", pageData.value);
+};
+</script>
+```
+
+## 全局能力
+
+安装后可以通过 `this.$vtk` 或 `getCurrentInstance().proxy.$vtk` 使用以下能力：
+
+```js
+const { proxy } = getCurrentInstance();
+
+proxy.$vtk.request;
+proxy.$vtk.storage;
+proxy.$vtk.message;
+proxy.$vtk.Validation;
+proxy.$vtk.filters;
+```
+
+其中：
+
+- `request`：HTTP 请求封装
+- `storage`：本地存储封装
+- `message`：全局消息、确认框、加载框
+- `Validation`：表单校验方法
+- `filters`：字典转换、脱敏、格式化等工具
+
+## 组件使用
+
+组件库默认全局注册，注册插件后可直接在模板中使用。
+
+### 常用组件列表
+
+- `VtkArea`：地区下拉选择
+- `VtkAreaTabs`：Tab 版地区选择
+- `VtkDept`：人员选择
+- `VtkBreadcrumb`：面包屑导航
+- `VtkStepper`：步骤条
+- `VtkPage`：分页
+- `VtkFormItem`：表单项包装
+- `VtkSelect`：下拉选择
+- `VtkCheckbox`：复选框组
+- `VtkRadio`：单选框组
+- `VtkDatePicker`：日期选择
+- `VtkDateSelector`：高级日期选择
+- `VtkImg`：图片预览
+- `VtkPdf`：PDF 查看
+- `VtkUpload`：文件上传
+- `VtkEmpty`：空状态
+- `VtkFab`：悬浮按钮
+
+### VtkArea
+
+```vue
+<template>
+  <VtkArea v-model="areaCode" />
+</template>
+
+<script setup>
+import { ref } from "vue";
+
+const areaCode = ref("");
+</script>
+```
+
+常用属性：
+
+- `v-model`：地区编码
+- `maxArea`：最大地区层级
+- `minArea`：最小地区层级
+
+### VtkDept
+
+```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>
+```
+
+### VtkDateSelector
+
+```vue
+<template>
+  <VtkDateSelector v-model="date" placeholder="请选择日期" />
+
+  <VtkDateSelector
+    v-model="dateRange"
+    mode="range"
+    display-mode="month"
+    placeholder="请选择月份范围"
+  />
+</template>
+
+<script setup>
+import { ref } from "vue";
+
+const date = ref("");
+const dateRange = ref([]);
+</script>
+```
+
+常用属性：
+
+- `display-mode`：`day` / `week` / `month` / `year`
+- `mode`：`single` / `range`
+- `inline`：是否内联显示
+- `singlePanel`：范围选择时是否单面板
+- `disableFuture`：是否禁用未来日期
+
+### VtkUpload
+
+```vue
+<template>
+  <VtkUpload
+    v-model="files"
+    action="/api/upload"
+    list-type="picture-card"
+    accept=".jpg,.png,.pdf,.xlsx"
+    :limit="5"
+    :max-size="5"
+    tip="支持 jpg/png/pdf/xlsx，单文件不超过 5MB"
+  />
+</template>
+
+<script setup>
+import { ref } from "vue";
+
+const files = ref([]);
+</script>
+```
+
+常用属性：
+
+- `action`：上传接口地址
+- `listType`：`text` / `picture` / `picture-card`
+- `limit`：最大文件数
+- `maxSize`：单文件大小限制，单位 MB
+- `beforeUpload`：上传前校验
+- `beforeRemove`：删除前校验
+
+## 工具方法
+
+### 1. request
+
+```js
+const { proxy } = getCurrentInstance();
+
+proxy.$vtk.request.getForm("/api/user", { id: 1 });
+proxy.$vtk.request.postForm("/api/user", { name: "test" });
+proxy.$vtk.request.getJson("/api/user", { id: 1 });
+proxy.$vtk.request.postJson("/api/user", { name: "test" });
+proxy.$vtk.request.imp("/api/upload", formData);
+proxy.$vtk.request.exp("/api/export", { id: 1 });
+```
+
+说明：
+
+- 自动读取 token 并注入请求头
+- `baseURL` 来自 `window.VITE_APP_API_URL`
+- 登录失效时会自动弹窗并回到首页
+
+### 2. storage
+
+```js
+const { proxy } = getCurrentInstance();
+
+proxy.$vtk.storage.set("key", "value");
+proxy.$vtk.storage.set("user", { name: "admin" });
+
+proxy.$vtk.storage.get("key");
+proxy.$vtk.storage.remove("key");
+proxy.$vtk.storage.clear();
+```
+
+### 3. message
+
+```js
+const { proxy } = getCurrentInstance();
+
+proxy.$vtk.message.success("操作成功");
+proxy.$vtk.message.error("操作失败");
+proxy.$vtk.message.warning("警告信息");
+proxy.$vtk.message.info("提示信息");
+proxy.$vtk.message.toast("普通提示");
+
+proxy.$vtk.message.confirm({
+  title: "提示",
+  text: "确认删除吗？",
+  onConfirm: () => console.log("confirm"),
+  onCancel: () => console.log("cancel")
+});
+
+proxy.$vtk.message.alert({
+  title: "提示",
+  text: "保存成功"
+});
+
+proxy.$vtk.message.loading.show();
+proxy.$vtk.message.loading.hide();
+```
+
+### 4. Validation
+
+```js
+const { proxy } = getCurrentInstance();
+
+const rules = [
+  proxy.$vtk.Validation.required("不能为空"),
+  proxy.$vtk.Validation.mobile("手机号格式不正确")
+];
+```
+
+### 5. filters
+
+`dictionary.js`、`mask.js`、`format.js` 中的方法会一起挂到 `$vtk.filters`，同时字典方法也会被直接导出。
+
+```js
+const { proxy } = getCurrentInstance();
+
+proxy.$vtk.filters.dict("1", "0:禁用/1:启用");
+proxy.$vtk.filters.analyType("1");
+proxy.$vtk.filters.analyLevel("2");
+proxy.$vtk.filters.mobile("13812345678");
+proxy.$vtk.filters.idcard("330101199001011234");
+```
+
+### 6. appendAppParams
+
+用于根据应用 `aid` 获取真实地址，或对已有 URL 追加参数。
+
+```js
+const { proxy } = getCurrentInstance();
+
+const url1 = await proxy.$vtk.filters.appendAppParams(
+  "1226652a-3245-11ec-ad84-506b4bfd2204",
+  "",
+  { stoken: "123", name: "xiong" }
+);
+
+const url2 = await proxy.$vtk.filters.appendAppParams(
+  "https://mis.hzcl.org.cn/test#/page",
+  "",
+  { stoken: "123" }
+);
+```
+
+当前逻辑：
+
+- 如果第一个参数是 `aid`，会请求 `/kudas/xfwez/apps`
+- 接口参数格式：`{ aid }`
+- 默认取返回结果中的 `puri`
+- `sobject` 中的参数会自动拼接到结果 URL 上
+- 如果 URL 已有同名参数，则不会重复追加
+
+## 配置说明
+
+### VTK_CONFIG
+
+```js
+window.VTK_CONFIG = {
+  storageKeys: {
+    user: "_mis_acis_users",
+    token: "_mis_acis_token"
+  }
+};
+```
+
+默认值：
+
+- `user`: `_mis_acis_users`
+- `token`: `_mis_acis_token`
+
+### API 地址
+
+```js
+window.VITE_APP_API_URL = import.meta.env.VITE_APP_API_URL;
+```
+
+也可以在 `.env` 中配置：
+
+```env
+VITE_APP_API_URL=https://api.example.com
+VITE_MIS_USERS=_mis_acis_users
+VITE_MIS_TOKEN=_mis_acis_token
+```
+
+## 开发与发布
+
+### 本地开发
+
+```bash
+npm run dev
+```
+
+### 打包
+
+```bash
+npm run build
+```
+
+### 发布前版本更新
+
+```bash
+npm version patch
+npm version minor
+npm version major
+```
+
+### 发布
+
+```bash
+npm publish --access public
+```
+
+## 常见问题
+
+### 1. 组件未生效
+
+请确认：
+
+- 已执行 `app.use(SpecterPuiVtk)`
+- 已引入样式 `@yxhl/specter-pui-vtk/dist/specter-pui-vtk.css`
+
+### 2. 消息组件不显示
+
+请确认根组件中已挂载：
+
+```vue
+<vtk-message />
+```
+
+### 3. 请求地址是 `undefined`
+
+请确认已设置：
+
+```js
+window.VITE_APP_API_URL = import.meta.env.VITE_APP_API_URL;
+```
+
+### 4. 组件读取不到用户信息
+
+请确认用户信息已写入本地存储，并且 key 与 `window.VTK_CONFIG.storageKeys.user` 一致。
+
+## 版本
+
+当前版本：`1.0.68`
+
+## License
+
+MIT