my-uniapp-tools 1.0.0

package/README.md

@@ -0,0 +1,457 @@
+# Huang UniApp Toolkit
+
+一个专为 UniApp 开发设计的实用工具函数库，提供常用的功能模块，帮助开发者快速构建跨平台应用。
+
+## 📦 安装
+
+```bash
+# 使用 npm
+npm install huang-uniapp-toolkit
+
+# 使用 yarn
+yarn add huang-uniapp-toolkit
+
+# 使用 pnpm
+pnpm add huang-uniapp-toolkit
+```
+
+## 🚀 快速开始
+
+```javascript
+// 导入所有工具函数
+import * from 'huang-uniapp-toolkit'
+
+// 或者按需导入
+import { 
+  useToast, 
+  useBack, 
+  copyText, 
+  setStorageSync, 
+  getStorageSync, 
+  getPlatform, 
+  getCurrentEnv, 
+  onCheckForUpdate,
+  getStatusBarHeight,
+  getNavHeight,
+  getAppConfig
+} from 'huang-uniapp-toolkit'
+```
+
+## 📚 API 文档
+
+### 🎨 UI交互工具 (UI)
+
+#### `useToast(title, mask, icon, duration)`
+
+显示消息提示框
+
+**参数:**
+- `title` (string): 提示的内容，默认为空字符串
+- `mask` (boolean): 是否显示透明蒙层，默认为 `false`
+- `icon` (string): 图标类型，可选值：`'none'` | `'success'` | `'loading'` | `'error'` | `'fail'` | `'exception'`，默认为 `'none'`
+- `duration` (number): 提示的延迟时间，默认为 `2000` 毫秒
+
+**示例:**
+```javascript
+// 基础用法
+useToast('操作成功')
+
+// 完整参数
+useToast(
+  '操作成功',           // 提示文字
+  false,               // 是否显示透明蒙层
+  'success',           // 图标类型
+  2000                 // 显示时长(毫秒)
+)
+```
+
+#### `useBack(params)`
+
+返回上一页并支持传递参数给上一页的 init 方法
+
+**参数:**
+- `params` (any): 传递给上一页 init 方法的参数，默认为空字符串
+
+**示例:**
+```javascript
+// 简单返回
+useBack()
+
+// 返回并传递参数
+useBack({ refresh: true, data: 'some data' })
+```
+
+**注意：** 上一页需要暴露 `init` 方法来接收参数
+
+#### `copyText(text)`
+
+跨平台文本复制功能，支持 H5、App、小程序。H5 平台优先使用现代的 Clipboard API，失败时回退到传统方法。
+
+**参数:**
+- `text` (string): 要复制的文本内容
+
+**示例:**
+```javascript
+copyText('要复制的文本内容')
+```
+
+#### `useWindowInfo()`
+
+获取当前窗口的尺寸、像素比等信息
+
+**返回值:**
+- 窗口信息对象
+
+**示例:**
+```javascript
+const windowInfo = useWindowInfo()
+console.log(windowInfo.windowWidth)  // 窗口宽度
+console.log(windowInfo.windowHeight) // 窗口高度
+```
+
+#### `getPlatform()`
+
+获取当前运行平台类型
+
+**返回值:**
+- `string`: 平台类型，可能的值：`'weixin'` | `'web'` | `'app'` | `'alipay'` | `'h5'`
+
+**示例:**
+```javascript
+const platform = getPlatform()
+console.log(platform) // 'weixin' | 'web' | 'app' | 'alipay' | 'h5'
+
+// 根据平台执行不同逻辑
+if (platform === 'weixin') {
+  // 微信小程序特有逻辑
+} else if (platform === 'h5') {
+  // H5 特有逻辑
+}
+```
+
+#### `getCurrentEnv()`
+
+获取小程序账户信息，包含appId、版本、环境等信息
+
+**返回值:**
+- `object`: 小程序账户信息对象
+  - `appId` (string): 小程序appId
+  - `version` (string): 小程序版本号
+  - `envVersion` (string): 小程序环境版本（develop开发版、trial体验版、release正式版）
+  - `accountInfo` (object): 完整的账户信息对象
+
+**示例:**
+```javascript
+const envInfo = getCurrentEnv()
+console.log(envInfo.appId)      // 小程序appId
+console.log(envInfo.version)    // 小程序版本号
+console.log(envInfo.envVersion) // 环境版本
+
+// 根据环境执行不同逻辑
+if (envInfo.envVersion === 'develop') {
+  // 开发版特有逻辑
+} else if (envInfo.envVersion === 'release') {
+  // 正式版特有逻辑
+}
+```
+
+#### `onCheckForUpdate()`
+
+检查小程序版本更新，自动处理版本检查、下载和更新流程
+
+**参数:**
+- 无参数
+
+**功能说明:**
+- 自动检查小程序是否有新版本
+- 发现新版本时静默下载
+- 下载完成后弹窗提示用户是否重启应用
+- 处理下载失败的情况
+- 支持用户选择稍后更新或立即重启
+
+**平台支持:**
+- ✅ 微信小程序
+- ✅ 支付宝小程序
+- ✅ 百度小程序
+- ✅ 抖音小程序
+- ✅ QQ小程序
+- ✅ 快手小程序
+- ✅ 京东小程序
+- ❌ App (App端请使用其他更新方案)
+- ❌ H5 (H5端无需此功能)
+
+**示例:**
+```javascript
+// 在App.vue中使用
+export default {
+  onLaunch() {
+    // 应用启动时检查更新
+    onCheckForUpdate()
+  },
+  onShow() {
+    // 每次从后台切换到前台时检查更新
+    onCheckForUpdate()
+  }
+}
+
+// 或在页面中手动调用
+onCheckForUpdate()
+```
+
+**注意事项:**
+- 建议在App.vue的onLaunch或onShow生命周期中调用
+- 开发版和体验版无法检查版本更新，需要在正式版中测试
+- 在开发者工具中可以通过"模拟更新编译"来测试更新功能
+- 函数内部已处理异常情况，不会影响应用正常运行
+
+#### `getStatusBarHeight()`
+
+获取设备状态栏高度
+
+**返回值:**
+- `number`: 状态栏高度（单位：px）
+
+**示例:**
+```javascript
+const statusBarHeight = getStatusBarHeight()
+console.log(statusBarHeight) // 44 (iPhone) 或其他设备的状态栏高度
+
+// 用于页面布局适配
+const pageStyle = {
+  paddingTop: statusBarHeight + 'px'
+}
+```
+
+#### `getNavHeight()`
+
+获取小程序导航栏总高度，包含状态栏高度和菜单按钮高度
+
+**返回值:**
+- `number`: 导航栏总高度（单位：px）
+
+**示例:**
+```javascript
+const navHeight = getNavHeight()
+console.log(navHeight) // 88 (iPhone) 或其他设备的导航栏总高度
+
+// 用于自定义导航栏高度设置
+const customNavStyle = {
+  height: navHeight + 'px'
+}
+```
+
+#### `getAppConfig()`
+
+一次性获取应用所需的状态栏和导航栏高度配置信息
+
+**返回值:**
+- `object`: 配置信息对象
+  - `statusBarHeight` (number): 状态栏高度（单位：px）
+  - `navHeight` (number): 导航栏总高度（单位：px）
+
+**示例:**
+```javascript
+const appConfig = getAppConfig()
+console.log(appConfig.statusBarHeight) // 状态栏高度
+console.log(appConfig.navHeight)       // 导航栏总高度
+
+// 用于全局配置
+const globalConfig = {
+  ...appConfig,
+  contentHeight: windowHeight - appConfig.navHeight
+}
+```
+
+**注意事项:**
+- 这些函数主要用于小程序平台的界面适配
+- 在不同设备上返回的高度值可能不同
+- 建议在应用启动时获取并存储这些配置信息
+- 如果获取失败，会返回默认值确保应用正常运行
+
+
+
+### 💾 本地存储工具 (Storage)
+
+#### `setStorageSync(key, obj)`
+
+同步设置本地缓存，自动处理对象序列化
+
+**参数:**
+- `key` (string): 缓存键
+- `obj` (unknown): 要缓存的值，可以是任何类型
+
+**示例:**
+```javascript
+// 存储字符串
+setStorageSync('username', 'john')
+
+// 存储对象（自动序列化）
+setStorageSync('userInfo', { name: 'john', age: 25 })
+
+// 存储数组
+setStorageSync('list', [1, 2, 3, 4, 5])
+
+// 存储布尔值
+setStorageSync('isLogin', true)
+```
+
+#### `getStorageSync(key)`
+
+同步获取本地缓存，自动处理对象反序列化
+
+**参数:**
+- `key` (string): 缓存键
+
+**返回值:**
+- 缓存的值。如果存储的是 JSON 字符串，则返回解析后的对象；否则返回原始值
+
+**示例:**
+```javascript
+// 获取字符串
+const username = getStorageSync('username')
+
+// 获取对象（自动反序列化）
+const userInfo = getStorageSync('userInfo')
+
+// 获取数组
+const list = getStorageSync('list')
+
+// 获取布尔值
+const isLogin = getStorageSync('isLogin')
+```
+
+#### `clearStorageSync(key?)`
+
+清理本地缓存，支持清理指定项或全部清理
+
+**参数:**
+- `key` (string, 可选): 缓存键。如果传入则删除对应的缓存项，如果不传入则清除所有缓存
+
+**示例:**
+```javascript
+// 清理指定缓存
+clearStorageSync('username')
+
+// 清理所有缓存
+clearStorageSync()
+```
+
+## 🛠️ 开发使用
+
+### 安装依赖
+```bash
+yarn install
+# 或
+npm install
+```
+
+### 开发脚本
+```bash
+# 开发模式
+yarn dev
+# 或
+npm run dev
+```
+
+## 🏗️ 技术栈
+
+- **TypeScript** - 类型安全的 JavaScript
+- **UniApp** - 跨平台应用开发框架
+- **ES6 Modules** - 模块化开发
+
+## 📁 项目结构
+
+```
+huang-uniapp-toolkit/
+├── src/
+│   ├── ui/              # UI交互工具函数
+│   │   └── index.ts
+│   ├── navigation/      # 导航相关工具
+│   │   └── index.ts
+│   ├── clipboard/       # 剪贴板工具
+│   │   └── index.ts
+│   ├── system/          # 系统信息工具
+│   │   └── index.ts
+│   ├── localStorage/    # 本地存储工具
+│   │   └── index.ts
+│   └── index.js        # 主入口文件
+├── package.json        # 项目配置
+├── tsconfig.json       # TypeScript 配置
+└── README.md          # 项目说明
+```
+
+## 🔄 版本信息
+
+当前版本：v1.0.5
+
+## 📄 许可证
+
+ISC
+
+## 🤝 贡献指南
+
+欢迎提交 Issue 和 Pull Request 来完善这个工具库！
+
+### 开发规范
+
+1. 所有函数都应该遵循单一职责原则
+2. 必须添加详细的中文注释
+3. 新增功能需要在 README.md 中更新文档
+4. 保持代码简洁可读
+5. 确保跨平台兼容性
+
+## 📝 更新日志
+
+### v1.0.6
+- ✨ **新增功能**：添加状态栏和导航栏高度获取函数
+- 📏 新增 `getStatusBarHeight()` 函数，用于获取设备状态栏高度
+- 📐 新增 `getNavHeight()` 函数，用于获取小程序导航栏总高度
+- ⚙️ 新增 `getAppConfig()` 函数，一次性获取状态栏和导航栏配置信息
+- 🛡️ 添加完善的错误处理机制，确保在获取失败时返回默认值
+- 📚 更新API文档，添加详细的使用说明和界面适配示例
+- 💡 遵循单一职责原则，每个函数专注于特定的高度获取功能
+- 🎯 主要用于小程序平台的界面适配和自定义导航栏开发
+
+### v1.0.5
+- ✨ **新增功能**：完善 `onCheckForUpdate()` 函数
+- 📱 实现小程序版本更新检查功能，支持自动检查、下载和提示更新
+- 🔄 支持静默下载新版本，用户可选择立即重启或稍后更新
+- 🛡️ 添加完善的错误处理机制，包括下载失败和异常情况处理
+- 📚 更新API文档，添加详细的平台支持说明和使用示例
+- 💡 遵循单一职责原则，提供用户友好的更新体验
+- 🎯 支持微信、支付宝、百度、抖音、QQ、快手、京东等主流小程序平台
+
+### v1.0.4
+- ✨ **新增功能**：完善 `getCurrentEnv()` 函数
+- 📱 新增小程序账户信息获取功能，支持获取appId、版本号、环境版本等信息
+- 🛡️ 添加错误处理机制，确保函数调用的稳定性
+- 📚 更新API文档，添加详细的使用说明和示例
+- 💡 遵循单一职责原则，提供清晰的返回值结构
+
+### v1.0.3
+- 🏗️ **重大重构**：按功能类型重新组织代码结构
+- 📁 将原 `common` 模块拆分为 5 个专门模块：
+  - `ui` - UI交互工具（useToast）
+  - `navigation` - 导航工具（useBack）
+  - `clipboard` - 剪贴板工具（copyText）
+  - `system` - 系统信息工具（useWindowInfo, getPlatform, getCurrentEnv）
+  - `localStorage` - 本地存储工具（保持不变）
+- 📚 更新文档结构，按模块分类展示API
+- 💡 遵循单一职责原则，提高代码可维护性
+- 🔧 完善函数注释，便于后续维护
+
+### v1.0.2
+- 🎉 完善项目文档
+- 🔧 优化代码注释
+- 🛡️ 添加错误处理机制
+- ✨ 新增 `getPlatform()` 函数，用于获取当前运行平台
+- 🚀 优化 `copyText()` 函数，H5 平台优先使用现代 Clipboard API
+
+### v1.0.1
+- 🎯 初始版本发布
+- 📦 基础工具函数实现
+- 💾 本地存储工具实现
+
+---
+
+如有问题或建议，请提交 Issue 或联系开发者。感谢您的使用！ 🙏

