@hzw-tech/utils

hzw，ts前端工具包，包含常用css类以及ts工具方法等。可以用于vue以及react项目

[!WARNING] sass使用了最新版本语法，引入时使用@use 替换原先的@import，使用map-get获取map类型变量需要@use 'sass:map';再使用map.get

[!WARNING] 0.3.0起不再支持cem通用样式类，请使用tailwindcss 替换。无法引入dist/styles/index.scss

1.安装

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
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,//校验是否是合法的中文
}

框架

统一的eslint规范文件

3.使用

vue项目使用

main.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等工具方法，比如

<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中获得类型提示

{
  "compilerOptions": {
    "types": ["@hzw-tech/utils/dist/types/main", "@hzw-tech/utils/dist/types/global"]
  }
}

vite配置

在vite中配置autoImport后，会将相关方法注入到ts和vue文件中

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. 工具整体配置：

app.use(hzwUtils, {
  aes: {
      encryptKey: string;
  };
  appVersion: number;
  storage: {
      aes?: boolean;
      prefix?: string;
      jsonParse?: boolean;
      replace?: boolean;
  };
})

2. 请求配置

自定义请求配置：

// 默认请求修改
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，内容如下：

@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的引用

{
  css: {
    // https://vitejs.dev/config/shared-options.html#css-preprocessoroptions
    preprocessorOptions: {
      scss: {
        additionalData: '@use "@/styles/index.scss" as *;'
      }
    }
  }
}

5.工具列表

bem reg request validators utils

6. 全局type

global

7. 打包与发布

修改package.json中的version

pnpm build
pnpm release