@yxhl/specter-pui-vtk

基于 Vue 3 + Vuetify 3 的业务组件库，内置常用业务组件、消息能力、请求封装、存储工具和格式化方法。

目录

• 安装
• 快速开始
• 全局能力
• 组件使用
• 工具方法
• 配置说明
• 开发与发布
• 常见问题

安装

npm install @yxhl/specter-pui-vtk

适用环境：

• Vue 3.x
• Vuetify 3.x
• Node.js >= 16

快速开始

1. 在 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);

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 中加入：

<template>
  <v-app>
    <router-view />
    <vtk-message />
  </v-app>
</template>

3. 基础使用示例

<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 使用以下能力：

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

<template>
  <VtkArea v-model="areaCode" />
</template>

<script setup>
import { ref } from "vue";

const areaCode = ref("");
</script>

常用属性：

• v-model：地区编码
• maxArea：最大地区层级
• minArea：最小地区层级

VtkDept

<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

<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

<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

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

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

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

const { proxy } = getCurrentInstance();

const rules = [
  proxy.$vtk.Validation.required("不能为空"),
  proxy.$vtk.Validation.mobile("手机号格式不正确")
];

5. filters

dictionary.js、mask.js、format.js 中的方法会一起挂到 $vtk.filters，同时字典方法也会被直接导出。

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 追加参数。

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

window.VTK_CONFIG = {
  storageKeys: {
    user: "_mis_acis_users",
    token: "_mis_acis_token"
  }
};

默认值：

• user: _mis_acis_users
• token: _mis_acis_token

API 地址

window.VITE_APP_API_URL = import.meta.env.VITE_APP_API_URL;

也可以在 .env 中配置：

VITE_APP_API_URL=https://api.example.com
VITE_MIS_USERS=_mis_acis_users
VITE_MIS_TOKEN=_mis_acis_token

开发与发布

本地开发

npm run dev

打包

npm run build

发布前版本更新

npm version patch
npm version minor
npm version major

发布

npm publish --access public

常见问题

1. 组件未生效

请确认：

• 已执行 app.use(SpecterPuiVtk)
• 已引入样式 @yxhl/specter-pui-vtk/dist/specter-pui-vtk.css

2. 消息组件不显示

请确认根组件中已挂载：

<vtk-message />

3. 请求地址是 undefined

请确认已设置：

window.VITE_APP_API_URL = import.meta.env.VITE_APP_API_URL;

4. 组件读取不到用户信息

请确认用户信息已写入本地存储，并且 key 与 window.VTK_CONFIG.storageKeys.user 一致。

版本

当前版本：1.0.68

License

MIT