zhengsi-utils

🚀 一个功能丰富的 Vue 3 组件库和工具函数集合，专为现代 Web 应用设计。

✨ 特性

• 🎯 Vue 3 原生支持 - 基于 Vue 3 Composition API 构建
• 🧩 丰富的组件库 - 提供 9 个常用 UI 组件
• 🛠️ 实用工具函数 - 包含 20+ 个常用工具函数
• 📱 移动端友好 - 支持 iPhone 安全区域等移动端特性
• 🎨 灵活样式 - 支持 SCSS 和 UnoCSS
• 📦 按需引入 - 支持 Tree Shaking，减小打包体积
• 🔧 TypeScript - 完整的类型定义支持

📦 安装

# 使用 npm
npm install zhengsi-utils

# 使用 yarn
yarn add zhengsi-utils

# 使用 pnpm
pnpm add zhengsi-utils

🚀 快速开始

完整引入

import { createApp } from 'vue'
import ZhengsiUtils from 'zhengsi-utils'
import 'zhengsi-utils/style'

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

按需引入

// 引入特定组件
import { BaseButton, Empty } from 'zhengsi-utils'

// 引入工具函数
import { formatDuration, parseUrlParams } from 'zhengsi-utils'

🧩 组件库

BaseButton - 基础按钮

功能丰富的按钮组件，支持多种类型、尺寸和状态。

<template>
  <BaseButton 
    type="primary" 
    size="large" 
    :loading="loading"
    @click="handleClick"
  >
    点击我
  </BaseButton>
</template>

<script setup>
import { BaseButton } from 'zhengsi-utils'

const loading = ref(false)
const handleClick = () => {
  console.log('按钮被点击了！')
}
</script>

Props: | 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | type | 'primary' \| 'default' \| 'danger' \| 'warn' \| 'success' | 'default' | 按钮类型 | | size | 'small' \| 'middle' \| 'large' | 'middle' | 按钮尺寸 | | disabled | boolean | false | 是否禁用 | | loading | boolean | false | 是否显示加载状态 | | circle | boolean | false | 是否为圆形按钮 | | plain | boolean | false | 是否为朴素样式 |

Empty - 空状态

用于显示空数据状态的组件。

<template>
  <Empty description="暂无数据" />
</template>

FloatButton - 浮动按钮

一个可以浮动的按钮组件，通常用于快速操作。

<template>
  <FloatButton 
    position="bottom-right"
    @click="handleFloatClick"
  >
    <Icon name="plus" />
  </FloatButton>
</template>

IPhoneBottom - iPhone 底部安全区域

为 iPhone 设备提供底部安全区域适配的组件。

<template>
  <IPhoneBottom>
    <div class="bottom-content">
      底部内容
    </div>
  </IPhoneBottom>
</template>

LabelList - 标签列表

用于显示标签列表的组件。

<template>
  <LabelList 
    :labels="['Vue', 'React', 'Angular']"
    :max="5"
    closable
    @close="handleLabelClose"
  />
</template>

FixedBox - 固定定位盒子

一个固定定位的容器组件。

<template>
  <FixedBox position="top" :z-index="1000">
    <div class="fixed-header">固定头部</div>
  </FixedBox>
</template>

CubeLoader - 立方体加载器

一个立方体样式的加载动画组件。

<template>
  <CubeLoader 
    :size="40"
    :color="'#1890ff'"
  />
</template>

ScrollList - 滚动列表

一个支持分页加载的滚动列表组件。

<template>
  <ScrollList 
    :api="apiConfig"
    :params="queryParams"
    :pages="{ page: 1, size: 20 }"
  >
    <template #row="{ row, index }">
      <div class="list-item">
        <span>{{ index + 1 }}. {{ row.name }}</span>
      </div>
    </template>
  </ScrollList>
</template>

<script setup>
const apiConfig = {
  url: '/api/list',
  method: 'GET'
}

const queryParams = {
  category: 'all'
}
</script>

Props: | 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | api | object | - | API 配置对象 | | params | object | {} | 请求参数 | | pages | object | { page: 1, size: 20 } | 分页配置 | | defaultRequest | boolean | true | 是否默认执行请求 | | noPagination | boolean | false | 是否无分页 |

TabBar - 标签栏

一个标签栏组件，用于页面导航。

<template>
  <TabBar 
    :tabs="tabs"
    :active="activeTab"
    @change="handleTabChange"
  />
</template>

<script setup>
const tabs = [
  { key: 'home', label: '首页', icon: 'home' },
  { key: 'about', label: '关于', icon: 'info' },
  { key: 'contact', label: '联系', icon: 'phone' }
]

const activeTab = ref('home')
const handleTabChange = (key) => {
  activeTab.value = key
}
</script>

🛠️ 工具函数

格式化工具

import { formatDuration, formatDate, formatNumber } from 'zhengsi-utils'

// 格式化时长
formatDuration(3661) // "1小时1分1秒"
formatDuration(65)   // "1分5秒"

// 格式化日期
formatDate(new Date(), 'YYYY-MM-DD') // "2024-01-01"

// 格式化数字
formatNumber(1234.56) // "1,234.56"

URL 工具

import { parseUrlParams, buildUrl } from 'zhengsi-utils'

// 解析 URL 参数
const params = parseUrlParams('?name=test&age=18')
// { name: 'test', age: '18' }

