my-uniapp-tools 1.0.0 → 1.0.2

package/README.md

@@ -1,4 +1,4 @@
-# Huang UniApp Toolkit
+# My UniApp Tools
 
 一个专为 UniApp 开发设计的实用工具函数库，提供常用的功能模块，帮助开发者快速构建跨平台应用。
 
@@ -6,20 +6,20 @@
 
 ```bash
 # 使用 npm
-npm install huang-uniapp-toolkit
+npm install my-uniapp-tools
 
 # 使用 yarn
-yarn add huang-uniapp-toolkit
+yarn add my-uniapp-tools
 
 # 使用 pnpm
-pnpm add huang-uniapp-toolkit
+pnpm add my-uniapp-tools
 ```
 
 ## 🚀 快速开始
 
 ```javascript
 // 导入所有工具函数
-import * from 'huang-uniapp-toolkit'
+import * as Tools from 'my-uniapp-tools'
 
 // 或者按需导入
 import { 
@@ -28,13 +28,15 @@ import {
   copyText, 
   setStorageSync, 
   getStorageSync, 
+  clearStorageSync,
+  useWindowInfo,
   getPlatform, 
   getCurrentEnv, 
   onCheckForUpdate,
   getStatusBarHeight,
   getNavHeight,
-  getAppConfig
-} from 'huang-uniapp-toolkit'
+  getTopNavBarHeight
+} from 'my-uniapp-tools'
 ```
 
 ## 📚 API 文档
@@ -65,6 +67,8 @@ useToast(
 )
 ```
 
+### 🧭 导航工具 (Navigation)
+
 #### `useBack(params)`
 
 返回上一页并支持传递参数给上一页的 init 方法
@@ -83,6 +87,8 @@ useBack({ refresh: true, data: 'some data' })
 
 **注意：** 上一页需要暴露 `init` 方法来接收参数
 
+### 📋 剪贴板工具 (Clipboard)
+
 #### `copyText(text)`
 
 跨平台文本复制功能，支持 H5、App、小程序。H5 平台优先使用现代的 Clipboard API，失败时回退到传统方法。
@@ -95,12 +101,14 @@ useBack({ refresh: true, data: 'some data' })
 copyText('要复制的文本内容')
 ```
 
+### 🖥️ 系统信息工具 (System)
+
 #### `useWindowInfo()`
 
 获取当前窗口的尺寸、像素比等信息
 
 **返回值:**
-- 窗口信息对象
+- 窗口信息对象，包含窗口尺寸、像素比等信息
 
 **示例:**
 ```javascript
@@ -240,7 +248,7 @@ const customNavStyle = {
 }
 ```
 
-#### `getAppConfig()`
+#### `getTopNavBarHeight()`
 
 一次性获取应用所需的状态栏和导航栏高度配置信息
 