package/RECORD.md

@@ -0,0 +1,34 @@
+# 项目记录 (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`: 封装了与浏览器或小程序本地存储相关的操作。

package/package.json

@@ -0,0 +1,16 @@
+{
+    "name": "my-uniapp-tools",
+    "version": "1.0.0",
+    "main": "src/index.js",
+    "type": "module",
+    "scripts": {
+        "test": "echo \"Error: no test specified\" && exit 1",
+        "dev": "node src/index.js"
+    },
+    "author": "",
+    "license": "ISC",
+    "description": "",
+    "dependencies": {
+        "@dcloudio/types": "^3.4.14"
+    }
+}

package/src/clipboard/index.ts

@@ -0,0 +1,55 @@
+/**
+ * 剪贴板相关工具函数
+ */
+
+import { useToast } from '../ui';
+
+/**
+ * 跨平台文本复制功能
+ * @param text 要复制的文本内容
+ * @description 支持 H5、App、小程序。H5 平台优先使用现代的 Clipboard API，失败时回退到传统方法
+ */
+export function copyText(text: string) {
+  // #ifndef H5 条件编译：非 H5 平台（如 App、小程序）执行此代码块
+  uni.setClipboardData({
+    data: text, // 要复制的文本内容
+    success: function () {
+      useToast('复制成功!');
+    },
+    fail: function () {
+      useToast('复制失败!');
+    },
+  });
+  // #endif
+  // #ifdef H5 条件编译：仅 H5 平台执行此代码块
+  // 优先使用现代的 Clipboard API
+  if (navigator.clipboard && window.isSecureContext) {
+    navigator.clipboard.writeText(text).then(() => {
+      useToast('复制成功');
+    }).catch(() => {
+      // 如果 Clipboard API 失败，回退到传统方法
+      fallbackCopyTextToClipboard(text);
+    });
+  } else {
+    // 回退到传统的复制方法
+    fallbackCopyTextToClipboard(text);
+  }
+
+  /**
+   * 传统复制方法的辅助函数
+   * @param text 要复制的文本内容
+   * @description 使用 document.execCommand 方式进行文本复制
+   */
+  function fallbackCopyTextToClipboard(text: string) {
+    const createInput = document.createElement('textarea');
+    createInput.value = text; // 设置 textarea 的值为要复制的文本
+    document.body.appendChild(createInput);
+    createInput.select();
+    document.execCommand('Copy');
+    createInput.className = 'createInput';
+    createInput.style.display = 'none';
+    useToast('复制成功');
+    createInput.remove(); // 复制完成后移除临时创建的 textarea 元素
+  }
+  // #endif
+}