// 构建 URL
const url = buildUrl('/api/users', { page: 1, size: 20 })
// "/api/users?page=1&size=20"

文件工具

import { base64ToFile, fileToBase64 } from 'zhengsi-utils'

// Base64 转文件
const file = base64ToFile(base64String, 'filename.jpg')

// 文件转 Base64
const base64 = await fileToBase64(fileInput.files[0])

环境判断

import { isDevelopment, isProduction, isMobile } from 'zhengsi-utils'

// 环境判断
isDevelopment()  // 是否为开发环境
isProduction()   // 是否为生产环境
isMobile()       // 是否为移动设备

加密工具

import { encrypt, decrypt } from 'zhengsi-utils'

// RSA 加密
const encrypted = encrypt('hello world', publicKey)

// RSA 解密
const decrypted = decrypt(encrypted, privateKey)

📚 API 参考

组件 Props 类型

// BaseButton Props
interface BaseButtonProps {
  type?: 'primary' | 'default' | 'danger' | 'warn' | 'success'
  size?: 'small' | 'middle' | 'large'
  disabled?: boolean
  loading?: boolean
  circle?: boolean
  plain?: boolean
}

// ScrollList Props
interface ScrollListProps {
  api: {
    url: string
    method?: string
    headers?: Record<string, string>
  }
  params?: Record<string, any>
  pages?: {
    page: number
    size: number
  }
  defaultRequest?: boolean
  noPagination?: boolean
}

工具函数类型

// 格式化时长
function formatDuration(seconds: number): string

// 解析 URL 参数
function parseUrlParams(url: string): Record<string, string>

// Base64 转文件
function base64ToFile(base64: string, filename: string): File

// 环境判断
function isDevelopment(): boolean
function isProduction(): boolean
function isMobile(): boolean

🎨 样式定制

使用 CSS 变量

:root {
  --zhengsi-primary-color: #1890ff;
  --zhengsi-border-radius: 6px;
  --zhengsi-font-size: 14px;
}

使用 SCSS 变量

@import 'zhengsi-utils/styles/variables';

.custom-button {
  background-color: $primary-color;
  border-radius: $border-radius;
}

项目结构

zhengsi-utils/
├── src/
│   ├── components/          # Vue 组件
│   │   ├── BaseButton/     # 基础按钮
│   │   ├── Empty/          # 空状态
│   │   ├── FloatButton/    # 浮动按钮
│   │   ├── IPhoneBottom/   # iPhone 底部安全区域
│   │   ├── LabelList/      # 标签列表
│   │   ├── FixedBox/       # 固定定位盒子
│   │   ├── CubeLoader/     # 立方体加载器
│   │   ├── ScrollList/     # 滚动列表
│   │   └── TabBar/         # 标签栏
│   ├── services/           # 工具函数和服务
│   │   ├── utils/          # 工具函数
│   │   ├── api/            # API 接口
│   │   └── router/         # 路由相关
│   └── index.ts            # 主入口文件
├── dist/                   # 构建输出
├── types/                  # TypeScript 类型定义
└── docs/                   # 文档

🚨 项目问题分析与改进建议

已修复的问题

1. TypeScript 配置缺失 ✅

   • 问题：缺少 tsconfig.json 文件，导致模块解析错误
   • 解决：创建了完整的 TypeScript 配置文件

2. 构建配置不一致 ✅

   • 问题：package.json 与 vite.config.ts 中的文件名不匹配
   • 解决：统一了输出文件名格式

3. 类型定义文件不完整 ✅

   • 问题：生成的类型定义文件过于简单
   • 解决：配置了 vite-plugin-dts 生成更完整的类型定义

仍需改进的问题

1. Vue 组件中的 TypeScript 错误

   • 问题：多个组件中存在 Vue 3 Composition API 函数未导入的错误
   • 建议：在每个 Vue 组件中正确导入所需的 Vue 函数

2. UniApp 相关代码的类型定义

   • 问题：代码中使用了 uni 和 getCurrentPages 等 UniApp API，但缺少类型定义
   • 建议：添加 UniApp 类型定义或重构为纯 Web 环境代码

3. 动态导入与静态导入冲突

   • 问题：构建警告显示多个模块同时被动态导入和静态导入
   • 建议：统一使用静态导入，移除不必要的动态导入

4. 环境变量配置

   • 问题：代码中使用了 import.meta.env 但缺少环境变量配置
   • 建议：创建 .env 文件或重构为配置对象

改进建议

1. 代码质量提升

   • 添加 ESLint 和 Prettier 配置
   • 完善 TypeScript 类型定义
   • 添加单元测试

2. 文档完善

   • 添加组件使用示例
   • 完善 API 文档
   • 添加变更日志

3. 构建优化

   • 优化 Tree Shaking
   • 减少打包体积
   • 添加构建分析工具

4. 兼容性改进

   • 支持更多构建工具（Webpack、Rollup 等）
   • 添加 CommonJS 支持
   • 优化浏览器兼容性

📝 变更日志

v1.0.2 (当前版本)

• ✅ 修复了 TypeScript 配置问题
• ✅ 统一了构建配置
• ✅ 完善了类型定义生成
• ✅ 修复了构建警告

v1.0.1

• 🚀 初始版本发布
• 📦 包含基础组件和工具函数

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

ISC License