@zfqh/uniapp 0.1.1

package/docs/api/utils/cos.md

@@ -0,0 +1,269 @@
+# COS 上传
+
+::: tip 工具模块
+`@zfqh/uniapp/lib/utils/cos`
+:::
+
+基于腾讯云 COS 临时密钥上传文件，并提供图片压缩 URL 拼接能力。
+
+## 平台兼容性
+
+| App | H5 | 微信小程序 | 其他小程序 | WebView |
+| --- | --- | --- | --- | --- |
+| √ | √ | √ | 视平台 API 而定 | 视运行容器而定 |
+
+## 基本使用
+
+```ts
+import { cos } from '@zfqh/uniapp';
+```
+
+## 上传文件
+
+```ts
+import { cos } from '@zfqh/uniapp';
+
+// 直接传入 uni.chooseImage 的 tempFiles 文件对象（推荐）
+const { url } = await cos.uploadFile(res.tempFiles[0]);
+
+// 传入临时路径
+const { url } = await cos.uploadFile({ path: tempFilePath });
+
+// 指定子目录
+const { url } = await cos.uploadFile(file, { path: 'avatar/' });
+
+// 指定完整 key
+const { url } = await cos.uploadFile(file, { key: 'avatar/user-1.png' });
+```
+
+`uploadFile` 支持多种文件来源：
+
+| 来源 | 字段 |
+| --- | --- |
+| `uni.chooseImage` 的 `tempFiles` | 直接传入 `res.tempFiles[0]`（推荐） |
+| 临时路径对象 | `{ path: '...' }` |
+| H5 File 对象 | 直接传入 File |
+| 自定义文件名 | `{ name: 'photo.jpg', path: '...' }` |
+
+未指定 `key` 时会自动生成：`<path><yyyymmddhhMMss><guid>.<ext>`
+
+## 完整上传流程
+
+### 回调风格（推荐）
+
+直接传入 `res.tempFiles[0]` 文件对象：
+
+```ts
+import { cos, toast } from '@zfqh/uniapp';
+
+uni.chooseImage({
+  count: 1,
+  sizeType: ['compressed'],
+  sourceType: ['album'],
+  async success(res) {
+    try {
+      toast.loading('上传中');
+      const { url } = await cos.uploadFile(res.tempFiles[0]);
+      imageUrl.value = url;
+    } catch (e) {
+      if (e?.message) {
+        toast.message(e.message);
+      }
+    } finally {
+      toast.hideLoading();
+    }
+  },
+});
+```
+
+### Promise 风格
+
+使用 `res.tempFilePaths` 包装为对象传入：
+
+```ts
+import { cos, toast } from '@zfqh/uniapp';
+
+async function uploadImage() {
+  try {
+    const res = await uni.chooseImage({ count: 1, sizeType: ['compressed'] });
+    toast.loading('上传中');
+    const { url } = await cos.uploadFile({ path: res.tempFilePaths[0] });
+    return url;
+  } catch (e) {
+    toast.message(e?.message || '上传失败');
+  } finally {
+    toast.hideLoading();
+  }
+}
+```
+
+## 图片压缩 URL
+
+```ts
+import { cosCompress } from '@zfqh/uniapp';
+
+// 缩放到宽度 200px
+cosCompress(imageUrl, '200x');
+
+// 裁剪为 200x200
+cosCompress(imageUrl, '200x200', 'cut');
+
+// 旋转
+cosCompress(imageUrl, '90', 'rotate');
+```
+
+基于腾讯云 COS `imageMogr2` 参数拼接，最终 URL 格式：`${url}?imageMogr2/${type}/${rule}/format/webp`
+
+## 手动刷新凭证
+
+```ts
+import { checkRefreshToken } from '@zfqh/uniapp';
+
+// 手动刷新 COS 临时凭证（uploadFile 内部会自动调用）
+await checkRefreshToken();
+```
+
+## API
+
+发布路径：`@zfqh/uniapp/lib/utils/cos`
+
+| 名称 | 签名/声明 | 说明 |
+| --- | --- | --- |
+| `checkRefreshToken` | `export async function checkRefreshToken(): Promise<boolean> {` | 调用 upload.request({ mode: "cos" }) 获取并缓存 COS 临时密钥；1 秒内并发上传复用同一个请求。 |
+| `uploadFile` | `export async function uploadFile(file: any, opts: UploadFileOptions = {}): Promise<{ url: string }> {` | 上传文件到腾讯 COS，自动生成 key、刷新过期 token，并返回 https url。 |
+| `cosCompress` | `export function cosCompress(url: string, rule: string, type?: string): string {` | 基于腾讯云 COS `imageMogr2` 拼接图片压缩 URL。`rule` 为尺寸规则（如 `'200x'`、`'200x200'`），`type` 可选 `'cut'`（裁剪）或默认（缩放）。 |
+
+`cosCompress` 常用示例：
+
+```ts
+import { cosCompress } from '@zfqh/uniapp';
+
+// 缩放到宽度 200px
+const thumbnail = cosCompress(imageUrl, '200x');
+
+// 裁剪为 200x200
+const avatar = cosCompress(imageUrl, '200x200', 'cut');
+```
+
+## COS 上传指南
+
+根入口导出：
+
+```ts
+import { cos } from '@zfqh/uniapp';
+```
+
+上传文件：
+
+```ts
+const { url } = await cos.uploadFile(file, {
+  path: 'avatar/',
+});
+```
+
+指定完整 key：
+
+```ts
+const { url } = await cos.uploadFile(file, {
+  key: 'avatar/user-1.png',
+});
+```
+
+## 临时凭证
+
+上传前会调用：
+
+```ts
+config.upload.request({ mode: 'cos' });
+```
+
+需要在 `defineConfig` 中配置：
+
+```ts
+import { defineConfig } from '@zfqh/uniapp';
+import { getTencentToken } from '@zfqh/uniapp/lib/apis';
+
+defineConfig({
+  upload: {
+    async request() {
+      const { data } = await getTencentToken();
+      return {
+        secret_id: data.tmpSecretId,
+        secret_key: data.tmpSecretKey,
+        session_token: data.sessionToken,
+        create_time: data.createTime,
+        expire_time: data.expirationTime,
+        bucket: data.bucket,
+        region: data.region,
+      };
+    },
+  },
+});
+```
+
+门店端如果需要全球加速，可根据业务 store 改写 `region`：
+
+```ts
+import { getTencentToken } from '@zfqh/uniapp/lib/apis';
+import store from '@/store';
+
+defineConfig({
+  upload: {
+    async request() {
+      const { data } = await getTencentToken();
+      return {
+        secret_id: data.tmpSecretId,
+        secret_key: data.tmpSecretKey,
+        session_token: data.sessionToken,
+        create_time: data.createTime,
+        expire_time: data.expirationTime,
+        bucket: data.bucket,
+        region: store.state.storeConfig.isGlobalAccelerate ? 'accelerate' : data.region,
+      };
+    },
+  },
+});
+```
+
+`getTencentToken` 是内置业务接口，来自 `@zfqh/uniapp/lib/apis`，路径为 `/app-api/infra/file/getTencentToken`。如果项目有自定义接口，可以替换请求函数，但必须把响应字段映射成下方 COS 字段。
+
+返回字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `secret_id` | 临时密钥 ID。 |
+| `secret_key` | 临时密钥 Key。 |
+| `session_token` | 临时 token。 |
+| `bucket` | COS bucket。 |
+| `region` | COS region。 |
+| `create_time` | 创建时间戳，秒。 |
+| `expire_time` | 过期时间戳，秒。 |
+
+## 上传文件对象
+
+`uploadFile` 支持：
+
+| 来源 | 字段 |
+| --- | --- |
+| uni 选择文件 | `file.path` |
+| H5 File 对象 | `file` |
+| 自定义文件名 | `file.name` 用于推断扩展名 |
+
+未指定 `key` 时会自动生成：
+
+```text
+&lt;path&gt;&lt;yyyymmddhhMMss&gt;&lt;guid&gt;.&lt;ext&gt;
+```
+
+## 图片压缩 URL
+
+```ts
+const url = cos.compress(originUrl, '200x');
+const cutUrl = cos.compress(originUrl, '200x200', 'cut');
+```
+
+实现基于腾讯云 COS `imageMogr2` 参数：
+
+```text
+imageMogr2/&lt;type&gt;/&lt;rule&gt;/format/webp
+```

