@hlw-uni/mp-vue 2.1.70 → 2.1.97

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

@@ -46,6 +46,42 @@
 </template>
 
 <script setup lang="ts">
+/**
+ * HlwPaging — 高级分页滚动加载组件
+ *
+ * 基于 z-paging 封装，集成了系统级 HlwLoading 和 HlwEmpty 状态。
+ * 支持下拉刷新、上拉加载、自动空状态占位与错误提示展示。
+ *
+ * @props
+ *   modelValue         - 绑定的列表数组数据
+ *   fixed              - 是否固定在屏幕上，默认 false
+ *   usePageScroll      - 是否使用页面滚动，默认 false
+ *   height             - 高度样式，如 "100%"
+ *   refresherEnabled   - 是否开启下拉刷新，默认 true
+ *   loadingMoreEnabled - 是否开启上拉加载，默认 true
+ *   defaultPageSize    - 默认每页大小
+ *   loadingText        - 加载提示文案，默认 "加载中..."
+ *   emptyText          - 数据为空提示文案，默认 "暂无数据"
+ *   errorText          - 数据加载失败提示文案，默认 "加载失败，请稍后重试"
+ *   emptyImage         - 自定义空状态图片地址
+ *   useDefaultLoading  - 是否使用内置加载状态插槽，默认 true
+ *   useDefaultEmpty    - 是否使用内置空状态插槽，默认 true
+ *
+ * @events
+ *   update:modelValue - 更新列表数组数据时触发
+ *   query             - 请求新一页数据时触发 (pageNo, pageSize)
+ *
+ * @exposed
+ *   pagingRef          - 内部 z-paging 的 ref 实例
+ *   completeByNoMore   - 结束加载并判断是否还有更多数据 (list, isNoMore)
+ *   completeByError    - 请求出错时调用
+ *   reload             - 重载当前列表
+ *
+ * @example
+ * ```vue
+ * <HlwPaging v-model="list" @query="fetchData" />
+ * ```
+ */
 import { computed, ref, useSlots } from "vue";
 import ZPaging from "z-paging/components/z-paging/z-paging.vue";
 import type { HlwPagingRef } from "./types";

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

@@ -16,6 +16,29 @@
 </template>
 
 <script setup lang="ts">
