@zfqh/uniapp 0.1.1

package/docs/api/utils/index.md

@@ -0,0 +1,547 @@
+# 工具
+
+工具文档按 `@zfqh/uniapp/lib/utils` 发布路径组织，每个 Markdown 文件对应一个独立功能文件。`index.md` 对应 `@zfqh/uniapp/lib/utils`，用于说明根入口导出的通用工具函数。
+
+## 文件清单
+
+| 文件 | 说明 |
+| --- | --- |
+| [index](./) | 通用工具函数，包含图片路径、日期、路径拼接、webview 通信、脱敏、数值格式化等方法。 |
+| [audio](./audio) | 封装互斥播放、停止和销毁逻辑。 |
+| [consts](./consts) | 暴露系统信息、小程序胶囊、webview 环境、平台代码和语言常量。 |
+| [cos](./cos) | 腾讯云 COS 上传与图片压缩 URL。 |
+| [debounce](./debounce) | 防抖类和默认实例。 |
+| [file](./file) | URL、dataURL、base64、File、本地路径互转。 |
+| [locale](./locale) | 当前语言、回退语言和 nvue 文案读取。 |
+| [message](./message) | webview 与宿主环境通信的消息类型常量。 |
+| [navigate](./navigate) | 页面跳转、登录拦截、tabBar、webview、自定义协议。 |
+| [pages](./pages) | 根据页面配置生成页面集合。 |
+| [permission](./permission) | 平台运行时补丁或内部实现。 |
+| [permit](./permit) | App/小程序权限申请。 |
+| [query](./query) | 当前页面或 H5 地址栏 query 解析。 |
+| [request](./request) | 请求方法创建和通用拦截器。 |
+| [storage](./storage) | uni storage 项目和环境命名空间。 |
+| [subscribe](./subscribe) | 微信小程序订阅消息调用。 |
+| [throttle](./throttle) | 节流类和默认实例。 |
+| [toast](./toast) | loading、toast、success、error、fail、exception 和自定义提示适配。 |
+| [uni](./uni) | 平台运行时补丁或内部实现。 |
+| [update](./update) | App、Electron H5、小程序更新。 |
+
+## 通用工具
+
+根入口导出了多组常用工具。
+
+## 基本使用
+
+```ts
+import {
+  transformImagePath,
+  transformLinkPath,
+  requestDelay,
+  dateStringToTime,
+  cutDate,
+  timeFrom,
+  getRectById,
+  joinPath,
+  postMessage,
+  openLocation,
+  codeSplit,
+  parentCall,
+  deepMerge,
+  navigateBack,
+  cosCompress,
+  phoneCall,
+  copyToClipboard,
+  hiddenValue,
+  hiddenPhone,
+  formatPhone,
+  toFixed,
+  OptionsToObject,
+  numberPlus,
+} from '@zfqh/uniapp';
+```
+
+## requestDelay
+
+`requestDelay` 用于保证异步操作至少持续指定时间，防止接口响应过快导致 loading 状态闪烁。
+
+```ts
+import { requestDelay } from '@zfqh/uniapp';
+```
+
+签名：
+
+```ts
+requestDelay<T>(fn: () => Promise<T>, delay?: number): Promise<T>
+```
+
+- `fn`：返回 Promise 的异步函数。
+- `delay`：最小持续时间（毫秒），默认 `500`。
+
+典型用法：
+
+```ts
+// 保证提交操作至少展示 500ms loading
+await requestDelay(() => submitOrder(data));
+
+// 自定义延迟时间
+await requestDelay(() => fetchData(), 800);
+```
+
+常与 `toast.loading` 配合使用：
+
+```ts
+import { toast, requestDelay } from '@zfqh/uniapp';
+
+toast.loading('提交中');
+await requestDelay(() => submitOrder(data));
+toast.success('提交成功');
+```
+
+## 日期时间
+
+```ts
+import { cutDate, dateStringToTime, timeFrom } from '@zfqh/uniapp';
+```
+
+| 方法 | 签名 | 说明 |
+| --- | --- | --- |
+| `cutDate` | `cutDate(date: string): string` | 截取日期部分，去掉时间。`'2024-01-15 10:30:00'` → `'2024-01-15'` |
+| `dateStringToTime` | `dateStringToTime(date: string \| number): number` | 日期字符串转时间戳（毫秒）。传入数字直接返回，字符串兼容 `-` 和 `/` 分隔符 |
+| `timeFrom` | `timeFrom(time: string \| number, separate?: string): string` | 相对时间描述 |
+
+`timeFrom` 输出规则：
+
+| 时间差 | 输出 |
+| --- | --- |
+| < 1 分钟 | `'刚刚'` |
+| < 1 小时 | `'N分钟前'` |
+| < 1 天 | `'N小时前'` |
+| 1 ~ 2 天 | `'昨天 HH:MM'` |
+| 2 ~ 7 天 | `'N天前'` |
+| > 7 天（同年） | `'MM-DD HH:MM'` |
+| > 7 天（跨年） | `'YYYY-MM-DD HH:MM'` |
+
+```ts
+cutDate('2024-01-15 10:30:00'); // '2024-01-15'
+dateStringToTime('2024-01-15'); // 1705276800000
+timeFrom('2024-01-15 10:30:00'); // '昨天 10:30'（如果距当前 1-2 天）
+```
+
+## 电话
+
+```ts
+import { phoneCall } from '@zfqh/uniapp';
+
+phoneCall('18888888888');
+```
+
+`phoneCall(phoneNumber: string)` 调用 `uni.makePhoneCall` 拨打电话。传入空值不触发。
+
+## 图片路径
+
+```ts
+import { transformImagePath } from '@zfqh/uniapp';
+```
+
+`transformImagePath<T>(images: T, path: string, useImages?: boolean): T`
+
+批量为图片对象拼接 CDN 前缀。已有 `https?://` 前缀的值不做处理，相对路径会拼接为 `${path}/${dir}${value}`。`useImages` 为 `true` 时路径中会插入 `/images` 目录。
+
+```ts
+const images = {
+  avatar: 'user1.png',
+  banner: 'https://cdn.example.com/banner.jpg',
+};
+
+transformImagePath(images, 'https://cdn.example.com');
+// images.avatar → 'https://cdn.example.com/avatar/user1.png'
+// images.banner → 'https://cdn.example.com/banner.jpg'（不变）
+```
+
+## 链接路径
+
+```ts
+import { transformLinkPath } from '@zfqh/uniapp';
+```
+
+`transformLinkPath<T>(links: T, path: string): T`
+
+批量为链接对象拼接 CDN 前缀。只有 `url` 为空的对象会被处理，拼接为 `${path}/${key}.html`。
+
+```ts
+const links = {
+  agreement: { url: '', title: '用户协议' },
+  privacy: { url: 'https://example.com/privacy', title: '隐私政策' },
+};
+
+transformLinkPath(links, 'https://cdn.example.com/pages');
+// links.agreement.url → 'https://cdn.example.com/pages/agreement.html'
+// links.privacy.url → 'https://cdn.example.com/privacy'（不变）
+```
+
+## 发送消息
+
+```ts
+import { postMessage } from '@zfqh/uniapp';
+```
+
+`postMessage(data: { type: string; payload: Record<string, string> }): void`
+
+向 webview 子页面发送消息。H5 端通过 `window.postMessage` 发送，小程序端通过 `uni.webView.postMessage` 发送。仅在 H5 平台有效。
+
+```ts
+// 向 webview 内的 H5 页面发送数据
+postMessage({
+  type: 'UPDATE_DATA',
+  payload: { userId: '123', token: 'xxx' },
+});
+```
+
+## 打开地图
+
+```ts
+import { openLocation } from '@zfqh/uniapp';
+```
+
+`openLocation(data: UniNamespace.OpenLocationOptions): void`
+
+调用 `uni.openLocation` 打开地图导航。失败时自动弹出提示。
+
+```ts
+openLocation({
+  latitude: 39.908823,
+  longitude: 116.397470,
+  name: '天安门广场',
+  address: '北京市东城区长安街',
+});
+```
+
+## 编码分段
+
+```ts
+import { codeSplit } from '@zfqh/uniapp';
+```
+
+`codeSplit(code: string | number, format?: number[]): string`
+
+按指定格式用空格拆分编码字符串。
+
+```ts
+codeSplit('18888888888', [3, 4, 4]); // '188 8888 8888'
+codeSplit('110101199001011234', [6, 8, 4]); // '110101 19900101 1234'
+```
+
+## 调用父组件方法
+
+```ts
+import { parentCall } from '@zfqh/uniapp';
+```
+
+`parentCall(name: string, ...args: any[]): any`
+
+在 Options API 子组件中向上遍历父组件链，调用第一个匹配的方法。需要通过 `.call(this, ...)` 传入当前组件实例。
+
+```ts
+export default {
+  methods: {
+    onSubmit() {
+      // 调用最近的父组件中的 refresh 方法
+      parentCall.call(this, 'refresh');
+
+      // 带参数调用
+      parentCall.call(this, 'handleResult', { id: 1 });
+    },
+  },
+};
+```
+
+## 深度合并
+
+```ts
+import { deepMerge } from '@zfqh/uniapp';
+```
+
+`deepMerge(target: object, ...sources: object[]): object`
+
+深度合并多个对象，`null` 和 `undefined` 值不会覆盖已有属性。数组不做合并，直接替换。
+
+```ts
+const defaults = { a: 1, b: { c: 2, d: 3 } };
+const overrides = { b: { c: 10 }, e: 5 };
+
+deepMerge(defaults, overrides);
+// → { a: 1, b: { c: 10, d: 3 }, e: 5 }
+```
+
+## 返回并通信
+
+```ts
+import { navigateBack } from '@zfqh/uniapp';
+```
+
+`navigateBack(options?: NavigateBackOptions & { method?: string; emit?: string; data?: any }): void`
+
+在 `uni.navigateBack` 基础上增加了三种页面间通信方式：
+
+```ts
+// 方式1：调用上一页的指定方法
+navigateBack({ method: 'refresh' });
+navigateBack({ method: 'handleResult', data: { id: 1 } });
+
+// 方式2：通过 uni.$emit 发送事件
+navigateBack({ emit: 'orderCreated', data: { orderId: '123' } });
+
+// 方式3：普通返回（不通信）
+navigateBack({ delta: 2 });
+navigateBack();
+```
+
+## 脱敏显示
+
+```ts
+import { hiddenValue, hiddenPhone, formatPhone } from '@zfqh/uniapp';
+```
+
+| 方法 | 签名 | 说明 |
+| --- | --- | --- |
+| `hiddenValue` | `hiddenValue(str: string, start?: number, end?: number): string` | 保留前后指定位数，中间替换为 `*` |
+| `hiddenPhone` | `hiddenPhone(phone: string \| number): string` | 手机号脱敏，保留前 3 后 4 |
+| `formatPhone` | `formatPhone(phone: string \| number): string` | 手机号格式化为 `188 8888 8888` |
+
+```ts
+hiddenValue('6222021234567890', 4, 4); // '6222********7890'
+hiddenPhone('18888888888'); // '188****8888'
+formatPhone('18888888888'); // '188 8888 8888'
+```
+
+## 数字格式化
+
+```ts
+import { toFixed, numberPlus } from '@zfqh/uniapp';
+```
+
+| 方法 | 签名 | 说明 |
+| --- | --- | --- |
+| `toFixed` | `toFixed(value: string \| number, decimal?: number): string` | 小数位控制，默认 2 位 |
+| `numberPlus` | `numberPlus(num: number \| string, min?: number): string` | 超过阈值显示 `N+`，默认阈值 100 |
+
+```ts
+toFixed('12.345', 2); // '12.35'
+toFixed(100, 2); // '100.00'
+numberPlus(1234); // '1000+'
+numberPlus(50); // '50'
+numberPlus(999, 500); // '500+'
+```
+
+## 选项转对象
+
+```ts
+import { OptionsToObject } from '@zfqh/uniapp';
+```
+
+`OptionsToObject(data: any): object`
+
+将选项数组转为对象，方便按 key 查找。
+
+```ts
+const options = [
+  { key: 'status', label: '状态' },
+  { key: 'type', label: '类型' },
+];
+
+OptionsToObject(options);
+// → { status: { key: 'status', label: '状态' }, type: { key: 'type', label: '类型' } }
+```
+
+## 路径拼接
+
+```ts
+import { joinPath } from '@zfqh/uniapp';
+```
+
+`joinPath(base?: string, path?: string): string`
+
+拼接路径，支持相对路径解析（`.` 和 `..`）。自动处理 query 参数。
+
+```ts
+joinPath('/pages/a/index?id=1', '../b/index'); // '/pages/b/index'
+joinPath('/pages/a/index', './detail'); // '/pages/a/detail'
+joinPath('/pages/a/index', '../b/detail?tab=1'); // '/pages/b/detail?tab=1'
+```
+
+## 复制到剪贴板
+
+```ts
+import { copyToClipboard } from '@zfqh/uniapp';
+```
+
+`copyToClipboard(text?: string, tips?: string): void`
+
+复制文本到系统剪贴板，成功后弹出提示（默认 `'内容已复制'`）。微信小程序端不弹额外提示（系统自带）。
+
+```ts
+copyToClipboard('订单号: 123456');
+copyToClipboard('邀请码', '邀请码已复制'); // 自定义提示文案
+```
+
+## DOM 元素定位
+
+```ts
+import { getRectById } from '@zfqh/uniapp';
+```
+
+`getRectById(id: string): Promise<{ data: { height, width, top, bottom, left, right } }>`
+
+获取指定 id 元素的尺寸和位置信息，常用于浮层定位、滚动目标计算等场景。
+
+```ts
+// Options API：需要通过 this 上下文限定查询范围
+export default {
+  mounted() {
+    getRectById.call(this, 'target').then(({ data }) => {
+      console.log(data.height, data.top);
+    });
+  },
+};
+```
+
+```ts
+// Composition API：需要传入组件实例
+import { getCurrentInstance } from 'vue';
+import { getRectById } from '@zfqh/uniapp';
+
+const instance = getCurrentInstance();
+getRectById.call(instance.proxy, 'target').then(({ data }) => {
+  console.log(data.width, data.left);
+});
+```
+
+## 文件工具
+
+```ts
+import { urlToBase64, dataUrlToBase64, base64ToFile, pathToBase64, base64ToPath } from '@zfqh/uniapp';
+```
+
+| 方法 | 说明 |
+| --- | --- |
+| `urlToBase64(url, type?)` | 网络图片转 base64。`type` 指定 MIME 类型（默认 `'image/png'`） |
+| `dataUrlToBase64(url)` | 从 data URL 中提取 base64 数据部分 |
+| `base64ToFile(base64, filename)` | base64 转 File 对象（H5 端） |
+| `pathToBase64(path)` | 本地路径转 base64（App/小程序端） |
+| `base64ToPath(base64, filename)` | base64 写入本地临时路径，返回文件路径 |
+
+```ts
+// H5 端：相机拍照后转 File 上传
+const { file } = base64ToFile(base64Data, 'photo.jpg');
+const { url } = await cos.uploadFile(file);
+
+// App 端：本地图片转 base64 缓存
+const base64 = await pathToBase64(tempFilePath);
+setStorageSync('cachedImage', base64);
+
+// 网络图片转 base64 用于离线显示
+const base64 = await urlToBase64('https://cdn.example.com/avatar.png');
+```
+
+## 本地存储
+
+```ts
+import {
+  getStorage,
+  getStorageSync,
+  setStorage,
+  setStorageSync,
+  removeStorage,
+  removeStorageSync,
+  clearStorage,
+  clearStorageSync,
+  storageKeys,
+} from '@zfqh/uniapp';
+```
+
+存储 key 会自动拼接 `config.storage.prefix` 前缀和环境名（非 prod 环境）。实际存储的 key 格式为 `PREFIX_ENV_NAME`（全大写）。
+
+### storageKeys
+
+内置 key 常量：`query`、`login`、`user`、`open`、`launch`、`location`。
+
+```ts
+// 保存登录信息
+setStorageSync(storageKeys.login, { token: 'xxx', userId: 1 });
+
+// 读取登录信息
+const loginInfo = getStorageSync(storageKeys.login);
+
+// 删除缓存
+removeStorageSync(storageKeys.login);
+```
+
+### 完整工作流
+
+```ts
+// 同步操作（推荐在非异步上下文使用）
+setStorageSync('formData', { name: '张三', age: 30 });
+const form = getStorageSync('formData');
+removeStorageSync('formData');
+
+// 异步操作
+await setStorage('asyncKey', { data: 'value' });
+const result = await getStorage('asyncKey');
+await removeStorage('asyncKey');
+
+// 清除所有缓存（谨慎使用）
+clearStorageSync();
+```
+
+## 页面工具
+
+```ts
+import { getPage, inPages, createPages } from '@zfqh/uniapp';
+```
+
+| 方法 | 说明 |
+| --- | --- |
+| `getPage(name)` | 从 `config.path` 页面别名中获取页面路径 |
+| `inPages(pages, url)` | 判断 URL 是否命中页面集合 |
+| `createPages(pagesJson)` | 从 pages.json 生成页面集合配置 |
+
+```ts
+// 获取登录页路径
+const loginPath = getPage('login'); // '/pages/login/login'
+
+// 判断是否需要登录
+const needLogin = inPages(config.page.needLoginPages, '/pages/user/profile');
+```
+
+## 请求工具
+
+```ts
+import { formatURL, createInterceptors, createRequest } from '@zfqh/uniapp';
+```
+
+通常只有自定义请求实例时才需要使用，业务请求推荐引用 `@zfqh/uniapp/lib/apis`。详见 [请求封装](./request)。
+
+## 权限和订阅
+
+```ts
+import { requestPermission, openAuthorizeSetting, subscribeMessage } from '@zfqh/uniapp';
+```
+
+详见 [权限申请](./permit) 和 [订阅消息](./subscribe)。
+
+## 音频
+
+```ts
+import { Audio } from '@zfqh/uniapp';
+```
+
+详见 [音频](./audio)。
+
+## 防抖与节流
+
+```ts
+import { Debounce, debounce, Throttle, throttle } from '@zfqh/uniapp';
+```
+
+详见 [防抖](./debounce) 和 [节流](./throttle)。

