@yxhl/specter-pui-vtk 1.0.77 → 1.0.79

package/README.md

@@ -1,453 +1,453 @@
-# @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.location;
-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.location.appendAppParams(
-  "1226652a-3245-11ec-ad84-506b4bfd2204",
-  { name: "xiong" },
-  "fwez"
-);
-
-const url2 = await proxy.$vtk.location.appendAppParams(
-  "https://mis.hzcl.org.cn/test#/page",
-  { name: "xiong" },
-  "fwez"
-);
-
-const stoken = proxy.$vtk.location.GetQueryString("stoken");
-```
-
-当前逻辑：
-
-- 如果第一个参数是 `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
+# @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.location;
+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.location.appendAppParams(
+  "1226652a-3245-11ec-ad84-506b4bfd2204",
+  { name: "xiong" },
+  "fwez"
+);
+
+const url2 = await proxy.$vtk.location.appendAppParams(
+  "https://mis.hzcl.org.cn/test#/page",
+  { name: "xiong" },
+  "fwez"
+);
+
+const stoken = proxy.$vtk.location.GetQueryString("stoken");
+```
+
+当前逻辑：
+
+- 如果第一个参数是 `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