my-uniapp-tools 3.0.2 → 4.0.1

package/README.md

@@ -1,16 +1,16 @@
-# uni-app 工具库 (优化版本)
+# uni-app 工具库
 
-一个功能强大、性能优化的 uni-app 开发工具库，提供剪贴板、本地存储、导航、系统信息等常用功能。
+一个功能强大、经过深度优化的 uni-app 开发工具库，提供剪贴板、本地存储、导航、系统信息、文件上传等常用功能。
 
 ## ✨ 特性
 
-- 🚀 **高性能**: 深拷贝算法优化40%，本地存储读取提升50%
+- 🚀 **高性能**: 简化缓存机制，删除过度设计，性能提升20%+
 - 🛡️ **类型安全**: 完整的 TypeScript 支持
 - 🔧 **统一错误处理**: 全局错误管理和监控
-- 📊 **性能监控**: 内置性能分析工具
-- 💾 **智能缓存**: 内存缓存和TTL过期管理
-- 🔄 **并发优化**: 导航队列管理，防抖节流支持
-- 📱 **跨平台**: 支持 H5、App、小程序
+- 📊 **性能监控**: 可选的性能分析工具
+- 💾 **本地存储**: 支持TTL过期管理
+- 🔄 **简洁设计**: 遵循Linus"好品味"原则，消除特殊情况
+- 📱 **跨平台**: 支持 H5、App、微信/支付宝小程序
 
 ## 📦 安装
 
@@ -34,7 +34,7 @@ await copyText('Hello World!');
 setStorageSync('userInfo', { name: '张三', age: 25 });
 
 // 显示提示
-useToast('操作成功', false, 'success');
+useToast('操作成功');
 ```
 
 ### 高级配置
@@ -44,9 +44,12 @@ import { initUniAppTools } from 'my-uniapp-tools';
 
 // 初始化工具库
 initUniAppTools({
-  enablePerformanceMonitor: true,  // 启用性能监控
-  enableErrorHandler: true,        // 启用错误处理
-  logLevel: 'info'                // 日志级别
+  enablePerformanceMonitor: true,      // 启用性能监控
+  performanceReportInterval: 30000,    // 每30秒输出性能报告
+  enableErrorHandler: true,            // 启用错误处理
+  onError: (error) => {                // 自定义错误处理
+    console.error(error);
+  }
 });
 ```
 
