mstf-kit

English | 简体中文

一个现代化的 JavaScript/TypeScript 工具库，提供了丰富的常用工具函数。

✨ 特性

📦 支持 Tree Shaking
🔧 TypeScript 支持
📚 完整的类型定义
🎯 模块化设计
💪 全面的测试覆盖
📝 详细的文档
🔒 代码混淆保护

📦 安装

npm install mstf-kit
# 或
yarn add mstf-kit
# 或
pnpm add mstf-kit

🚀 使用方法

// 导入所需的工具函数
import { formatDate, isEmail } from 'mstf-kit';

// 使用日期格式化
const date = formatDate(new Date(), 'YYYY-MM-DD');
console.log(date); // 2024-03-10

// 验证邮箱
const isValidEmail = isEmail('example@email.com');
console.log(isValidEmail); // true

按需导入

为了减小打包体积，推荐使用 tree-shaking 按需导入具体的工具函数：

// 只导入需要的函数
import { capitalize, truncate } from 'mstf-kit';
import { formatDate } from 'mstf-kit';
import { createLottiePlayer } from 'mstf-kit';

// 不要这样导入整个库
// import * as mstfKit from 'mstf-kit'; // ❌ 不推荐

现代打包工具（如 webpack、rollup、vite）会自动进行 tree-shaking，只打包您实际使用的代码。

📚 API 文档

🔤 字符串工具 (String Utils)

字符串处理相关的工具函数。

capitalize(str: string): string - 首字母大写
camelCase(str: string): string - 转换为驼峰命名
truncate(str: string, length: number): string - 截断字符串

🔢 数字工具 (Number Utils)

数字处理和计算相关的工具函数。

formatNumber(num: number, locale?: string): string - 数字格式化
round(num: number, decimals?: number): number - 四舍五入
clamp(num: number, min: number, max: number): number - 限制数字范围
random(min: number, max: number, isInteger?: boolean): number - 生成随机数
percentage(value: number, total: number, decimals?: number): number - 计算百分比

📋 数组工具 (Array Utils)

数组操作和处理的工具函数。

unique<T>(arr: T[]): T[] - 数组去重
groupBy<T>(arr: T[], key: string | ((item: T) => string)): Record<string, T[]> - 数组分组
flatten<T>(arr: any[], depth?: number): T[] - 数组扁平化
sample<T>(arr: T[], count?: number): T | T[] - 随机采样
shuffle<T>(arr: T[]): T[] - 数组乱序
closest(arr: number[], target: number): number - 查找最接近的值

📦 对象工具 (Object Utils)

对象操作和处理的工具函数。

deepClone<T>(obj: T): T - 深拷贝
get(obj: any, path: string | string[], defaultValue?: any): any - 获取嵌套属性
set(obj: any, path: string | string[], value: any): void - 设置嵌套属性
pick<T, K extends keyof T>(obj: T, keys: K[]): Pick<T, K> - 选择属性
omit<T, K extends keyof T>(obj: T, keys: K[]): Omit<T, K> - 排除属性
merge<T>(...objects: T[]): T - 对象合并

📅 日期工具 (Date Utils)

日期和时间处理的工具函数。

formatDate(date: Date | number | string, format?: string): string - 日期格式化
getRelativeTime(date: Date | number | string, now?: Date): string - 相对时间
getDateRange(start: Date | number | string, end: Date | number | string): Date[] - 日期范围
addTime(date: Date | number | string, amount: number, unit: string): Date - 添加时间
isSameDay(date1: Date | number | string, date2: Date | number | string): boolean - 判断同一天

✅ 验证工具 (Validation Utils)

数据验证相关的工具函数。

isEmail(email: string): boolean - 验证邮箱
isChinesePhone(phone: string): boolean - 验证手机号（中国大陆）
isChineseIdCard(idCard: string): boolean - 验证身份证号（中国大陆）
isUrl(url: string): boolean - 验证URL
isIPv4(ip: string): boolean - 验证IPv4地址
validatePassword(password: string, options?: object): boolean - 验证密码强度
isSafeString(str: string): boolean - 验证XSS安全

🎵 音频处理 (Audio)

音频流处理 (audioStream)

音频流处理工具，用于处理音频数据流，支持ArrayBuffer和流式数据，并提供自动播放功能。

import { 
  createAudioStreamHandler, 
  handleAudioBuffer, 
  createAudioHandlers 
} from 'mstf-kit';

// 示例1: 处理ArrayBuffer响应
const response = await axios.post('/api/voice/synthesize', {
  voice_id: 'my-voice',
  text: '你好，世界！'
}, {
  responseType: 'arraybuffer',
  headers: { Accept: 'audio/mp3' }
});