package/docs/api/utils/debounce.md

@@ -0,0 +1,89 @@
+# 防抖
+
+::: tip 工具模块
+`@zfqh/uniapp/lib/utils/debounce`
+:::
+
+提供类实例和默认实例，适合搜索输入、表单提交和按钮防重复点击。
+
+## 平台兼容性
+
+| App | H5 | 微信小程序 | 其他小程序 | WebView |
+| --- | --- | --- | --- | --- |
+| √ | √ | √ | 视平台 API 而定 | 视运行容器而定 |
+
+## 基本使用
+
+```ts
+import { Debounce, debounce } from '@zfqh/uniapp';
+
+// 使用默认实例（简单场景）
+debounce.exec(() => submit(), 300);
+
+// 创建独立实例（多个防抖互不干扰）
+const searchDebounce = new Debounce();
+searchDebounce.exec(() => search(keyword), 300);
+```
+
+## API
+
+发布路径：`@zfqh/uniapp/lib/utils/debounce`
+
+| 名称 | 签名/声明 | 说明 |
+| --- | --- | --- |
+| `Debounce` | `export default function Debounce()` | 防抖类，可创建独立实例。 |
+| `debounce` | `export const debounce = new Debounce();` | 默认防抖实例，适合单一防抖场景快捷使用。 |
+
+### exec 方法
+
+```ts
+exec(func: Function, wait?: number, immediate?: boolean): void
+```
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `func` | - | 要执行的回调函数 |
+| `wait` | `500` | 延迟时间（毫秒） |
+| `immediate` | `false` | 是否立即执行（首次触发立即执行，后续在 wait 内不再触发） |
+
+## 典型场景
+
+### 搜索输入
+
+```ts
+const searchDebounce = new Debounce();
+
+function onInput(e) {
+  searchDebounce.exec(() => {
+    search(e.detail.value);
+  }, 300);
+}
+```
+
+### 表单提交防重复
+
+```ts
+import { debounce } from '@zfqh/uniapp';
+
+function onSubmit() {
+  debounce.exec(() => {
+    submitForm(formData);
+  }, 500);
+}
+```
+
+### 多个独立防抖
+
+```ts
+const searchDebounce = new Debounce();
+const filterDebounce = new Debounce();
+
+// 互不影响
+searchDebounce.exec(() => search(keyword), 300);
+filterDebounce.exec(() => applyFilter(filters), 300);
+```
+
+## 使用建议
+
+- `debounce` 为共享实例；多个按钮、输入框或业务动作需要互不影响时，请分别 `new Debounce()`。
+