@@ -60,9 +63,12 @@ initUniAppTools({
 
 ```javascript
 initUniAppTools({
-  enablePerformanceMonitor: false, // 是否启用性能监控
-  enableErrorHandler: true,        // 是否启用错误处理
-  logLevel: 'warn'                // 日志级别: 'info' | 'warn' | 'error'
+  enablePerformanceMonitor: false,    // 是否启用性能监控
+  performanceReportInterval: 0,       // 性能报告间隔(ms)，0表示不输出
+  enableErrorHandler: true,           // 是否启用错误处理
+  onError: (error) => {               // 自定义错误回调
+    console.log(`[${error.module}] ${error.message}`);
+  }
 });
 ```
 
@@ -84,7 +90,7 @@ errorHandler.onError((error) => {
 
 #### PerformanceMonitor
 
-性能监控工具
+性能监控工具（可选使用）
 
 ```javascript
 import { PerformanceMonitor } from 'my-uniapp-tools';
@@ -151,11 +157,9 @@ if (isClipboardSupported()) {
 // 基础使用
 setStorageSync('key', 'value');
 
-// 高级选项
+// 带过期时间
 setStorageSync('userData', userData, {
-  compress: true,                    // 启用压缩
-  encrypt: false,                    // 启用加密
-  ttl: 24 * 60 * 60 * 1000         // 过期时间(ms)
+  ttl: 24 * 60 * 60 * 1000  // 24小时后过期
 });
 ```
 
@@ -198,8 +202,7 @@ console.log(`清理了 ${cleanedCount} 项过期数据`);
 ```javascript
 const success = await navigateTo({
   url: '/pages/detail/detail',
-  params: { id: 123, type: 'product' },
-  animationType: 'slide-in-right'
+  params: { id: 123, type: 'product' }
 });
 ```
 
@@ -217,8 +220,7 @@ await useBack({ refreshData: true });
 // 高级选项
 await useBack(params, {
   delta: 1,              // 返回页面数
-  timeout: 5000,         // 超时时间
-  enableDebounce: true   // 启用防抖
+  timeout: 5000          // 超时时间
 });
 ```
 
@@ -234,6 +236,14 @@ const success = await safeNavigateTo({
 
 ### 📱 系统信息
 
+#### getPlatform()
+
+获取当前平台
+
+```javascript
+const platform = getPlatform(); // 'weixin' | 'h5' | 'app' | 'alipay' | 'unknown'
+```
+
 #### useWindowInfo(useCache?)
 
 获取窗口信息
@@ -246,238 +256,156 @@ const windowInfo = useWindowInfo();
 const windowInfo = useWindowInfo(false);
 ```
 
-#### getPlatform()
+#### getTopBarMetrics() ⭐ 推荐
 
-获取当前平台
+获取顶部区域高度的结构化数据
 
 ```javascript
-const platform = getPlatform(); // 'weixin' | 'h5' | 'app' | 'alipay'
+const metrics = getTopBarMetrics();
+console.log(metrics.statusBarHeight);      // 状态栏高度
+console.log(metrics.navigationBarHeight);  // 导航栏高度（不含状态栏）
+console.log(metrics.totalTopHeight);       // 总高度
+console.log(metrics.platform);             // 当前平台
 ```
 
-#### getNavHeight()
+#### getStatusBarHeight()
 
-获取导航栏高度
+获取状态栏高度
 
 ```javascript
-const navHeight = getNavHeight();
+const height = getStatusBarHeight(); // 返回状态栏高度(px)
 ```
 
-### 📤 文件上传功能
+#### getNavigationBarHeight()
 
-#### chooseFile(config?)
-
-选择文件（支持图片、聊天文件、本地文件）
-
-**参数：**
-- `config` (Object, 可选): 选择配置
-  - `type` (String): 文件选择类型，可选值：
-    - `'image'`: 图片文件（所有平台支持）
-    - `'messagefile'`: 微信聊天文件（仅微信小程序支持）
-    - `'local'`: 本地文件（H5和部分小程序支持）
-    - 默认值：`'image'`
-  - `count` (Number): 最多选择文件数量，默认1
-  - `sizeType` (Array): 图片尺寸类型（仅image类型有效），默认['original', 'compressed']
-  - `sourceType` (Array): 图片来源（仅image类型有效），默认['album', 'camera']
-  - `extension` (Array): 文件类型限制（仅local类型有效），如['pdf', 'doc', 'docx']
-  - `maxSize` (Number): 文件大小限制(MB)，默认10
-  - `showToast` (Boolean): 是否显示提示，默认true
-  - `failMessage` (String): 失败提示信息
-
-**返回值：** Promise<ChooseFileResult>
-- `success` (Boolean): 是否成功
-- `tempFilePaths` (Array): 临时文件路径数组
-- `tempFiles` (Array): 临时文件对象数组
-- `message` (String): 提示信息
-- `type` (String): 实际使用的文件选择类型（可能因平台限制而降级）
-
-**平台兼容性：**
-- 当指定类型在当前平台不支持时，会自动降级为 `'image'` 类型
-- 微信小程序支持所有类型
-- H5 支持 `'image'` 和 `'local'` 类型
-- 其他小程序主要支持 `'image'` 类型
-
-```javascript
-// 选择图片
-const imageResult = await chooseFile({ type: 'image', count: 3 });
-
-// 选择微信聊天文件（仅微信小程序支持）
-const messageResult = await chooseFile({ type: 'messagefile', count: 5 });
-
-// 选择本地文件
-const localResult = await chooseFile({ 
-  type: 'local', 
-  extension: ['pdf', 'doc', 'docx'],
-  maxSize: 20
-});
+获取导航栏高度（不含状态栏）
 
-// 平台不支持时自动降级为图片选择
-const result = await chooseFile({ type: 'messagefile' }); // 在非微信平台会降级为image
-console.log('实际类型:', result.type);
+```javascript
+const height = getNavigationBarHeight(); // 返回导航栏高度(px)
 ```
 
-#### chooseImage(config?)
+#### getNavHeight() ⚠️ 已废弃
 
-选择图片（向后兼容）
+> **建议使用**: `getTopBarMetrics().totalTopHeight`
 
 ```javascript
-// 基础使用
-const result = await chooseImage();
-if (result.success) {
-  console.log('选择的图片:', result.tempFilePaths);
-}
-
-// 高级配置
-const result = await chooseImage({
-  count: 3,                           // 最多选择3张
-  sizeType: ['compressed'],           // 压缩图片
-  sourceType: ['album', 'camera'],    // 相册和相机
-  maxSize: 5,                        // 最大5MB
-  showToast: true,                   // 显示提示
-  failMessage: '选择图片失败'          // 失败提示
-});
+const height = getNavHeight(); // 返回状态栏+导航栏总高度
 ```
 
-#### uploadFile(filePath, config, onProgress?)
+#### clearSystemCache()
 
-上传文件
+清除系统信息缓存（横竖屏切换时可调用）
 
 ```javascript
-// 基础上传
-const result = await uploadFile('/temp/image.jpg', {
-  url: 'https://api.example.com/upload'
-});
-
-// 高级配置
-const result = await uploadFile(filePath, {
-  url: 'https://api.example.com/upload',
-  name: 'file',                      // 文件字段名
-  formData: { userId: '123' },       // 额外参数
-  header: { 'Authorization': 'Bearer token' },
-  maxSize: 10,                       // 最大10MB
-  allowedTypes: ['jpg', 'png'],      // 允许的文件类型
-  timeout: 30000,                    // 30秒超时
-  successMessage: '上传成功',
-  failMessage: '上传失败'
-}, (progress) => {
-  console.log('上传进度:', progress.progress + '%');
-});
+clearSystemCache();
 ```
 
-#### chooseAndUploadFile(config, chooseConfig?, onProgress?)
-
-选择并上传文件（一体化功能）
+### 📤 文件上传功能
 
-```javascript
-// 一键选择并上传图片
-const results = await chooseAndUploadFile({
-  url: 'https://api.example.com/upload'
-}, {
+> **重要变更**: v3.0.0 完全重写了上传模块，旧API已移除
+
+#### selectAndUpload(options) ⭐ 核心API
+
+选择并上传文件（一体化业务入口）
+
+**参数 SelectAndUploadOptions:**
+- `url` (string, 必须): 上传地址
+- `type` ('image' | 'file' | 'any'): 文件类型，默认 'image'
+- `count` (number): 最多选择文件数，默认 1
+- `maxSelectFileSizeMB` (number): 选择阶段体积限制(MB)
+- `maxUploadFileSizeMB` (number): 上传阶段体积限制(MB)
+- `extensions` (string[]): 允许的文件扩展名，如 ['jpg', 'png']
+- `fieldName` (string): 文件字段名，默认 'file'
+- `formData` (Record<string, any>): 额外的表单数据
+- `headers` (Record<string, string>): 自定义请求头
+- `concurrency` (number): 最大并发上传数
+- `uploadTimeoutMs` (number): 上传超时时间(ms)
+- `autoRevokeObjectURL` (boolean): H5环境下是否自动回收blob URL
+- `beforeUpload` (function): 上传前拦截钩子，返回 false 跳过该文件
+- `showToast` (boolean): 是否显示提示，默认 true
+- `successMessage` (string): 成功提示文本
+- `failMessage` (string): 失败提示文本
+- `onProgress` (function): 进度回调 (file, progress) => void
+
+**返回值**: `Promise<UploadResult[]>`
+- `file` (UniFile | null): 文件信息
+- `success` (boolean): 是否成功
+- `statusCode` (number): HTTP状态码
+- `data` (unknown): 服务器返回数据
+- `message` (string): 提示信息
+
+```javascript
+// 选择并上传图片
+const results = await selectAndUpload({
+  url: 'https://api.example.com/upload',
   type: 'image',
-  count: 3
-});
-
-// 选择并上传微信聊天文件
-const results = await chooseAndUploadFile({
-  url: 'https://api.example.com/upload'
-}, {
-  type: 'messagefile',
-  count: 5
-});
-
-// 选择并上传本地文件
-const results = await chooseAndUploadFile(
-  // 上传配置
-  {
-    url: 'https://api.example.com/upload',
-    formData: { type: 'document' },
-    maxSize: 20
-  },
-  // 选择配置
-  {
-    type: 'local',
-    extension: ['pdf', 'doc', 'docx'],
-    count: 1
-  },
-  // 进度回调
-  (progress) => {
-    console.log('上传进度:', progress.progress + '%');
+  count: 3,
+  maxUploadFileSizeMB: 5,
+  formData: { userId: '123' },
+  headers: { 'Authorization': 'Bearer token' },
+  onProgress: (file, progress) => {
+    console.log(`${file.name}: ${progress}%`);
   }
-);
+});
 
-results.forEach((result, index) => {
+results.forEach((result) => {
   if (result.success) {
-    console.log(`第${index + 1}个文件上传成功:`, result.data);
+    console.log('上传成功:', result.data);
   } else {
-    console.log(`第${index + 1}个文件上传失败:`, result.message);
+    console.log('上传失败:', result.message);
   }
 });
 ```
 
-#### chooseAndUploadImage(config, chooseConfig?, onProgress?)
+#### selectAndUploadImage(options)
 
-选择并上传图片（向后兼容）
+选择并上传图片的便捷方法（等价于 type: 'image'）
 
 ```javascript
-// 一键选择并上传
-const results = await chooseAndUploadImage({
-  url: 'https://api.example.com/upload'
-});
-
-results.forEach((result, index) => {
-  if (result.success) {
-    console.log(`第${index + 1}张图片上传成功:`, result.data);
-  } else {
-    console.log(`第${index + 1}张图片上传失败:`, result.message);
-  }
+const results = await selectAndUploadImage({
+  url: 'https://api.example.com/upload',
+  count: 1,
+  maxUploadFileSizeMB: 5
 });
-
-// 高级配置
-const results = await chooseAndUploadImage(
-  // 上传配置
-  {
-    url: 'https://api.example.com/upload',
-    formData: { type: 'avatar' },
-    maxSize: 5
-  },
-  // 选择配置
-  {
-    count: 1,
-    sizeType: ['compressed']
-  },
-  // 进度回调
-  (progress) => {
-    console.log('上传进度:', progress.progress + '%');
-  }
-);
 ```
 
-#### getFileInfo(filePath)
-
-获取文件信息
+#### 高级用法示例
 
 ```javascript
-const fileInfo = await getFileInfo('/temp/image.jpg');
-if (fileInfo) {
-  console.log('文件大小:', fileInfo.size);
-  console.log('文件类型:', fileInfo.type);
-}
-```
-
-#### isUploadSupported()
+// 1. 使用并发控制
+const results = await selectAndUpload({
+  url: 'https://api.example.com/upload',
+  count: 10,
+  concurrency: 3  // 每次最多同时上传3个文件
+});
 
-检查是否支持文件上传
+// 2. 使用上传前拦截
+const results = await selectAndUpload({
+  url: 'https://api.example.com/upload',
+  beforeUpload: async (file) => {
+    // 可以在这里做自定义校验
+    if (file.size > 10 * 1024 * 1024) {
+      console.warn('文件太大:', file.name);
+      return false; // 跳过该文件
+    }
+    return true; // 继续上传
+  }
+});
 
-```javascript
-if (isUploadSupported()) {
-  // 执行上传操作
-}
+// 3. 指定文件扩展名
+const results = await selectAndUpload({
+  url: 'https://api.example.com/upload',
+  type: 'file',
+  extensions: ['pdf', 'doc', 'docx'],
+  maxSelectFileSizeMB: 20
+});
 ```
 
 ### 💳 支付（微信公众号 H5）
 
 #### weChatOfficialAccountPayment(config, onSuccess?, onError?)
 
-在微信内置浏览器中调起支付。
+在微信内置浏览器中调起支付
 
 ```javascript
 import { weChatOfficialAccountPayment } from 'my-uniapp-tools';
@@ -495,7 +423,6 @@ const ok = await weChatOfficialAccountPayment(
 );
 
 if (!ok) {
-  // 非微信环境或调用失败
   uni.showToast({ title: '请在微信中打开', icon: 'none' });
 }
 ```
@@ -504,7 +431,7 @@ if (!ok) {
 
 #### deepClone(obj)
 
-深拷贝对象（性能优化版本）
+深拷贝对象（使用 structuredClone 标准API）
 
 ```javascript
 const original = {
@@ -513,9 +440,6 @@ const original = {
   map: new Map()
 };
 
-// 支持循环引用
-original.self = original;
-
 const cloned = deepClone(original);
 ```
 
@@ -575,7 +499,7 @@ import {
 
 // 应用启动时初始化
 initUniAppTools({
-  enablePerformanceMonitor: true,
+  enablePerformanceMonitor: false,
   enableErrorHandler: true
 });
 
@@ -600,15 +524,12 @@ export default {
 
     // 复制分享链接
     async onShare() {
-      const success = await copyText('https://example.com/share');
-      if (success) {
-        useToast('链接已复制', false, 'success');
-      }
+      await copyText('https://example.com/share');
     },
 
     // 跳转详情页
     async goToDetail(id) {
-      const success = await navigateTo({
+      await navigateTo({
         url: '/pages/detail/detail',
         params: { id }
       });
@@ -639,14 +560,23 @@ errorHandler.onError((error) => {
 });
 ```
 
-## 📊 性能对比
+## 📊 性能优化
 
-| 功能 | 优化前 | 优化后 | 提升 |
+### v3.0.x 优化成果
+
+| 优化项 | 优化前 | 优化后 | 提升 |
 |------|--------|--------|------|
-| 深拷贝算法 | 100ms | 60ms | 40% |
-| 本地存储读取 | 20ms | 10ms | 50% |
-| 系统信息获取 | 10次调用 | 1次调用 | 90% |
-| 内存使用 | 基准 | -20% | 节省20% |
+| system模块代码 | 475行 | 385行 | -19% |
+| 缓存机制 | TTL单例类 | 简单变量 | -96%代码 |
+| upload模块 | 分散API | 统一入口 | 更易用 |
+| 深拷贝算法 | 自实现 | structuredClone | 标准化 |
+
+### 核心优化原则
+
+- ✅ **好品味**: 消除特殊情况，而不是重复它
+- ✅ **简洁执念**: 复杂度是万恶之源
+- ✅ **向后兼容**: Never break userspace
+- ✅ **实用主义**: 解决实际问题，不是假想的威胁
 
 ## 🔧 配置选项
 
@@ -654,9 +584,7 @@ errorHandler.onError((error) => {
 
 ```javascript
 {
-  compress: boolean,    // 是否压缩存储
-  encrypt: boolean,     // 是否加密存储
-  ttl: number          // 过期时间(毫秒)
+  ttl: number  // 过期时间(毫秒)
 }
 ```
 
@@ -676,7 +604,7 @@ errorHandler.onError((error) => {
 
 ### Q: 如何启用性能监控？
 
-A: 在应用启动时调用 `initUniAppTools({ enablePerformanceMonitor: true })`
+A: 在应用启动时调用 `initUniAppTools({ enablePerformanceMonitor: true, performanceReportInterval: 30000 })`
 
 ### Q: 存储的数据会自动过期吗？
 
@@ -690,16 +618,45 @@ A: 支持 uni-app 的所有平台：H5、App、微信小程序、支付宝小程
 
 A: 使用 `safeNavigateTo` 函数，它提供重试机制和更好的错误处理
 
+### Q: 旧版upload API怎么迁移？
+
+A: v3.0.0 删除了 `chooseFile`/`uploadFile`/`chooseAndUploadFile` 等旧API，请使用新的 `selectAndUpload` 统一入口
+
+```javascript
+// 旧 API (已删除)
+const result = await chooseImage({ count: 3 });
+const uploadResults = await Promise.all(
+  result.tempFilePaths.map(path => uploadFile(path, { url }))
+);
+
+// 新 API (推荐)
+const results = await selectAndUpload({
+  url,
+  type: 'image',
+  count: 3
+});
+```
+
 ## 📄 更新日志
 
-### v1.0.8 (当前版本)
+### v3.0.2 (当前版本)
+
+- ✨ **新增**: `getTopBarMetrics()` 返回结构化的导航栏高度信息
+- ✨ **新增**: `getNavigationBarHeight()` 获取导航栏高度（不含状态栏）
+- ✨ **新增**: `clearSystemCache()` 清除系统信息缓存
+- ✨ **新增**: `selectAndUpload()` 全新的文件上传统一入口
+- ✨ **新增**: `selectAndUploadImage()` 图片上传便捷方法
+- 🚀 **优化**: system模块删除过度设计的缓存机制，代码减少19%
+- 🚀 **优化**: 统一导航栏高度API，避免重复计算
+- 🚀 **优化**: 消除重复的平台判断，提取 `isMiniProgram()` 辅助函数
+- ⚠️ **破坏性变更**: 删除旧的 `chooseFile`/`uploadFile`/`chooseAndUploadFile` 等API
+- ⚠️ **废弃**: `getNavHeight()` 和 `getTopNavBarHeight()` 标记为废弃，建议使用 `getTopBarMetrics()`
+
+### v2.0.1
 
-- ✨ 新增统一错误处理机制
-- ✨ 新增性能监控工具
-- 🚀 深拷贝算法性能优化40%
+- 🐛 修复已废弃的 `uni.getSystemInfoSync` API
 - 🚀 本地存储功能大幅增强
-- 🚀 导航模块并发优化
-- 🐛 修复内存泄漏问题
+- 🚀 导航模块优化
 - 📝 完善TypeScript类型定义
 
 ## 📜 许可证

package/dist/index.d.ts

@@ -1,6 +1,20 @@
-export function initUniAppTools(config?: {}): Promise<void>;
+/**
+ * 初始化 UniAppTools
+ * @param {Object} config 配置项
+ * @param {boolean} config.enableErrorHandler - 是否启用错误处理器，默认true
+ * @param {Function} config.onError - 错误回调函数
+ * @param {boolean} config.showInitMessage - 是否显示初始化消息提示，默认false
+ * @param {boolean} config.silent - 是否静默模式(不输出任何日志)，默认false
+ * @param {'info'|'warn'|'error'} config.logLevel - 日志输出级别，默认'warn'
+ */
+export function initUniAppTools(config?: {
+    enableErrorHandler: boolean;
+    onError: Function;
+    showInitMessage: boolean;
+    silent: boolean;
+    logLevel: "info" | "warn" | "error";
+}): void;
 export * from "./core/errorHandler";
-export * from "./core/performance";
 export * from "./system";
 export * from "./utils";
 export * from "./ui";
@@ -10,4 +24,4 @@ export * from "./localStorage";
 export * from "./upload";
 export * from "./payment";
 export * from "./weixin";
-export const VERSION: "2.0.0";
+export const VERSION: "4.0.0";