@zfqh/uniapp 0.1.1

package/docs/api/utils/storage.md

@@ -0,0 +1,145 @@
+# 本地缓存
+
+::: tip 工具模块
+`@zfqh/uniapp/lib/utils/storage`
+:::
+
+给 uni storage 增加项目和环境命名空间，避免多环境缓存互相污染。
+
+## 平台兼容性
+
+| App | H5 | 微信小程序 | 其他小程序 | WebView |
+| --- | --- | --- | --- | --- |
+| √ | √ | √ | 视平台 API 而定 | 视运行容器而定 |
+
+## 基本使用
+
+```ts
+import { getStorageSync, setStorageSync, removeStorageSync, storageKeys } from '@zfqh/uniapp';
+```
+
+具体方法、参数语义和返回值以发布包类型为准；下方表格按 `@zfqh/uniapp/lib/utils/storage` 的导出整理。
+
+## 命名空间规则
+
+存储 key 会自动拼接 `config.storage.prefix` 和环境名（非 prod 环境）。实际存储的 key 格式为 `PREFIX_ENV_NAME`（全大写）。
+
+例如 `storage.prefix` 为 `'zfqh'`，当前环境为 `sit`：
+
+```ts
+setStorageSync('login', { token: 'xxx' });
+// 实际存储 key: 'ZFQH_SIT_LOGIN'
+```
+
+生产环境不拼接环境名：
+
+```ts
+setStorageSync('login', { token: 'xxx' });
+// 实际存储 key: 'ZFQH_LOGIN'
+```
+
+## storageKeys 内置常量
+
+```ts
+import { storageKeys } from '@zfqh/uniapp';
+```
+
+| 属性 | 值 | 用途 |
+| --- | --- | --- |
+| `query` | `'query'` | URL query 参数缓存 |
+| `login` | `'login'` | 登录信息（token、userId 等） |
+| `user` | `'user'` | 用户信息 |
+| `open` | `'open'` | 第三方开放平台信息 |
+| `launch` | `'launch'` | 启动参数 |
+| `location` | `'location'` | 定位信息 |
+
+```ts
+// 保存登录信息
+setStorageSync(storageKeys.login, { token: 'xxx', userId: 1, tenantId: 1 });
+
+// 读取登录信息
+const loginInfo = getStorageSync(storageKeys.login);
+
+// 删除缓存
+removeStorageSync(storageKeys.login);
+```
+
+## 完整工作流
+
+### 同步操作（推荐在非异步上下文使用）
+
+```ts
+import { setStorageSync, getStorageSync, removeStorageSync } from '@zfqh/uniapp';
+
+// 保存
+setStorageSync('formData', { name: '张三', age: 30 });
+
+// 读取
+const form = getStorageSync('formData');
+
+// 删除
+removeStorageSync('formData');
+```
+
+### 异步操作
+
+```ts
+import { setStorage, getStorage, removeStorage } from '@zfqh/uniapp';
+
+// 保存
+await setStorage('asyncKey', { data: 'value' });
+
+// 读取
+const result = await getStorage('asyncKey');
+
+// 删除
+await removeStorage('asyncKey');
+```
+
+### 清除全部缓存
+
+```ts
+import { clearStorageSync, clearStorage } from '@zfqh/uniapp';
+
+// 同步清除（谨慎使用，会删除所有缓存包括其他应用的）
+clearStorageSync();
+
+// 异步清除
+await clearStorage();
+```
+
+### 自定义 storageKeys
+
+如果项目需要额外的缓存 key，可以用 `setStorageKeys` 扩展：
+
+```ts
+import { setStorageKeys, setStorageSync, getStorageSync } from '@zfqh/uniapp';
+
+const myKeys = setStorageKeys({
+  constitution: '',
+  medicalRecord: '',
+  cartData: '',
+});
+
+setStorageSync(myKeys.constitution, { type: '气虚', score: 85 });
+const data = getStorageSync(myKeys.constitution);
+```
+
+## API
+
+发布路径：`@zfqh/uniapp/lib/utils/storage`
+
+| 名称 | 签名/声明 | 说明 |
+| --- | --- | --- |
+| `getStorageSync` | `export function getStorageSync(name: string) {` | 按 storage.prefix 和 env.name 生成命名空间 key 后同步读取缓存。 |
+| `getStorage` | `export function getStorage(name: string) {` | 按命名空间 key 异步读取缓存。 |
+| `setStorageSync` | `export function setStorageSync(name: string, data: any) {` | 按命名空间 key 同步写入缓存。 |
+| `setStorage` | `export function setStorage(name: string, data: any) {` | 按命名空间 key 异步写入缓存。 |
+| `removeStorageSync` | `export function removeStorageSync(name: string) {` | 按命名空间 key 同步删除缓存。 |
+| `removeStorage` | `export function removeStorage(name: string) {` | 按命名空间 key 异步删除缓存。 |
+| `clearStorageSync` | `export function clearStorageSync() {` | 同步清空全部本地缓存。 |
+| `clearStorage` | `export function clearStorage() {` | 异步清空全部本地缓存。 |
+| `setStorageKeys` | `export function setStorageKeys<T>(data: T) {` | 把对象每个字段值设置为字段名，用于生成稳定 storageKeys。 |
+| `StorageKeys` | `export interface StorageKeys {` | 内置缓存 key 类型，包含 query、login、user、open、launch、location。 |
+| `storageKeys` | `export const storageKeys: StorageKeys = setStorageKeys({` | 内置缓存 key 常量。 |
+

