ZXD Components

一个基于 Vue3 + TypeScript 的组件库，提供了常用的 UI 组件和工具函数。

✨ 特性

• 🚀 基于 Vue 3 + TypeScript 开发
• 📦 开箱即用的高质量组件
• 🛠️ 丰富的工具函数库
• 💪 完整的 TypeScript 类型支持
• 🎨 现代化的 UI 设计

📦 安装

npm install zxd-components-utils
# 或
yarn add zxd-components-utils
# 或
pnpm add zxd-components-utils

🔨 使用

完整引入

import { createApp } from 'vue'
import App from './App.vue'
import ZXDComponents from 'zxd-components-utils'
import 'zxd-components-utils/style.css'

const app = createApp(App)
app.use(ZXDComponents)
app.mount('#app')

按需引入（推荐）⭐

支持 Tree Shaking，自动移除未使用的代码，减小打包体积。

import { ZXDButton, ZXDCard, ZXDSignature } from 'zxd-components-utils'
import 'zxd-components-utils/style.css'

export default {
  components: {
    ZXDButton,
    ZXDCard,
    ZXDSignature
  }
}

📚 详细的按需导入指南： 查看 ON_DEMAND_IMPORT.md

使用工具函数（支持按需导入）

import { 
  // 通用工具
  zxd_formatDate, 
  zxd_debounce, 
  zxd_throttle,
  zxd_deepClone,
  zxd_generateId,
  zxd_isEmpty,
  zxd_setStorage,
  zxd_getStorage,
  zxd_removeStorage,
  // 数组工具
  unique,
  groupBy,
  sortBy,
  // 字符串工具
  capitalize,
  camelCase,
  // 数字工具
  formatNumber,
  toFixed
} from 'zxd-components-utils'

// 格式化日期
const formatted = zxd_formatDate(new Date(), 'YYYY-MM-DD')

// 防抖
const handleInput = zxd_debounce(() => {
  console.log('input changed')
}, 300)

// 数组去重
const arr = unique([1, 2, 2, 3, 3])

// 生成唯一ID
const id = zxd_generateId('user')

📚 组件列表

ZXDButton 按钮

基础的按钮组件，支持多种类型和尺寸。

<template>
  <ZXDButton type="primary" size="medium" @click="handleClick">
    点击我
  </ZXDButton>
</template>

Props:

• type: 按钮类型 - primary | success | warning | danger | info | default
• size: 按钮尺寸 - large | medium | small
• disabled: 是否禁用 - boolean

Events:

• click: 点击事件

ZXDCard 卡片

卡片容器组件，可包含标题、内容和底部。

<template>
  <ZXDCard header="卡片标题" shadow="always">
    <p>卡片内容</p>
    <template #footer>
      <button>操作按钮</button>
    </template>
  </ZXDCard>
</template>

Props:

• header: 卡片标题 - string
• shadow: 阴影显示时机 - always | hover | never

Slots:

• default: 卡片内容
• header: 自定义头部
• footer: 自定义底部

ZXDSignature 手写签名

手写签名组件，支持鼠标和触摸操作，适用于电子签名场景。

<template>
  <div>
    <ZXDSignature
      ref="signatureRef"
      :width="600"
      :height="400"
      :line-width="2"
      line-color="#000000"
      @save="handleSave"
      @change="handleChange"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'

const signatureRef = ref(null)

const handleSave = (dataUrl) => {
  console.log('签名图片:', dataUrl)
  // 可以上传到服务器或保存到本地
}

const handleChange = (isEmpty) => {
  console.log('签名状态:', isEmpty ? '空' : '已签名')
}

// 手动调用方法
const clearSignature = () => {
  signatureRef.value?.clear()
}

const saveSignature = () => {
  signatureRef.value?.save()
}

const exportAsImage = () => {
  const dataUrl = signatureRef.value?.toDataURL('image/png', 1)
  console.log(dataUrl)
}
</script>

Props:

• width: 画布宽度 - number (默认: 600)
• height: 画布高度 - number (默认: 400)
• lineWidth: 线条粗细 - number (默认: 2)
• lineColor: 线条颜色 - string (默认: '#000000')
• backgroundColor: 背景颜色 - string (默认: '#ffffff')
• placeholder: 占位文字 - string (默认: '请在此处签名')
• showToolbar: 是否显示工具栏 - boolean (默认: true)
• showPlaceholder: 是否显示占位文字 - boolean (默认: true)
• undoText: 撤销按钮文字 - string (默认: '撤销')
• clearText: 清空按钮文字 - string (默认: '清空')
• saveText: 保存按钮文字 - string (默认: '保存')
• imageType: 导出图片格式 - 'png' | 'jpeg' | 'webp' (默认: 'png')
• imageQuality: 图片质量 - number (默认: 1, 范围: 0-1)

Events:

• save: 保存签名时触发，参数为图片 DataURL
• change: 签名状态改变时触发，参数为是否为空
• clear: 清空签名时触发

Methods:

• clear(): 清空签名
• undo(): 撤销上一步
• save(): 保存签名（触发 save 事件）
• toDataURL(type?, quality?): 获取签名图片的 DataURL
• toBlob(callback, type?, quality?): 获取签名图片的 Blob
• fromDataURL(dataUrl): 从 DataURL 加载签名
• isEmpty(): 判断签名是否为空

使用场景：

• 电子合同签署
• 快递签收
• 会议签到
• 表单签名确认

🛠️ 工具函数

zxd_formatDate(date, format)

格式化日期

zxd_formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')
// => '2024-01-01 12:30:45'

zxd_debounce(fn, delay)

防抖函数

const handleSearch = zxd_debounce((keyword: string) => {
  console.log('搜索:', keyword)
}, 300)

zxd_throttle(fn, delay)

节流函数

const handleScroll = zxd_throttle(() => {
  console.log('滚动中')
}, 100)

zxd_deepClone(obj)

深拷贝对象

const cloned = zxd_deepClone({ a: 1, b: { c: 2 } })

zxd_generateId(prefix)

生成唯一ID

const id = zxd_generateId('user')
// => 'user_1234567890_abc123def'

zxd_isEmpty(value)

判断是否为空值

zxd_isEmpty('')        // => true
zxd_isEmpty([])        // => true
zxd_isEmpty({})        // => true
zxd_isEmpty(null)      // => true
zxd_isEmpty('hello')   // => false

本地存储工具

// 保存数据
zxd_setStorage('user', { name: 'Zhang San', age: 25 })

// 读取数据
const user = zxd_getStorage<{ name: string; age: number }>('user')

// 删除数据
zxd_removeStorage('user')

日期工具函数

import { 
  zxd_formatPhone,
  zxd_validateEmail,
  zxd_formatTimestampToYearMonth,
  zxd_formatTimestampToDate,
  zxd_getWeekOfYear,
  zxd_getWeekStartAndEnd,
  zxd_generateWeekList,
  zxd_generateMonthList,
  zxd_generateYearList
} from 'zxd-components-utils'

// 手机号格式化
zxd_formatPhone('13812345678')  // => '138****5678'

// 邮箱验证
zxd_validateEmail('[email protected]')  // => true

// 时间戳转年月数组
zxd_formatTimestampToYearMonth(1698825600000)  // => [2023, 11]

// 获取当年第几周
zxd_getWeekOfYear(new Date())  // => 45

// 获取某年某周的起止日期
zxd_getWeekStartAndEnd(2025, 10)  // => ['2025-03-03', '2025-03-09']

// 生成周列表（用于选择器）
const weeks = zxd_generateWeekList(30)
// => [{ label: '01周', year: 2025, week: 1, startDate: '...', endDate: '...' }, ...]

// 生成月份列表
const months = zxd_generateMonthList(12)
// => [{ label: '01月', year: 2025, month: 1, startDate: '...', endDate: '...' }, ...]

// 生成年份列表
const years = zxd_generateYearList(10)
// => [{ label: '2025年', year: 2025, startDate: '...', endDate: '...' }, ...]

加密工具函数