package/src/index.js

@@ -0,0 +1,14 @@
+// UI交互相关
+export * from './ui'
+
+// 导航相关
+export * from './navigation'
+
+// 剪贴板相关
+export * from './clipboard'
+
+// 系统信息相关
+export * from './system'
+
+// 本地存储相关
+export * from './localStorage'

package/src/localStorage/index.ts

@@ -0,0 +1,69 @@
+/**
+ * 本地存储相关工具函数
+ */
+
+/**
+ * 同步设置本地缓存
+ * @param key 缓存键
+ * @param obj 要缓存的值，可以是任何类型
+ * @description 如果值是字符串，直接存储；否则，尝试将其 JSON 序列化后存储。
+ *              添加了错误处理，以防 JSON 序列化失败。
+ */
+export function setStorageSync(key: string, obj: unknown) {
+  // 检查传入的值是否为字符串类型
+  if (typeof obj === 'string') {
+    // 如果是字符串，直接使用 uni.setStorageSync 存储
+    uni.setStorageSync(key, obj);
+  } else {
+    // 如果不是字符串，尝试将其 JSON 序列化
+    try {
+      // 使用 uni.setStorageSync 存储序列化后的字符串
+      uni.setStorageSync(key, JSON.stringify(obj));
+    } catch (e) {
+      // 如果 JSON 序列化失败，打印错误日志
+      console.error('Failed to stringify object for localStorage:', e);
+    }
+  }
+}
+
+/**
+ * 同步获取本地缓存
+ * @param key 缓存键
+ * @returns 缓存的值。如果存储的是 JSON 字符串，则返回解析后的对象；否则返回原始值。
+ * @description 获取指定键的值。如果值是非空字符串，尝试进行 JSON 解析。
+ *              如果解析成功，返回解析后的对象；如果解析失败或值不是有效字符串，返回原始值。
+ */
+export function getStorageSync(key: string) {
+  // 使用 uni.getStorageSync 获取原始值
+  let val = uni.getStorageSync(key);
+  // 检查获取到的值是否为非空字符串
+  if (typeof val === 'string' && val) {
+    // 如果是非空字符串，尝试进行 JSON 解析
+    try {
+      // 解析成功，返回解析后的对象
+      return JSON.parse(val);
+    } catch (e) {
+      // 解析失败，返回原始值
+      return val;
+    }
+  }
+  // 如果值不是非空字符串，直接返回原始值
+  return val;
+}
+
+/**
+ * 同步清理本地缓存
+ * @param key 可选的缓存键
+ * @description 如果传入 key，则删除对应的缓存项。
+ *              如果不传入 key，则清除所有本地缓存。
+ */
+export function clearStorageSync(key?: string) {
+  // 检查是否传入了 key
+  if (key) {
+    // 如果传入 key，使用 uni.removeStorageSync 删除对应的缓存项
+    uni.removeStorageSync(key);
+  } else {
+    // 如果没有传入 key，使用 uni.clearStorageSync 清除所有缓存
+    uni.clearStorageSync();
+  }
+}

