@hlw-uni/mp-vue 2.1.71 → 2.1.97

package/dist/utils/ad/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 小程序广告工具。
+ * 提供插屏广告 (Interstitial Ad) 与激励视频广告 (Rewarded Video Ad) 的注册、缓存与展示能力。
+ */
+/**
+ * 广告播放/加载结果数据结构。
+ */
+export interface AdRes {
+    /** 广告是否正常加载或成功展示完成 */
+    success: boolean;
+    /** 激励视频是否完全播放完毕 (仅激励视频有此属性) */
+    isEnded: boolean;
+    /** 加载或展示失败时的错误对象 */
+    err?: any;
+}
+/**
+ * 配置/预加载插屏广告
+ *
+ * @param adId 广告单元 ID
+ * @param done 广告关闭后的回调（可选）
+ * @returns 是否配置成功
+ */
+export declare function setPopupAd(adId: string, done?: (ok: boolean) => void): boolean;
+/**
+ * 延迟展示已配置的插屏广告
+ *
+ * @param delay 延迟毫秒数，默认 3000ms
+ * @returns 返回 Promise，指示是否成功显示且被关闭
+ */
+export declare function showPopupAd(delay?: number): Promise<boolean>;
+/**
+ * 配置/预加载激励视频广告
+ *
+ * @param adId 广告单元 ID
+ * @param done 播放结束的回调（可选）
+ * @returns 返回 Promise<AdRes>
+ */
+export declare function setRewardAd(adId: string, done?: (res: AdRes) => void): Promise<AdRes>;
+/**
+ * 立即播放已加载的激励视频广告
+ *
+ * @param onShowSuccess 广告成功拉起播放时的回调（常用于关闭 Loading 等待提示）
+ * @returns 返回 Promise<AdRes>，指示广告是否正常播放完毕
+ */
+export declare function showRewardAd(onShowSuccess?: () => void): Promise<AdRes>;
+/**
+ * 弹窗提示需要看完广告才有奖励。
+ * 提供“继续观看”和“取消”按钮。
+ * @returns 返回 Promise<boolean>，用户点击“继续”返回 true，点击“取消”返回 false
+ */
+export declare function confirmRewardAd(): Promise<boolean>;
+/**
+ * @deprecated 推荐直接从库导入独立函数使用 (例如：import { showRewardAd } from '@hlw-uni/mp-vue')
+ */
+export declare function useHlwAd(): {
+    setPopupAd: typeof setPopupAd;
+    showPopupAd: typeof showPopupAd;
+    setRewardAd: typeof setRewardAd;
+    showRewardAd: typeof showRewardAd;
+    confirmRewardAd: typeof confirmRewardAd;
+};

package/dist/{composables/utils → utils/common}/index.d.ts