// 方式1: 直接处理
const { blob, url, handler } = await handleAudioBuffer(response, {
  mimeType: 'audio/mp3',
  autoPlay: true,
  logLevel: 'debug'
});

// 示例2: 处理流式数据
// 创建处理器
const audioHandler = createAudioStreamHandler({
  mimeType: 'audio/mp3',
  logLevel: 'debug'
});

// 示例3: 最简单的方式 (一步到位)
const { config, handler } = createAudioHandlers(
  {
    responseType: 'arraybuffer',
    headers: { Accept: 'audio/mp3' }
  },
  {
    mimeType: 'audio/mp3',
    autoPlayOnComplete: true,
    logLevel: 'debug'
  }
);

// 使用增强的配置发送请求
const response = await axios.post('/api/voice/synthesize', data, config);

停止/中止处理

支持通过AbortController中止处理过程：

// 创建AbortController
const controller = new AbortController();
const signal = controller.signal;

// 方法1: 通过配置传入
const { config, handler } = createAudioHandlers(
  { /* axios配置 */ },
  { 
    abortSignal: signal,
    // 其他选项...
  }
);

// 方法2: 直接设置
audioHandler.setAbortSignal(signal);

// 方法3: 直接调用abort方法
audioHandler.abort();

// 在需要中止时：
controller.abort(); // 这将触发中止处理

控制播放

// 暂停播放
handler.pause();

// 恢复播放
handler.resume();

// 停止播放
handler.stop();

// 设置音量 (0-1)
handler.setVolume(0.5);

// 释放资源
handler.release();

配置选项

AudioStreamOptions 支持以下选项：

{
  // 日志级别: 'none' | 'error' | 'warn' | 'info' | 'debug'
  logLevel?: LogLevel;
  
  // 是否自动播放
  autoPlay?: boolean;
  
  // 自定义的MIME类型
  mimeType?: string;
  
  // 是否循环播放
  loop?: boolean;
  
  // 初始音量 (0-1)
  volume?: number;
  
  // 播放完成回调
  onEnded?: () => void;
  
  // 播放错误回调
  onError?: (error: Error) => void;
  
  // 播放开始回调
  onPlay?: () => void;
  
  // 播放进度回调
  onProgress?: (currentTime: number, duration: number) => void;
  
  // 数据加载回调
  onDataLoaded?: (blob: Blob) => void;
  
  // 处理被中止回调
  onAborted?: () => void;
}

DownloadProgressConfig 支持以下选项：

{
  // 是否需要解析处理
  needParse?: boolean;
  
  // 音频数据路径，如 "audio.b"
  audioPath?: string;
  
  // MIME类型
  mimeType?: string;
  
  // 是否在接收到第一块数据时自动播放
  autoPlayOnFirstChunk?: boolean;
  
  // 是否在下载完成时自动播放
  autoPlayOnComplete?: boolean;
  
  // 用于停止处理的AbortSignal
  abortSignal?: AbortSignal;
}

🔊 音频播放器

mstf-kit 提供了功能强大的音频播放工具，支持背景播放和页面渲染两种模式：

背景播放模式

import { createAudioPlayer, playAudio } from 'mstf-kit';

// 简易播放方式
const audioBlob = new Blob([...]); // 音频数据
const player = await playAudio(audioBlob, {
  volume: 0.8,
  loop: true
});

// 或使用完整API
const backgroundPlayer = createAudioPlayer();
await backgroundPlayer.load('https://example.com/audio.mp3');
await backgroundPlayer.play();

// 控制播放
backgroundPlayer.pause();
backgroundPlayer.setVolume(0.5);
backgroundPlayer.seek(30); // 跳转到30秒位置

页面渲染模式

import { createAudioPlayer, AUDIO_FORMATS } from 'mstf-kit';

// 创建一个带UI界面的播放器
const uiPlayer = createAudioPlayer({
  renderUI: true,           // 启用UI渲染
  container: '#player-box', // 指定容器元素
  theme: 'dark',            // 使用暗色主题
  showVisualization: true,  // 显示音频可视化
  visualizationType: 'bars' // 使用柱状频谱图
});

// 加载音频
await uiPlayer.load(audioBlob);
await uiPlayer.play();

// 播放结束后的回调
uiPlayer.onEnded = () => {
  console.log('播放完成');
};

// 不需要时释放资源
uiPlayer.destroy();

Vue 集成

