t-comm
Version:
专业、稳定、纯粹的工具库
304 lines (217 loc) • 9.38 kB
Markdown
# t-comm
<!-- 复制到 docs 时，去掉 ”详细文档“ 那一节 -->
<div align="center">
<img src="https://mike-1255355338.cos.ap-guangzhou.myqcloud.com/press%2Fimg%2Fown_mike_5489135b5a3b9258d8.gif" width="120" style="margin-bottom: 20px;margin-top: 20px;" />
</div>
<p align="center">
<img src="https://img.shields.io/npm/v/t-comm">
<img src="https://img.shields.io/npm/l/t-comm">
<img src="https://img.shields.io/npm/dw/t-comm">
<img src="https://img.shields.io/npm/unpacked-size/t-comm">
<br/>
<img src="https://img.shields.io/badge/modules-100%2B-blue">
<img src="https://img.shields.io/badge/TypeScript-strict-blue?logo=typescript&logoColor=white">
<img src="https://img.shields.io/badge/build-passing-brightgreen">
<img src="https://img.shields.io/badge/coverage-88.44%25-green" alt="coverage">
<img src="https://img.shields.io/badge/created-2022--01-blue?logo=github&logoColor=white">
</p>
## 项目介绍
`t-comm` 是一个专业、稳定、纯粹的现代化前端工具库，专为提升开发效率和代码质量而设计。它整合了 100+ 个实用模块，涵盖了从基础数据处理到复杂业务场景的全方位工具链。
### 核心价值
- **全面覆盖**：提供从基础工具函数到复杂业务场景的完整解决方案
- **类型安全**：完全基于 TypeScript 开发，提供完整的类型定义和智能提示
- **按需引入**：支持 tree-shaking，大幅减少打包体积
- **跨平台适配**：统一封装 Web、小程序、uni-app 等多平台 API
- **生产级稳定**：经过大量项目验证，确保高可靠性
- **持续维护**：活跃的社区贡献和定期的功能更新
### 应用场景
- **Web 应用开发**：提供丰富的前端工具函数和 UI 组件
- **小程序开发**：深度集成微信、QQ 小程序 API
- **跨端应用**：uni-app 项目统一适配
- **DevOps 流程**：自动化构建、发布、监控工具
- **云服务集成**：腾讯云 CDN、COS、配置中心等无缝对接
---
## 功能简介
### 基础工具模块
- **字符串处理**：长度检查、随机生成、格式转换、国际化编码
- **数组操作**：扁平化、分块、排序、去重、乱序
- **对象操作**：深拷贝、合并、排序、路径处理、属性遍历
- **数字计算**：千分位格式化、比例计算、随机数、范围生成
- **日期时间**：时间戳转换、格式化、倒计时、相对时间显示
- **正则表达式**：匹配列表提取、版本号解析
### 平台适配功能
- **环境检测**：微信、QQ、Android、iOS 等运行环境识别
- **小程序工具**：页面统计、组件信息、版本更新、图片保存
- **uni-app 支持**：项目启动、路由拦截、状态缓存、响应式布局
- **地理位置**：跨平台定位、坐标转换、地图打开
### 网络与通信
- **SSE 服务器推送**：支持 Web 和小程序环境的实时消息推送
- **HTTP 请求封装**：统一的请求拦截器和错误处理
- **JSONP 跨域请求**：支持超时和回调函数配置
- **轮询请求管理**：可配置间隔和最大轮询次数
### 数据处理
- **JSON 安全解析**：避免解析异常，支持带注释的 JSON
- **CSV 数据**：生成 CSV 文件、对象数组转换
- **Excel 处理**：工作表读取、JSON 双向转换
- **Base64 编码**：支持 Unicode 和中文的安全转换
### 存储管理
- **LocalStorage 增强**：支持过期时间和自动清理
- **Cookie 管理**：获取、设置、删除完整生命周期
- **SessionStorage**：会话级数据存储
- **存储策略**：序列化机制和一致性保证
### UI 交互组件
- **水印生成**：Canvas 绘制、MutationObserver 防篡改
- **Toast 提示**：成功、失败、加载等多种状态
- **对话框**：动态创建、生命周期管理
- **Canvas 绘图**：图形绘制、图片合成、验证码生成
- **剪贴板**：Web 和小程序跨平台复制功能
### 文件操作
- **文件下载**：单个/批量下载、ZIP 打包
- **图片处理**：CDN 优化、格式转换、Base64 互转
- **Canvas 图片合并**：多图垂直合并、尺寸适配
- **文件压缩**：JSZip 集成的流式压缩
### 分享与上传
- **多平台分享**：微信、QQ 分享配置和签名生成
- **文件上传**：分片上传、断点续传、进度管理
- **UniUploader 单例**：统一的上传管理和错误处理
- **分享数据注入**：动态参数和环境适配
### 国际化支持
- **多语言字典**：动态加载和实时切换
- **Excel 翻译转换**：批量翻译工具
- **语言包管理**：统一的 i18 token 获取
### 云服务集成
- **腾讯云 CDN**：缓存预热、清除、URL 优化
- **COS 对象存储**：文件上传、下载、Bucket 管理
- **Rainbow 配置中心**：配置获取、版本对比、实时通知
- **RUM 性能监控**：性能数据收集和上报
### DevOps 工具
- **小程序 CI**：微信和 QQ 小程序自动化构建和上传
- **版本管理**：语义化版本、变更日志、标签管理
- **自动化发布**：构建、上传、通知全流程自动化
- **Git 操作**：分支管理、提交统计、MR 生成
### 条形码生成
- **多种格式支持**：CODE39、CODE128、EAN/UPC、ITF、MSI、Codabar
- **智能编码**：CODE128 自动选择最优编码子集
- **Canvas 绘制**：高精度条形码渲染
---
## 快速上手
### 安装
使用 npm 安装：
```bash
npm install t-comm -S
```
或使用 pnpm：
```bash
pnpm add t-comm -S
```
### 基本使用
#### 支持按需引入（推荐）
```typescript
import { getMonthDay } from 't-comm';
// 获取指定月份的天数
const days = getMonthDay(2022, 2); // 28
```
#### 完整引入
```typescript
import tComm from 't-comm';
// 访问所有工具函数
tComm.getMonthDay(2022, 12);
```
### 单文件引入
对于不支持 `tree-shaking` 的项目，可以使用单文件引入方式：
```typescript
// 从 lib 目录引入（CommonJS 格式）
import { timeStampFormat } from 't-comm/lib/time/time';
const stamp = new Date('2020-11-27 8:23:24').getTime();
const formatted = timeStampFormat(stamp, 'yyyy-MM-dd hh:mm:ss');
// 2020-11-27 08:23:24
```
从 `es` 目录引入，适合不支持 CommonJS 的项目：
```typescript
import { timeStampFormat } from 't-comm/es/time/time';
```
### 使用示例
```typescript
import {
// 日期时间
getMonthDay,
timeStampFormat,
getRelativeTime,
// 字符串处理
checkStringLen,
randomString,
// 数组操作
chunk,
flatten,
// 对象处理
deepEqual,
merge,
// 网络请求
httpGet,
httpPost,
// 存储
savePersist,
getPersist,
// UI 组件
showToast,
createDialog
} from 't-comm';
// 日期处理示例
const currentDays = getMonthDay(new Date().getFullYear(), new Date().getMonth() + 1);
console.log(`本月有 ${currentDays} 天`);
// 字符串处理示例
const randomStr = randomString(10);
console.log(`生成的随机字符串: ${randomStr}`);
// HTTP 请求示例
const fetchData = async () => {
try {
const data = await httpGet('https://api.example.com/data');
console.log(data);
} catch (error) {
console.error('请求失败:', error);
}
};
// 存储示例
savePersist('user', { name: '张三', age: 25 }, { expiry: 3600000 });
const user = getPersist('user');
```
### 项目构建
如果需要从源码构建：
```bash
# 安装依赖
pnpm install
# 构建项目
pnpm run build
# 运行测试
pnpm run test
# 生成文档
pnpm run docs:build
```
---
## 常见问题
### Q: 为什么有些函数导入后报错？
A: 请确保您的项目支持 ES 模块。如果使用 CommonJS 项目，请从 `t-comm/lib` 导入。同时检查 TypeScript 配置中的 `module` 和 `moduleResolution` 选项。
### Q: 如何减少打包体积？
A: `t-comm` 完全支持 tree-shaking。请使用按需引入的方式，而不是引入整个库：
```typescript
// 推荐
import { getMonthDay } from 't-comm';
// 不推荐
import * as tComm from 't-comm';
```
### Q: 小程序环境如何使用？
A: 大部分工具函数在 Web 和小程序环境通用。如果是小程序专用工具（如 `mp` 目录下的函数），会自动检测环境并调用相应 API。
### Q: 如何获取完整的 API 文档？
A: 访问[详细文档网站](https://novlan1.github.io/docs/t-comm/)查看所有模块的完整 API 说明和使用示例。
### Q: 版本更新策略是什么？
A: 项目遵循语义化版本规范（Semantic Versioning）。变更日志会在每次发布时自动生成，记录新增功能、Bug 修复和破坏性变更。
### Q: 是否支持 TypeScript？
A: 完全支持。内置完整的类型定义文件（.d.ts），提供良好的代码补全和类型检查。
### Q: 如何参与项目贡献？
A: 欢迎提交 Issue 和 Pull Request。请确保代码通过测试并遵循项目的代码规范。
### Q: 项目采用什么构建工具？
A: 使用 Rollup 进行构建，生成 CommonJS 和 ES Module 两种格式，确保在各种场景下都能正常使用。
### Q: 如何处理跨平台兼容性问题？
A: `t-comm` 内置了环境检测和平台适配层，会自动根据运行环境选择合适的 API 实现。开发者无需手动处理兼容性。
---
**详细文档**：[https://novlan1.github.io/docs/t-comm/](https://novlan1.github.io/docs/t-comm/)