package/src/navigation/index.ts

@@ -0,0 +1,37 @@
+/**
+ * 导航相关工具函数
+ */
+
+/**
+ * 返回上一页并支持传递参数给上一页的 init 方法
+ * @param params 返回上一页时传入的参数，默认为空字符串
+ * @returns 无返回值
+ * @description 调用此函数会返回到上一页，如果上一页存在 init 方法，会自动调用并传入参数
+ */
+export const useBack = (params: any = ''): void => {
+  // 调用uni.navigateBack方法，用于导航回前一页
+  uni.navigateBack({
+    delta: 1, // 默认返回上一页
+    success() {
+      // 获取当前所有页面栈
+      const pages = getCurrentPages();
+      if (pages.length < 2) {
+        console.warn('没有上一页');
+        return;
+      }
+      // 获取前一个页面的实例对象
+      const prevPage = pages[pages.length - 2];
+      // 检查前一个页面实例 (prevPage.$vm) 是否存在，并且是否包含 init 方法
+      // 这是一个约定：需要刷新的页面需要暴露一个 init 方法供调用
+      if (prevPage.$vm && typeof prevPage.$vm.init === 'function') {
+        // 如果存在 init 方法，则调用该方法并传入参数，用于页面刷新或数据更新
+        prevPage.$vm.init(params);
+      } else {
+        console.warn('前一个页面没有init方法');
+      }
+    },
+    fail() {
+      console.error('导航失败');
+    },
+  });
+};

