uniapp-request-sdk 1.6.1 → 1.7.1

package/dist/index.d.ts

@@ -15,6 +15,8 @@ interface IParams {
     timeout?: number;
     /** 上传文件的请求超时时间，ms为单位，默认5s */
     uploadTimeout?: number;
+    /** 下载文件的请求超时时间，ms为单位，默认30s */
+    downloadTimeout?: number;
     /** 请求尝试延迟时间默认3s，ms为单位 */
     retryDelay?: number;
     /** token，APP初始化给到小程序的token */
@@ -30,40 +32,102 @@ interface IParams {
     /** 用户名，用于日志排查使用 */
     username?: string;
 }
+/**
+ * uni.uploadFile 的选项扩展类型，支持进度回调
+ * @description 在 UploadFileOption 基础上扩展了进度更新回调
+ */
 type UploadFileWithProgressOption = UploadFileOption & {
+    /** 上传进度更新回调函数 */
     onProgressUpdateCallback?: (result: OnProgressUpdateResult) => void;
 };
-declare function requestPromise(options?: RequestOptions & {
-    timeout: number;
-}): Promise<RequestSuccessCallbackResult>;
+/**
+ * uni.downloadFile 的选项扩展类型，支持进度回调
+ * @description 在 DownloadFileOption 基础上扩展了进度更新回调
+ */
+type DownloadFileWithProgressOption = DownloadFileOption & {
+    /** 下载进度更新回调函数 */
+    onProgressUpdateCallback?: (result: any) => void;
+};
+/**
+ * UniRequest 网络请求管理类
+ * @description 统一封装 uni-app 的网络请求（request、uploadFile、downloadFile），
+ * 提供 Promise 风格的 API 和高级特性，如自动重试、token 管理、请求头预处理等
+ * @example
+ * const uniRequest = new UniRequest({
+ *   baseUrl: 'https://api.example.com',
+ *   timeout: 10000,
+ *   uploadTimeout: 5000
+ * });
+ *
+ * // 普通请求
+ * const data = await uniRequest.post('/path', { key: 'value' });
+ *
+ * // 上传文件
+ * const result = await uniRequest.uploadFile('/upload', filePath, formData);
+ *
+ * // 下载文件
+ * const filePath = await uniRequest.downloadFile('/download/file.pdf');
+ */
 declare class UniRequest {
-    /** 基准路径 */
+    /** 基准路径，用于构建完整的请求 URL */
     private baseUrl;
-    /** 用户名 */
+    /** 用户名，用于日志记录和问题排查 */
     private username;
-    /** 错误处理函数 */
+    /** 错误处理函数，当请求失败时会被调用 */
     private onErrorHandler;
-    /** 默认请求头 */
+    /** 默认请求头，会被合并到所有请求中 */
     private header?;
-    /** 请求头预处理函数 */
+    /** 请求头预处理函数，用于动态修改请求头（在 token 设置之后执行） */
     private headerProcessor?;
+    /** 请求失败时的最大重试次数，默认 3 次 */
     private maxRetryCount;
-    /** 超时时间 */
+    /** 普通请求的超时时间，单位毫秒，默认 10 秒 */
     private timeout;
-    /** 上传文件的超时时间 */
+    /** 上传文件的超时时间，单位毫秒，默认 5 秒 */
     private uploadTimeout;
+    /** 下载文件的超时时间，单位毫秒，默认 30 秒 */
+    private downloadTimeout;
+    /** 请求失败后的重试延迟时间，单位毫秒，默认 3 秒 */
     private retryDelay;
+    /** 当前的 token，用于授权请求 */
     private token?;
+    /** 获取 token 的事件名称，默认为 'getToken' */
     private tokenEventName;
-    /** token的header名称，默认Authorization */
+    /** token 所在的请求头字段名称，默认为 'Authorization' */
     private tokenHeader;
-    /** 传入的token前缀，默认Bearer ，注意Bearer有个空字符串*/
+    /** token 的前缀，默认为 'Bearer '（注意末尾有空格） */
     private tokenPrefix;
-    /** 自定义得到token的函数 */
+    /** 自定义的获取 token 函数，若未设置则使用 getToken() */
     private getTokenFun?;
+    /**
+     * 构造函数，初始化 UniRequest 实例
+     * @param params - 初始化参数，详见 IParams 接口
+     */
     constructor(params?: IParams);
+    /**
+     * 内部错误处理函数
+     * @description 触发 reject 并调用全局错误处理函数
+     * @param rej - Promise 的 reject 函数
+     * @param data - 错误数据
+     */
     private rejectHandler;
+    /**
+     * 动态设置配置参数
+     * @description 可以在实例创建后动态修改配置，用于变更超时时间、token、请求头等
+     * @param params - 要设置的参数，详见 IParams 接口
+     * @example
+     * uniRequest.setParams({ token: 'new_token', timeout: 15000 });
+     */
     setParams(params?: IParams): void;
+    /**
+     * 底层通用请求方法
+     * @description 所有具体的请求方法（post、get 等）都调用此方法来执行请求。
+     * 支持自动重试、token 管理、请求头处理等高级功能
+     * @param params - 请求参数，包含 url、method、data、header、timeout 等
+     * @param callbackPromise - 回调函数，可以是 requestPromise、uploadFilePromise 或 downloadFilePromise
+     * @returns Promise<T> 返回解析后的响应数据
+     * @internal 此方法不建议直接调用，应使用 post、get、uploadFile 等高层方法
+     */
     request<T>(params: {
         url: string;
         method: RequestOptions['method'];
@@ -71,29 +135,91 @@ declare class UniRequest {
         header?: RequestOptions['header'];
         /** 超时时间 */
         timeout?: number;
-    } & RequestOptions & UploadFileWithProgressOption, callbackPromise?: typeof requestPromise): Promise<T>;
+    } & RequestOptions & UploadFileWithProgressOption & DownloadFileWithProgressOption, callbackPromise?: any): Promise<T>;
     /**
-     * post请求
-     * @param url
-     * @param data 可传可不传
-     * @param header
-     * @returns
+     * 发送 POST 请求
+     * @param url - 请求地址；支持相对路径（会拼接 baseUrl）和完整的 http/https 地址
+     * @param data - 请求数据，可选；如不传递则默认为空对象
+     * @param header - 当前请求的自定义请求头；会与实例级公共请求头合并
+     * @returns Promise<T> 返回解析后的响应数据
+     * @example
+     * const result = await uniRequest.post('/users', { name: 'John', age: 30 });
+     * const result = await uniRequest.post('https://api.example.com/users', data);
      */
     post<T>(url: string, data?: {}, header?: Record<string, string>): Promise<T>;
+    /**
+     * 发送 GET 请求
+     * @param url - 请求地址；支持相对路径（会拼接 baseUrl）和完整的 http/https 地址
+     * @param data - 查询参数，可选；如不传递则默认为空对象
+     * @param header - 当前请求的自定义请求头；会与实例级公共请求头合并
+     * @returns Promise<T> 返回解析后的响应数据
+     * @example
+     * const result = await uniRequest.get('/users', { page: 1, limit: 10 });
+     */
     get<T>(url: string, data?: {}, header?: Record<string, string>): Promise<T>;
+    /**
+     * 发送 DELETE 请求
+     * @param url - 请求地址；支持相对路径（会拼接 baseUrl）和完整的 http/https 地址
+     * @param data - 请求数据，可选；如不传递则默认为空对象
+     * @param header - 当前请求的自定义请求头；会与实例级公共请求头合并
+     * @returns Promise<T> 返回解析后的响应数据
+     * @example
+     * const result = await uniRequest.delete('/users/123');
+     */
     delete<T>(url: string, data?: {}, header?: Record<string, string>): Promise<T>;
+    /**
+     * 发送 PUT 请求
+     * @param url - 请求地址；支持相对路径（会拼接 baseUrl）和完整的 http/https 地址
+     * @param data - 请求数据，可选；如不传递则默认为空对象
+     * @param header - 当前请求的自定义请求头；会与实例级公共请求头合并
+     * @returns Promise<T> 返回解析后的响应数据
+     * @example
+     * const result = await uniRequest.put('/users/123', { name: 'Jane', age: 25 });
+     */
     put<T>(url: string, data?: {}, header?: Record<string, string>): Promise<T>;
     /**
      * 文件上传
-     * @param url 上传接口地址；支持相对路径和完整的 http/https 地址
-     * @param filePath 待上传文件的本地临时路径
-     * @param formData 额外的表单字段，会与文件一起作为 multipart/form-data 提交
-     * @param name 文件字段名；服务端通过该字段读取文件内容，默认值为 file
-     * @param header 当前上传请求的自定义请求头；会与实例级公共请求头合并
-     * @param onProgressUpdateCallback 上传进度回调；传入后会绑定到 uni.uploadFile 返回的 UploadTask.onProgressUpdate
-     * @returns 返回一个 Promise；成功时解析服务端响应中的 data 字段，失败时抛出错误信息
+     * @param url - 上传接口地址；支持相对路径和完整的 http/https 地址
+     * @param filePath - 待上传文件的本地临时路径
+     * @param formData - 额外的表单字段，会与文件一起作为 multipart/form-data 提交
+     * @param name - 文件字段名；服务端通过该字段读取文件内容，默认值为 file
+     * @param header - 当前上传请求的自定义请求头；会与实例级公共请求头合并
+     * @param onProgressUpdateCallback - 上传进度回调；传入后会绑定到 uni.uploadFile 返回的 UploadTask.onProgressUpdate
+     * @returns Promise<T> 返回一个 Promise；成功时解析服务端响应中的 data 字段，失败时抛出错误信息
+     * @example
+     * const result = await uniRequest.uploadFile('/upload', filePath);
+     *
+     * // 带上传进度
+     * const result = await uniRequest.uploadFile(
+     *   '/upload',
+     *   filePath,
+     *   { category: 'profile' },
+     *   'file',
+     *   { 'Authorization': 'Bearer token' },
+     *   (progress) => console.log(`上传进度: ${progress.progress}%`)
+     * );
      */
     uploadFile<T>(url: string, filePath: string, formData?: Record<string, any>, name?: string, header?: Record<string, string>, onProgressUpdateCallback?: (result: OnProgressUpdateResult) => void): Promise<T>;
+    /**
+     * 文件下载
+     * @param url - 下载资源的 url；支持相对路径和完整的 http/https 地址
+     * @param filePath - 指定文件下载后存储的路径（本地路径），仅小程序端支持；如不指定则保存到临时目录
+     * @param header - 当前下载请求的自定义请求头；会与实例级公共请求头合并
+     * @param onProgressUpdateCallback - 下载进度回调；传入后会绑定到 uni.downloadFile 返回的 DownloadTask.onProgressUpdate
+     * @returns Promise<T> 返回一个 Promise；成功时解析得到的文件临时路径（tempFilePath），失败时抛出错误信息
+     * @example
+     * // 简单下载
+     * const filePath = await uniRequest.downloadFile('/files/document.pdf');
+     *
+     * // 带自定义保存路径和进度回调
+     * const filePath = await uniRequest.downloadFile(
+     *   '/files/large-file.zip',
+     *   'local/storage/path',
+     *   { 'Authorization': 'Bearer token' },
+     *   (progress) => console.log(`下载进度: ${progress.progress}%`)
+     * );
+     */
+    downloadFile<T extends string = string>(url: string, filePath?: string, header?: Record<string, string>, onProgressUpdateCallback?: (result: any) => void): Promise<T>;
 }
 
 export { IParams, UniRequest as default };

