@hlw-uni/mp-vue 2.1.57 → 2.1.58

package/src/composables/refs/index.ts

@@ -1,26 +1,48 @@
 /**
  * useRefs - 模板 Ref 批量管理
- *
- * 用于 v-for 场景下收集一组动态生成的子元素或子组件引用。
+ * 
+ * 主要用于在 v-for 循环场景下，动态收集一组子元素或子组件的引用实例。
+ * 规避了 Vue3 在 v-for 中绑定 ref 时需要手动处理数组收集和清理的冗余逻辑。
  */
 import { ref, onBeforeUpdate, onUnmounted } from "vue";
 
 /**
- * 管理动态 ref 集合，适合 v-for 场景。
+ * 管理动态 ref 集合的 hook，尤其适合 v-for 列表场景。
+ * 
+ * @example
+ * ```vue
+ * <template>
+ *   <view v-for="item in list" :key="item.id" :ref="setRefs(item.id)">
+ *     {{ item.name }}
+ *   </view>
+ * </template>
+ * 
+ * <script setup>
+ * const { refs, setRefs } = useRefs();
+ * // 访问特定子项的 DOM/实例: refs.value[itemId]
+ * </script>
+ * ```
  */
 export function useRefs() {
+    /** 存放动态收集到的所有组件或 DOM 实例的 Key-Value 映射对象 */
     const refs = ref<Record<string, any>>({});
 
+    // 每次组件更新前清空缓存，以便重新收集最新存在的元素引用
     onBeforeUpdate(() => {
         refs.value = {};
     });
 
+    // 组件卸载时清空所有引用，防止内存泄漏
     onUnmounted(() => {
         refs.value = {};
     });
 
     /**
-     * 按 key 生成 ref 回调并写入 refs 集合。
+     * 按 key 生成一个 ref 绑定回调函数。
+     * Vue 模板的 `:ref` 绑定此返回值后，会自动在挂载时填入实例，卸载时清除。
+     * 
+     * @param key 标识该子项的唯一 Key
+     * @returns 用于 ref 绑定的回调函数
      */
     const setRefs = (key: string) => (el: any) => {
         if (el) refs.value[key] = el;
@@ -28,3 +50,4 @@ export function useRefs() {
 
     return { refs, setRefs };
 }
+

package/src/composables/request/client.ts

@@ -10,20 +10,98 @@ import type {
 } from "./types";
 import { getAdapter } from "./adapters";
 
+/**
+ * HTTP 请求客户端接口定义。
+ * 提供基础的 HTTP 请求方法、文件直传服务配置以及拦截器管理。
+ */
 export interface RequestClient {
+    /**
+     * 发送网络请求。
+     * @param config 请求配置项
+     * @returns 封装后的响应结果 Promise
+     */
     request<T = unknown>(config: RequestConfig): Promise<ApiResponse<T>>;
+
+    /**
+     * 发送 GET 请求的快捷方法。
+     * @param url 请求的目标 URL
+     * @param data 请求携带的 query 参数
+     * @returns 封装后的响应结果 Promise
+     */
     get<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>>;
+
+    /**
+     * 发送 POST 请求的快捷方法。
+     * @param url 请求的目标 URL
+     * @param data 请求携带的 body 数据
+     * @returns 封装后的响应结果 Promise
+     */
     post<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>>;
+
+    /**
+     * 发送 PUT 请求的快捷方法。
+     * @param url 请求的目标 URL
+     * @param data 请求携带的 body 数据
+     * @returns 封装后的响应结果 Promise
+     */
     put<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>>;
+
+    /**
+     * 发送 DELETE 请求的快捷方法。
+     * @param url 请求的目标 URL
+     * @param data 请求携带的 query 或 body 数据
+     * @returns 封装后的响应结果 Promise
+     */
     del<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>>;
+
+    /**
+     * 上传本地文件到服务器或第三方云存储。
+     * @param config 文件上传配置项
+     * @returns 上传解析结果 Promise
+     */
     upload(config: UploadConfig): Promise<UploadResult>;
+
+    /**
+     * 设置基础请求域名或前缀。
+     * @param url 域名字符串（如 'https://api.example.com'）
+     */
     setBaseURL(url: string): void;
+
+    /**
+     * 拼接并解析微服务模块或命名空间下的请求 URL。
+     * @param namespace 命名空间/模块名称
+     * @param url 具体的接口路径
+     * @param servicePrefix 服务的前缀，可选
+     * @returns 拼接完成的完整路径
+     */
     resolveServiceUrl(namespace: string, url: string, servicePrefix?: string): string;
+
+    /**
+     * 注册请求拦截器，在请求发出前触发。
+     * @param fn 拦截器处理函数
+     * @returns 用于注销该拦截器的注销函数
+     */
     onRequest(fn: RequestInterceptor): () => void;
+
+    /**
+     * 注册响应拦截器，在成功接收响应后触发。
+     * @param fn 拦截器处理函数
+     * @returns 用于注销该拦截器的注销函数
+     */
     onResponse<T = unknown>(fn: ResponseInterceptor<T>): () => void;
+
+    /**
+     * 注册错误拦截器，在请求或响应阶段发生异常时触发。
+     * @param fn 错误拦截处理器
+     * @returns 用于注销该拦截器的注销函数
+     */
     onError(fn: ErrorInterceptor): () => void;
 }
 
+/**
+ * UniApp 请求客户端的实现类。
+ * 基于 uni.request 与 uni.uploadFile 封装，内置拦截器调用链路。
+ */
 class UniRequestClient implements RequestClient {
     private reqInterceptors: RequestInterceptor[] = [];
     private resInterceptors: ResponseInterceptor[] = [];
@@ -31,26 +109,41 @@ class UniRequestClient implements RequestClient {
     private baseURL = "";
     private defaultHeaders: Record<string, string> = { "Content-Type": "application/json" };
 
+    /**
+     * 设置全局基础请求 URL。
+     */
     setBaseURL(url: string): void {
         this.baseURL = url;
     }
 
+    /**
+     * 注册一个请求拦截器。
+     */
     onRequest(fn: RequestInterceptor): () => void {
         this.reqInterceptors.push(fn);
         return () => this.remove(this.reqInterceptors, fn);
     }
 
+    /**
+     * 注册一个响应拦截器。
+     */
     onResponse<T = unknown>(fn: ResponseInterceptor<T>): () => void {
         const item = fn as ResponseInterceptor;
         this.resInterceptors.push(item);
         return () => this.remove(this.resInterceptors, item);
     }
 
+    /**
+     * 注册一个错误拦截器。
+     */
     onError(fn: ErrorInterceptor): () => void {
         this.errInterceptors.push(fn);
         return () => this.remove(this.errInterceptors, fn);
     }
 
+    /**
+     * 执行 HTTP 请求。
+     */
     async request<T = unknown>(config: RequestConfig): Promise<ApiResponse<T>> {
         let cfg: RequestConfig = {
             method: "GET",
@@ -58,12 +151,14 @@ class UniRequestClient implements RequestClient {
             headers: { ...this.defaultHeaders, ...config.headers },
         };
 
+        // 顺序执行请求拦截器
         for (const fn of this.reqInterceptors) {
             cfg = await fn(cfg);
         }
 
         try {
             const res = await this.send<T>(this.resolveUrl(cfg.url), cfg);
+            // 顺序执行响应拦截器
             for (const fn of this.resInterceptors) {
                 const next = await fn(res as ApiResponse<unknown>);
                 if (next !== undefined) return next as ApiResponse<T>;
@@ -71,6 +166,7 @@ class UniRequestClient implements RequestClient {
             return res;
         } catch (e) {
             const err = e as Error;
+            // 执行错误拦截器
             for (const fn of this.errInterceptors) {
                 await fn(err);
             }
@@ -78,22 +174,37 @@ class UniRequestClient implements RequestClient {
         }
     }
 
+    /**
+     * 发送 GET 请求。
+     */
     get<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>> {
         return this.request<T>({ url, method: "GET", data });
     }
 
+    /**
+     * 发送 POST 请求。
+     */
     post<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>> {
         return this.request<T>({ url, method: "POST", data });
     }
 
+    /**
+     * 发送 PUT 请求。
+     */
     put<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>> {
         return this.request<T>({ url, method: "PUT", data });
     }
 
+    /**
+     * 发送 DELETE 请求。
+     */
     del<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>> {
         return this.request<T>({ url, method: "DELETE", data });
     }
 
+    /**
+     * 上传本地文件，适配云存储（COS/OSS/七牛/Alist）或本地直传。
+     */
     upload(config: UploadConfig): Promise<UploadResult> {
         const fileName = config.fileName ?? config.filePath.split("/").pop() ?? "file";
         const server = config.type === "local" && config.url ? config.url : config.server;
@@ -134,6 +245,9 @@ class UniRequestClient implements RequestClient {
         });
     }
 
+    /**
+     * 解析微服务风格的命名空间 URL。
+     */
     resolveServiceUrl(namespace: string, url: string, servicePrefix = ""): string {
         if (isAbsolute(url)) return url;
 
@@ -145,11 +259,17 @@ class UniRequestClient implements RequestClient {
         return prefix ? `/${prefix}${path}` : path;
     }
 
+    /**
+     * 内部拼接基础 URL 与相对路径。
+     */
     private resolveUrl(url: string): string {
         if (isAbsolute(url)) return url;
         return `${this.baseURL}${url}`;
     }
 
+    /**
+     * 内部基于 uni.request 发送网络请求的方法。
+     */
     private send<T>(url: string, cfg: RequestConfig): Promise<ApiResponse<T>> {
         return new Promise((resolve, reject) => {
             uni.request({
@@ -172,22 +292,51 @@ class UniRequestClient implements RequestClient {
         });
     }
 
+    /**
+     * 从数组中安全移除某个拦截器实例。
+     */
     private remove<T>(items: T[], item: T): void {
         const index = items.indexOf(item);
         if (index > -1) items.splice(index, 1);
     }
 }
 
+/**
+ * 判断 URL 是否为绝对路径（支持 http://, https://, file://）。
+ */
 function isAbsolute(url: string): boolean {
     return /^(https?:)?\/\//.test(url) || url.startsWith("file://");
 }
 
 const requestClient = new UniRequestClient();
 
+/**
+ * 获取全局请求客户端单例。
+ * 
+ * @example
+ * ```ts
+ * const http = useRequest();
+ * http.setBaseURL('https://api.example.com');
+ * ```
+ */
 export function useRequest(): RequestClient {
     return requestClient;
 }
 
+/**
+ * 文件上传 composable。
+ * 提供 `uploading` 状态与上传方法。
+ * 
+ * @example
+ * ```ts
+ * const { uploading, upload } = useUpload();
+ * const res = await upload({
+ *   type: 'oss',
+ *   filePath: 'temp-path',
+ *   server: 'https://oss-endpoint.com'
+ * });
+ * ```
+ */
 export function useUpload() {
     const uploading = ref(false);
 

package/src/composables/request/service.ts

@@ -1,22 +1,56 @@
 import { useRequest } from "./client";
 import type { ApiResponse, RequestConfig } from "./types";
 
+/**
+ * 带有具体必填 URL 的服务请求配置。
+ */
 export type ServiceRequestConfig = Omit<RequestConfig, "url"> & {
     url: string;
 };
 
+/**
+ * 命名空间装饰器配置项。
+ */
 export interface ServiceNamespaceOptions {
+    /** 微服务或模块命名空间 */
     namespace: string;
 }
 
+/**
+ * 服务前缀装饰器配置项。
+ */
 export interface ServicePrefixOptions {
+    /** 基础路径前缀 */
     prefix: string;
 }
 
+/**
+ * 基础服务抽象类。
+ * 业务 Service 类继承此类后，可通过 decorators 注入前缀与命名空间，
+ * 并通过便捷方法发起网络请求。
+ * 
+ * @example
+ * ```ts
+ * @ServicePrefix('/api')
+ * @ServiceNamespace('user')
+ * class UserService extends BaseService {
+ *   getUserInfo(id: string) {
+ *     return this.get(`/info?id=${id}`);
+ *   }
+ * }
+ * ```
+ */
 export class BaseService {
+    /** 当前服务的命名空间（一般由 @ServiceNamespace 注入） */
     declare namespace: string;
+    /** 当前服务的基础路径前缀（一般由 @ServicePrefix 注入） */
     declare servicePrefix: string;
 
+    /**
+     * 发送服务请求。会自动拼接前缀与命名空间。
+     * @param options 请求配置项
+     * @returns 响应结果 Promise
+     */
     request<T = unknown>(options: ServiceRequestConfig): Promise<ApiResponse<T>> {
         return useRequest().request<T>({
             ...options,
@@ -24,29 +58,59 @@ export class BaseService {
         });
     }
 
+    /**
+     * 快捷发送 GET 请求。
+     * @param url 请求相对路径
+     * @param data 请求参数
+     */
     get<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>> {
         return this.request<T>({ url, method: "GET", data });
     }
 
+    /**
+     * 快捷发送 POST 请求。
+     * @param url 请求相对路径
+     * @param data 请求携带的 body
+     */
     post<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>> {
         return this.request<T>({ url, method: "POST", data });
     }
 
+    /**
+     * 快捷发送 PUT 请求。
+     * @param url 请求相对路径
+     * @param data 请求携带的 body
+     */
     put<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>> {
         return this.request<T>({ url, method: "PUT", data });
     }
 
+    /**
+     * 快捷发送 DELETE 请求。
+     * @param url 请求相对路径
+     * @param data 请求参数
+     */
     del<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>> {
         return this.request<T>({ url, method: "DELETE", data });
     }
 }
 
+/**
+ * 服务命名空间类装饰器。
+ * 注入 `namespace` 到服务类中。
+ * @param value 命名空间名称或配置对象
+ */
 export function ServiceNamespace(value: string | ServiceNamespaceOptions) {
     return function (target: { prototype: { namespace?: string } }) {
         target.prototype.namespace = typeof value === "string" ? value : value.namespace;
     };
 }
 
+/**
+ * 服务前缀类装饰器。
+ * 注入 `servicePrefix` 到服务类中。
+ * @param value 前缀值或配置对象
+ */
 export function ServicePrefix(value: string | ServicePrefixOptions) {
     return function (target: { prototype: { servicePrefix?: string } }) {
         target.prototype.servicePrefix = typeof value === "string" ? value : value.prefix;

package/src/composables/request/types.ts

@@ -1,53 +1,93 @@
-/** API 统一响应格式 */
+/**
+ * API 统一响应格式
+ * 定义服务端接口的标准数据返回格式。
+ */
 export interface ApiResponse<T = unknown> {
+    /** 业务状态码 (例如: 1 代表成功，非 1 代表不同类型的失败) */
     code: number;
+    /** 响应的主体数据 */
     data: T;
+    /** 响应的文本提示信息（如：操作成功、系统繁忙） */
     info: string;
 }
 
-/** 分页数据 */
+/**
+ * 分页请求的标准数据包装格式。
+ */
 export interface PageResult<T = unknown> {
+    /** 分页列表数据 */
     list: T[];
+    /** 总记录数 */
     total: number;
+    /** 当前页码 */
     page: number;
+    /** 每页记录条数 */
     pageSize: number;
 }
 
-/** 请求配置 */
+/**
+ * HTTP 请求参数配置项。
+ */
 export interface RequestConfig {
+    /** 请求的目标 URL，支持绝对路径或相对 BaseURL 的相对路径 */
     url: string;
+    /** 请求的 HTTP 方法，默认 "GET" */
     method?: "GET" | "POST" | "PUT" | "DELETE";
+    /** 请求携带的数据载体，GET/DELETE 对应 Query 传参，POST/PUT 对应 Body 传参 */
     data?: unknown;
+    /** 自定义请求头 */
     headers?: Record<string, string>;
+    /** 请求超时时间，单位毫秒 */
     timeout?: number;
 }
 
-/** 拦截器类型 */
+/** 
+ * 请求拦截器函数定义。
+ * 允许在请求被发出前修改请求配置，支持异步处理。
+ */
 export type RequestInterceptor = (config: RequestConfig) => RequestConfig | Promise<RequestConfig>;
+
+/** 
+ * 响应拦截器函数定义。
+ * 允许在响应被接收并传递给业务逻辑前对响应数据做预处理，支持异步处理。
+ */
 export type ResponseInterceptor<T = unknown> = (res: ApiResponse<T>) => ApiResponse<T> | void | Promise<ApiResponse<T> | void>;
+
+/** 
+ * 错误拦截器函数定义。
+ * 用于统一捕获和处理网络层或业务层抛出的异常。
+ */
 export type ErrorInterceptor = (err: Error) => void | Error | Promise<void | Error>;
 
-/** 上传配置 */
+/**
+ * 云存储或文件直传服务配置项。
+ */
 export interface UploadConfig {
-    /** 上传接口地址 */
+    /** 上传的服务器网关 URL */
     server: string;
-    /** 文件路径 */
+    /** 本地待上传的文件路径 (tempFilePath) */
     filePath: string;
-    /** 文件名，可选，默认取 filePath */
+    /** 直传服务器接收的文件参数名称，默认自动从 filePath 中截取 */
     fileName?: string;
-    /** 上传类型，支持 cos | oss | qiniu | alist | local */
+    /** 云直传供应商类型，支持 'cos' | 'oss' | 'qiniu' | 'alist' | 'local' */
     type: string;
-    /** 云存储密钥凭证 */
+    /** 直传签名凭证所需的一组敏感密钥对（AK、Signature、Token 等） */
     credentials?: Record<string, string>;
-    /** 自定义请求头 */
+    /** 直传时的自定义 HTTP 请求头 */
     header?: Record<string, string>;
-    /** 上传类型为 local 时，作为最终 server */
+    /** 当 type="local" 时，可以通过此属性覆盖 server 参数作为最终上传端点 */
     url?: string;
 }
 
-/** 上传结果 */
+/**
+ * 文件上传完成后标准接口解析出的结果。
+ */
 export interface UploadResult {
+    /** 业务状态码 */
     code: number;
+    /** 上传提示信息 */
     msg: string;
+    /** 上传成功后云端资源的可访问 URL 或文件路径 */
     data: string;
 }
+

package/src/composables/share/index.ts

@@ -3,24 +3,53 @@ import {
     onShareTimeline as registerShareTimeline,
 } from "@dcloudio/uni-app";
 
+/**
+ * 分享卡片配置项。
+ */
 export interface ShareConfig {
+    /** 分享的标题，默认使用小程序名称 */
     title?: string;
+    /** 分享的页面路径，支持携带 query 参数，如 '/pages/index/index?id=123' */
     path?: string;
+    /** 分享卡片的展示图 URL 或本地路径 */
     imageUrl?: string;
 }
 
+/**
+ * 支持静态配置或动态解析器函数。
+ */
 export type ShareConfigResolver = ShareConfig | (() => ShareConfig);
 
+/**
+ * 分享操作句柄接口。
+ */
 export interface ShareHandlers {
+    /**
+     * 手动触发分享好友设置。
+     * @param config 可选的额外覆盖分享配置
+     */
     onShareAppMessage: (config?: ShareConfigResolver) => void;
+    /**
+     * 手动触发分享朋友圈设置。
+     * @param config 可选的额外覆盖分享配置
+     */
     onShareTimeline: (config?: ShareConfigResolver) => void;
+    /**
+     * 显示分享菜单项，启用小程序右上角分享。
+     */
     showShareMenu: () => void;
 }
 
+/**
+ * 解析分享配置。
+ */
 function resolveConfig(config?: ShareConfigResolver): ShareConfig {
     return typeof config === "function" ? config() : (config ?? {});
 }
 
+/**
+ * 合并并构建标准的分享数据载体。
+ */
 function buildPayload(base: ShareConfigResolver, extra?: ShareConfigResolver): ShareConfig {
     const current = {
         ...resolveConfig(base),
@@ -33,6 +62,9 @@ function buildPayload(base: ShareConfigResolver, extra?: ShareConfigResolver): S
     return payload;
 }
 
+/**
+ * 显示微信原生分享菜单。
+ */
 function showShareMenu(): void {
     const api = typeof uni !== "undefined" ? (uni as unknown as {
         showShareMenu?: (options: {
@@ -49,6 +81,21 @@ function showShareMenu(): void {
     });
 }
 
+/**
+ * 小程序页面分享 Hook。
+ * 自动调用并监听当前页面的 `onShareAppMessage` 与 `onShareTimeline` 原生事件。
+ * 
+ * @param config 默认的分享配置或配置函数
+ * @returns 包含手动触发或配置的方法句柄
+ * 
+ * @example
+ * ```ts
+ * useShare({
+ *   title: '欢迎体验我的小程序',
+ *   path: '/pages/index/index'
+ * });
+ * ```
+ */
 export function useShare(config: ShareConfigResolver = {}): ShareHandlers {
     let appMessageRegistered = false;
     let timelineRegistered = false;
@@ -74,6 +121,7 @@ export function useShare(config: ShareConfigResolver = {}): ShareHandlers {
         });
     };
 
+    // 默认在 setup 阶段触发注册
     onShareAppMessage();
     onShareTimeline();