package/src/system/index.ts

@@ -0,0 +1,192 @@
+/**
+ * 系统信息相关工具函数
+ */
+
+/**
+ * 获取窗口信息
+ * @returns 窗口信息对象，包含窗口尺寸、像素比等信息
+ * @description 调用 uni.getWindowInfo() 获取当前设备的窗口相关信息
+ */
+export const useWindowInfo = () => {
+  // 调用 uni.getWindowInfo() 获取窗口尺寸、像素比等信息
+  return uni.getWindowInfo();
+};
+
+/**
+ * 获取当前运行平台
+ * @returns 平台类型字符串 ('weixin' | 'web' | 'app' | 'alipay' | 'h5')
+ * @description 通过条件编译判断当前代码运行的平台环境
+ */
+export const getPlatform = () => {
+  let platform
+  // #ifdef MP-WEIXIN
+  platform = 'weixin'
+  // #endif
+  // #ifdef WEB
+  platform = 'web'
+  // #endif
+  // #ifdef APP
+  platform = 'app'
+  // #endif
+  // #ifdef MP-ALIPAY
+  platform = 'alipay'
+  // #endif
+  // #ifdef H5
+  platform = 'h5'
+  // #endif
+  return platform
+}
+
+/**
+ * 获取小程序账户信息
+ * @returns 小程序账户信息对象，包含appId、版本、环境等信息
+ * @description 调用 uni.getAccountInfoSync() 获取当前小程序的账户相关信息
+ */
+export const getCurrentEnv = () => {
+  try {
+    // 调用 uni.getAccountInfoSync() 获取小程序账户信息
+    const accountInfo = uni.getAccountInfoSync();
+    return {
+      // 小程序appId
+      appId: accountInfo.miniProgram?.appId || '',
+      // 小程序版本号
+      version: accountInfo.miniProgram?.version || '',
+      // 小程序环境版本（develop开发版、trial体验版、release正式版）
+      envVersion: accountInfo.miniProgram?.envVersion || '',
+      // 完整的账户信息
+      accountInfo
+    };
+  } catch (error) {
+    console.error('获取小程序账户信息失败:', error);
+    return {
+      appId: '',
+      version: '',
+      envVersion: '',
+      accountInfo: null
+    };
+  }
+}
+
+
+/**
+ * 检查小程序版本更新
+ * @description 检查小程序是否有新版本，如果有则提示用户更新并重启应用
+ * @returns void
+ * @example
+ * // 在App.vue的onLaunch或onShow中调用
+ * onCheckForUpdate()
+ */
+export const onCheckForUpdate = () => {
+  try {
+    // 获取全局唯一的版本更新管理器对象
+    const updateManager = uni.getUpdateManager();
+
+    // 检查小程序是否有新版本发布
+    updateManager.onCheckForUpdate(function (res) {
+      // 请求完新版本信息的回调
+      console.log('检查更新结果:', res.hasUpdate);
+      if (res.hasUpdate) {
+        console.log('发现新版本，开始下载...');
+      }
+    });
+
+    // 小程序有新版本，静默下载新版本，做好更新准备
+    updateManager.onUpdateReady(function (res) {
+      uni.showModal({
+        title: '更新提示',
+        content: '新版本已经准备好，是否重启应用？',
+        showCancel: true,
+        cancelText: '稍后',
+        confirmText: '立即重启',
+        success(modalRes) {
+          if (modalRes.confirm) {
+            // 新的版本已经下载好，调用 applyUpdate 应用新版本并重启
+            updateManager.applyUpdate();
+          }
+        }
+      });
+    });
+
+    // 新版本下载失败处理
+    updateManager.onUpdateFailed(function (res) {
+      console.error('新版本下载失败:', res);
+      uni.showModal({
+        title: '更新失败',
+        content: '新版本下载失败，请检查网络连接或稍后重试',
+        showCancel: false,
+        confirmText: '知道了'
+      });
+    });
+
+  } catch (error) {
+    console.error('版本更新检查失败:', error);
+    // 静默处理错误，不影响用户正常使用
+  }
+}
+
+/**
+ * 获取状态栏高度
+ * @returns 状态栏高度（单位：px）
+ * @description 获取设备状态栏的高度，用于适配不同设备的状态栏
+ */
+export const getStatusBarHeight = () => {
+  try {
+    // 获取系统信息中的状态栏高度
+    const statusBarHeight = uni.getSystemInfoSync().statusBarHeight || 0;
+    console.log("🚀 ~ 状态栏高度:", statusBarHeight);
+    return statusBarHeight;
+  } catch (error) {
+    console.error('获取状态栏高度失败:', error);
+    return 0;
+  }
+}
+
+/**
+ * 获取导航栏高度
+ * @returns 导航栏高度（单位：px）
+ * @description 获取小程序导航栏的总高度，包含状态栏高度和菜单按钮高度
+ */
+export const getNavHeight = () => {
+  try {
+    // 获取状态栏高度
+    const statusBarHeight = getStatusBarHeight();
+
+    // 获取菜单按钮的边界信息
+    const menuButtonInfo = uni.getMenuButtonBoundingClientRect();
+
+    // 计算导航栏总高度：状态栏高度 + 菜单按钮高度
+    const navHeight = menuButtonInfo.height + statusBarHeight;
+    console.log("🚀 ~ 导航栏高度:", navHeight);
+
+    return navHeight;
+  } catch (error) {
+    console.error('获取导航栏高度失败:', error);
+    // 返回默认高度（状态栏高度 + 44px 默认导航栏高度）
+    return getStatusBarHeight() + 44;
+  }
+}
+
+/**
+ * @returns 包含状态栏高度和导航栏高度的配置对象
+ * @description 一次性获取应用所需的状态栏和导航栏高度配置信息
+ */
+export const getTopNavBarHeight = () => {
+  try {
+    // 获取状态栏高度
+    const statusBarHeight = getStatusBarHeight();
+
+    // 获取导航栏高度
+    const navHeight = getNavHeight();
+
+    return {
+      statusBarHeight,
+      navHeight
+    };
+  } catch (error) {
+    console.error('获取全局配置失败:', error);
+    return {
+      statusBarHeight: 0,
+      navHeight: 44
+    };
+  }
+}

