npm package: @hzw-tech/utils
Description: 通用前端工具包，包含请求,正则校验,全局ts声明等
Author: hzw-tech
Latest version: 0.2.7

# @hzw-tech/utils

hzw，ts前端工具包，包含常用css类以及ts工具方法等。可以用于vue以及react项目

> [!WARNING]
> sass使用了最新版本语法，引入时使用@use 替换原先的@import，使用map-get获取map类型变量需要@use 'sass:map';再使用map.get

## 1.安装

```bash
pnpm i @hzw-tech/utils
# VUE项目
pnpm i @hzw-tech/utils @tailwindcss/postcss postcss tailwindcss
```

## 2.特性

### 样式

1. 支持scss全局aem和hem的mixin
2. 不再支持cem，请使用tailwindcss 替换
3. tailwindcss 在vue中需要安装@tailwindcss/postcss postcss tailwindcss，并新建postcss.config.mjs以及src/styles/tailwind.css

### 工具方法：utils

1. utils.storage.set('test','test-data')支持storage的aes加密解密
2. utils.mergeObject({a:1,b:{b2:{b3:123}}},{a:2})合并对象默认值，如果对象某个层级的某个属性为空，则会换成默认对象的对应属性
3. utils.objectKey({a:1,b:2},1);根据value获取key
4. utils.arrayDelete([1,2,3,4],2);根据value删除数组中的元素
5. utils.clearLocalStorage();根据配置的app-version与用户本地的版本对比，如果版本有升级则清空用户的localStorage
6. utils.isEmpty(0);判断数据是否为空，尤其是[]和{}，空字符串和0不属于空
7. utils.getType(aa);获取变量类型
8. utils.isJson(aa);判断数据是否可以被解析为json

### 请求：request

1. 通过request.setConfig()方法进行全局配置;示例文件：[requestConfig](./src/examples/request.ts)
2. 配置项requestConfig在头部：requestConfig(config) {config.headers.Authorization = `Bearer XXXXX`;return config}
3. 配置项loading用于加载元素的创建，false则禁用loading，不为false时其必须返回带有close方法的实例：loading: {
   creator: () => {
   console.log('===loading===')
   return ElLoading.service({
   fullscreen: true,
   text: '加载中...',
   background: 'rgba(0, 0, 0, 0.7)',
   })
   },
   },
4. 配置项errorCatch用于错误处理，false则禁用错误处理，不为false时需要传递message方法，用于信息弹出，可以修改status中的400以上的状态码用于自定义错误处理
5. 通过new ApiRequest({...requestConfig,})的方式创建其他request实例
6. 单个接口的请求配置会覆盖request实例的配置，比如request.post({url:"/api/test",loading:false,errorCatch:false})

### 校验：validators（仅限element-plus的form自定义校验器）

element-plus的规则校验
export const validators = {
validatePhoneEmail,//校验是否是合法的手机或者邮箱
validateEmail,//校验是否是合法的邮箱
validatePhone,//校验是否是合法的手机
validateEn,//校验是否是合法的英文
validateCn,//校验是否是合法的中文
}

4. 通用的工具方法，校验方法，bem，请求方法，支持自定义配置
5. 通用的scss样式，mixin，变量等，支持自定义
6. 统一的eslint风格配置
7. 全局导入vue，vue-router，pinia，request，utils，validators，@umi/max，react等常用方法

## 3.使用

### vue项目使用

main.ts文件中：

```ts
import hzwUtils from '@hzw-tech/utils'
import { createPinia } from 'pinia'
import { createApp } from 'vue'
import App from './App.vue'
import '@hzw-tech/utils/dist/styles/index.scss'// 引入全局样式文件

const app = createApp(App)
app.use(router)
app.mount('#app')
app.use(hzwUtils, { storage: { prefix: 'hzw' } })
```

之后可以在ts文件和vue中使用bem，utils等工具方法，比如

```html
<template>
  <h1 :class="[css.bm('color', 'red')]">132</h1>
</template>
<script>
  console.log('aes:', utils.aes.encrypt('test'))
</script>

```

### ts支持

在项目的tsconfig.json中将@hzw-tech/utils相关ts声明文件加入到types中，这样可以在ts中获得类型提示

```json
{
  "compilerOptions": {
    "types": ["@hzw-tech/utils/dist/types/main", "@hzw-tech/utils/dist/types/global"]
  }
}
```

### vite配置

在vite中配置autoImport后，会将相关方法注入到ts和vue文件中

```ts
import hzwVite from '@hzw-tech/utils/dist/vite'
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

// https://vite.dev/config/
export default defineConfig({
  plugins: [vue(), hzwVite.autoImport()],
  css: {
    preprocessorOptions: {
      // 引入通用的全局mixin和变量
      scss: hzwVite.scss(),
    },
  },
})
```

## 4.自定义配置

1. 工具整体配置：

```ts
app.use(hzwUtils, {
  aes: {
      encryptKey: string;
  };
  appVersion: number;
  storage: {
      aes?: boolean;
      prefix?: string;
      jsonParse?: boolean;
      replace?: boolean;
  };
})
```

2. 请求配置

---

自定义请求配置：

```ts
// 默认请求修改
request.setConfig({
  baseURL: '/cgi',
  requestConfig(config) {
    config.headers.Authorization = `Bearer XXXXX`
    return config
  },
  // 如果不需要loading，则loading:false
  loading: {
    creator: () => {
      console.log('===loading===')
      return ElLoading.service({
        fullscreen: true,
        text: '加载中...',
        background: 'rgba(0, 0, 0, 0.7)',
      })
    },
  },

  // 如果不需要捕捉错误，则errorCatch:false，捕捉异常除了状态>=400会捕捉，同时状态200，返回的数据中status>=400也会捕捉
  errorCatch: {
    message: (data) => {
      // 400以及500会弹出错误信息,如果不想弹出信息则不传errorCatch.message，在errorCatch.status中单独处理
      console.log('===error===', data)
      ElMessage.error(data.data)
    },
    status: {
      // 除了弹出信息还可以配置额外处理
      400: (data) => {
        console.log('400', data)
      },
      // 具体状态处理，400,500如果配置了
      404: (data) => {
        console.log('404', data)
        ElMessage.error('404 无法访问该接口')
      },
      401: () => {
        console.log('401')
      },
    },
  },
  response: {
    // 返回数据解析
    parser: (data) => {
      // 默认返回data.data
      return data.data
    },
  },
})

// 新增其他请求，以及配置
export const requestAdmin = new ApiRequest({
  baseURL: '/admin',
  loading: false,
})
```

3. 自定义scss变量

1.新建一个scss文件，比如src/styles/index.scss，内容如下：

```scss
@forward '@hzw-tech/utils/dist/styles/reference/config.scss' with (
  $colors: (
    'red': blue,
    //你的自定义变量
  )
);
@forward '@hzw-tech/utils/dist/styles/reference/index.scss';

```

2.修改vite中全局变量以及mixins的引用

```ts
{
  css: {
    // https://vitejs.dev/config/shared-options.html#css-preprocessoroptions
    preprocessorOptions: {
      scss: {
        additionalData: '@use "@/styles/index.scss" as *;'
      }
    }
  }
}
```

## 5.工具列表

[bem](./dist/ts/bem.d.ts)
[reg](./dist/ts/reg.d.ts)
[request](./dist/ts/request.d.ts)
[validators](./dist/ts/validators.d.ts)
[utils](./dist/ts/utils.d.ts)
[通用样式大全](./dist/styles/index.css)

## 6. 全局type

[global](./dist/types/global.d.ts)