package/docs/api/utils/subscribe.md

@@ -0,0 +1,77 @@
+# 订阅消息
+
+::: tip 工具模块
+`@zfqh/uniapp/lib/utils/subscribe`
+:::
+
+封装微信小程序订阅消息调用。
+
+## 平台兼容性
+
+| App | H5 | 微信小程序 | 其他小程序 | WebView |
+| --- | --- | --- | --- | --- |
+| √ | √ | √ | 视平台 API 而定 | 视运行容器而定 |
+
+## 基本使用
+
+```ts
+import { subscribeMessage } from '@zfqh/uniapp';
+```
+
+## 签名
+
+```ts
+subscribeMessage(
+  data: string[] | { title: string; id: string }[],
+  acceptCallback?: (key: string) => void,
+  rejectCallback?: (key: string) => void,
+): Promise<number>
+```
+
+- `data`：模板 ID 数组，或带 `title` 和 `id` 的对象数组（用于权限提示文案）
+- `acceptCallback`：用户同意某个模板时触发
+- `rejectCallback`：用户拒绝某个模板时触发
+- 返回值：`1` 表示成功发起订阅，`0` 表示取消或失败
+
+## 使用示例
+
+```ts
+import { subscribeMessage } from '@zfqh/uniapp';
+
+// 简单用法：传入模板 ID 数组
+await subscribeMessage([
+  'template-id-1',
+  'template-id-2',
+]);
+
+// 带标题的用法：权限被关闭时显示友好提示
+await subscribeMessage([
+  { id: 'template-id-1', title: '订单发货通知' },
+  { id: 'template-id-2', title: '物流更新通知' },
+]);
+
+// 处理用户选择
+await subscribeMessage(
+  ['template-id-1'],
+  (key) => console.log('同意:', key),
+  (key) => console.log('拒绝:', key),
+);
+```
+
+## 平台差异
+
+仅在微信小程序端有效（`#ifdef MP-WEIXIN`）。非微信端调用会直接 resolve `0`。
+
+内部会自动检测订阅权限状态：
+
+- 主开关关闭时引导用户打开设置页
+- 单个模板被拒绝时提示具体模板名称
+
+## API
+
+发布路径：`@zfqh/uniapp/lib/utils/subscribe`
+
+| 名称 | 签名/声明 | 说明 |
+| --- | --- | --- |
+| `subscribeMessage` | `export function subscribeMessage(` | 小程序订阅消息封装。 |
+

package/docs/api/utils/throttle.md

