xframelib/README.md

积累的前端开发基础库,来源于项目和服务于项目。

# xframelib

<p>
<a href="https://www.npmjs.com/package/xframelib" target="_blank">
 <img src="https://img.shields.io/npm/v/xframelib?color=orange&logo=npm" />
</a>
<a href="https://www.npmjs.com/package/xframelib" target="_blank">
 <img src="https://img.shields.io/npm/dt/xframelib?logo=npm"/>
</a>
</p>

## XFramelib前端基础库

> 基于 VUE3+Hprose+Typescript+Widget 的前端框架，与ElementUI、AntDesign VUE、Quasar等界面库无关，一直是来源于项目和服务于项目。

- v0.9.9 修改init方法，使用Global.Config.ServiceURL.IconServiceURL注册自己的IconAPIProvider（解决内网时xwindow组件无按钮符号） ;
- v0.9.8  移除streamsaver依赖库，改为内部引用，解决弹框请求mitm.html导致无法下载文件的问题(http下的IP:端口请求会出现域安全问题);
- v0.9.7  解决v0.9.6使用useTemplateRef后导致LayoutManager不断报警告问题：client-entry.js:313 [Vue warn] Set operation on key "value" failed: target is readonly. RefImpl
- *v0.9.6   改用vite打包；解决存在的循环引用问题；引入webworker,增加xmathWorker和xxteaWorker；XWindow增加点击header栏置顶窗体；优化widgetConfig加载，提升优化LayoutContainer和LayoutManager内部处理效率（保留旧方法，兼容旧开发模板）；更新依赖库版本;
- v0.9.5  SysConfig.js引入UI.OnlyUserVerify配置可以启用“只验证用户，不验证功能”;uuid方法改为小写;解决存在的循环引用问题;更新依赖库版本;
- v0.9.4   修改ADivider组件线样式问题;修改XWindow组件拖拽位置计算不对的BUG;更新js依赖版本;
- v0.9.3   更新依赖;提升单个大文件上传速度，对应后端服务并发写排队模式（前端默认并发3个请求）;
- v0.9.2   精简更新依赖;升级增强内部功能控制;积累与完善部分基础功能;匹配最新简化模板;
- v0.9.1   增加a-divider组件;升级BigFileDownload方法（与新版文件服务匹配）；解决GlobalHprose.getDefaultClient()为空对象问题；
- v0.9.0   给LayoutContainer增加id属性;ZipTool使用扩展promise方法时，出现内部this指向不明错误,增加saveZipFromFiles文件数组压缩和saveZipFileSync同步压缩方法;引入iconv-lite字符编码库，可直接使用iconv里所有方法；
- v0.8.9   为Function扩展promise方法（事件异步方法将按Promise异步执行）；修改isElement判断错误；~~增加ZipTool用于文件在线压缩和解压(存在问题，不要使用)~~；H5Tool增加blockEvent停止冒泡bindDropFileHanlder拖拽文件、readFilePromise异步读取文件、优化readFileBytes为bytes二进制数组;IsTool增加isStringLikeJson、isStringLikeKml方法;H5Tool增加了onPasteHandler和offPasteHandler使用document绑定粘贴事件（不是任意div元素都可以绑定paste事件，只有设置了 contenteditable="true" 的元素，才会触发该事件）；FileDownload增加SaveToSelectedFile方法，将文件保存到选定路径；
- v0.8.7   修改0.8.6版的getDownload内部错误（与HttpDownload方法共存使用）;
- v0.8.6   修改get方法支持：业务服务API请求、请求网站public下资源、http完整URL请求; ~~增加getDownload方法下载文件（废弃HttpDownload方法）;~~
- v0.8.5   动态加载Widget时绑定更多IWidgetConfig属性（如：id,layoutID等）;加载widget报错，输出更多异常信息;
- v0.8.4   为widget权限对象，增加layoutid属性;修改LockHelper锁屏功能BUG;去掉DownloadByUrl（可改用HttpDownload方法）;为H5Tool增加readFileBytes方法（读取前端文件，为bytes二进制数组/字符串）;更新依赖库版本;
- v0.8.3   增加HproseRPC过程的请求字符串和返回字符串的外部解码类HproseRPCCodec;
- v0.8.2   修改VueWindow组件（VWindow）拖动定位错误;弃用DownloadByUrl方法;移除窗体同步库WSynchro.js;更新依赖库版本;
- v0.8.1   修改RouterTransition组件，增加具有默认动画的RouterTransitionAnimate组件;widget组件配置对象（IWidgetConfig）启用layout属性（IWidgetLayout布局样式），增加cssClass外部配置样式类名；更新依赖库版本;
- v0.8.0   更新LayoutContainer各层的默认样式，默认空白区域鼠标可以穿越，各元素鼠标可点击;更新依赖库版本;
- *v0.7.9  给H5Tool增加常用DOM操作方法；为SysEvents增加LayoutContainerLoaded，每个LayoutManager对象自动加载到Global.LayoutMap里，为Global默认增加CesiumViewer对象；强化Widget链式排队加载，必须先afterid对应的widget加载成功，然后才加载当前widget。
- v0.7.8 更新依赖库版本；增加SysConfig默认配置项；controls增加XWindow和XWindowManager取代VWindow；增加全局的Global.WidgetConfigList数组和getLayoutManager方法；删除VCollapsiblePanel、 VCollapsiblePanelGroup组件。
- v0.7.7 增加hprose二进制序列化方法serialize和deserialize;修改Global默认自带LayoutMap和默认为console的Message;为LayoutManager增加静态方法getLayoutManager;增加RouterTransition控件,并应用于layoutcontainer中;更新依赖库版本。
- v0.7.6 为LayoutManager增加卸载全部组件unloadAllWidgets、批量卸载组件unloadWidgets、获得已经加载组件ID列表getWidgetLoadedIDList;解决H5Tool的windowResizeHandler和offWindowResizeHandler内部调用错误方法的问题。
- ~~v0.7.5 解决上一版LayoutContainer存在问题：CSS样式对应上，调整层级顺序；加入组件引用，changeWidgetVisible能控制Widget组件可见性；修改getWidgetComponent方法，实现对Widget组件的defineExpose方法调用;增加isWidgetVisible判断组件是否可见。~~
- ~~v0.7.4 完善Axios异常捕捉（对接后端Furion包装异常）;更新完善LayoutContainer；H5Tool增加removeHandler和offWindowResizeHandler方法；升级依赖基础库。~~
- v0.7.3 升级依赖库；loadWidget失败输出日志和事件SysEvents.WidgetLoadedErrorEvent；优化系统权限相关模型；增加GetSignalRClient、ValidateTool、WaterMark等工具。
- v0.7.2 解决v0.7.0的deepMerge方法存在复制对象的BUG。
- v0.7.0 修改requestPost无法使用FormData参数；修改deepMerge方法；修改isObjectX方法;更新rollup-plugin-scss应用版本。
- ~~v0.6.9 默认引入loglevel,为Global增加Logger()方法，使用例如：Global.Logger().warn('123')。~~
- v0.6.8 解决Axios 0.x升级为1.x后，序列化时带来的AxiosError: options must be an object错误 
- v0.6.7 解决ExitLogin时报415错误；SysEvents.AxiosRequestErrorEvent、SysEvents.WebAPIErrorEvent、SysEvents.HproseServiceErrorEvent改为默认为后台记录，不主动弹框提示，需要提示使用Global.EventBus自主监听事件；升级依赖库版本;
- v0.6.6 解决requestGet里params参数为数组解析错误问题;更改Layout布局层次为100;解决提示XXTEA未导出的问题;copyText默认改用Clipboard方式，支持根据元素ID复制内容;
- v0.6.5 copyText默认改用Clipboard方式，支持根据元素ID复制内容；
- v0.6.4 调整LayoutContainer层级；修改centerDiv的默认pointer-events
- v0.6.3 
升级基础库;完善LayoutContainer增加enableRouterView控制是否启用内置的RouterView;H5Tool增加dispatchWindowResize和dispatchElementEvent主动触发元素事件
- v0.6.2 增加计算完整MD5值和文件上传导出问题;部分小问题修改;增加窗体同步消息库WSynchro.js;
- v0.6.1 增加全局捕捉Axios请求报错信息；Token认证时间BUG：客户端为过去时间或未来时间;
- v0.6.0 解决requestPost支持FormData数组参数问题;IMapKeys支持地图Key配置为数组;ServiceURL配置增加IconServiceURL、UILoginURL等
- v0.5.9 重构用户模型和登录验证,对接用户权限管理系统;增加XXTEA加密算法;增加http network error错误捕捉
- v0.5.8 修改 VueWindow 报 fixPosition 错误；重构升级 widget 加载过程；升级依赖基础库版本
- v0.5.7 修改 init 初始化增加 sysGroup 参数;增加 Global.SystemGroup 字段，Axios 和 Hprose 的 Http 请求头加入 sysgroup 系统分组名;解决 Global 变量的循环引用,增加 SysConfig 的 UI 下的 GrayMode 参数、部分 ServiceURL 下参数，修改一些小 BUG;
- v0.5.6 修改 init 初始化方法增加 sysID 参数；增加 Global.SystemID 字段，Axios 和 Hprose 的 Http 请求头加入 sysid;
- v0.5.5 截取捕捉后台返回的有用异常信息，重新抛出;异常警告输出统一模型增加 isExceptionInfo 字段;更新依赖库;
- v0.5.4 解决 IRole 相关模型类型未导出;LayoutManager.d.ts 输出两遍问题;完善 axios http 请求异常警告输出统一模型,发送 SysEvents.AxiosRequestErrorEvent 系统事件;
- v0.5.3 撤销的版本
- v0.5.2 撤销的版本
- v0.5.1 路由权限过滤只比较 path;修改返回权限结果判断错误问题
- v0.5.0 增加用户权限管理组;增加 CodeHelper 来辅助生成部分代码的方法;解决大文件下载路径传递、全屏时不传对象报错等问题;引入 axios 对象外部化 axios 库
- v0.4.9 解决 Global.User 对象赋值错误导致 0.4.8 无法登录的问题
- v0.4.8 解决 UserToken 里没有 appkey 信息;刷新 token 时丢失 appkey 信息（弃用该版本）
- v0.4.7 解决 Hprose 使用 ClientContext 进行公共传参问题,默认 headers 自带 token 值
- v0.4.6 解决文件分片下载并发请求过多的超时问题;AxiosHelper 增加超时时间参数，请求出错不默认弹框
- v0.4.5 解决大文件下载的问题（修复 0.4.4 版本问题）;增加库依赖资源 public 文件夹
- v0.4.4 修改单个文件（单片）下载报错问题;（废弃不要使用）
- v0.4.3 修改组件卸载事件的错误;增加用于大屏的浅灰色窗体样式
- v0.4.2 重要修改：修改打包方式;支持组件导出;新增布局组件及管理方法;requestFullScreen 不传要素窗体全屏
- v0.4.1 解决补充遗漏的 BigFileDownload 类;
- v0.4.0 增加 isTool 的相关函数,修改补充方法,增加导出 IUser;
- v0.3.9 init 方法需要传入 axios 对象（不能将 axios 打包进去，因为存在错误）;
- v0.3.8 取消 init 方法传入 axios 对象（改为内部自带 Global.Axios）;完善 AxiosHelper 工具类;增加大文件分片/断点续传下载类 BigFileDownload;
- v0.3.7 增加 LockHelper 长时间操作退出登录，增加 SystemConfig.UI.LockTime 可选配置和接口 onLockListener、 unLockListener、getLockState;
- v0.3.6 H5Tool 增加基于 SparkMD5 的 MD5 计算;解决 TokenHelper 与 Global 循环引用问题;增加模仿 JQuery 的 HTML 元素 Style 类名操作 hasClass、addClass、removeClass、toggleClass;完善 getProxyClient 支持 Map 缓存 HproseProxy 对象
- v0.3.5 增加大文件切片上传 FileUpload;增加 newGuid 方法;
  修改 requestPost 使用 FormData 方式提交数据,增加 requestPostBody 使用 JSON 方式提交;
  移除 UserCookies 和 JS-js-cookie 依赖;
  H5Tool 增加 getFileShortMD5 获取文件 MD5 值,增加 getObjectURL 获取 File 对象的路径;