与 Vue3 框架无缝集成，支持直接使用 ref 作为容器：

import { ref, onMounted, onUnmounted } from 'vue';
import { createAudioPlayer } from 'mstf-kit';

export default {
  setup() {
    // 创建容器引用
    const playerContainer = ref(null);
    let audioPlayer = null;
    
    onMounted(async () => {
      // 创建播放器并使用ref作为容器
      audioPlayer = createAudioPlayer({
        renderUI: true,
        container: playerContainer, // 直接传入ref
        theme: 'dark',
        showVisualization: true
      });
      
      // 加载并播放音频
      await audioPlayer.load('/audio/example.mp3');
      await audioPlayer.play();
    });
    
    // 组件卸载时清理资源
    onUnmounted(() => {
      if (audioPlayer) {
        audioPlayer.destroy();
      }
    });
    
    return { playerContainer };
  }
}

可视化类型

播放器支持三种可视化类型：

waveform: 波形图显示
bars: 频谱柱状图
circle: 圆形频谱图

支持的主题

default: 默认主题（浅色）
dark: 暗色主题
minimal: 简约主题（透明背景）

🎭 Lottie动画

mstf-kit 支持 Lottie 动画的加载、渲染和控制，可以轻松地在您的应用中展示高质量的矢量动画。

基本使用

import { createLottiePlayer, playLottie } from 'mstf-kit';

// 快速加载并播放Lottie动画
const player = await playLottie(
  'https://assets.lottiefiles.com/packages/lf20_UJNc2t.json',
  '#animation-container',
  { loop: true, speed: 1.5 }
);

// 或使用完整API
const lottiePlayer = await createLottiePlayer({
  container: '#animation-container',
  renderer: 'canvas', // dotlottie-web 使用 canvas 渲染
  loop: true,
  autoplay: true
});

// 加载动画
await lottiePlayer.load('https://assets.lottiefiles.com/packages/lf20_UJNc2t.json');

// 控制动画
lottiePlayer.pause();
lottiePlayer.setSpeed(2.0);
lottiePlayer.play();

Vue 集成

与 Vue3 框架无缝集成，支持直接使用 ref 作为容器：

import { ref } from 'vue';
import { playLottie } from 'mstf-kit';

export default {
  setup() {
    // 创建容器引用
    const animationContainer = ref(null);
    
    // 加载动画（在onMounted中）
    onMounted(async () => {
      const player = await playLottie(
        'https://assets.lottiefiles.com/packages/lf20_UJNc2t.json',
        animationContainer,
        { loop: true }
      );
    });
    
    return { animationContainer };
  }
}

多种库加载模式

支持多种加载方式：

// 默认使用内置的 dotlottie-web
const player1 = await createLottiePlayer({
  container: '#animation-container',
  loop: true
});

// 使用自定义外部库
import customLottieLib from 'custom-lottie-lib';
const player2 = await createLottiePlayer({
  container: '#animation-container',
  libOptions: {
    source: 'external',
    externalLib: customLottieLib
  }
});

// 从CDN加载
const player3 = await createLottiePlayer({
  container: '#animation-container',
  libOptions: {
    source: 'cdn',
    cdnURL: 'https://cdn.jsdelivr.net/npm/@lottiefiles/dotlottie-web/+esm'
  }
});

渲染模式

Lottie播放器默认使用Canvas渲染模式，提供高性能的动画播放体验。

动画控制

播放器支持丰富的控制方法：

// 播放控制
player.play();
player.pause();
player.stop();

// 播放速度和方向
player.setSpeed(1.5);  // 1.5倍速
player.setDirection(-1); // 反向播放

// 跳转控制
player.goToFrame(24);  // 跳转到第24帧
player.goToAndPlay(24); // 跳转并播放
player.setSegment(10, 50); // 只播放10-50帧

// 循环控制
player.setLoop(true);  // 无限循环
player.setLoop(3);     // 循环3次

// 动画信息
console.log(`总帧数: ${player.getTotalFrames()}`);
console.log(`当前帧: ${player.getCurrentFrame()}`);
console.log(`时长: ${player.getDuration()}ms`);
console.log(`是否播放中: ${player.isPlaying()}`);

// 资源释放
player.destroy();

高级特性

小巧高效: 使用 dotlottie-web 库，体积更小，性能更好
多种库来源: 支持内置库（默认）、CDN加载或外部提供的自定义库
Vue框架支持: 无缝支持Vue3的ref作为容器引用
多种来源: 支持从URL、JSON字符串或对象加载动画
动画事件: 提供丰富的回调函数，可监听动画状态变化
响应式: 通过resize()方法支持自适应容器大小