package/docs/api/utils/locale.md

@@ -0,0 +1,32 @@
+# 多语言辅助
+
+::: tip 工具模块
+`@zfqh/uniapp/lib/utils/locale`
+:::
+
+提供当前语言、回退语言和 nvue 可用的简易文案读取方法。
+
+## 平台兼容性
+
+| App | H5 | 微信小程序 | 其他小程序 | WebView |
+| --- | --- | --- | --- | --- |
+| √ | √ | √ | 视平台 API 而定 | 视运行容器而定 |
+
+## 基本使用
+
+```ts
+import { defaultLocale, fallbackLocale, showLocale } from '@zfqh/uniapp';
+```
+
+具体方法、参数语义和返回值以发布包类型为准；下方表格按 `@zfqh/uniapp/lib/utils/locale` 的导出整理。
+
+## API
+
+发布路径：`@zfqh/uniapp/lib/utils/locale`
+
+| 名称 | 签名/声明 | 说明 |
+| --- | --- | --- |
+| `defaultLocale` | `export const defaultLocale = uni.getLocale();` | 默认语言。 |
+| `fallbackLocale` | `export const fallbackLocale = 'zh-Hans';` | 回退语言。 |
+| `showLocale` | `export function showLocale(key, values) {` | nvue 场景下的简易 i18n 文案获取函数。 |
+