- v0.3.4 增加统一用户登录和 Token 支持;解决类循环引用问题;增加系统配置参数为具体接口
- v0.3.3 解决 支持 Hprose 旧版本不支持 useServiceAsync 的问题
- v0.3.2 解决 0.3.1 版本更新错误（导致 HproseClient 无法实例化的问题）
- v0.3.1 修改系统 DefaultProxyClient 初始化弹框报错问题（DefaultHproseAPI 配置项可为空或不设置）;增加 getProxyClient 和 initDefaultProxyClient 全局方法。
- v0.3.0 修改 UserCookies 支持自定义 KEY;修改 H5Tool 增强全屏操作功能方法;升级依赖的基础库
- v0.2.9 删除 uuid 的 NPM 包,增加 uuid 工具类,解决类型问题
- v0.2.8 删除对 axios 的依赖（因 axios 使用了 process 对象,vue 中报错）
- v0.2.7 增加 VUE WINDOW,FileDownload 等,打包入 axios（出现问题）
- v0.2.6 新建前端 xframelib,支持 VUE 组件打包基于 ESbuild
- v0.2.5 减小发布包大小,外部依赖 hprose
- v0.2.4 正式应用于项目中,提供.d.ts 声明文件。

## 主要功能:

- 网站系统配置Sysconfig.js对应的Global.Config
- 公共事件总线Global.EventBus