+/**
+ * HlwPopup — 基础遮罩弹窗组件
+ *
+ * 轻量级弹窗容器，支持从页面上、下、中等不同方位弹出。支持自定义圆角、头部标题及关闭按钮。
+ *
+ * @props
+ *   show     - 是否展示弹窗，默认 false
+ *   position - 弹窗滑出方向：top / center / bottom，默认 bottom
+ *   round    - 是否启用圆角效果，默认 true
+ *   closable - 是否展示关闭按钮，默认 true
+ *   title    - 弹窗顶部的标题文字
+ *
+ * @events
+ *   update:show - 双向绑定显示状态时触发
+ *   close       - 弹窗关闭时触发
+ *
+ * @example
+ * ```vue
+ * <HlwPopup v-model:show="visible" title="协议内容" position="bottom">
+ *     <view>这里是协议正文内容...</view>
+ * </HlwPopup>
+ * ```
+ */
 interface Props {
     show?: boolean;
     position?: "bottom" | "center" | "top";

package/src/components/hlw-reward-ad/index.vue

@@ -0,0 +1,133 @@
+<template>
+    <view class="hlw-reward-ad" @tap="handleClick">
+        <slot />
+    </view>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, watch } from "vue";
+import { setRewardAd, showRewardAd, confirmRewardAd } from "../../utils/ad";
+
+defineOptions({ name: "HlwRewardAd" });
+
+interface Props {
+    /** 微信广告单元 ID */
+    unitId: string;
+}
+
+const props = defineProps<Props>();
+
+const emit = defineEmits<{
+    (e: "onHandle", res: { success: boolean; isEnded: boolean; err?: any }): void;
+}>();
+
+// 点击锁定状态，防止连续多次点击重复触发广告
+const isClicked = ref(false);
+
+/**
+ * 提前初始化并静默加载广告实例的辅助方法。
+ */
+function preloadAd(id: string) {
+    if (!id) return;
+    // 异步静默加载，不使用 await 阻塞组件渲染或生命周期
+    setRewardAd(id).catch((err) => {
+        console.warn("[HlwRewardAd] Preload error:", err);
+    });
+}
+
+// 组件挂载时，提前执行激励视频广告的初始化与加载
+onMounted(() => {
+    preloadAd(props.unitId);
+});
+
+// 监听 unitId 的变化，确保广告单元 ID 动态改变时能够重新静默加载
+watch(
+    () => props.unitId,
+    (newId) => {
+        preloadAd(newId);
+    },
+);
+
+async function playRewardAdFlow(): Promise<void> {
+    // 弹出全局模态 Loading 状态
+    let hidden = false;
+    hlw.$msg.showLoading("正在拉起广告");
+
+    // 设置 8 秒防超时定时器，如果 8 秒后还没有关闭加载提示，则强制关闭
+    const timer = setTimeout(() => {
+        hide();
+    }, 8000);
+
+    function hide() {
+        if (hidden) return;
+        hidden = true;
+        clearTimeout(timer);
+        hlw.$msg.hideLoading();
+    }
+
+    try {
+        // 确保实例当前处于激活绑定状态
+        setRewardAd(props.unitId);
+
+        // 立即展示并播放广告
+        const res = await showRewardAd(hide);
+
+        // 播放流结束后（不管成功或退出），立刻关闭 Loading 状态
+        hide();
+
+        if (res.success && res.isEnded) {
+            emit("onHandle", {
+                success: true,
+                isEnded: true,
+            });
+        } else if (res.err) {
+            emit("onHandle", {
+                success: false,
+                isEnded: false,
+                err: res.err,
+            });
+        } else {
+            // 未看完（中途退出），提示用户是否继续观看
+            const retry = await confirmRewardAd();
+            if (retry) {
+                // 如果用户点击继续观看，递归执行广告流程
+                await playRewardAdFlow();
+            } else {
+                emit("onHandle", {
+                    success: false,
+                    isEnded: false,
+                });
+            }
+        }
+    } catch (e) {
+        hide();
+        console.error("[HlwRewardAd] Failed to show reward ad:", e);
+        emit("onHandle", {
+            success: false,
+            isEnded: false,
+            err: e,
+        });
+    }
+}
+
+async function handleClick() {
+    if (isClicked.value) return;
+    if (!props.unitId) {
+        console.warn("[HlwRewardAd] unitId is required but empty.");
+        return;
+    }
+
+    isClicked.value = true;
+    try {
+        await playRewardAdFlow();
+    } finally {
+        isClicked.value = false;
+    }
+}
+</script>
+
+<style scoped>
+.hlw-reward-ad {
+    display: inline-block;
+}
+</style>

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

@@ -20,6 +20,31 @@
 </template>
 
 <script setup lang="ts">