@@ -0,0 +1,101 @@
+# 节流
+
+::: tip 工具模块
+`@zfqh/uniapp/lib/utils/throttle`
+:::
+
+提供类实例和默认实例，适合重复跳转、登录退出、滚动加载等高频触发场景。
+
+## 平台兼容性
+
+| App | H5 | 微信小程序 | 其他小程序 | WebView |
+| --- | --- | --- | --- | --- |
+| √ | √ | √ | 视平台 API 而定 | 视运行容器而定 |
+
+## 基本使用
+
+```ts
+import { Throttle, throttle } from '@zfqh/uniapp';
+
+// 使用默认实例（简单场景）
+throttle.exec(() => loadMore(), 500);
+
+// 创建独立实例（多个节流互不干扰）
+const submitThrottle = new Throttle();
+submitThrottle.exec(() => submit(), 500);
+```
+
+## API
+
+发布路径：`@zfqh/uniapp/lib/utils/throttle`
+
+| 名称 | 签名/声明 | 说明 |
+| --- | --- | --- |
+| `Throttle` | `export default function Throttle()` | 节流类，可创建独立实例。 |
+| `throttle` | `export const throttle = new Throttle();` | 默认节流实例，适合单一级流场景快捷使用。 |
+
+### exec 方法
+
+```ts
+exec(func: Function, wait?: number, immediate?: boolean): void
+```
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `func` | - | 要执行的回调函数 |
+| `wait` | `500` | 节流时间（毫秒） |
+| `immediate` | `true` | 是否在 wait 开始时立即执行（默认立即执行，wait 内不再重复触发） |
+
+## 典型场景
+
+### 滚动加载更多
+
+```ts
+import { throttle } from '@zfqh/uniapp';
+
+function onScrollBottom() {
+  throttle.exec(() => {
+    loadMore();
+  }, 500);
+}
+```
+
+### 按钮防重复点击
+
+```ts
+const submitThrottle = new Throttle();
+
+function onSubmit() {
+  submitThrottle.exec(() => {
+    submitForm(formData);
+  }, 1000); // 1秒内只执行一次
+}
+```
+
+### 登录退出节流
+
+```ts
+import { throttle } from '@zfqh/uniapp';
+
+function onLogout() {
+  throttle.exec(() => {
+    store.dispatch('logout');
+  }, 1000);
+}
+```
+
+### 多个独立节流
+
+```ts
+const scrollThrottle = new Throttle();
+const clickThrottle = new Throttle();
+
+// 互不影响
+scrollThrottle.exec(() => loadMore(), 500);
+clickThrottle.exec(() => navigate(url), 500);
+```
+
+## 使用建议
+
+- `throttle` 为共享实例；多个按钮、滚动加载或业务动作需要互不影响时，请分别 `new Throttle()`。
+

package/docs/api/utils/toast.md