package/src/ui/index.ts

@@ -0,0 +1,24 @@
+/**
+ * UI交互相关工具函数
+ */
+
+/**
+ * 显示消息提示框
+ * @param title 提示的内容，默认为空字符串
+ * @param mask 是否显示透明蒙层，默认为 false
+ * @param icon 图标类型，默认为 'none'
+ * @param duration 提示的延迟时间，默认为 2000 毫秒
+ */
+export const useToast = (
+  title: string = '',
+  mask: boolean = false,
+  icon: 'none' | 'success' | 'loading' | 'error' | 'fail' | 'exception' | undefined = 'none',
+  duration: number = 2000
+) => {
+  uni.showToast({
+    title,
+    icon,
+    mask,
+    duration,
+  });
+};

package/tsconfig.json

@@ -0,0 +1,20 @@
+// tsconfig.json
+{
+    "compilerOptions": {
+        "target": "esnext",
+        "module": "esnext",
+        "strict": true,
+        "jsx": "preserve",
+        "moduleResolution": "node",
+        "esModuleInterop": true,
+        "sourceMap": true,
+        "skipLibCheck": true,
+        "importHelpers": true,
+        "allowSyntheticDefaultImports": true,
+        "useDefineForClassFields": true,
+        "resolveJsonModule": true,
+        "lib": ["esnext", "dom"],
+        "types": ["@dcloudio/types"]
+    },
+    "exclude": ["node_modules", "unpackage", "src/**/*.nvue"]
+}