package/docs/api/utils/file.md

@@ -0,0 +1,78 @@
+# 文件转换
+
+::: tip 工具模块
+`@zfqh/uniapp/lib/utils/file`
+:::
+
+处理 URL、dataURL、base64、File、本地路径之间的互转。
+
+## 平台兼容性
+
+| App | H5 | 微信小程序 | 其他小程序 | WebView |
+| --- | --- | --- | --- | --- |
+| √ | √ | √ | 视平台 API 而定 | 视运行容器而定 |
+
+## 基本使用
+
+```ts
+import { urlToBase64, dataUrlToBase64, base64ToFile, pathToBase64, base64ToPath } from '@zfqh/uniapp';
+```
+
+具体方法、参数语义和返回值以发布包类型为准；下方表格按 `@zfqh/uniapp/lib/utils/file` 的导出整理。
+
+## 使用示例
+
+### 网络图片转 base64
+
+```ts
+// 用于离线缓存图片
+const base64 = await urlToBase64('https://cdn.example.com/avatar.png');
+setStorageSync('cachedAvatar', base64);
+
+// 指定 MIME 类型
+const base64 = await urlToBase64(imageUrl, 'image/jpeg');
+```
+
+### dataURL 提取 base64
+
+```ts
+const dataUrl = 'data:image/png;base64,iVBORw0KGgo...';
+const pureBase64 = dataUrlToBase64(dataUrl); // 'iVBORw0KGgo...'
+```
+
+### H5 端 base64 转 File
+
+```ts
+// H5 相机拍照后转 File 上传
+const { file } = base64ToFile(base64Data, 'photo.jpg');
+const { url } = await cos.uploadFile(file);
+```
+
+### 本地路径转 base64
+
+```ts
+// App/小程序端：本地图片转 base64 缓存
+const base64 = await pathToBase64(tempFilePath);
+setStorageSync('offlineImage', base64);
+```
+
+### base64 写入本地文件
+
+```ts
+// 跨平台：base64 数据写入本地临时文件
+const { path } = await base64ToPath(base64Data, 'report.png');
+// path 可用于 <image :src="path"> 显示
+```
+
+## API
+
+发布路径：`@zfqh/uniapp/lib/utils/file`
+
+| 名称 | 签名/声明 | 说明 |
+| --- | --- | --- |
+| `urlToBase64` | `export function urlToBase64(url, type = 'webp') {` | 把网络图片或平台本地图片读取为 dataURL base64。 |
+| `dataUrlToBase64` | `export function dataUrlToBase64(url = '') {` | 从 dataURL 中截取纯 base64 内容。 |
+| `base64ToFile` | `export function base64ToFile(base64 = '', filename = '') {` | H5 下把 dataURL 转为 File 对象。 |
+| `pathToBase64` | `export function pathToBase64(path: string) {` | 跨 H5/App/小程序把本地路径读取为 dataURL。 |
+| `base64ToPath` | `export function base64ToPath(base64 = '', filename = '') {` | 跨 H5/App/小程序把 dataURL 写入临时本地文件并返回路径。 |
+