@@ -0,0 +1,164 @@
+# 提示反馈
+
+::: tip 工具模块
+`@zfqh/uniapp/lib/utils/toast`
+:::
+
+统一 loading、toast、success、error、fail、exception 和自定义提示组件适配。
+
+## 平台兼容性
+
+| App | H5 | 微信小程序 | 其他小程序 | WebView |
+| --- | --- | --- | --- | --- |
+| √ | √ | √ | 视平台 API 而定 | 视运行容器而定 |
+
+## 基本使用
+
+```ts
+import { toast } from '@zfqh/uniapp';
+```
+
+## 常用方法
+
+```ts
+// 加载中（显示 loading 遮罩）
+toast.loading('加载中');
+toast.loading('提交中', { mask: true }); // 禁止点击穿透
+
+// 普通提示（icon: none，返回 Promise）
+await toast.message('操作成功');
+
+// 语义提示（自动设置对应 icon）
+toast.success('保存成功');
+toast.error('保存失败');
+toast.fail('操作失败');
+toast.exception('系统异常');
+
+// 隐藏
+toast.hideLoading(); // 隐藏 loading
+toast.close();       // 隐藏 toast
+```
+
+## loading 完整流程
+
+```ts
+import { toast, requestDelay } from '@zfqh/uniapp';
+
+async function submitForm(data) {
+  try {
+    toast.loading('提交中');
+    await requestDelay(() => createOrder(data));
+    toast.success('提交成功');
+  } catch (e) {
+    toast.message(e.message || '提交失败');
+  } finally {
+    toast.hideLoading();
+  }
+}
+```
+
+## message 返回 Promise
+
+`toast.message` 会在 `duration`（默认 2000ms）后 resolve，适合需要等待提示消失再跳转的场景：
+
+```ts
+await toast.message('已提交，即将返回');
+navigate.back({ delta: 1 });
+```
+
+## 自定义 Toast
+
+如果项目有自己的 Toast 组件，可在 `defineConfig` 中接入：
+
+```ts
+defineConfig({
+  toast: {
+    custom: true,
+    show(options) {
+      const page = getCurrentPages().pop();
+      const result = page?.$vm?.$refs?.toast?.show({
+        type: ['error', 'success'].includes(options.icon) ? options.icon : 'default',
+        message: options.title,
+      });
+      return result !== false; // 返回 false 回退到原生 toast
+    },
+    hide() {
+      const page = getCurrentPages().pop();
+      const result = page?.$vm?.$refs?.toast?.hide();
+      return result !== false;
+    },
+  },
+});
+```
+
+## close 和 hideToast
+
+`toast.close()` 和 `toast.hideToast()` 是同一个函数，用于隐藏当前显示的 toast。`toast.hideLoading()` 用于隐藏 loading 遮罩，两者互不影响。
+
+## API
+
+发布路径：`@zfqh/uniapp/lib/utils/toast`
+
+| 名称 | 签名/声明 | 说明 |
+| --- | --- | --- |
+| `loading` | `export const loading = (` | 显示 loading，可传 title 或 ShowLoadingOptions。 |
+| `message` | `export const message = (` | 显示普通 toast，默认 icon 为 none，返回 duration 后 resolve 的 Promise。 |
+| `close` | `export const close = () => {` | 隐藏 toast；custom toast 开启时优先调用 toastConfig.hide。 |
+| `hideToast` | `export const hideToast = close;` | close 的别名。 |
+| `hideLoading` | `export const hideLoading = () => uni.hideLoading();` | 调用 uni.hideLoading。 |
+| `toast.loading(titleOrOptions, options?)` | `default export member` | 显示 loading。 |
+| `toast.message(titleOrOptions, options?)` | `default export member` | 显示普通提示并在 duration 后 resolve。 |
+| `toast.success/error/fail/exception(titleOrOptions, options?)` | `default export member` | 按对应 icon 显示 toast。 |
+| `toast.close()/toast.hideToast()` | `default export member` | 隐藏 toast。 |
+| `toast.hideLoading()` | `default export member` | 隐藏 loading。 |
+
+## toast 使用指南
+
+根入口导出：
+
+```ts
+import { toast } from '@zfqh/uniapp';
+```
+
+用法：
+
+```ts
+toast.loading('加载中');
+toast.message('普通提示');
+toast.success('保存成功');
+toast.error('保存失败');
+toast.fail('操作失败');
+toast.exception('系统异常');
+toast.hideLoading();
+toast.close();
+```
+
+`toast.message` 返回 Promise，会在 toast duration 后 resolve：
+
+```ts
+await toast.message('已提交');
+navigate.back({ delta: 1 });
+```
+
+## 自定义 Toast
+
+在配置中开启：
+
+```ts
+defineConfig({
+  toast: {
+    custom: true,
+    show(options) {
+      const page = getCurrentPages().pop() as any;
+      return page?.$vm?.$refs?.toast?.show({
+        type: ['error', 'success'].includes(options.icon as string) ? options.icon : 'default',
+        message: options.title,
+      }) !== false;
+    },
+    hide() {
+      const page = getCurrentPages().pop() as any;
+      return page?.$vm?.$refs?.toast?.hide() !== false;
+    },
+  },
+});
+```

package/docs/api/utils/uni.md

@@ -0,0 +1,28 @@
+# uni 运行时补丁
+
+::: tip 工具模块
+`@zfqh/uniapp/lib/utils/uni`
+:::
+
+包含平台运行时补丁或内部实现，一般不直接调用。
+
+## 平台兼容性
+
+| App | H5 | 微信小程序 | 其他小程序 | WebView |
+| --- | --- | --- | --- | --- |
+| √ | √ | √ | 视平台 API 而定 | 视运行容器而定 |
+
+## 基本使用
+
+```ts
+import uni from '@zfqh/uniapp/lib/utils/uni';
+```
+
+具体方法、参数语义和返回值以发布包类型为准；下方表格按 `@zfqh/uniapp/lib/utils/uni` 的导出整理。
+
+## API
+
+发布路径：`@zfqh/uniapp/lib/utils/uni`
+
+该文件只包含运行时补丁或平台专用内部实现，没有具名导出。
+

package/docs/api/utils/update.md