@@ -251,14 +259,14 @@ const customNavStyle = {
 
 **示例:**
 ```javascript
-const appConfig = getAppConfig()
-console.log(appConfig.statusBarHeight) // 状态栏高度
-console.log(appConfig.navHeight)       // 导航栏总高度
+const topNavConfig = getTopNavBarHeight()
+console.log(topNavConfig.statusBarHeight) // 状态栏高度
+console.log(topNavConfig.navHeight)       // 导航栏总高度
 
 // 用于全局配置
 const globalConfig = {
-  ...appConfig,
-  contentHeight: windowHeight - appConfig.navHeight
+  ...topNavConfig,
+  contentHeight: windowHeight - topNavConfig.navHeight
 }
 ```
 
@@ -351,6 +359,11 @@ npm install
 yarn dev
 # 或
 npm run dev
+
+# 运行测试
+yarn test
+# 或
+npm test
 ```
 
 ## 🏗️ 技术栈
@@ -362,7 +375,9 @@ npm run dev
 ## 📁 项目结构
 
 ```
-huang-uniapp-toolkit/
+my-uniapp-tools/
+├── .augment/           # 增强配置目录
+│   └── rules/
 ├── src/
 │   ├── ui/              # UI交互工具函数
 │   │   └── index.ts
@@ -375,14 +390,17 @@ huang-uniapp-toolkit/
 │   ├── localStorage/    # 本地存储工具
 │   │   └── index.ts
 │   └── index.js        # 主入口文件
+├── .gitignore          # Git 忽略配置
 ├── package.json        # 项目配置
 ├── tsconfig.json       # TypeScript 配置
-└── README.md          # 项目说明
+├── yarn.lock           # Yarn 依赖锁定文件
+├── README.md           # 项目说明
+└── RECORD.md           # 项目记录
 ```
 
 ## 🔄 版本信息
 
-当前版本：v1.0.5
+当前版本：v1.0.0
 
 ## 📄 许可证
 
@@ -402,55 +420,26 @@ ISC
 
 ## 📝 更新日志
 
-### v1.0.6
-- ✨ **新增功能**：添加状态栏和导航栏高度获取函数
-- 📏 新增 `getStatusBarHeight()` 函数，用于获取设备状态栏高度
-- 📐 新增 `getNavHeight()` 函数，用于获取小程序导航栏总高度
-- ⚙️ 新增 `getAppConfig()` 函数，一次性获取状态栏和导航栏配置信息
-- 🛡️ 添加完善的错误处理机制，确保在获取失败时返回默认值
-- 📚 更新API文档，添加详细的使用说明和界面适配示例
-- 💡 遵循单一职责原则，每个函数专注于特定的高度获取功能
-- 🎯 主要用于小程序平台的界面适配和自定义导航栏开发
-
-### v1.0.5
-- ✨ **新增功能**：完善 `onCheckForUpdate()` 函数
-- 📱 实现小程序版本更新检查功能，支持自动检查、下载和提示更新
-- 🔄 支持静默下载新版本，用户可选择立即重启或稍后更新
-- 🛡️ 添加完善的错误处理机制，包括下载失败和异常情况处理
-- 📚 更新API文档，添加详细的平台支持说明和使用示例
-- 💡 遵循单一职责原则，提供用户友好的更新体验
-- 🎯 支持微信、支付宝、百度、抖音、QQ、快手、京东等主流小程序平台
-
-### v1.0.4
-- ✨ **新增功能**：完善 `getCurrentEnv()` 函数
-- 📱 新增小程序账户信息获取功能，支持获取appId、版本号、环境版本等信息
-- 🛡️ 添加错误处理机制，确保函数调用的稳定性
-- 📚 更新API文档，添加详细的使用说明和示例
-- 💡 遵循单一职责原则，提供清晰的返回值结构
-
-### v1.0.3
-- 🏗️ **重大重构**：按功能类型重新组织代码结构
-- 📁 将原 `common` 模块拆分为 5 个专门模块：
+### v1.0.0
+- 🎯 **初始版本发布**
+- 🏗️ **模块化架构**：按功能类型组织代码结构
+- 📁 **五大核心模块**：
   - `ui` - UI交互工具（useToast）
   - `navigation` - 导航工具（useBack）
   - `clipboard` - 剪贴板工具（copyText）
-  - `system` - 系统信息工具（useWindowInfo, getPlatform, getCurrentEnv）
-  - `localStorage` - 本地存储工具（保持不变）
-- 📚 更新文档结构，按模块分类展示API
-- 💡 遵循单一职责原则，提高代码可维护性
-- 🔧 完善函数注释，便于后续维护
-
-### v1.0.2
-- 🎉 完善项目文档
-- 🔧 优化代码注释
-- 🛡️ 添加错误处理机制
-- ✨ 新增 `getPlatform()` 函数，用于获取当前运行平台
-- 🚀 优化 `copyText()` 函数，H5 平台优先使用现代 Clipboard API
-
-### v1.0.1
-- 🎯 初始版本发布
-- 📦 基础工具函数实现
-- 💾 本地存储工具实现
+  - `system` - 系统信息工具（useWindowInfo, getPlatform, getCurrentEnv, onCheckForUpdate, getStatusBarHeight, getNavHeight, getTopNavBarHeight）
+  - `localStorage` - 本地存储工具（setStorageSync, getStorageSync, clearStorageSync）
+- ✨ **核心功能**：
+  - 📱 跨平台消息提示和导航返回
+  - 📋 跨平台剪贴板操作
+  - 🖥️ 系统信息获取和平台检测
+  - 🔄 小程序版本更新检查
+  - 📏 状态栏和导航栏高度适配
+  - 💾 本地存储数据管理
+- 🛡️ **完善的错误处理机制**，确保函数调用的稳定性
+- 💡 **遵循单一职责原则**，每个函数专注于特定功能
+- 📚 **详细的API文档**，包含使用说明和示例代码
+- 🎯 **支持主流平台**：微信、支付宝、百度、抖音、QQ、快手、京东等小程序平台以及H5、App
 
 ---
 

package/examples/payment-example.js

@@ -0,0 +1,179 @@
+/**
+ * 支付功能使用示例
+ */
+
+import { usePayment } from '../src/utils/index.ts';
+
+/**
+ * 微信支付示例 (App端)
+ */
+export const wechatPayExample = async () => {
+  try {
+    const result = await usePayment('wxpay', {
+      // App端微信支付必需参数
+      appid: 'your_app_id',
+      partnerid: 'your_partner_id',
+      prepayid: 'your_prepay_id',
+      package: 'Sign=WXPay',
+      noncestr: 'random_string_' + Date.now(),
+      timestamp: Math.floor(Date.now() / 1000).toString(),
+      sign: 'your_calculated_sign'
+    });
+
+    if (result.success) {
+      console.log('微信支付成功！');
+      console.log('订单号:', result.orderInfo.orderId);
+      console.log('支付时间:', new Date(result.timestamp));
+
+      // 支付成功后的业务逻辑
+      handlePaymentSuccess(result);
+    } else {
+      console.error('微信支付失败:', result.error);
+
+      // 支付失败后的业务逻辑
+      handlePaymentFail(result);
+    }
+  } catch (error) {
+    console.error('支付过程中发生错误:', error);
+  }
+};
+
+/**
+ * 支付宝支付示例 (小程序 - String类型)
+ */
+export const alipayMiniProgramExample = async () => {
+  try {
+    // 支付宝小程序支付，orderInfo 为 String 类型的交易号
+    const result = await usePayment('alipay', 'your_trade_no_from_server');
+
+    if (result.success) {
+      console.log('支付宝小程序支付成功！');
+      handlePaymentSuccess(result);
+    } else {
+      console.error('支付宝小程序支付失败:', result.error);
+      handlePaymentFail(result);
+    }
+  } catch (error) {
+    console.error('支付过程中发生错误:', error);
+  }
+};
+
+/**
+ * 支付宝支付示例 (App端 - String类型)
+ */
+export const alipayAppExample = async () => {
+  try {
+    // App端支付宝支付，orderInfo 为 String 类型的订单字符串
+    const result = await usePayment('alipay', 'your_complete_order_string_from_server');
+
+    if (result.success) {
+      console.log('支付宝App支付成功！');
+      handlePaymentSuccess(result);
+    } else {
+      console.error('支付宝App支付失败:', result.error);
+      handlePaymentFail(result);
+    }
+  } catch (error) {
+    console.error('支付过程中发生错误:', error);
+  }
+};
+
+
+
+/**
+ * 支付成功处理函数
+ */
+const handlePaymentSuccess = (result) => {
+  console.log('处理支付成功逻辑...');
+
+  // 1. 更新本地状态
+  // 2. 发送支付成功通知到服务器
+  // 3. 更新用户界面
+  // 4. 跳转到成功页面
+
+  // 示例：显示成功提示
+  uni.showToast({
+    title: '支付成功',
+    icon: 'success',
+    duration: 2000
+  });
+
+  // 示例：跳转到成功页面
+  setTimeout(() => {
+    uni.navigateTo({
+      url: '/pages/payment/success?orderId=' + result.orderInfo.orderId
+    });
+  }, 2000);
+};
+
+/**
+ * 支付失败处理函数
+ */
+const handlePaymentFail = (result) => {
+  console.log('处理支付失败逻辑...');
+
+  // 1. 记录失败日志
+  // 2. 显示错误提示
+  // 3. 提供重试选项
+
+  let errorMessage = '支付失败，请重试';
+
+  // 根据错误类型显示不同提示
+  if (result.error && result.error.errMsg) {
+    if (result.error.errMsg.includes('cancel')) {
+      errorMessage = '支付已取消';
+    } else if (result.error.errMsg.includes('fail')) {
+      errorMessage = '支付失败，请检查网络或稍后重试';
+    }
+  }
+
+  uni.showModal({
+    title: '支付提示',
+    content: errorMessage,
+    showCancel: true,
+    cancelText: '取消',
+    confirmText: '重试',
+    success: (res) => {
+      if (res.confirm) {
+        // 用户选择重试，重新发起支付
+        console.log('用户选择重试支付');
+        // 这里可以重新调用对应的支付函数
+      }
+    }
+  });
+};
+
+/**
+ * 批量支付示例（多个商品）
+ */
+export const batchPaymentExample = async () => {
+  const orders = [
+    { orderId: 'order_001', amount: 1000, description: '商品1' },
+    { orderId: 'order_002', amount: 2000, description: '商品2' },
+    { orderId: 'order_003', amount: 3000, description: '商品3' }
+  ];
+
+  // 计算总金额
+  const totalAmount = orders.reduce((sum, order) => sum + order.amount, 0);
+
+  try {
+    const result = await usePayment('wxpay', {
+      orderId: 'batch_order_' + Date.now(),
+      amount: totalAmount,
+      description: `批量购买${orders.length}个商品`,
+      orderList: orders // 附加订单列表信息
+    });
+
+    if (result.success) {
+      console.log('批量支付成功！');
+      console.log('总金额:', totalAmount / 100, '元');
+      console.log('商品数量:', orders.length);
+      handlePaymentSuccess(result);
+    } else {
+      console.error('批量支付失败:', result.error);
+      handlePaymentFail(result);
+    }
+  } catch (error) {
+    console.error('批量支付过程中发生错误:', error);
+  }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "my-uniapp-tools",
-    "version": "1.0.0",
+    "version": "1.0.2",
     "main": "src/index.js",
     "type": "module",
     "scripts": {

package/src/clipboard/index.ts

@@ -10,7 +10,8 @@ import { useToast } from '../ui';
  * @description 支持 H5、App、小程序。H5 平台优先使用现代的 Clipboard API，失败时回退到传统方法
  */
 export function copyText(text: string) {
-  // #ifndef H5 条件编译：非 H5 平台（如 App、小程序）执行此代码块
+  // #ifndef H5
+  // 条件编译：非 H5 平台（如 App、小程序）执行此代码块
   uni.setClipboardData({
     data: text, // 要复制的文本内容
     success: function () {
@@ -21,7 +22,8 @@ export function copyText(text: string) {
     },
   });
   // #endif
-  // #ifdef H5 条件编译：仅 H5 平台执行此代码块
+  // #ifdef H5
+  // 条件编译：仅 H5 平台执行此代码块
   // 优先使用现代的 Clipboard API
   if (navigator.clipboard && window.isSecureContext) {
     navigator.clipboard.writeText(text).then(() => {

package/src/index.js

@@ -12,3 +12,9 @@ export * from './system'
 
 // 本地存储相关
 export * from './localStorage'
+
+// 支付相关
+export * from './utils/payment'
+
+// 其他工具函数
+export * from './utils'

package/src/system/index.ts

@@ -141,24 +141,55 @@ export const getStatusBarHeight = () => {
   }
 }
 
+/**
+ * 获取菜单按钮边界信息
+ * @returns 菜单按钮边界信息对象或null
+ * @description 获取小程序右上角菜单按钮的边界信息，仅在小程序平台有效
+ */
+export const getMenuButtonBoundingClientRect = () => {
+  try {
+    const platform = getPlatform();
+    
+    // 只有在小程序平台才执行getMenuButtonBoundingClientRect
+    if (platform === 'weixin' || platform === 'alipay') {
+      return uni.getMenuButtonBoundingClientRect();
+    }
+    
+    // 非小程序平台返回null
+    return null;
+  } catch (error) {
+    console.error('获取菜单按钮边界信息失败:', error);
+    return null;
+  }
+}
+
 /**
  * 获取导航栏高度
  * @returns 导航栏高度（单位：px）
- * @description 获取小程序导航栏的总高度，包含状态栏高度和菜单按钮高度
+ * @description 获取导航栏的总高度，根据不同平台采用不同的计算方式
  */
 export const getNavHeight = () => {
   try {
     // 获取状态栏高度
     const statusBarHeight = getStatusBarHeight();
-
-    // 获取菜单按钮的边界信息
-    const menuButtonInfo = uni.getMenuButtonBoundingClientRect();
-
-    // 计算导航栏总高度：状态栏高度 + 菜单按钮高度
-    const navHeight = menuButtonInfo.height + statusBarHeight;
-    console.log("🚀 ~ 导航栏高度:", navHeight);
-
-    return navHeight;
+    const platform = getPlatform();
+    
+    // 小程序平台：状态栏高度 + 菜单按钮高度
+    if (platform === 'weixin' || platform === 'alipay') {
+      const menuButtonInfo = getMenuButtonBoundingClientRect();
+      if (menuButtonInfo) {
+        const navHeight = menuButtonInfo.height + statusBarHeight;
+        console.log("🚀 ~ 小程序导航栏高度:", navHeight);
+        return navHeight;
+      }
+    }
+    
+    // App和H5平台：使用默认导航栏高度
+    const defaultNavHeight = 44; // 默认导航栏高度
+    const totalHeight = statusBarHeight + defaultNavHeight;
+    console.log(`🚀 ~ ${platform}平台导航栏高度:`, totalHeight);
+    
+    return totalHeight;
   } catch (error) {
     console.error('获取导航栏高度失败:', error);
     // 返回默认高度（状态栏高度 + 44px 默认导航栏高度）

package/src/utils/index.ts

@@ -0,0 +1 @@
+export * from './payment/index'

package/src/utils/payment/index.ts

@@ -0,0 +1,153 @@
+/**
+ * 支付相关工具函数
+ */
+
+/**
+ * 支付提供商类型
+ */
+export type PaymentProvider = 'wxpay' | 'alipay';
+
+/**
+ * 支付订单信息类型
+ * @description 根据不同支付方式，orderInfo 的类型和结构会有所不同：
+ * - 支付宝小程序：String 类型，表示支付宝交易号(tradeNO)
+ * - App端支付宝：String 类型，完整的订单字符串
+ * - App端微信：Object 类型，包含微信支付必需参数
+ */
+export type PaymentOrderInfo = string | {
+  /** 微信支付参数 (App端) */
+  appid?: string;
+  partnerid?: string;
+  prepayid?: string;
+  package?: string;
+  noncestr?: string;
+  timestamp?: string;
+  sign?: string;
+
+  /** 其他通用参数 */
+  [key: string]: any;
+};
+
+/**
+ * 支付结果接口
+ */
+export interface PaymentResult {
+  /** 支付是否成功 */
+  success: boolean;
+  /** 支付提供商 */
+  provider: PaymentProvider;
+  /** 订单信息 */
+  orderInfo: PaymentOrderInfo;
+  /** 支付时间戳 */
+  timestamp: number;
+  /** 错误信息（支付失败时） */
+  error?: any;
+}
+
+/**
+ * 统一支付接口
+ * @param provider 支付提供商，默认为 'wxpay'
+ * @param orderInfo 订单信息对象
+ * @returns Promise<PaymentResult> 支付结果
+ * @description 封装 uni.requestPayment，提供统一的支付接口，支持多种支付方式
+ * @example
+ * ```typescript
+ * // 微信支付 (App端)
+ * const wxResult = await usePayment('wxpay', {
+ *   appid: 'your_app_id',
+ *   partnerid: 'your_partner_id',
+ *   prepayid: 'your_prepay_id',
+ *   package: 'Sign=WXPay',
+ *   noncestr: 'random_string',
+ *   timestamp: '1234567890',
+ *   sign: 'your_sign'
+ * });
+ *
+ * // 支付宝支付 (小程序 - String类型)
+ * const alipayResult = await usePayment('alipay', 'your_trade_no_string');
+ *
+ * // 支付宝支付 (App端 - String类型)
+ * const alipayAppResult = await usePayment('alipay', 'your_order_string');
+ *
+ * // 检查支付结果
+ * if (wxResult.success) {
+ *   console.log('支付成功');
+ * } else {
+ *   console.error('支付失败:', wxResult.error);
+ * }
+ * ```
+ */
+export const usePayment = (
+  provider: PaymentProvider = 'wxpay',
+  orderInfo: PaymentOrderInfo = {}
+): Promise<PaymentResult> => {
+  return new Promise<PaymentResult>((resolve, reject) => {
+    // 参数验证
+    if (!provider) {
+      const error = new Error('支付提供商不能为空');
+      reject(error);
+      return;
+    }
+
+    // 根据不同平台验证 orderInfo 类型
+    if (orderInfo === null || orderInfo === undefined) {
+      const error = new Error('订单信息不能为空');
+      reject(error);
+      return;
+    }
+
+    // 支付宝小程序和App端支付宝需要 String 类型
+    if ((provider === 'alipay') && typeof orderInfo !== 'string' && typeof orderInfo !== 'object') {
+      const error = new Error('支付宝支付的订单信息格式不正确');
+      reject(error);
+      return;
+    }
+
+    // 其他平台需要 Object 类型
+    if (provider !== 'alipay' && typeof orderInfo !== 'object') {
+      const error = new Error('订单信息必须是一个对象');
+      reject(error);
+      return;
+    }
+
+    // 记录支付开始时间
+    const timestamp = Date.now();
+
+    // 调用 uni.requestPayment 进行支付
+    uni.requestPayment({
+      provider,
+      orderInfo,
+      success: () => {
+        // 支付成功，返回成功结果
+        const result: PaymentResult = {
+          success: true,
+          provider,
+          orderInfo,
+          timestamp,
+        };
+        resolve(result);
+      },
+      fail: (err) => {
+        // 支付失败，返回失败结果
+        const result: PaymentResult = {
+          success: false,
+          provider,
+          orderInfo,
+          timestamp,
+          error: err,
+        };
+
+        // 根据错误类型进行不同处理
+        if (err.errMsg && err.errMsg.includes('cancel')) {
+          console.log('用户取消支付');
+        } else {
+          console.error('支付失败:', err);
+        }
+
+        // 这里选择 resolve 而不是 reject，让调用者通过 result.success 判断支付结果
+        // 这样可以避免未捕获的 Promise 异常
+        resolve(result);
+      },
+    });
+  });
+};

package/RECORD.md

@@ -1,34 +0,0 @@
-# 项目记录 (RECORD.md)
-
-## 项目简介
-
-本项目名为 `my-uniapp-tool`，是一个基于 Node.js 的工具库，旨在为 UniApp 开发提供便利。根据 `package.json`，当前版本为 `1.0.2`，使用 ES Module 规范。
-
-## 核心框架/技术
-
-- **主要语言**: TypeScript (从 `tsconfig.json` 和 `.ts` 文件扩展名推断)
-- **运行环境**: Node.js (从 `package.json` 的 `scripts` 和 `main` 指向 `.js` 文件推断)
-- **核心依赖**:
-  - `@dcloudio/types`: 提供 DCloud UniApp 相关的类型定义，表明项目与 UniApp 生态紧密相关。
-
-## 目录结构
-
-```
-.
-├── .gitignore         # Git 忽略配置文件
-├── package.json       # 项目元数据和依赖管理
-├── tsconfig.json      # TypeScript 编译配置文件
-├── yarn.lock          # Yarn 依赖版本锁定文件
-├── src/               # 源代码目录
-│   ├── index.js       # 项目入口文件 (可能是编译后的 JS)
-│   ├── common/        # 通用工具或模块目录
-│   │   └── index.ts   # 通用模块入口文件
-│   └── localStorage/  # 本地存储相关模块目录
-│       └── index.ts   # 本地存储模块入口文件
-└── RECORD.md          # 本项目记录文件 (即本文档)
-```
-
-- **根目录**: 包含项目的基本配置文件和元数据。
-- **`src` 目录**: 存放项目的主要源代码。
-  - `common`: 包含项目中可复用的通用函数、常量或类型定义。
-  - `localStorage`: 封装了与浏览器或小程序本地存储相关的操作。