@@ -37,7 +37,7 @@ export interface DownloadRes {
  */
 export declare function withQuery(url: string, qs: string): string;
 /**
- * 将键值对对象转换为 URL 编码的 Query String。
+ * 将键值对对象转换为 URL 编码 of Query String。
  * 会自动过滤值为 `undefined` 或 `null` 的键。
  * @param data 需要转换的键值对数据对象
  * @returns 格式化后的 Query String 字符串
@@ -117,26 +117,3 @@ export declare function saveImageUrl(url: string, progress?: (value: number) =>
  * @returns 操作是否成功
  */
 export declare function saveVideoUrl(url: string, progress?: (value: number) => void): Promise<boolean>;
-/**
- * 获取系统通用工具方法的 hook。
- *
- * @example
- * ```ts
- * const { copy, saveImageUrl } = useUtils();
- * copy('hello');
- * ```
- */
-export declare function useUtils(): {
-    withQuery: typeof withQuery;
-    toQuery: typeof toQuery;
-    signText: typeof signText;
-    toNumber: typeof toNumber;
-    toBoolean: typeof toBoolean;
-    copy: typeof copy;
-    paste: typeof paste;
-    saveImage: typeof saveImage;
-    saveVideoFile: typeof saveVideoFile;
-    download: typeof download;
-    saveImageUrl: typeof saveImageUrl;
-    saveVideoUrl: typeof saveVideoUrl;
-};

package/dist/{composables → utils}/device/index.d.ts

@@ -12,7 +12,7 @@ export interface DeviceInfo {
     app_version_code: string;
     /** 小程序来源渠道 */
     app_channel: string;
-    /** 设备品牌。如：apple、huawei */
+    /** 设备 brand。如：apple、huawei */
     device_brand: string;
     /** 设备型号 */
     device_model: string;
@@ -64,14 +64,13 @@ export interface DeviceInfo {
  */
 export type DeviceQueryInfo = Pick<DeviceInfo, "appid" | "device_brand" | "device_model" | "device_id" | "device_type" | "device_orientation" | "platform" | "system" | "os" | "version" | "sdk_version" | "host_name" | "host_version" | "host_language" | "language" | "app_version" | "app_version_code" | "screen_width" | "screen_height">;
 /**
- * 访问当前设备配置信息的 hooks。
- *
- * @returns 包含 `info` (原始数据) 和 `query` (用于 HTTP 报头/URL query 的 urlencoded 字符串)
+ * 获取缓存后的设备信息数据。
  */
-export declare function useDevice(): {
-    info: DeviceInfo;
-    query: string;
-};
+export declare function getDevice(): DeviceInfo;
+/**
+ * 获取接口请求专用的设备信息 query 字符串。
+ */
+export declare function getDeviceQuery(): string;
 /**
  * 清除本地设备信息缓存，使下一次读取重新走系统调用收集。
  */

package/dist/utils/index.d.ts

@@ -0,0 +1,5 @@
+export * from './ad';
+export * from './common';
+export * from './navigator';
+export * from './device';
+export * from './request';

package/dist/{composables → utils}/navigator/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * useNavigate - uni-app 路由跳转工具
+ * uni-app 路由跳转工具
  * 封装并统一原生的页面跳转、重定向、Switch Tab、返回、以及打开外部小程序或 WebView 等方法。
  */
 /** 页面跳转类型，支持微信小程序的各类路由动作与 WebView/小程序跳转 */
@@ -28,32 +28,16 @@ export interface NavigateOptions {
  * @param url 跳转目标路径或小程序 AppId
  * @param options 额外的控制参数
  */
-declare function navigate(type?: NavigateType, url?: string, options?: NavigateOptions): void;
-/**
- * 路由跳转工具 hooks。
- *
- * @example
- * ```ts
- * const router = useNavigate();
- * router.to('/pages/index/index');
- * router.back();
- * router.miniProgram('app-id');
- * ```
- */
-export declare function useNavigate(): {
-    /** 核心底层路由分发函数 */
-    navigate: typeof navigate;
-    /** 保留当前页面，跳转到应用内的某个页面 */
-    to: (url: string, options?: NavigateOptions) => void;
-    /** 关闭当前页面，跳转到应用内的某个页面 */
-    redirect: (url: string, options?: NavigateOptions) => void;
-    /** 跳转到 switchTab 页面，并关闭其他所有非 tabBar 页面 */
-    tab: (url: string, options?: NavigateOptions) => void;
-    /** 关闭所有页面，打开到应用内的某个页面 */
-    reLaunch: (url: string, options?: NavigateOptions) => void;
-    /** 关闭当前页面，返回上一页面或多级页面 */
-    back: (delta?: number, options?: NavigateOptions) => void;
-    /** 打开另一个小程序 */
-    miniProgram: (appId: string, options?: NavigateOptions) => void;
-};
-export {};
+export declare function navigate(type?: NavigateType, url?: string, options?: NavigateOptions): void;
+/** 保留当前页面，跳转到应用内的某个页面 */
+export declare function navigateTo(url: string, options?: NavigateOptions): void;
+/** 关闭当前页面，跳转到应用内的某个页面 */
+export declare function redirectTo(url: string, options?: NavigateOptions): void;
+/** 跳转到 switchTab 页面，并关闭其他所有非 tabBar 页面 */
+export declare function switchTab(url: string, options?: NavigateOptions): void;
+/** 关闭所有页面，打开到应用内的某个页面 */
+export declare function reLaunch(url: string, options?: NavigateOptions): void;
+/** 关闭当前页面，返回上一页面或多级页面 */
+export declare function navigateBack(delta?: number, options?: NavigateOptions): void;
+/** 打开另一个小程序 */
+export declare function navigateToMiniProgram(appId: string, options?: NavigateOptions): void;

package/dist/{composables → utils}/request/client.d.ts

@@ -79,15 +79,9 @@ export interface RequestClient {
     onError(fn: ErrorInterceptor): () => void;
 }
 /**
- * 获取全局请求客户端单例。
- *
- * @example
- * ```ts
- * const http = useRequest();
- * http.setBaseURL('https://api.example.com');
- * ```
+ * 全局请求客户端单例。
  */
-export declare function useRequest(): RequestClient;
+export declare const request: RequestClient;
 /**
  * 文件上传 composable。
  * 提供 `uploading` 状态与上传方法。

package/dist/{composables → utils}/request/index.d.ts

@@ -1,4 +1,4 @@
-export { useRequest, useUpload } from './client';
+export { request, useUpload } from './client';
 export { BaseService, ServiceNamespace, ServicePrefix, PluginService } from './service';
 export type { RequestClient } from './client';
 export type { ApiResponse, PageResult, RequestConfig, RequestInterceptor, ResponseInterceptor, ErrorInterceptor, UploadConfig, UploadResult, } from './types';

package/dist/{composables → utils}/request/service.d.ts

@@ -56,13 +56,13 @@ export declare class BaseService {
     /**
      * 快捷发送 POST 请求。
      * @param url 请求相对路径
-     * @param data 请求携带的 body
+     * @param data 请求携带 the body
      */
     post<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>>;
     /**
      * 快捷发送 PUT 请求。
      * @param url 请求相对路径
-     * @param data 请求携带的 body
+     * @param data 请求携带 the body
      */
     put<T = unknown>(url: string, data?: unknown): Promise<ApiResponse<T>>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hlw-uni/mp-vue",
-    "version": "2.1.71",
+    "version": "2.1.97",
     "description": "hlw-uni 小程序运行时 — Vue 组件 + composables + theme + http + 工具集（合并自原 mp-core）",
     "main": "dist/index.js",
     "module": "dist/index.mjs",

package/src/app.ts

@@ -4,7 +4,7 @@
  */
 import { createSSRApp, type App, type Component } from 'vue';
 import { hlw } from '@/hlw';
-import { useRequest } from '@/composables/request';
+import { request } from '@/utils/request';
 
 let _installed = false;
 
@@ -60,6 +60,6 @@ export function useApp() {
         return createApp;
     }
 
-    return { install, use, hlw, request: useRequest() };
+    return { install, use, hlw, request };
 }
 

package/src/components/hlw-add-mini/README.md

@@ -1,16 +1,63 @@
-# 添加到我的小程序提示
+# hlw-add-mini 添加小程序提示气泡组件
 
-轻量提示用户从右上角菜单添加小程序。
+用于在页面顶部高亮显示提示气泡，指引并提示用户点击右上角将当前小程序“添加到我的小程序”中，以提升小程序的用户留存与二次回访率。
 
-| 参数 | 说明 | 类型 | 默认值 |
-| :-- | :-- | :-- | :-- |
-| show | 是否显示 | Boolean | false |
-| navigationStyle | 顶部导航栏样式，可选 `default`、`custom` | String | default |
-| title | 标题 | String | 添加到我的小程序 |
-| desc | 描述 | String | 点击右上角 ··· 添加 |
+---
+
+## 特性
+
+* **智能避让与精准指向**：利用小程序 `getMenuButtonBoundingClientRect` 胶囊元数据，气泡箭头将**像素级精准指向**右上角胶囊的“···”三点按钮中心。
+* **零配置自适应导航栏**：组件内部自动探测宿主页面的 `navigationStyle`（包括全局配置与页面单体配置）。若检测为全局/页面**自定义导航栏（`custom`）**，组件会自动避让胶囊按钮并下移气泡；若为默认原生导航栏，则自动贴顶展示，完全无需开发者手动传入导航栏参数。
+* **跨端优雅容错**：在不支持胶囊数据探测的非微信小程序平台，自动执行安全像素高度与宽度的优雅降级。
+
+---
+
+## 属性说明 (Props)
+
+| 属性名 | 说明 | 类型 | 默认值 |
+| :--- | :--- | :--- | :--- |
+| `show` | 控制气泡的显示与隐藏 | `Boolean` | `false` |
+| `title` | 提示气泡的主标题文字 | `String` | `"添加到我的小程序"` |
+| `desc` | 提示气泡的副标题/描述文字（传入空字符将不渲染描述行） | `String` | `"点击右上角 ··· 添加"` |
+
+---
+
+## 事件说明 (Events)
+
+| 事件名 | 说明 | 参数 |
+| :--- | :--- | :--- |
+| `@close` | 用户点击气泡右侧“×”关闭按钮时触发，开发者应在此事件中修改 `show` 为 `false` | 无 |
+
+---
+
+## 使用示例
 
 ```vue
 <template>
-	<hlw-add-mini :show="show" @close="close" />
+    <view class="container">
+        <!-- 指引添加小程序气泡 -->
+        <hlw-add-mini 
+            :show="showAddMiniTip" 
+            @close="showAddMiniTip = false" 
+        />
+        
+        <view class="content">
+            页面其它主体内容...
+        </view>
+    </view>
 </template>
+
+<script setup lang="ts">
+import { ref, onMounted } from "vue";
+
+const showAddMiniTip = ref(false);
+
+onMounted(() => {
+    // 首次进入页面时展示，或根据用户本地缓存判断是否展示
+    const hasAdded = uni.getStorageSync("has_added_mini");
+    if (!hasAdded) {
+        showAddMiniTip.value = true;
+    }
+});
+</script>
 ```

package/src/components/hlw-add-mini/index.vue

@@ -19,7 +19,7 @@
  * 会根据是否为自定义导航栏（custom），自动调整气泡浮动位置（避开胶囊按钮与状态栏）。
  */
 import { computed, ref, onMounted } from "vue";
-import { useDevice } from "../../composables/device";
+import { getDevice } from "../../utils/device";
 
 defineOptions({ name: "HlwAddMini" });
 
@@ -43,8 +43,8 @@ const emit = defineEmits<{
     close: [];
 }>();
 
-// 从 useDevice 获取缓存的设备系统信息，规避在 computed 中频繁调用同步系统 API 的性能问题
-const { info } = useDevice();
+// 从 getDevice 获取缓存的设备系统信息，规避在 computed 中频繁调用同步系统 API 的性能问题
+const info = getDevice();
 
 const isCustomNav = ref(false);
 
@@ -131,9 +131,10 @@ function close() {
 
 <style lang="scss" scoped>
 .hlw-add-mini {
+    --add-mini-bg: rgba(0, 0, 0, 0.72);
     position: fixed;
     right: 22rpx;
-    z-index: 99999;
+    z-index: 999;
     width: 340rpx;
     animation: hlw-add-mini-in 0.22s ease-out both;
 }
@@ -147,7 +148,7 @@ function close() {
     z-index: 99999;
     border-left: 12rpx solid transparent;
     border-right: 12rpx solid transparent;
-    border-bottom: 14rpx solid rgba(17, 24, 39, 0.82);
+    border-bottom: 14rpx solid var(--add-mini-bg);
 }
 
 .hlw-add-mini__content {
@@ -156,8 +157,10 @@ function close() {
     gap: 12rpx;
     padding: 16rpx 14rpx 16rpx 20rpx;
     border-radius: 14rpx;
-    background: rgba(17, 24, 39, 0.82);
-    box-shadow: 0 12rpx 34rpx rgba(15, 23, 42, 0.22);
+    background: var(--add-mini-bg);
+    backdrop-filter: blur(12rpx);
+    -webkit-backdrop-filter: blur(12rpx);
+    box-shadow: 0 12rpx 34rpx rgba(15, 23, 42, 0.15);
 }
 
 .hlw-add-mini__text {
@@ -174,11 +177,11 @@ function close() {
 }
 
 .hlw-add-mini__desc {
-    margin-top: 4rpx;
+    margin-top: 6rpx;
     color: rgba(255, 255, 255, 0.72);
     font-size: 21rpx;
     line-height: 1.3;
-    letter-spacing: 1rpx;
+    letter-spacing: 2rpx;
 }
 
 .hlw-add-mini__close {

package/src/components/hlw-avatar-upload/index.vue

@@ -0,0 +1,103 @@
+<template>
+    <view class="hlw-avatar-upload">
+        <button class="avatar-wrapper" open-type="chooseAvatar" @chooseavatar="onChooseAvatar" @click="onClick">
+            <hlw-avatar :src="props.src || ''" :name="props.name || '微信用户'" :size="props.size" :border="props.border" />
+            <view class="edit-avatar">
+                <span class="iconfont icon-xiangji edit-avatar-icon" />
+            </view>
+        </button>
+    </view>
+</template>
+
+<script setup lang="ts">
+defineOptions({ name: "HlwAvatarUpload" });
+
+interface Props {
+    /** 当前头像的网络/本地路径 */
+    src?: string;
+    /** 无头像时的备用展示昵称 */
+    name?: string;
+    /** 头像尺寸，可选 'small' | 'medium' | 'large' */
+    size?: "small" | "medium" | "large";
+    /** 边框线宽 */
+    border?: number;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+    src: "",
+    name: "微信用户",
+    size: "large",
+    border: 3,
+});
+
+const emit = defineEmits<{
+    (e: "onAvatar", filePath: string): void;
+}>();
+
+function onChooseAvatar(event: any) {
+    const filePath = String(event?.detail?.avatarUrl || "");
+    if (filePath) {
+        emit("onAvatar", filePath);
+    }
+}
+
+function onClick() {
+    // #ifndef MP-WEIXIN
+    uni.chooseImage({
+        count: 1,
+        success: (res) => {
+            const filePath = res.tempFilePaths[0];
+            if (filePath) {
+                emit("onAvatar", filePath);
+            }
+        },
+    });
+    // #endif
+}
+</script>
+
+<style scoped>
+.hlw-avatar-upload {
+    display: inline-block;
+}
+
+.avatar-wrapper {
+    position: relative;
+    display: inline-block;
+    border-radius: 50%;
+    margin: 0;
+    padding: 0;
+    background: transparent;
+    line-height: normal;
+    border: none;
+    overflow: visible;
+    cursor: pointer;
+}
+
+.avatar-wrapper::after {
+    border: none;
+    display: none;
+}
+
+.edit-avatar {
+    position: absolute;
+    bottom: -8rpx;
+    right: -8rpx;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 44rpx;
+    height: 44rpx;
+    margin: 0;
+    padding: 0;
+    border: 1rpx solid #e2e8f0; /* 圆角灰线 */
+    border-radius: 999rpx;
+    background: #ffffff; /* 白色背景 */
+    color: #64748b; /* 灰色相机图标 */
+    box-shadow: 0 4rpx 12rpx rgba(0, 0, 0, 0.08);
+}
+
+.edit-avatar .edit-avatar-icon {
+    font-size: 22rpx;
+}
+</style>

package/src/components/hlw-back-top/index.vue

@@ -7,7 +7,7 @@
         @tap="onTap"
     >
         <slot>
-            <text class="i-fa6-solid-chevron-up hlw-back-top__icon" />
+            <span class="i-fa6-solid-chevron-up hlw-back-top__icon" />
         </slot>
     </view>
 </template>

package/src/components/hlw-button/index.vue

@@ -37,24 +37,15 @@
 <script setup lang="ts">
 /**
  * HlwButton - 语义化/响应式通用按钮组件
- * 
+ *
  * 扩展了原生小程序 button 属性。支持丰富的语义色彩预设、尺寸自适应、圆角与 Block 状态，
  * 并且内置了快捷的 uni-app 路由跳转逻辑与 Native `open-type` 会话消息配置。
  */
 import { computed, useSlots } from "vue";
-import { useNavigate } from "@/composables/navigator";
+import { navigate } from "../../utils/navigator";
 
 /** 按钮类型：语义化颜色预设、边框模式、文本模式及幽灵模式 */
-type ButtonType =
-    | "primary"
-    | "success"
-    | "warning"
-    | "danger"
-    | "error"
-    | "info"
-    | "outline"
-    | "text"
-    | "ghost";
+type ButtonType = "primary" | "success" | "warning" | "danger" | "error" | "info" | "outline" | "text" | "ghost";
 
 /** 路由动作类型 */
 type NavigateType = "navigateTo" | "redirectTo" | "switchTab" | "reLaunch" | "navigateBack";
@@ -121,7 +112,7 @@ const props = withDefaults(defineProps<Props>(), {
 
 const emit = defineEmits<{
     /** 按钮点击事件（在未禁用且非 loading 时触发） */
-    click: []
+    click: [];
 }>();
 
 const slots = useSlots();
@@ -144,8 +135,6 @@ const buttonStyle = computed(() => {
     return style;
 });
 
-const navigator = useNavigate();
-
 /**
  * 处理点击事件与快捷页面跳转。
  */
@@ -156,7 +145,7 @@ const handleTap = () => {
 
     if (!props.url && props.navigateType !== "navigateBack") return;
 
-    navigator.navigate(props.navigateType, props.url, { delta: props.delta });
+    navigate(props.navigateType, props.url, { delta: props.delta });
 };
 </script>
 

package/src/components/hlw-canvas/index.vue

@@ -6,7 +6,7 @@
         hover-class="trigger--hover"
         @tap="onEnter"
     >
-        <text class="i-fa6-solid-pen-nib trigger-icon" />
+        <span class="i-fa6-solid-pen-nib trigger-icon" />
     </view>
 
     <!-- 全屏批注层，激活时覆盖整个页面（含 hlw-header） -->
@@ -25,7 +25,7 @@
         <!-- 顶部状态条：左关闭，右模式切换（避开右上角微信胶囊） -->
         <view class="bar">
             <view class="bar-close" hover-class="bar-close--hover" @tap="onExit">
-                <text class="i-fa6-solid-xmark bar-icon" />
+                <span class="i-fa6-solid-xmark bar-icon" />
             </view>
             <view
                 class="bar-toggle"
@@ -33,7 +33,7 @@
                 hover-class="bar-toggle--hover"
                 @tap="scrollMode = !scrollMode"
             >
-                <text :class="[scrollMode ? 'i-ri-arrow-up-down-line' : 'i-ri-pencil-line', 'bar-icon']" />
+                <span :class="[scrollMode ? 'i-ri-arrow-up-down-line' : 'i-ri-pencil-line', 'bar-icon']" />
                 <text class="bar-toggle-text">{{ scrollMode ? "滚动" : "绘画" }}</text>
             </view>
         </view>
@@ -50,7 +50,7 @@
                     hover-class="mode--hover"
                     @tap="mode = m.value"
                 >
-                    <text :class="m.icon" class="mode-icon" />
+                    <span :class="m.icon" class="mode-icon" />
                 </view>
             </view>
 
@@ -65,7 +65,7 @@
                         :style="{ background: c }"
                         @tap="color = c"
                     >
-                        <text v-if="c === color" class="i-fa6-solid-check color-check" />
+                        <span v-if="c === color" class="i-fa6-solid-check color-check" />
                     </view>
                 </view>
 
@@ -90,10 +90,10 @@
 
                 <view class="actions">
                     <view class="action" hover-class="action--hover" @tap="onUndo">
-                        <text class="i-ri-arrow-go-back-line action-icon" />
+                        <span class="i-ri-arrow-go-back-line action-icon" />
                     </view>
                     <view class="action" hover-class="action--hover" @tap="onClear">
-                        <text class="i-fa6-solid-trash-can action-icon" />
+                        <span class="i-fa6-solid-trash-can action-icon" />
                     </view>
                 </view>
             </view>

package/src/components/hlw-cell/index.vue

@@ -1,5 +1,5 @@
 <template>
-    <navigator v-if="url" :url="url" class="hlw-cell" :class="{ 'hlw-cell--border': border }" hover-class="hlw-cell--hover">
+    <navigator v-if="url" :url="url" animation-type="none" class="hlw-cell" :class="{ 'hlw-cell--border': border }" hover-class="hlw-cell--hover">
         <view v-if="icon || $slots.icon" class="hlw-cell-icon">
             <slot name="icon"><view :class="icon" /></slot>
         </view>