@@ -0,0 +1,165 @@
+# 应用更新
+
+::: tip 工具模块
+`@zfqh/uniapp/lib/utils/update`
+:::
+
+统一检查 App、Electron H5、小程序更新，处理热更新、整包更新和应用重启。
+
+## 平台兼容性
+
+| App | H5 | 微信小程序 | 其他小程序 | WebView |
+| --- | --- | --- | --- | --- |
+| √ | √ | √ | 视平台 API 而定 | 视运行容器而定 |
+
+## 基本使用
+
+```ts
+import { update } from '@zfqh/uniapp';
+```
+
+## 检查更新
+
+```ts
+import { update } from '@zfqh/uniapp';
+
+// 常规检查（弹出确认框让用户选择）
+await update.check();
+
+// 强制更新（跳过确认框，直接下载）
+await update.check(true);
+```
+
+`check(immediate?: boolean)` 会根据平台自动选择更新方式：
+
+| 平台 | 更新方式 |
+| --- | --- |
+| App（Android/iOS） | 热更新（wgt）或整包更新（apk/ipa） |
+| H5（Electron） | 热更新（zip）或整包更新（exe/dmg） |
+| 微信小程序 | `getUpdateManager` 原生更新 |
+
+## 配置 update.request
+
+需要在 `defineConfig` 中配置获取版本信息的请求函数：
+
+```ts
+import { defineConfig } from '@zfqh/uniapp';
+import { POST } from '@zfqh/uniapp/lib/apis';
+
+defineConfig({
+  update: {
+    request(data) {
+      return POST('/app-api/system/app/version/latest', data);
+    },
+  },
+});
+```
+
+请求参数包含：
+
+| 字段 | 说明 |
+| --- | --- |
+| `appId` | 当前应用 ID |
+| `appName` | 当前应用名称 |
+| `versionCode` | 当前资源版本号 |
+| `versionName` | 当前资源版本名 |
+| `appVersionCode` | 当前程序版本号 |
+| `appVersionName` | 当前程序版本名 |
+| `platform` | 当前平台 |
+
+响应字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `hot_update` | 是否热更新（1 = 热更新） |
+| `force_update` | 是否强制更新 |
+| `external_install` | 是否外部安装（Android 整包更新时跳浏览器） |
+| `wgt_url` | App WGT 热更新资源地址 |
+| `zip_url` | H5 Electron 热更新资源包地址 |
+| `apk_url` | Android 安装包地址 |
+| `ipa_url` | iOS 安装包地址 |
+| `exe_url` | Windows 安装包地址 |
+| `dmg_url` | macOS 安装包地址 |
+
+## 典型用法
+
+在 `App.vue` 的 `onLaunch` 或 `onShow` 中检查更新：
+
+```ts
+import { update } from '@zfqh/uniapp';
+
+export default {
+  onShow() {
+    // 非开发环境检查更新
+    // #ifndef H5
+    update.check();
+    // #endif
+  },
+};
+```
+
+在 Updater 组件中使用强制更新：
+
+```ts
+// 用户点击"立即更新"按钮
+async function onUpdate() {
+  await update.check(true); // 立即更新，不弹确认框
+}
+```
+
+## API
+
+发布路径：`@zfqh/uniapp/lib/utils/update`
+
+| 名称 | 签名/声明 | 说明 |
+| --- | --- | --- |
+| `update.check(immediate?)` | `default export member` | 检查 App/H5 Electron/小程序更新；immediate 为 true 时尽量跳过确认直接下载或应用更新。 |
+
+## App 更新
+
+根入口导出：
+
+```ts
+import { update } from '@zfqh/uniapp';
+```
+
+更新配置：
+
+```ts
+defineConfig({
+  update: {
+    request(data) {
+      return POST('/app-api/system/app/version/latest', data);
+    },
+  },
+});
+```
+
+请求参数可能包含：
+
+| 字段 | 说明 |
+| --- | --- |
+| `appId` | 当前应用 ID。 |
+| `appName` | 当前应用名称。 |
+| `versionCode` | 当前资源版本号。 |
+| `versionName` | 当前资源版本名。 |
+| `appVersionCode` | 当前程序版本号。 |
+| `appVersionName` | 当前程序版本名。 |
+| `platform` | 当前平台。 |
+
+响应字段可能包含：
+
+| 字段 | 说明 |
+| --- | --- |
+| `hot_update` | 是否热更新。 |
+| `version_code` | 新版本号。 |
+| `force_update` | 是否强制更新。 |
+| `external_install` | 是否外部安装。 |
+| `wgt_url` | App WGT 资源地址。 |
+| `zip_url` | 桌面资源包地址。 |
+| `apk_url` | Android 安装包地址。 |
+| `ipa_url` | iOS 安装包地址。 |
+| `exe_url` | Windows 安装包地址。 |
+| `dmg_url` | macOS 安装包地址。 |
+
+具体更新执行逻辑以 `@zfqh/uniapp/lib/utils/update` 的发布实现为准。