package/docs/api/utils/message.md

@@ -0,0 +1,81 @@
+# 消息常量
+
+::: tip 工具模块
+`@zfqh/uniapp/lib/utils/message`
+:::
+
+定义 webview 与宿主环境通信时使用的消息类型常量。
+
+## 平台兼容性
+
+| App | H5 | 微信小程序 | 其他小程序 | WebView |
+| --- | --- | --- | --- | --- |
+| √ | √ | √ | 视平台 API 而定 | 视运行容器而定 |
+
+## 基本使用
+
+```ts
+import { TYPES } from '@zfqh/uniapp';
+```
+
+也可以从深度路径引入：
+
+```ts
+import { TYPES } from '@zfqh/uniapp/lib/utils/message';
+```
+
+## API
+
+发布路径：`@zfqh/uniapp/lib/utils/message`
+
+| 名称 | 说明 |
+| --- | --- |
+| `TYPES.LOGIN` | 登录消息，payload 包含 `token` 和 `referrer` |
+| `TYPES.SHARE_PAGE` | 分享页面 |
+| `TYPES.GET_LOCATION` | 获取定位，宿主调用 `uni.getLocation` 后回传结果 |
+| `TYPES.OPEN_LOCATION` | 打开地图，宿主调用 `uni.openLocation` 后回传结果 |
+| `TYPES.CHNAGE_TITLE` | 修改 webview 标题 |
+| `TYPES.SAVE_IMAGE` | 保存图片到相册 |
+| `TYPES.HIDE_LOADING` | 隐藏加载提示 |
+
+## webview 消息通信
+
+`TYPES` 配合 webview mixin 使用。webview 承载页（配置了 `path.webview` 的页面）引入 `webview` mixin 后，会自动处理上述消息类型。
+
+H5 端会自动监听 `window.onmessage`，解析 `WEBVIEW_MESSAGE` 类型的事件并分发到对应的处理逻辑。
+
+### 扩展自定义消息
+
+在 webview mixin 基础上扩展自定义消息类型：
+
+```ts
+import webview from '@zfqh/uniapp/lib/mixins/webview';
+import { TYPES } from '@zfqh/uniapp/lib/utils/message';
+
+export default {
+  mixins: [webview],
+  methods: {
+    onMessage(e) {
+      // 先调用父 mixin 处理内置消息
+      if (this.$options.mixins[0].methods.onMessage) {
+        this.$options.mixins[0].methods.onMessage.call(this, e);
+      }
+      // 处理自定义消息
+      const { type, payload } = e.data || {};
+      if (type === 'CUSTOM_ACTION') {
+        this.handleCustomAction(payload);
+      }
+    },
+  },
+};
+```
+
+### 向 webview 发送消息
+
+```ts
+import { postMessage } from '@zfqh/uniapp';
+
+// 向 webview 子页面发送数据
+postMessage({ type: 'UPDATE_DATA', payload: { key: 'value' } });
+```
+