import {
  // Base64
  zxd_base64Encode,
  zxd_base64Decode,
  // AES 加密（推荐）⭐
  zxd_aesEncrypt,
  zxd_aesDecrypt,
  zxd_aesDecryptToObject,
  // DES 加密（不推荐，仅用于兼容旧系统）
  zxd_desEncrypt,
  zxd_desDecrypt,
  // TripleDES (3DES) 加密
  zxd_tripleDesEncrypt,
  zxd_tripleDesDecrypt,
  // 简单加密
  zxd_simpleEncrypt,
  zxd_simpleDecrypt,
  // 哈希函数
  zxd_md5,
  zxd_sha1,
  zxd_sha256,
  zxd_sha512,
  zxd_hashString,
  // HMAC
  zxd_hmacSha256,
  zxd_hmacSha512,
  // 密码哈希
  zxd_hashPassword,
  zxd_verifyPassword,
  // 其他
  zxd_generateKey,
  zxd_generateUUID,
  zxd_parseJWT,
  zxd_encryptObject,
  zxd_decryptObject,
  zxd_setEncryptedStorage,
  zxd_getEncryptedStorage
} from 'zxd-components-utils'

// === AES 加密（推荐）===
const aesKey = 'my-secret-key-2025'
const sensitiveData = '敏感数据'

// AES 加密字符串
const aesEncrypted = zxd_aesEncrypt(sensitiveData, aesKey)
const aesDecrypted = zxd_aesDecrypt(aesEncrypted, aesKey)

// AES 加密对象
const userData = { id: 1, name: '张三', age: 25 }
const encryptedObj = zxd_aesEncrypt(userData, aesKey)
const decryptedObj = zxd_aesDecryptToObject(encryptedObj, aesKey)

// === DES 加密（不推荐）===
const desEncrypted = zxd_desEncrypt('数据', 'des-key')
const desDecrypted = zxd_desDecrypt(desEncrypted, 'des-key')

// === 哈希函数 ===
const md5Hash = zxd_md5('data')           // MD5（不推荐用于密码）
const sha1Hash = zxd_sha1('data')         // SHA1
const sha256Hash = zxd_sha256('data')     // SHA256
const sha512Hash = zxd_sha512('data')     // SHA512

// === HMAC 签名 ===
const signature = zxd_hmacSha256('message', 'secret-key')

// === 密码加盐哈希（推荐用于密码存储）===
const { salt, hash } = await zxd_hashPassword('userPassword')
const isValid = await zxd_verifyPassword('userPassword', salt, hash)

// === Base64 编码/解码 ===
const encoded = zxd_base64Encode('Hello World')  // => 'SGVsbG8gV29ybGQ='
const decoded = zxd_base64Decode(encoded)        // => 'Hello World'

// === 生成随机值 ===
const key = zxd_generateKey(32)                  // 生成32字符密钥
const uuid = zxd_generateUUID()                  // 生成 UUID

// === JWT 解析 ===
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
const parsed = zxd_parseJWT(token)
console.log(parsed.payload)

// === 加密存储 ===
zxd_setEncryptedStorage('user', userData, aesKey)
const savedUser = zxd_getEncryptedStorage<User>('user', aesKey)

🔧 开发

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建组件库
npm run build

# 预览构建结果
npm run preview

📝 发布到 npm

1. 登录 npm

npm login

输入你的 npm 用户名、密码和邮箱。

2. 修改 package.json

在 package.json 中修改以下信息：

• name: 你的包名（必须是唯一的，当前为 zxd-components-utils）
• version: 版本号
• author: 作者信息
• repository: 仓库地址（如果有）

3. 构建项目

npm run build

4. 发布

npm publish

如果包名是作用域包（如 @username/zxd-components-utils），需要使用：

npm publish --access public

5. 更新版本

修改代码后，更新版本并重新发布：

# 补丁版本（bug修复）
npm version patch

# 次版本（新功能）
npm version minor

# 主版本（破坏性更新）
npm version major

# 发布新版本
npm publish

📄 License

MIT

👥 贡献

欢迎提交 Issue 和 Pull Request！