package/dist/index.esm.js

@@ -398,6 +398,12 @@ var EVENT_NAME = {
   /** 通知APP退出到登录页面 */
   LOGOUT: 'logout'
 };
+/**
+ * uni.request 的 Promise 包装函数
+ * @description 将回调式的 uni.request 转换为 Promise 风格，便于与 async/await 配合使用
+ * @param options - uni.request 的选项参数，必须包含 timeout 字段
+ * @returns Promise<RequestSuccessCallbackResult> 请求成功的响应数据
+ */
 function requestPromise(options) {
   return new Promise(function (res, rej) {
     uni.request(Object.assign(Object.assign({}, options), {
@@ -406,6 +412,12 @@ function requestPromise(options) {
     }));
   });
 }
+/**
+ * uni.uploadFile 的 Promise 包装函数
+ * @description 将回调式的 uni.uploadFile 转换为 Promise 风格，并自动处理进度回调的绑定
+ * @param options - uni.uploadFile 的选项参数，支持 onProgressUpdateCallback 扩展字段
+ * @returns Promise<UploadFileSuccessCallbackResult> 上传成功的响应数据
+ */
 function uploadFilePromise(options) {
   return new Promise(function (res, rej) {
     var _a = options || {},
@@ -420,7 +432,32 @@ function uploadFilePromise(options) {
     }
   });
 }
-/** 得到小程序的token */
+/**
+ * uni.downloadFile 的 Promise 包装函数
+ * @description 将回调式的 uni.downloadFile 转换为 Promise 风格，并自动处理进度回调的绑定
+ * @param options - uni.downloadFile 的选项参数，支持 onProgressUpdateCallback 扩展字段
+ * @returns Promise<any> 下载成功的响应数据（包含 tempFilePath 等）
+ */
+function downloadFilePromise(options) {
+  return new Promise(function (res, rej) {
+    var _a = options || {},
+      onProgressUpdateCallback = _a.onProgressUpdateCallback,
+      downloadOptions = __rest(_a, ["onProgressUpdateCallback"]);
+    var downloadTask = uni.downloadFile(Object.assign(Object.assign({}, downloadOptions), {
+      success: res,
+      fail: rej
+    }));
+    if (onProgressUpdateCallback) {
+      downloadTask.onProgressUpdate(onProgressUpdateCallback);
+    }
+  });
+}
+/**
+ * 从客户端获取 token
+ * @description 通过 uni.sendNativeEvent 向原生应用发送事件请求 token，超时时间为 5 秒
+ * @param eventName - 事件名称，用于向原生应用指示要获取 token
+ * @returns Promise<string> 返回获取到的 token 字符串
+ */
 function getToken(eventName) {
   return new Promise(function (res, rej) {
     var timeout = setTimeout(rej, 5000);
@@ -430,28 +467,57 @@ function getToken(eventName) {
     });
   });
 }
