# 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-89.73%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/)
