@zfqh/uniapp 0.3.16 → 0.3.18

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 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
+
+
+
+
+
 ## [0.3.16](http://10.10.10.16/caoben/front-end/compare/@zfqh/uniapp@0.3.15...@zfqh/uniapp@0.3.16) (2026-09-03)
 
 **Note:** Version bump only for package @zfqh/uniapp

package/docs/api/utils/consts.md

@@ -192,10 +192,37 @@ if (config.mp.envVersion === MP_ENV_VERSION.develop) {
 
 ## LANGUAGE 使用示例
 
-当前语言标识，用于请求 header 和国际化。
+当前语言标识，用于请求 header 和国际化。key 为 uni-app/vue-i18n 的 locale 标识，value 为请求头 `X-Language` 的语言代码。
 
 ```ts
 import { LANGUAGE } from '@zfqh/uniapp';
 
-headers['X-Language'] = LANGUAGE;
+// locale 取 uni.getLocale() / uni.$i18n.global.locale 或宿主传入的 query.locale
+headers['X-Language'] = LANGUAGE[locale];
 ```
+
+### 支持的语言
+
+| 分组 | locale key | 语言 | X-Language 值 |
+| --- | --- | --- | --- |
+| 亚洲语言 | `zh-Hans` | 简体中文 | `zh-CN` |
+| 亚洲语言 | `zh-Hant` | 繁体中文 | `zh-TW` |
+| 亚洲语言 | `ja` | 日语 | `ja-JP` |
+| 亚洲语言 | `ko` | 韩语 | `ko-KR` |
+| 亚洲语言 | `ar` | 阿拉伯语 | `ar-SA` |
+| 亚洲语言 | `fa` | 伊朗语（波斯语） | `fa-IR` |
+| 亚洲语言 | `th` | 泰语 | `th-TH` |
+| 亚洲语言 | `vi` | 越南语 | `vi-VN` |
+| 亚洲语言 | `my` | 缅甸语 | `my-MM` |
+| 亚洲语言 | `km` | 柬埔寨语 | `km-KH` |
+| 欧洲语言 | `en` | 英语 | `en-US` |
+| 欧洲语言 | `fr` | 法语 | `fr-FR` |
+| 欧洲语言 | `es` | 西班牙语 | `es-ES` |
+| 欧洲语言 | `ru` | 俄语 | `ru-RU` |
+| 欧洲语言 | `pt` | 葡萄牙语 | `pt-PT` |
+| 欧洲语言 | `de` | 德语 | `de-DE` |
+| 欧洲语言 | `it` | 意大利语 | `it-IT` |
+| 欧洲语言 | `el` | 希腊语 | `el-GR` |
+| 欧洲语言 | `pl` | 波兰语 | `pl-PL` |
+
+> **提示**：`LANGUAGE[uni.getLocale()]` 仅在对应 locale 已注册到业务侧 vue-i18n `messages` 时才能命中；未注册时 `uni.getLocale()` 会回退到 `fallbackLocale`（`zh-Hans`）。宿主可通过 `query.locale`（如 `?locale=ar`）直接指定语言。

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/apis/request.js

@@ -36,7 +36,7 @@ http.interceptors.request.use((conf) => {
         }
         // #endif
         const header = {
-            'X-Language': LANGUAGE[query.locale || uni.getLocale()],
+            'X-Language': query.xLanguage || LANGUAGE[query.locale || uni.getLocale()],
             'Tenant-Id': tenantId || 1,
             channel,
             terminal,

package/lib/mixins/webview.js

@@ -1,6 +1,6 @@
 import Url from 'url-parse';
 import { stringify, parse } from 'qs';
-import { PLATFORM_CODE, IS_WEBVIEW_ENV, SYSTEM_INFO, TYPES } from '../utils/consts';
+import { PLATFORM_CODE, IS_WEBVIEW_ENV, SYSTEM_INFO, TYPES, LANGUAGE } from '../utils/consts';
 import app from '../configs/app';
 import { requestPermission, openAuthorizeSetting } from '../utils/permit';
 import web from '../configs/web';
@@ -39,6 +39,7 @@ export default {
                 safeTop: SYSTEM_INFO.safeAreaInsets.top,
                 safeBottom: SYSTEM_INFO.safeAreaInsets.bottom,
                 locale: uni.$i18n?.global?.locale,
+                xLanguage: LANGUAGE[uni.$i18n?.global?.locale],
                 accelerate: cdn.isAccelerate ? 1 : undefined,
             };
             if (query.primary) {

package/lib/utils/consts.d.ts

@@ -30,9 +30,22 @@ export declare const LANGUAGE: {
     'zh-Hans': string;
     'zh-Hant': string;
     ja: string;
+    ko: string;
+    ar: string;
+    fa: string;
+    th: string;
+    vi: string;
+    my: string;
+    km: string;
     en: string;
     fr: string;
     es: string;
+    ru: string;
+    pt: string;
+    de: string;
+    it: string;
+    el: string;
+    pl: string;
 };
 export declare const TYPES: {
     readonly MESSAGE: {

package/lib/utils/consts.js

@@ -60,12 +60,27 @@ export var CHANNEL;
     CHANNEL[CHANNEL["\u95E8\u5E97\u7AEF"] = 3] = "\u95E8\u5E97\u7AEF";
 })(CHANNEL || (CHANNEL = {}));
 export const LANGUAGE = {
-    'zh-Hans': 'zh-CN',
-    'zh-Hant': 'zh-TW',
-    ja: 'ja-JP',
-    en: 'en-US',
-    fr: 'fr-FR',
-    es: 'es-ES',
+    // 亚洲语言
+    'zh-Hans': 'zh-CN', // 简体中文
+    'zh-Hant': 'zh-TW', // 繁体中文
+    ja: 'ja-JP', // 日语
+    ko: 'ko-KR', // 韩语
+    ar: 'ar-SA', // 阿拉伯语
+    fa: 'fa-IR', // 伊朗语（波斯语）
+    th: 'th-TH', // 泰语
+    vi: 'vi-VN', // 越南语
+    my: 'my-MM', // 缅甸语
+    km: 'km-KH', // 柬埔寨语
+    // 欧洲语言
+    en: 'en-US', // 英语
+    fr: 'fr-FR', // 法语
+    es: 'es-ES', // 西班牙语
+    ru: 'ru-RU', // 俄语
+    pt: 'pt-PT', // 葡萄牙语
+    de: 'de-DE', // 德语
+    it: 'it-IT', // 意大利语
+    el: 'el-GR', // 希腊语
+    pl: 'pl-PL', // 波兰语
 };
 // webview 与宿主环境通信的消息类型
 export const TYPES = {

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.16",
+  "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": "482fb66642df55a676ac10fb902cba10da3720d2"
+  }
 }

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.