+/**
+ * HlwSearch — 高感官度输入搜索栏组件
+ *
+ * 规范化的小程序搜索栏输入框，支持一键清空、禁用、聚焦/失焦回调及回车直接搜索。
+ *
+ * @props
+ *   modelValue  - 双向绑定的输入内容
+ *   placeholder - 占位符提示文本，默认 "搜索"
+ *   disabled    - 是否禁用输入，默认 false
+ *   clearable   - 是否允许一键清空输入，默认 true
+ *   shape       - 形状样式：square(方角) / round(圆角)，默认 round
+ *   background  - 自定义搜索栏组件的背景色
+ *
+ * @events
+ *   update:modelValue - 更新绑定内容时触发
+ *   search            - 点击键盘回车搜索时触发 (value)
+ *   clear             - 点击清除按钮时触发
+ *   focus             - 输入框聚焦时触发
+ *   blur              - 输入框失焦时触发
+ *
+ * @example
+ * ```vue
+ * <HlwSearch v-model="keywords" placeholder="搜索商品" @search="onSearch" />
+ * ```
+ */
 interface Props {
     modelValue?: string;
     placeholder?: string;

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

@@ -6,7 +6,7 @@
                 <view v-if="showHandle" class="hlw-sheet-handle" />
                 <text v-if="title" class="hlw-sheet-title">{{ title }}</text>
                 <view v-if="showClose" class="hlw-sheet-close" @tap="handleClose">
-                    <text class="i-fa6-solid-xmark" />
+                    <span class="i-fa6-solid-xmark" />
                 </view>
             </view>
 

package/src/components/hlw-status-bar/index.vue

@@ -0,0 +1,113 @@
+<template>
+    <view 
+        class="hlw-status-bar" 
+        :class="[theme, props.fixed ? 'fixed' : '', props.customClass]" 
+        :style="statusBarStyle"
+    >
+        <slot></slot>
+    </view>
+    <!-- Spacer block when fixed is true to prevent layout shift -->
+    <view v-if="props.fixed && props.placeholder" :style="{ height: statusBarHeight + 'px' }"></view>
+</template>
+
+<script lang="ts" setup>
+/**
+ * hlw-status-bar — 自适应系统状态栏背景组件
+ *
+ * 自动获取设备系统状态栏高度，并应用与 hlw-nav-bar 完全一致的全局配色主题。
+ * 同时支持自定义 class 或自定义背景色/渐变色（自定义优先级最高）。
+ *
+ * @props
+ *   fixed       - 是否固定在顶部，默认 false
+ *   placeholder - 是否生成占位高度区块（仅在 fixed 为 true 时有效），默认 true
+ *   zIndex      - 自定义 z-index 层级，默认 999
+ *   customClass - 自定义样式类
+ *   bgColor     - 自定义背景颜色或渐变色（最高优先级，覆盖主题）
+ *
+ * @example
+ * ```vue
+ * <hlw-status-bar fixed bg-color="#ff0000" />
+ * ```
+ */
+import { computed } from "vue";
+import { useTheme } from "@/core";
+
+const { theme } = useTheme();
+
+const props = defineProps({
+    /** 是否固定在顶部 */
+    fixed: {
+        type: Boolean,
+        default: false,
+    },
+    /** 是否生成占位高度区块（仅在 fixed 为 true 时有效，防止页面内容被遮挡） */
+    placeholder: {
+        type: Boolean,
+        default: true,
+    },
+    /** 自定义 z-index（在 fixed 为 true 时生效） */
+    zIndex: {
+        type: Number,
+        default: 999,
+    },
+    /** 自定义 CSS Class */
+    customClass: {
+        type: String,
+        default: "",
+    },
+    /** 自定义背景颜色（支持 Hex/RGB/渐变色，优先级最高） */
+    bgColor: {
+        type: String,
+        default: "",
+    },
+});
+
+const statusBarHeight: number = uni.getSystemInfoSync()?.statusBarHeight || 20;
+
+const statusBarStyle = computed(() => {
+    const style: Record<string, any> = {
+        height: statusBarHeight + "px",
+    };
+    if (props.fixed) {
+        style.zIndex = props.zIndex;
+    }
+    if (props.bgColor) {
+        // 自定义颜色优先级最高，直接设置 background 样式覆盖 class 的 background-color
+        style.background = props.bgColor;
+    }
+    return style;
+});
+</script>
+
+<style lang="scss" scoped>
+.hlw-status-bar {
+    width: 750rpx;
+    transition: background-color 0.2s ease, background 0.2s ease;
+
+    &.fixed {
+        position: fixed;
+        top: 0;
+        left: 0;
+    }
+
+    /* 白色主题：白色状态栏 */
+    &.white-theme {
+        background-color: var(--navbar-bg-color, #ffffff);
+    }
+
+    /* 简洁主题：背景色与页面全局背景色一致 */
+    &.light-theme {
+        background-color: var(--bg-page, #f8f8f8);
+    }
+
+    /* 单色主题：纯主题色状态栏 */
+    &.mono-theme {
+        background-color: var(--primary-color, #3b82f6);
+    }
+
+    /* 颜色主题：立体光影感的主题色渐变背景 */
+    &.color-theme {
+        background: linear-gradient(135deg, rgba(0, 0, 0, 0.15) 0%, rgba(255, 255, 255, 0.15) 100%), var(--primary-color, #3b82f6);
+    }
+}
+</style>

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

@@ -11,6 +11,28 @@
 </template>
 
 <script setup lang="ts">
+/**
+ * HlwTag — 轻量徽标标签组件
+ *
+ * 适用于标记状态、商品分类、分类标签等，支持多种色彩类型、镂空样式、圆角胶囊轮廓及可关闭动作。
+ *
+ * @props
+ *   type     - 标签色彩类型：primary / success / warning / danger / error / info，默认 primary
+ *   plain    - 是否为镂空样式，默认 false
+ *   closable - 是否为可关闭标签（右侧展示 X 关闭按钮），默认 false
+ *   size     - 尺寸大小：small / medium，默认 medium
+ *   round    - 是否为圆角胶囊形状，默认 false
+ *   color    - 自定义背景与边框颜色（覆盖 type 样式）
+ *
+ * @events
+ *   click - 点击标签时触发
+ *   close - 点击关闭按钮时触发
+ *
+ * @example
+ * ```vue
+ * <HlwTag type="success" plain round>已发货</HlwTag>
+ * ```
+ */
 import { computed } from "vue";
 
 interface Props {

package/src/core/index.ts

@@ -1 +1,4 @@
 export * from "./theme";
+export * from "./msg";
+export * from "./refs";
+export * from "./share";

package/src/{composables → core}/msg/index.ts

@@ -187,4 +187,3 @@ export function useMsg(): HlwMsg {
         setLoadingBar,
     };
 }
-

package/src/{composables → core}/refs/index.ts

@@ -50,4 +50,3 @@ export function useRefs() {
 
     return { refs, setRefs };
 }
-

package/src/core/theme/index.ts

@@ -0,0 +1,115 @@
+import { computed, watch, onMounted } from "vue";
+import type { ComputedRef } from "vue";
+import { onShow } from "@dcloudio/uni-app";
+import { 
+    useThemeStore, 
+    themePresets, 
+    fontSizePresets, 
+    fontFamilyPresets 
+} from "../../stores/theme";
+
+declare const uni: any;
+
+export { 
+    themePresets, 
+    type ThemePreset, 
+    fontSizePresets, 
+    type FontSizePreset, 
+    fontFamilyPresets, 
+    type FontFamilyPreset 
+} from "../../stores/theme";
+
+// ==========================================
+// 统一个性化外观配置 Hook (useTheme)
+// ==========================================
+
+export function useTheme() {
+    const store = useThemeStore();
+    
+    // 主题
+    const theme: ComputedRef<string> = computed(() => store.theme);
+
+    // 辅助方法：设置系统状态栏/导航栏前景色（mono-theme 和 color-theme 设为白色，其余为黑色）
+    const updateNavbarColor = (targetTheme: string) => {
+        const isDarkTheme = ["mono-theme", "color-theme"].includes(targetTheme);
+        uni.setNavigationBarColor({
+            frontColor: isDarkTheme ? "#ffffff" : "#000000",
+            backgroundColor: isDarkTheme ? "#3b82f6" : "#ffffff",
+            fail: () => {}
+        });
+    };
+
+    // 1. 监控主题属性改变时，动态刷新
+    watch(
+        theme,
+        (newTheme) => {
+            updateNavbarColor(newTheme);
+        }
+    );
+
+    // 2. 组件/页面挂载完成时，执行一次设定
+    onMounted(() => {
+        updateNavbarColor(store.theme);
+    });
+
+    // 3. 页面显示或回退时，强行重刷前景色（try-catch 规避非 Page 的报错）
+    try {
+        onShow(() => {
+            updateNavbarColor(store.theme);
+        });
+    } catch (e) {
+        // 忽略非 Page 组件的绑定失败
+    }
+
+    // 4. 在 setup 初始化同步阶段以最快速度设定一次，尽可能规避生命周期滞后导致的闪烁
+    updateNavbarColor(store.theme);
+    
+    // 字体大小
+    const fontSize: ComputedRef<string> = computed(() => store.fontSize);
+    const fontSizeClass: ComputedRef<string> = computed(() => {
+        const found = fontSizePresets.find((p) => p.id === store.fontSize);
+        return found ? found.class : "font-size-standard";
+    });
+
+    // 字体样式
+    const fontFamily: ComputedRef<string> = computed(() => store.fontFamily);
+    const fontFamilyClass: ComputedRef<string> = computed(() => {
+        const found = fontFamilyPresets.find((p) => p.id === store.fontFamily);
+        return found ? found.class : "font-family-system";
+    });
+
+    // 动作方法
+    function setFontSize(size: string): void {
+        store.setFontSize(size);
+    }
+
+    function setFontFamily(font: string): void {
+        store.setFontFamily(font);
+    }
+
+    return {
+        theme,
+        fontSize,
+        fontSizeClass,
+        setFontSize,
+        fontFamily,
+        fontFamilyClass,
+        setFontFamily,
+        store,
+    };
+}
+
+/**
+ * 首次打开小程序时，初始化默认的主题配色
+ * @param defaultTheme 默认主题 ID，默认为 "mono-theme"
+ */
+export function initTheme(defaultTheme = "mono-theme"): void {
+    const hasCachedTheme = uni.getStorageSync("theme");
+    if (!hasCachedTheme) {
+        const store = useThemeStore();
+        const validThemes = themePresets.map((t) => t.id);
+        if (validThemes.includes(defaultTheme)) {
+            store.theme = defaultTheme;
+        }
+    }
+}

package/src/hlw.ts

@@ -1,11 +1,4 @@
-/**
- * hlw - 全局命名空间工厂
- * 提供 $msg、$device、$request、$utils 的统一访问入口。
- */
-import { useMsg } from '@/composables/msg';
-import { useDevice, type DeviceInfo } from '@/composables/device';
-import { useRequest } from '@/composables/request';
-import { useUtils } from '@/composables/utils';
+import { useMsg } from '@/core/msg';
 
 /**
  * 全局 hlw 实例接口定义，聚合了框架的核心能力。
@@ -13,16 +6,9 @@ import { useUtils } from '@/composables/utils';
 export interface HlwInstance {
   /** 统一的消息提示与模态弹窗管理模块 */
   $msg: ReturnType<typeof useMsg>;
-  /** 当前运行设备的详细系统信息 */
-  $device: DeviceInfo;
-  /** 全局配置的统一 HTTP 请求实例 */
-  $request: ReturnType<typeof useRequest>;
-  /** 聚合的常用小程序公共工具函数 */
-  $utils: ReturnType<typeof useUtils>;
 }
 
 let _msg: ReturnType<typeof useMsg> | null = null;
-let _utils: ReturnType<typeof useUtils> | null = null;
 
 /**
  * 全局单例 `hlw` 实例，各核心模块在首次读取时延迟初始化并缓存。
@@ -30,11 +16,5 @@ let _utils: ReturnType<typeof useUtils> | null = null;
 export const hlw: HlwInstance = {
   /** 延迟创建消息提示实例。 */
   get $msg() { return (_msg ??= useMsg()); },
-  /** 延迟读取并缓存设备信息。 */
-  get $device() { return useDevice().info; },
-  /** 复用全局请求实例。 */
-  $request: useRequest(),
-  /** 延迟创建通用工具实例。 */
-  get $utils() { return (_utils ??= useUtils()); },
 };
 

package/src/index.ts

@@ -8,17 +8,9 @@
  * UI 组件（hlw-page / hlw-button / hlw-ad 等）走 easycom 自动注册，不在这里 export。
  */
 
-// Composables / 工具 / Theme
-export * from "./composables";
-export { 
-    useTheme, 
-    themePresets, 
-    type ThemePreset,
-    fontFamilyPresets,
-    type FontFamilyPreset,
-    fontSizePresets,
-    type FontSizePreset
-} from "./core/theme";
+// Core / 工具
+export * from "./core";
+export * from "./utils";
 
 // 类型
 export type { HlwMenuItem } from "./components/hlw-menu/types";