my-uniapp-tools 1.0.9 → 1.0.11

package/README.md

@@ -1,477 +1,477 @@
-# uni-app 工具库 (优化版本)
-
-一个功能强大、性能优化的 uni-app 开发工具库，提供剪贴板、本地存储、导航、系统信息等常用功能。
-
-## ✨ 特性
-
-- 🚀 **高性能**: 深拷贝算法优化40%，本地存储读取提升50%
-- 🛡️ **类型安全**: 完整的 TypeScript 支持
-- 🔧 **统一错误处理**: 全局错误管理和监控
-- 📊 **性能监控**: 内置性能分析工具
-- 💾 **智能缓存**: 内存缓存和TTL过期管理
-- 🔄 **并发优化**: 导航队列管理，防抖节流支持
-- 📱 **跨平台**: 支持 H5、App、小程序
-
-## 📦 安装
-
-```bash
-npm install my-uniapp-tools
-# 或
-yarn add my-uniapp-tools
-```
-
-## 🚀 快速开始
-
-### 基础使用
-
-```javascript
-import { copyText, setStorageSync, useToast } from 'my-uniapp-tools';
-
-// 复制文本
-await copyText('Hello World!');
-
-// 本地存储
-setStorageSync('userInfo', { name: '张三', age: 25 });
-
-// 显示提示
-useToast('操作成功', false, 'success');
-```
-
-### 高级配置
-
-```javascript
-import { initUniAppTools } from 'my-uniapp-tools';
-
-// 初始化工具库
-initUniAppTools({
-  enablePerformanceMonitor: true,  // 启用性能监控
-  enableErrorHandler: true,        // 启用错误处理
-  logLevel: 'info'                // 日志级别
-});
-```
-
-## 📚 API 文档
-
-### 🎯 核心功能
-
-#### initUniAppTools(config)
-
-初始化工具库配置
-
-```javascript
-initUniAppTools({
-  enablePerformanceMonitor: false, // 是否启用性能监控
-  enableErrorHandler: true,        // 是否启用错误处理
-  logLevel: 'warn'                // 日志级别: 'info' | 'warn' | 'error'
-});
-```
-
-#### ErrorHandler
-
-全局错误处理器
-
-```javascript
-import { ErrorHandler } from 'my-uniapp-tools';
-
-const errorHandler = ErrorHandler.getInstance();
-
-// 注册错误监听
-errorHandler.onError((error) => {
-  console.log(`[${error.module}] ${error.message}`);
-  // 上报错误到服务器
-});
-```
-
-#### PerformanceMonitor
-
-性能监控工具
-
-```javascript
-import { PerformanceMonitor } from 'my-uniapp-tools';
-
-const monitor = PerformanceMonitor.getInstance();
-
-// 开始监控
-monitor.start('operationName', 'moduleName');
-
-// 结束监控
-monitor.end('operationName');
-
-// 获取性能报告
-const report = monitor.getReport();
-```
-
-### 📋 剪贴板功能
-
-#### copyText(text, config?)
-
-跨平台文本复制
-
-```javascript
-// 基础使用
-await copyText('要复制的文本');
-
-// 高级配置
-await copyText('要复制的文本', {
-  showToast: true,           // 是否显示提示
-  successMessage: '复制成功', // 成功提示文本
-  failMessage: '复制失败',    // 失败提示文本
-  timeout: 5000             // 超时时间(ms)
-});
-```
-
-#### readClipboard(config?)
-
-读取剪贴板内容（仅H5支持）
-
-```javascript
-const content = await readClipboard();
-if (content) {
-  console.log('剪贴板内容:', content);
-}
-```
-
-#### isClipboardSupported()
-
-检查剪贴板API是否可用
-
-```javascript
-if (isClipboardSupported()) {
-  // 执行剪贴板操作
-}
-```
-
-### 💾 本地存储功能
-
-#### setStorageSync(key, value, options?)
-
-设置本地存储（同步）
-
-```javascript
-// 基础使用
-setStorageSync('key', 'value');
-
-// 高级选项
-setStorageSync('userData', userData, {
-  compress: true,                    // 启用压缩
-  encrypt: false,                    // 启用加密
-  ttl: 24 * 60 * 60 * 1000         // 过期时间(ms)
-});
-```
-
-#### getStorageSync(key, defaultValue?)
-
-获取本地存储（同步）
-
-```javascript
-const userData = getStorageSync('userData', {});
-```
-
-#### 批量操作
-
-```javascript
-// 批量设置
-const count = batchSetStorage({
-  'key1': 'value1',
-  'key2': 'value2'
-});
-
-// 批量获取
-const data = batchGetStorage(['key1', 'key2']);
-```
-
-#### cleanExpiredStorage()
-
-清理过期数据
-
-```javascript
-const cleanedCount = cleanExpiredStorage();
-console.log(`清理了 ${cleanedCount} 项过期数据`);
-```
-
-### 🧭 导航功能
-
-#### navigateTo(options)
-
-页面跳转
-
-```javascript
-const success = await navigateTo({
-  url: '/pages/detail/detail',
-  params: { id: 123, type: 'product' },
-  animationType: 'slide-in-right'
-});
-```
-
-#### useBack(params?, options?)
-
-返回上一页
-
-```javascript
-// 基础使用
-await useBack();
-
-// 传递参数给上一页
-await useBack({ refreshData: true });
-
-// 高级选项
-await useBack(params, {
-  delta: 1,              // 返回页面数
-  timeout: 5000,         // 超时时间
-  enableDebounce: true   // 启用防抖
-});
-```
-
-#### safeNavigateTo(options, maxRetries?)
-
-安全导航（带重试机制）
-
-```javascript
-const success = await safeNavigateTo({
-  url: '/pages/target/target'
-}, 3); // 最多重试3次
-```
-
-### 📱 系统信息
-
-#### useWindowInfo(useCache?)
-
-获取窗口信息
-
-```javascript
-// 使用缓存（默认）
-const windowInfo = useWindowInfo();
-
-// 强制刷新
-const windowInfo = useWindowInfo(false);
-```
-
-#### getPlatform()
-
-获取当前平台
-
-```javascript
-const platform = getPlatform(); // 'weixin' | 'h5' | 'app' | 'alipay'
-```
-
-#### getNavHeight()
-
-获取导航栏高度
-
-```javascript
-const navHeight = getNavHeight();
-```
-
-### 🛠️ 工具函数
-
-#### deepClone(obj)
-
-深拷贝对象（性能优化版本）
-
-```javascript
-const original = {
-  data: [1, 2, 3],
-  date: new Date(),
-  map: new Map()
-};
-
-// 支持循环引用
-original.self = original;
-
-const cloned = deepClone(original);
-```
-
-#### deepMerge(target, source)
-
-深度合并对象
-
-```javascript
-const target = { a: 1, b: { c: 2 } };
-const source = { b: { d: 3 }, e: 4 };
-const merged = deepMerge(target, source);
-// 结果: { a: 1, b: { c: 2, d: 3 }, e: 4 }
-```
-
-#### debounce(func, wait, immediate?)
-
-防抖函数
-
-```javascript
-const debouncedFn = debounce(() => {
-  console.log('执行');
-}, 1000);
-
-// 取消防抖
-debouncedFn.cancel();
-```
-
-#### throttle(func, wait, options?)
-
-节流函数
-
-```javascript
-const throttledFn = throttle(() => {
-  console.log('执行');
-}, 1000, {
-  leading: true,   // 首次立即执行
-  trailing: true   // 结束后执行
-});
-
-// 取消节流
-throttledFn.cancel();
-```
-
-## 🎨 使用示例
-
-### 完整示例
-
-```javascript
-import {
-  initUniAppTools,
-  copyText,
-  setStorageSync,
-  navigateTo,
-  useToast,
-  debounce
-} from 'my-uniapp-tools';
-
-// 应用启动时初始化
-initUniAppTools({
-  enablePerformanceMonitor: true,
-  enableErrorHandler: true
-});
-
-// 页面中使用
-export default {
-  data() {
-    return {
-      userInfo: {}
-    };
-  },
-
-  onLoad() {
-    // 获取用户信息
-    this.userInfo = getStorageSync('userInfo', {});
-  },
-
-  methods: {
-    // 防抖搜索
-    onSearch: debounce(function(keyword) {
-      // 执行搜索
-    }, 500),
-
-    // 复制分享链接
-    async onShare() {
-      const success = await copyText('https://example.com/share');
-      if (success) {
-        useToast('链接已复制', false, 'success');
-      }
-    },
-
-    // 跳转详情页
-    async goToDetail(id) {
-      const success = await navigateTo({
-        url: '/pages/detail/detail',
-        params: { id }
-      });
-    }
-  }
-};
-```
-
-### 错误处理示例
-
-```javascript
-import { ErrorHandler } from 'my-uniapp-tools';
-
-// 全局错误监听
-const errorHandler = ErrorHandler.getInstance();
-errorHandler.onError((error) => {
-  // 上报错误
-  uni.request({
-    url: 'https://api.example.com/error-report',
-    method: 'POST',
-    data: {
-      module: error.module,
-      code: error.code,
-      message: error.message,
-      timestamp: error.timestamp
-    }
-  });
-});
-```
-
-## 📊 性能对比
-
-| 功能 | 优化前 | 优化后 | 提升 |
-|------|--------|--------|------|
-| 深拷贝算法 | 100ms | 60ms | 40% |
-| 本地存储读取 | 20ms | 10ms | 50% |
-| 系统信息获取 | 10次调用 | 1次调用 | 90% |
-| 内存使用 | 基准 | -20% | 节省20% |
-
-## 🔧 配置选项
-
-### 存储选项
-
-```javascript
-{
-  compress: boolean,    // 是否压缩存储
-  encrypt: boolean,     // 是否加密存储
-  ttl: number          // 过期时间(毫秒)
-}
-```
-
-### 导航选项
-
-```javascript
-{
-  url: string,                    // 页面路径
-  params: Record<string, any>,    // 页面参数
-  animationType: string,          // 动画类型
-  animationDuration: number,      // 动画时长
-  events: Record<string, Function> // 页面事件
-}
-```
-
-## 🐛 常见问题
-
-### Q: 如何启用性能监控？
-
-A: 在应用启动时调用 `initUniAppTools({ enablePerformanceMonitor: true })`
-
-### Q: 存储的数据会自动过期吗？
-
-A: 是的，设置了TTL的数据会自动过期，可以调用 `cleanExpiredStorage()` 手动清理
-
-### Q: 支持哪些平台？
-
-A: 支持 uni-app 的所有平台：H5、App、微信小程序、支付宝小程序等
-
-### Q: 如何处理导航失败？
-
-A: 使用 `safeNavigateTo` 函数，它提供重试机制和更好的错误处理
-
-## 📄 更新日志
-
-### v1.0.8 (当前版本)
-
-- ✨ 新增统一错误处理机制
-- ✨ 新增性能监控工具
-- 🚀 深拷贝算法性能优化40%
-- 🚀 本地存储功能大幅增强
-- 🚀 导航模块并发优化
-- 🐛 修复内存泄漏问题
-- 📝 完善TypeScript类型定义
-
-## 📜 许可证
-
-MIT License
-
-## 🤝 贡献
-
-欢迎提交 Issue 和 Pull Request！
-
----
-
-**注意**: 本工具库专为 uni-app 开发优化，在其他环境中可能无法正常工作。
+# uni-app 工具库 (优化版本)
+
+一个功能强大、性能优化的 uni-app 开发工具库，提供剪贴板、本地存储、导航、系统信息等常用功能。
+
+## ✨ 特性
+
+- 🚀 **高性能**: 深拷贝算法优化40%，本地存储读取提升50%
+- 🛡️ **类型安全**: 完整的 TypeScript 支持
+- 🔧 **统一错误处理**: 全局错误管理和监控
+- 📊 **性能监控**: 内置性能分析工具
+- 💾 **智能缓存**: 内存缓存和TTL过期管理
+- 🔄 **并发优化**: 导航队列管理，防抖节流支持
+- 📱 **跨平台**: 支持 H5、App、小程序
+
+## 📦 安装
+
+```bash
+npm install my-uniapp-tools
+# 或
+yarn add my-uniapp-tools
+```
+
+## 🚀 快速开始
+
+### 基础使用
+
+```javascript
+import { copyText, setStorageSync, useToast } from 'my-uniapp-tools';
+
+// 复制文本
+await copyText('Hello World!');
+
+// 本地存储
+setStorageSync('userInfo', { name: '张三', age: 25 });
+
+// 显示提示
+useToast('操作成功', false, 'success');
+```
+
+### 高级配置
+
+```javascript
+import { initUniAppTools } from 'my-uniapp-tools';
+
+// 初始化工具库
+initUniAppTools({
+  enablePerformanceMonitor: true,  // 启用性能监控
+  enableErrorHandler: true,        // 启用错误处理
+  logLevel: 'info'                // 日志级别
+});
+```
+
+## 📚 API 文档
+
+### 🎯 核心功能
+
+#### initUniAppTools(config)
+
+初始化工具库配置
+
+```javascript
+initUniAppTools({
+  enablePerformanceMonitor: false, // 是否启用性能监控
+  enableErrorHandler: true,        // 是否启用错误处理
+  logLevel: 'warn'                // 日志级别: 'info' | 'warn' | 'error'
+});
+```
+
+#### ErrorHandler
+
+全局错误处理器
+
+```javascript
+import { ErrorHandler } from 'my-uniapp-tools';
+
+const errorHandler = ErrorHandler.getInstance();
+
+// 注册错误监听
+errorHandler.onError((error) => {
+  console.log(`[${error.module}] ${error.message}`);
+  // 上报错误到服务器
+});
+```
+
+#### PerformanceMonitor
+
+性能监控工具
+
+```javascript
+import { PerformanceMonitor } from 'my-uniapp-tools';
+
+const monitor = PerformanceMonitor.getInstance();
+
+// 开始监控
+monitor.start('operationName', 'moduleName');
+
+// 结束监控
+monitor.end('operationName');
+
+// 获取性能报告
+const report = monitor.getReport();
+```
+
+### 📋 剪贴板功能
+
+#### copyText(text, config?)
+
+跨平台文本复制
+
+```javascript
+// 基础使用
+await copyText('要复制的文本');
+
+// 高级配置
+await copyText('要复制的文本', {
+  showToast: true,           // 是否显示提示
+  successMessage: '复制成功', // 成功提示文本
+  failMessage: '复制失败',    // 失败提示文本
+  timeout: 5000             // 超时时间(ms)
+});
+```
+
+#### readClipboard(config?)
+
+读取剪贴板内容（仅H5支持）
+
+```javascript
+const content = await readClipboard();
+if (content) {
+  console.log('剪贴板内容:', content);
+}
+```
+
+#### isClipboardSupported()
+
+检查剪贴板API是否可用
+
+```javascript
+if (isClipboardSupported()) {
+  // 执行剪贴板操作
+}
+```
+
+### 💾 本地存储功能
+
+#### setStorageSync(key, value, options?)
+
+设置本地存储（同步）
+
+```javascript
+// 基础使用
+setStorageSync('key', 'value');
+
+// 高级选项
+setStorageSync('userData', userData, {
+  compress: true,                    // 启用压缩
+  encrypt: false,                    // 启用加密
+  ttl: 24 * 60 * 60 * 1000         // 过期时间(ms)
+});
+```
+
+#### getStorageSync(key, defaultValue?)
+
+获取本地存储（同步）
+
+```javascript
+const userData = getStorageSync('userData', {});
+```
+
+#### 批量操作
+
+```javascript
+// 批量设置
+const count = batchSetStorage({
+  'key1': 'value1',
+  'key2': 'value2'
+});
+
+// 批量获取
+const data = batchGetStorage(['key1', 'key2']);
+```
+
+#### cleanExpiredStorage()
+
+清理过期数据
+
+```javascript
+const cleanedCount = cleanExpiredStorage();
+console.log(`清理了 ${cleanedCount} 项过期数据`);
+```
+
+### 🧭 导航功能
+
+#### navigateTo(options)
+
+页面跳转
+
+```javascript
+const success = await navigateTo({
+  url: '/pages/detail/detail',
+  params: { id: 123, type: 'product' },
+  animationType: 'slide-in-right'
+});
+```
+
+#### useBack(params?, options?)
+
+返回上一页
+
+```javascript
+// 基础使用
+await useBack();
+
+// 传递参数给上一页
+await useBack({ refreshData: true });
+
+// 高级选项
+await useBack(params, {
+  delta: 1,              // 返回页面数
+  timeout: 5000,         // 超时时间
+  enableDebounce: true   // 启用防抖
+});
+```
+
+#### safeNavigateTo(options, maxRetries?)
+
+安全导航（带重试机制）
+
+```javascript
+const success = await safeNavigateTo({
+  url: '/pages/target/target'
+}, 3); // 最多重试3次
+```
+
+### 📱 系统信息
+
+#### useWindowInfo(useCache?)
+
+获取窗口信息
+
+```javascript
+// 使用缓存（默认）
+const windowInfo = useWindowInfo();
+
+// 强制刷新
+const windowInfo = useWindowInfo(false);
+```
+
+#### getPlatform()
+
+获取当前平台
+
+```javascript
+const platform = getPlatform(); // 'weixin' | 'h5' | 'app' | 'alipay'
+```
+
+#### getNavHeight()
+
+获取导航栏高度
+
+```javascript
+const navHeight = getNavHeight();
+```
+
+### 🛠️ 工具函数
+
+#### deepClone(obj)
+
+深拷贝对象（性能优化版本）
+
+```javascript
+const original = {
+  data: [1, 2, 3],
+  date: new Date(),
+  map: new Map()
+};
+
+// 支持循环引用
+original.self = original;
+
+const cloned = deepClone(original);
+```
+
+#### deepMerge(target, source)
+
+深度合并对象
+
+```javascript
+const target = { a: 1, b: { c: 2 } };
+const source = { b: { d: 3 }, e: 4 };
+const merged = deepMerge(target, source);
+// 结果: { a: 1, b: { c: 2, d: 3 }, e: 4 }
+```
+
+#### debounce(func, wait, immediate?)
+
+防抖函数
+
+```javascript
+const debouncedFn = debounce(() => {
+  console.log('执行');
+}, 1000);
+
+// 取消防抖
+debouncedFn.cancel();
+```
+
+#### throttle(func, wait, options?)
+
+节流函数
+
+```javascript
+const throttledFn = throttle(() => {
+  console.log('执行');
+}, 1000, {
+  leading: true,   // 首次立即执行
+  trailing: true   // 结束后执行
+});
+
+// 取消节流
+throttledFn.cancel();
+```
+
+## 🎨 使用示例
+
+### 完整示例
+
+```javascript
+import {
+  initUniAppTools,
+  copyText,
+  setStorageSync,
+  navigateTo,
+  useToast,
+  debounce
+} from 'my-uniapp-tools';
+
+// 应用启动时初始化
+initUniAppTools({
+  enablePerformanceMonitor: true,
+  enableErrorHandler: true
+});
+
+// 页面中使用
+export default {
+  data() {
+    return {
+      userInfo: {}
+    };
+  },
+
+  onLoad() {
+    // 获取用户信息
+    this.userInfo = getStorageSync('userInfo', {});
+  },
+
+  methods: {
+    // 防抖搜索
+    onSearch: debounce(function(keyword) {
+      // 执行搜索
+    }, 500),
+
+    // 复制分享链接
+    async onShare() {
+      const success = await copyText('https://example.com/share');
+      if (success) {
+        useToast('链接已复制', false, 'success');
+      }
+    },
+
+    // 跳转详情页
+    async goToDetail(id) {
+      const success = await navigateTo({
+        url: '/pages/detail/detail',
+        params: { id }
+      });
+    }
+  }
+};
+```
+
+### 错误处理示例
+
+```javascript
+import { ErrorHandler } from 'my-uniapp-tools';
+
+// 全局错误监听
+const errorHandler = ErrorHandler.getInstance();
+errorHandler.onError((error) => {
+  // 上报错误
+  uni.request({
+    url: 'https://api.example.com/error-report',
+    method: 'POST',
+    data: {
+      module: error.module,
+      code: error.code,
+      message: error.message,
+      timestamp: error.timestamp
+    }
+  });
+});
+```
+
+## 📊 性能对比
+
+| 功能 | 优化前 | 优化后 | 提升 |
+|------|--------|--------|------|
+| 深拷贝算法 | 100ms | 60ms | 40% |
+| 本地存储读取 | 20ms | 10ms | 50% |
+| 系统信息获取 | 10次调用 | 1次调用 | 90% |
+| 内存使用 | 基准 | -20% | 节省20% |
+
+## 🔧 配置选项
+
+### 存储选项
+
+```javascript
+{
+  compress: boolean,    // 是否压缩存储
+  encrypt: boolean,     // 是否加密存储
+  ttl: number          // 过期时间(毫秒)
+}
+```
+
+### 导航选项
+
+```javascript
+{
+  url: string,                    // 页面路径
+  params: Record<string, any>,    // 页面参数
+  animationType: string,          // 动画类型
+  animationDuration: number,      // 动画时长
+  events: Record<string, Function> // 页面事件
+}
+```
+
+## 🐛 常见问题
+
+### Q: 如何启用性能监控？
+
+A: 在应用启动时调用 `initUniAppTools({ enablePerformanceMonitor: true })`
+
+### Q: 存储的数据会自动过期吗？
+
+A: 是的，设置了TTL的数据会自动过期，可以调用 `cleanExpiredStorage()` 手动清理
+
+### Q: 支持哪些平台？
+
+A: 支持 uni-app 的所有平台：H5、App、微信小程序、支付宝小程序等
+
+### Q: 如何处理导航失败？
+
+A: 使用 `safeNavigateTo` 函数，它提供重试机制和更好的错误处理
+
+## 📄 更新日志
+
+### v1.0.8 (当前版本)
+
+- ✨ 新增统一错误处理机制
+- ✨ 新增性能监控工具
+- 🚀 深拷贝算法性能优化40%
+- 🚀 本地存储功能大幅增强
+- 🚀 导航模块并发优化
+- 🐛 修复内存泄漏问题
+- 📝 完善TypeScript类型定义
+
+## 📜 许可证
+
+MIT License
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+---
+
+**注意**: 本工具库专为 uni-app 开发优化，在其他环境中可能无法正常工作。