🔌 WebSocket 工具 (WebSocket Utils)

提供高效可靠的 WebSocket 连接管理和通信工具。

createWebSocketClient(options: WebSocketOptions): WebSocketClient - 创建一个 WebSocket 客户端
isWebSocketSupported(): boolean - 检查当前环境是否支持 WebSocket

WebSocket 客户端 API

WebSocket 客户端 (WebSocketClient) 提供以下核心功能：

自动重连 - 网络中断时自动尝试重新连接
心跳检测 - 保持连接活跃并检测断线
消息队列 - 离线时自动缓存消息，连接恢复后发送
消息优先级 - 支持高、中、低三种优先级消息处理
事件系统 - 提供丰富的事件监听接口
批量发送 - 支持消息批处理以优化网络传输
超时处理 - 自动处理消息超时和重试
完整指标 - 提供详细的连接和性能统计数据

基本使用示例

import { WebSocketClient, WebSocketState, MessagePriority } from 'mstf-kit';

// 创建 WebSocket 客户端
const ws = new WebSocketClient({
  url: 'wss://example.com/socket',
  protocols: ['v1'],
  debug: true,               // 启用调试日志
  connectionTimeout: 8000,   // 连接超时 (ms)
  
  // 心跳配置
  heartbeat: {
    enabled: true,
    interval: 30000,         // 每30秒发送一次心跳
    message: { type: 'ping' },
    timeout: 5000            // 心跳5秒无响应判定为超时
  },
  
  // 自动重连配置
  reconnect: {
    enabled: true,
    maxRetries: 10,          // 最多重试10次
    initialDelay: 1000,      // 初始重试延迟1秒
    maxDelay: 30000,         // 最大重试延迟30秒
    factor: 1.5,             // 指数退避系数
    jitter: 0.5              // 随机抖动系数
  }
});

// 连接到服务器
ws.connect()
  .then(() => {
    console.log('连接成功');
    
    // 发送消息
    return ws.send({ type: 'hello', data: 'world' });
  })
  .catch(error => {
    console.error('连接错误:', error);
  });

// 监听消息
ws.on('message', data => {
  console.log('收到消息:', data);
});

// 监听连接状态变化
ws.on('close', event => {
  console.log('连接关闭:', event.code);
});

ws.on('reconnect', attempt => {
  console.log(`重连成功 (第${attempt}次尝试)`);
});

// 发送不同优先级的消息
ws.send(criticalData, { priority: MessagePriority.HIGH });
ws.send(normalData, { priority: MessagePriority.NORMAL });
ws.send(statsData, { priority: MessagePriority.LOW });

// 期望服务器响应的消息
ws.send({ type: 'query', id: 'user-123' }, {
  expectResponse: true,      // 等待响应
  timeout: 5000,             // 响应超时时间
  retries: 2,                // 超时后重试次数
  retryDelay: 1000           // 重试间隔
}).then(response => {
  console.log('收到响应:', response);
}).catch(error => {
  console.error('请求失败:', error);
});

// 获取连接状态和统计信息
console.log('当前状态:', ws.getState());
console.log('连接延迟:', ws.getLatency());
console.log('统计信息:', ws.getConnectionStats());

// 不再使用时销毁资源
ws.destroy();

高级特性

批量消息: 适用于需要发送大量小消息的场景，自动合并为批量消息减少网络开销
动态配置: 可在运行时调整心跳、重连、消息处理等配置
完整生命周期管理: 自动处理资源释放，防止内存泄漏
兼容性: 支持各种浏览器环境和 Node.js

更多高级用法详见 API 文档。

mstf-kit

mstf-kit

✨ 特性

📦 安装

🚀 使用方法

按需导入

📚 API 文档

🔤 字符串工具 (String Utils)

🔢 数字工具 (Number Utils)

📋 数组工具 (Array Utils)

📦 对象工具 (Object Utils)

📅 日期工具 (Date Utils)

✅ 验证工具 (Validation Utils)

🎵 音频处理 (Audio)

音频流处理 (audioStream)

停止/中止处理

控制播放

配置选项

🔊 音频播放器

背景播放模式

页面渲染模式

Vue 集成

可视化类型

支持的主题

🎭 Lottie动画

基本使用

Vue 集成

多种库加载模式

渲染模式

动画控制

高级特性

🔌 WebSocket 工具 (WebSocket Utils)

WebSocket 客户端 API

基本使用示例

高级特性

📄 许可证

Readme

Keywords

Package Sidebar

Install

Repository

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads