@zfqh/uniapp 0.3.17 → 0.3.18

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.3.18](http://10.10.10.16/caoben/front-end/compare/@zfqh/uniapp@0.3.17...@zfqh/uniapp@0.3.18) (2026-09-16)
+
+**Note:** Version bump only for package @zfqh/uniapp
+
+
+
+
+
 ## [0.3.17](http://10.10.10.16/caoben/front-end/compare/@zfqh/uniapp@0.3.16...@zfqh/uniapp@0.3.17) (2026-09-03)
 
 **Note:** Version bump only for package @zfqh/uniapp

package/docs/api/utils/cos.md

@@ -45,7 +45,52 @@ const { url } = await cos.uploadFile(file, { key: 'avatar/user-1.png' });
 | H5 File 对象 | 直接传入 File |
 | 自定义文件名 | `{ name: 'photo.jpg', path: '...' }` |
 
-未指定 `key` 时会自动生成：`<path><yyyymmddhhMMss><guid>.<ext>`
+未指定 `key` 时会自动生成：`<path><yyyymmdd>/<hhMMss><guid>.<ext>`（`yyyymmdd` 用于按日期分目录，`hhMMss` 便于看出日内上传先后）
+
+## 取消上传
+
+传入 `getTask` 可以拿到 `uni.uploadFile` 返回的 `UploadTask` 实例，需要时调用 `task.abort()` 取消本次上传：
+
+```ts
+import { cos } from '@zfqh/uniapp';
+
+let task;
+
+const { url } = await cos.uploadFile(file, {
+  path: 'avatar/',
+  getTask(obj) {
+    task = obj;
+  },
+});
+
+// 需要取消时（例如用户点了删除、离开页面）
+task?.abort();
+```
+
+`getTask(obj)` 的写法也可以直接使用：
+
+```ts
+let task;
+
+cos.uploadFile({
+  Bucket: 'xxx-1250000000',
+  Region: 'ap-nanjing',
+  Key: 'avatar/user-1.png',
+  FilePath: tempFilePath,
+  getTask(obj) {
+    task = obj;
+  },
+});
+```
+
+### 注意事项
+
+- `getTask` 在**每次** `uni.uploadFile` 调用时都会回调。token 过期（`ExpiredToken`）触发内部重试时会创建新的 task 并再次回调，因此请始终使用**最近一次**回调收到的 task，不要缓存第一次的。
+- 取消会让该次上传的 Promise reject，但各端错误文案不一致：H5 为 `uploadFile:fail abort`，App 为 `uploadFile:fail statusCode: 0`（**不含 `abort` 字样**），微信小程序通常为 `uploadFile:fail abort`。请不要通过匹配错误文案判断是否被取消。
+- App 端调用 `abort()` 后不保证触发 `fail` 回调，Promise 可能一直 pending，取消后的 UI 状态需要业务自行切换。
+- 取消支持的范围为 App / H5 / 微信小程序。支付宝小程序 `my.uploadFile` 的 `abort` 需要传参对象，无参 `abort()` 可能无效。
+- 上传已完成后再调用 `abort()` 是空操作。
+- H5 端请勿调用 `task.onHeadersReceived` / `task.offHeadersReceived`（H5 实现为直接抛错）。
 
 ## 完整上传流程
 
@@ -131,6 +176,14 @@ await checkRefreshToken();
 | --- | --- | --- |
 | `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。 |
+
+`UploadFileOptions` 支持的选项：
+
+| 选项 | 类型 | 说明 |
+| --- | --- | --- |
+| `path` | `string` | key 前缀（子目录），如 `'avatar/'`。 |
+| `key` | `string` | 完整 key，传入时忽略自动生成的 key。 |
+| `getTask` | `(task: UniNamespace.UploadTask) => void` | 获取本次上传的 `UploadTask`，可用 `task.abort()` 取消。每次上传尝试（含 token 过期重试）都会回调。 |
 | `cosCompress` | `export function cosCompress(url: string, rule: string, type?: string): string {` | 基于腾讯云 COS `imageMogr2` 拼接图片压缩 URL。`rule` 为尺寸规则（如 `'200x'`、`'200x200'`），`type` 可选 `'cut'`（裁剪）或默认（缩放）。 |
 
 `cosCompress` 常用示例：
@@ -251,7 +304,7 @@ defineConfig({
 未指定 `key` 时会自动生成：
 
 ```text
-&lt;path&gt;&lt;yyyymmddhhMMss&gt;&lt;guid&gt;.&lt;ext&gt;
+&lt;path&gt;&lt;yyyymmdd&gt;/&lt;hhMMss&gt;&lt;guid&gt;.&lt;ext&gt;
 ```
 
 ## 图片压缩 URL

package/lib/utils/cos.d.ts

@@ -1,8 +1,10 @@
 import { cosCompress } from './index';
 export declare function checkRefreshToken(): Promise<boolean>;
-interface UploadFileOptions {
+export interface UploadFileOptions {
     key?: string;
     path?: string;
+    /** 获取上传任务实例，可用于 task.abort() 取消上传；token 过期重试时会再次回调 */
+    getTask?: ((task: UniNamespace.UploadTask) => void) | ((task: any) => void);
 }
 export declare function uploadFile(file: any, opts?: UploadFileOptions): Promise<{
     url: string;

package/lib/utils/cos.js

@@ -54,7 +54,7 @@ class COS {
                 'q-key-time': qKeyTime,
                 'q-signature': qSignature,
             };
-            uni.uploadFile({
+            const task = uni.uploadFile({
                 url: `https://${cosHost}`,
                 filePath: FilePath,
                 file: File,
@@ -102,6 +102,7 @@ class COS {
                     });
                 },
             });
+            params.getTask?.(task);
         });
     }
 }
@@ -114,12 +115,14 @@ export async function uploadFile(file, opts = {}) {
             ext = match[0];
         }
     }
-    const key = `${opts.path || ''}${uni.$uv.timeFormat(new Date().getTime(), 'yyyymmddhhMMss')}${uni.$uv.guid(50)}${ext}`;
+    const [day, clock] = uni.$uv.timeFormat(new Date().getTime(), 'yyyymmdd hhMMss').split(' ');
+    const key = `${opts.path || ''}${day}/${clock}${uni.$uv.guid(30)}${ext}`;
     await checkRefreshToken();
     const params = {
         Bucket: data.bucket,
         Region: data.region,
         Key: opts.key || key,
+        getTask: opts.getTask,
     };
     if (file.path) {
         params.FilePath = file.path;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zfqh/uniapp",
-  "version": "0.3.17",
+  "version": "0.3.18",
   "description": "uniapp公共模块",
   "author": "yinjiazeng@163.com",
   "license": "MIT",
@@ -45,6 +45,5 @@
     "@types/crypto-js": "^4.2.2",
     "@types/qs": "^6.9.16",
     "@types/url-parse": "^1.4.11"
-  },
-  "gitHead": "d56ac10822cd04b832695122cc7daa21e67d6628"
+  }
 }

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024 aniu
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.