+/**
+ * UniRequest 网络请求管理类
+ * @description 统一封装 uni-app 的网络请求（request、uploadFile、downloadFile），
+ * 提供 Promise 风格的 API 和高级特性，如自动重试、token 管理、请求头预处理等
+ * @example
+ * const uniRequest = new UniRequest({
+ *   baseUrl: 'https://api.example.com',
+ *   timeout: 10000,
+ *   uploadTimeout: 5000
+ * });
+ *
+ * // 普通请求
+ * const data = await uniRequest.post('/path', { key: 'value' });
+ *
+ * // 上传文件
+ * const result = await uniRequest.uploadFile('/upload', filePath, formData);
+ *
+ * // 下载文件
+ * const filePath = await uniRequest.downloadFile('/download/file.pdf');
+ */
 var UniRequest = /*#__PURE__*/function () {
+  /**
+   * 构造函数，初始化 UniRequest 实例
+   * @param params - 初始化参数，详见 IParams 接口
+   */
   function UniRequest(params) {
     var _this = this;
     _classCallCheck(this, UniRequest);
-    /** 基准路径 */
+    /** 基准路径，用于构建完整的请求 URL */
     this.baseUrl = '';
-    /** 用户名 */
+    /** 用户名，用于日志记录和问题排查 */
     this.username = '';
-    /** 错误处理函数 */
+    /** 错误处理函数，当请求失败时会被调用 */
     this.onErrorHandler = function (error) {
       console.error(error);
     };
+    /** 请求失败时的最大重试次数，默认 3 次 */
     this.maxRetryCount = 3;
-    /** 超时时间 */
+    /** 普通请求的超时时间，单位毫秒，默认 10 秒 */
     this.timeout = 10000;
-    /** 上传文件的超时时间 */
+    /** 上传文件的超时时间，单位毫秒，默认 5 秒 */
     this.uploadTimeout = 5000;
+    /** 下载文件的超时时间，单位毫秒，默认 30 秒 */
+    this.downloadTimeout = 30000;
+    /** 请求失败后的重试延迟时间，单位毫秒，默认 3 秒 */
     this.retryDelay = 3000;
+    /** 获取 token 的事件名称，默认为 'getToken' */
     this.tokenEventName = 'getToken';
-    /** token的header名称，默认Authorization */
+    /** token 所在的请求头字段名称，默认为 'Authorization' */
     this.tokenHeader = 'Authorization';
-    /** 传入的token前缀，默认Bearer ，注意Bearer有个空字符串*/
+    /** token 的前缀，默认为 'Bearer '（注意末尾有空格） */
     this.tokenPrefix = 'Bearer ';
     if (params) {
       Object.keys(params).forEach(function (key) {
@@ -461,6 +527,12 @@ var UniRequest = /*#__PURE__*/function () {
       });
     }
   }
+  /**
+   * 内部错误处理函数
+   * @description 触发 reject 并调用全局错误处理函数
+   * @param rej - Promise 的 reject 函数
+   * @param data - 错误数据
+   */
   _createClass(UniRequest, [{
     key: "rejectHandler",
     value: function rejectHandler(rej, data) {
@@ -468,6 +540,13 @@ var UniRequest = /*#__PURE__*/function () {
       rej(data);
       (_a = this.onErrorHandler) === null || _a === void 0 ? void 0 : _a.call(this, data);
     }
+    /**
+     * 动态设置配置参数
+     * @description 可以在实例创建后动态修改配置，用于变更超时时间、token、请求头等
+     * @param params - 要设置的参数，详见 IParams 接口
+     * @example
+     * uniRequest.setParams({ token: 'new_token', timeout: 15000 });
+     */
   }, {
     key: "setParams",
     value: function setParams(params) {
@@ -480,6 +559,15 @@ var UniRequest = /*#__PURE__*/function () {
         });
       }
     }
+    /**
+     * 底层通用请求方法
+     * @description 所有具体的请求方法（post、get 等）都调用此方法来执行请求。
+     * 支持自动重试、token 管理、请求头处理等高级功能
+     * @param params - 请求参数，包含 url、method、data、header、timeout 等
+     * @param callbackPromise - 回调函数，可以是 requestPromise、uploadFilePromise 或 downloadFilePromise
+     * @returns Promise<T> 返回解析后的响应数据
+     * @internal 此方法不建议直接调用，应使用 post、get、uploadFile 等高层方法
+     */
   }, {
     key: "request",
     value: function request(params) {
@@ -500,43 +588,49 @@ var UniRequest = /*#__PURE__*/function () {
         /** 添加日志上报的小程序username */
         'X-Request-Username': this.username
       });
+      var finalHeader;
       var requestedToken = false;
       var retryCount = 0;
       return new Promise(function (res, rej) {
         var retryFucntion = /*#__PURE__*/function () {
           var _ref = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee() {
-            var finalHeader, processedHeader;
+            var requestHeader, processedHeader;
             return _regeneratorRuntime().wrap(function _callee$(_context) {
               while (1) switch (_context.prev = _context.next) {
                 case 0:
+                  if (finalHeader) {
+                    _context.next = 17;
+                    break;
+                  }
+                  requestHeader = Object.assign({}, header);
                   /** 因为token需要动态获取，因此放入这里 */
-                  header[_this3.tokenHeader] = "".concat(_this3.tokenPrefix).concat(_this3.token);
+                  requestHeader[_this3.tokenHeader] = "".concat(_this3.tokenPrefix).concat(_this3.token);
                   /** 针对h5调试的时候，因为塞入cookie是不安全的，因此无需塞入cookie，使用登录页后，后端塞入的cookie */
                   // #ifdef H5
                   if (_this3.tokenHeader === 'cookie') {
-                    delete header[_this3.tokenHeader];
+                    delete requestHeader[_this3.tokenHeader];
                   }
                   // #endif
-                  /** 执行请求头预处理 */
-                  finalHeader = header;
+                  /** 单次请求生命周期内只执行一次请求头预处理，重试复用同一份结果 */
+                  finalHeader = requestHeader;
                   if (!_this3.headerProcessor) {
-                    _context.next = 15;
+                    _context.next = 17;
                     break;
                   }
-                  _context.prev = 4;
-                  _context.next = 7;
-                  return _this3.headerProcessor(header);
-                case 7:
+                  _context.prev = 6;
+                  _context.next = 9;
+                  return _this3.headerProcessor(requestHeader);
+                case 9:
                   processedHeader = _context.sent;
-                  finalHeader = Object.assign(Object.assign({}, header), processedHeader);
-                  _context.next = 15;
+                  finalHeader = Object.assign(Object.assign({}, requestHeader), processedHeader);
+                  _context.next = 17;
                   break;
-                case 11:
-                  _context.prev = 11;
-                  _context.t0 = _context["catch"](4);
+                case 13:
+                  _context.prev = 13;
+                  _context.t0 = _context["catch"](6);
                   _this3.rejectHandler(rej, _context.t0);
                   return _context.abrupt("return");
-                case 15:
+                case 17:
                   callbackPromise(Object.assign(Object.assign({}, params), {
                     header: finalHeader,
                     url: url,
@@ -545,7 +639,10 @@ var UniRequest = /*#__PURE__*/function () {
                     var statusCode = resData.statusCode,
                       data = resData.data;
                     if (statusCode === 200) {
-                      if (!data.errno) {
+                      /** downloadFile 特殊处理：直接返回 tempFilePath */
+                      if (callbackPromise === downloadFilePromise) {
+                        res(resData.tempFilePath);
+                      } else if (!data.errno) {
                         var jsonData = data;
                         /** 如果是上传API的话，返回的结果需要解析成json对象 */
                         if (Object.prototype.toString.call(data) !== '[object Object]' && callbackPromise === uploadFilePromise) {
@@ -566,6 +663,7 @@ var UniRequest = /*#__PURE__*/function () {
                       (_this3.getTokenFun ? _this3.getTokenFun() : getToken(_this3.tokenEventName)).then(function (token) {
                         _this3.token = token;
                         requestedToken = true;
+                        finalHeader = void 0;
                         /** 获取token应该立马请求,不需要延迟 */
                         retryFucntion();
                       })["catch"](function () {
@@ -599,11 +697,11 @@ var UniRequest = /*#__PURE__*/function () {
                       _this3.rejectHandler(rej, rejData);
                     }
                   });
-                case 16:
+                case 18:
                 case "end":
                   return _context.stop();
               }
-            }, _callee, null, [[4, 11]]);
+            }, _callee, null, [[6, 13]]);
           }));
           return function retryFucntion() {
             return _ref.apply(this, arguments);
@@ -619,11 +717,14 @@ var UniRequest = /*#__PURE__*/function () {
       });
     }
     /**
-     * post请求
-     * @param url
-     * @param data 可传可不传
-     * @param header
-     * @returns
+     * 发送 POST 请求
+     * @param url - 请求地址；支持相对路径（会拼接 baseUrl）和完整的 http/https 地址
+     * @param data - 请求数据，可选；如不传递则默认为空对象
+     * @param header - 当前请求的自定义请求头；会与实例级公共请求头合并
+     * @returns Promise<T> 返回解析后的响应数据
+     * @example
+     * const result = await uniRequest.post('/users', { name: 'John', age: 30 });
+     * const result = await uniRequest.post('https://api.example.com/users', data);
      */
   }, {
     key: "post",
@@ -637,6 +738,15 @@ var UniRequest = /*#__PURE__*/function () {
         method: 'POST'
       });
     }
+    /**
+     * 发送 GET 请求
+     * @param url - 请求地址；支持相对路径（会拼接 baseUrl）和完整的 http/https 地址
+     * @param data - 查询参数，可选；如不传递则默认为空对象
+     * @param header - 当前请求的自定义请求头；会与实例级公共请求头合并
+     * @returns Promise<T> 返回解析后的响应数据
+     * @example
+     * const result = await uniRequest.get('/users', { page: 1, limit: 10 });
+     */
   }, {
     key: "get",
     value: function get(url) {
@@ -649,6 +759,15 @@ var UniRequest = /*#__PURE__*/function () {
         method: 'GET'
       });
     }
+    /**
+     * 发送 DELETE 请求
+     * @param url - 请求地址；支持相对路径（会拼接 baseUrl）和完整的 http/https 地址
+     * @param data - 请求数据，可选；如不传递则默认为空对象
+     * @param header - 当前请求的自定义请求头；会与实例级公共请求头合并
+     * @returns Promise<T> 返回解析后的响应数据
+     * @example
+     * const result = await uniRequest.delete('/users/123');
+     */
   }, {
     key: "delete",
     value: function _delete(url) {
@@ -661,6 +780,15 @@ var UniRequest = /*#__PURE__*/function () {
         method: 'DELETE'
       });
     }
+    /**
+     * 发送 PUT 请求
+     * @param url - 请求地址；支持相对路径（会拼接 baseUrl）和完整的 http/https 地址
+     * @param data - 请求数据，可选；如不传递则默认为空对象
+     * @param header - 当前请求的自定义请求头；会与实例级公共请求头合并
+     * @returns Promise<T> 返回解析后的响应数据
+     * @example
+     * const result = await uniRequest.put('/users/123', { name: 'Jane', age: 25 });
+     */
   }, {
     key: "put",
     value: function put(url) {
@@ -675,13 +803,25 @@ var UniRequest = /*#__PURE__*/function () {
     }
     /**
      * 文件上传
-     * @param url 上传接口地址；支持相对路径和完整的 http/https 地址
-     * @param filePath 待上传文件的本地临时路径
-     * @param formData 额外的表单字段，会与文件一起作为 multipart/form-data 提交
-     * @param name 文件字段名；服务端通过该字段读取文件内容，默认值为 file
-     * @param header 当前上传请求的自定义请求头；会与实例级公共请求头合并
-     * @param onProgressUpdateCallback 上传进度回调；传入后会绑定到 uni.uploadFile 返回的 UploadTask.onProgressUpdate
-     * @returns 返回一个 Promise；成功时解析服务端响应中的 data 字段，失败时抛出错误信息
+     * @param url - 上传接口地址；支持相对路径和完整的 http/https 地址
+     * @param filePath - 待上传文件的本地临时路径
+     * @param formData - 额外的表单字段，会与文件一起作为 multipart/form-data 提交
+     * @param name - 文件字段名；服务端通过该字段读取文件内容，默认值为 file
+     * @param header - 当前上传请求的自定义请求头；会与实例级公共请求头合并
+     * @param onProgressUpdateCallback - 上传进度回调；传入后会绑定到 uni.uploadFile 返回的 UploadTask.onProgressUpdate
+     * @returns Promise<T> 返回一个 Promise；成功时解析服务端响应中的 data 字段，失败时抛出错误信息
+     * @example
+     * const result = await uniRequest.uploadFile('/upload', filePath);
+     *
+     * // 带上传进度
+     * const result = await uniRequest.uploadFile(
+     *   '/upload',
+     *   filePath,
+     *   { category: 'profile' },
+     *   'file',
+     *   { 'Authorization': 'Bearer token' },
+     *   (progress) => console.log(`上传进度: ${progress.progress}%`)
+     * );
      */
   }, {
     key: "uploadFile",
@@ -700,6 +840,37 @@ var UniRequest = /*#__PURE__*/function () {
         onProgressUpdateCallback: onProgressUpdateCallback
       }, uploadFilePromise);
     }
+    /**
+     * 文件下载
+     * @param url - 下载资源的 url；支持相对路径和完整的 http/https 地址
+     * @param filePath - 指定文件下载后存储的路径（本地路径），仅小程序端支持；如不指定则保存到临时目录
+     * @param header - 当前下载请求的自定义请求头；会与实例级公共请求头合并
+     * @param onProgressUpdateCallback - 下载进度回调；传入后会绑定到 uni.downloadFile 返回的 DownloadTask.onProgressUpdate
+     * @returns Promise<T> 返回一个 Promise；成功时解析得到的文件临时路径（tempFilePath），失败时抛出错误信息
+     * @example
+     * // 简单下载
+     * const filePath = await uniRequest.downloadFile('/files/document.pdf');
+     *
+     * // 带自定义保存路径和进度回调
+     * const filePath = await uniRequest.downloadFile(
+     *   '/files/large-file.zip',
+     *   'local/storage/path',
+     *   { 'Authorization': 'Bearer token' },
+     *   (progress) => console.log(`下载进度: ${progress.progress}%`)
+     * );
+     */
+  }, {
+    key: "downloadFile",
+    value: function downloadFile(url, filePath, header, onProgressUpdateCallback) {
+      return this.request({
+        url: url,
+        filePath: filePath,
+        header: header,
+        method: 'GET',
+        timeout: this.downloadTimeout,
+        onProgressUpdateCallback: onProgressUpdateCallback
+      }, downloadFilePromise);
+    }
   }]);
   return UniRequest;
 }();