- Layout布局容器和Widget机制实现

- Axios的Http请求封装实现Global.Axios、AxiosHelper{get, post, requestPost, requestGet, getData, requestPostBody} 

- Hprose Proxy方式调用后台Hprose服务实现

- 与用户系统后台服务适配的Token验证/刷新和角色权限过滤

- 大文件下载BigFileDownload

- 普通文件下载FileDownload封装{ Download, SaveAs, JsonDownload, HttpDownload, DownloadByUrl }

- 大文件上传FileUpload

- H5Tool常用小功能

- SignalrClient

- JQuery工具 （hasClass 、addClass、removeClass、toggleClass、setCssProperty）

- StorageHelper 本地缓存对象

- IsTool类型判断工具（数字、字符串、对象、数组、函数等）

- ValidateTool验证工具（身份证、手机号、IP地址、邮箱、密码强度判断、URL、车牌号等）

- 与后端配合使用的加密解密算法XXTEA

## 使用

`pnpm add xframelib`

or

`npm i xframelib`

全局引入库样式：

import 'xframelib/dist/index.css';

- **应用案例：前端开发模板 vue-widget-template**

https://github.com/zorrowm/vue-widget-template

全面基于XFramelib和Widget思想的开发模板

- **main.ts 文件**
  In Typescript:

```js
import { createApp } from 'vue';
import App from './App.vue';
//模板添加的
import { setupRouter } from './router/index';
import {setupGlobDirectives} from './directives/index';
import { init, Global } from 'xframelib';
import 'xframelib/dist/index.css';
import { getSystemPKG, getSystemID } from '@/utils/sysTool';
import { createPinia } from 'pinia';
import { message } from 'ant-design-vue';
import {Icon} from '@iconify/vue';
//dev阶段打开，build注销
import 'ant-design-vue/dist/antd.css';


if(window.global===undefined)
{
  window.global=globalThis;
}
message.config({
  top: `100px`,
  duration: 1,
  maxCount: 3
});
//绑定消息和初始化xframe
//系统ID,唯一标识
const sysID = getSystemID();
//分组名，工程名
const sysGroup = getSystemPKG().name;
init(message, sysID, sysGroup);

// 创建pinia 实例
const pinia = createPinia();
const app = createApp(App);
// 挂载到 Vue 根实例上
app.use(pinia);
//定义v-drag命令
setupGlobDirectives(app);
setupRouter(app);
//注册全局组件
app.component('Icon',Icon);

app.mount('#app');

```

- **Quasar boot 使用示例**

```vue
import { boot } from 'quasar/wrappers';
import { addAPIProvider, Icon } from '@iconify/vue';
import { Dropdown } from 'floating-vue';
import { EmitLoadingInfo } from 'src/events/index';
import { autoRefresh } from 'src/utils/autoUpdate';
import { message } from 'src/utils/MessageNotify';
//封装的消息提示
import { getSystemID, getSystemPKG } from 'src/utils/sysTool';
import { Global, init } from 'xframelib';
function preInit() {
  if (window.global === undefined) {
    window.global = globalThis;
  }
  //系统ID,唯一标识
  const sysID = getSystemID();
  //分组名，工程名
  const sysGroup = getSystemPKG().name;
  init(message, sysID, sysGroup);
  //挂载进度通知方法
  Global.Loading = EmitLoadingInfo;
  //注册自己的IconAPIProvider
  if (Global.Config.ServiceURL.IconServiceURL)
    addAPIProvider('', {
      resources: [Global.Config.ServiceURL.IconServiceURL]
    });
  else {
    //离线使用图标：生效，IconServiceURL配置为空
    import('../components/IconOffline').then((it) => {
      it.default();
    });
  }
}
export default boot(({ app }) => {
  EmitLoadingInfo('XFramelib库');
  //初始化Xframelib
  preInit();
  //启动热更新监测
  if (import.meta.env.DEV) autoRefresh();
  // 创建pinia 实例——20240221这里不需要了，在src/stores/index.ts里挂接的
  // const pinia = createPinia();
  // app.use(pinia);
  //注册全局组件
  app.component('Icon', Icon);
  app.component('VDropdown', Dropdown);
  // app.component('VTooltip', Tooltip);
  // app.component('VMenu', Menu);

  //开发时,全局注册tiny组件
  // if (import.meta.env.DEV) {
  //   // import('@opentiny/vue').then((it) => {
  //   //   const TinyVue = it.default;
  //   //   app.use(TinyVue);
  //   // });
  // }
  console.log('环境变量',process.env);
  //保存网站根地址
  app.config.globalProperties.$AppURL=process.env.APP_URL;
});

```

## 应用示例

![开发模版](https://zorrowm.github.io/npm/xframelib.png)