@hlw-uni/mp-vue 1.0.21 → 1.0.23

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

@@ -70,19 +70,60 @@
 </template>
 
 <script setup lang="ts">
+/**
+ * HlwMenu 菜单组件
+ *
+ * 支持列表模式和宫格模式，数据驱动，适用于个人中心、设置页等场景。
+ *
+ * @example 列表模式
+ * ```vue
+ * <hlw-menu title="我的服务" :items="menuItems" @click="handleClick" />
+ * ```
+ *
+ * @example 宫格模式
+ * ```vue
+ * <hlw-menu mode="grid" :columns="4" :items="gridItems" @click="handleClick" />
+ * ```
+ *
+ * @example 无边框
+ * ```vue
+ * <hlw-menu :items="menuItems" :border="false" />
+ * ```
+ */
+
 import { computed } from "vue";
 import type { HlwMenuItem } from "./types";
 export type { HlwMenuItem } from "./types";
 
 interface Props {
+    /**
+     * 菜单项数据列表。
+     * 每项可设置图标、文字、跳转路径、右侧标签、右侧纯文字、加载状态等。
+     * 设置 `visible: false` 可隐藏某一项。
+     */
     items: HlwMenuItem[];
-    /** 标题 */
+    /**
+     * 卡片标题，显示在菜单上方，标题下方带虚线分割。
+     * 不传则不显示标题区域。
+     * @default ""
+     */
     title?: string;
-    /** 布局模式，默认 list */
+    /**
+     * 布局模式。
+     * - `list`：列表模式，左侧图标 + 文字，右侧可显示标签 / 纯文字 / 加载状态 + 箭头
+     * - `grid`：宫格模式，图标居中 + 文字在下方，支持右上角角标
+     * @default "list"
+     */
     mode?: "list" | "grid";
-    /** 宫格列数，默认 4 */
+    /**
+     * 宫格模式每行列数，仅 `mode="grid"` 时生效。
+     * @default 4
+     */
     columns?: number;
-    /** 是否显示外边框，默认 true */
+    /**
+     * 是否显示卡片外边框。
+     * @default true
+     */
     border?: boolean;
 }
 
@@ -94,6 +135,11 @@ const props = withDefaults(defineProps<Props>(), {
 });
 
 const emit = defineEmits<{
+    /**
+     * 点击无跳转路径的菜单项时触发。
+     * 有 `url` 的项由 `navigator` 自行跳转，不触发此事件。
+     * @param item 被点击的菜单项
+     */
     click: [item: HlwMenuItem];
 }>();
 

package/src/components/hlw-menu/types.ts

@@ -1,25 +1,55 @@
+/** 图标主题色，对应预设的背景色 + 前景色组合 */
 export type HlwMenuIconTheme = "orange" | "purple" | "cyan" | "emerald" | "slate" | "wechat" | "rose" | "blue" | "red";
+
+/** 标签 / 角标的主题色 */
 export type HlwMenuTagTheme = "orange" | "red" | "wechat" | "rose" | "blue";
 
 export interface HlwMenuItem {
-    /** 图标 class，如 'i-fa6-solid-gear' */
+    /**
+     * 图标的 CSS class，使用 UnoCSS / iconify 图标名。
+     * @example "i-fa6-solid-gear"
+     */
     icon: string;
-    /** 图标主题色 */
+    /**
+     * 图标背景色主题。不传默认使用 `slate`（灰色）。
+     * @default "slate"
+     */
     iconTheme?: HlwMenuIconTheme;
-    /** 菜单文字 */
+    /** 菜单项文字 */
     label: string;
-    /** 跳转路径，有值则用 navigator 包裹 */
+    /**
+     * 跳转路径。有值时使用 `<navigator>` 包裹，点击直接跳转，不触发 `click` 事件。
+     * @example "/pages/setting/index"
+     */
     url?: string;
-    /** 右侧纯文字说明（列表模式），如版本号、状态文字 */
+    /**
+     * 右侧纯文字说明，仅列表模式显示。适合展示版本号、状态等辅助信息。
+     * @example "v1.2.0"
+     */
     value?: string;
-    /** 右侧标签文字（列表模式）/ 角标文字（宫格模式） */
+    /**
+     * 右侧彩色标签文字（列表模式）或图标右上角角标文字（宫格模式）。
+     * @example "NEW"
+     */
     tag?: string;
-    /** 标签主题色 */
+    /**
+     * 标签 / 角标的主题色。不传默认 `rose`（红色）。
+     * @default "rose"
+     */
     tagTheme?: HlwMenuTagTheme;
-    /** 标签是否闪烁 */
+    /**
+     * 标签是否呼吸闪烁动画，用于吸引用户注意。
+     * @default false
+     */
     tagPulse?: boolean;
-    /** 加载中状态（列表模式） */
+    /**
+     * 显示加载中转圈图标，仅列表模式生效。适合异步操作进行中的状态。
+     * @default false
+     */
     loading?: boolean;
-    /** 是否显示，默认 true */
+    /**
+     * 是否渲染该菜单项。`false` 时从列表中隐藏，不占位。
+     * @default true
+     */
     visible?: boolean;
 }

package/src/index.ts

@@ -2,14 +2,12 @@
  * @hlw-uni/mp-vue — Vue 组件库统一导出
  */
 
-export { default as HlwAd } from './components/hlw-ad/index.vue';
-export { default as HlwAvatar } from './components/hlw-avatar/index.vue';
-export { default as HlwCard } from './components/hlw-card/index.vue';
-export { default as HlwEmpty } from './components/hlw-empty/index.vue';
-export { default as HlwHeader } from './components/hlw-header/index.vue';
-export { default as HlwLoading } from './components/hlw-loading/index.vue';
-export { default as HlwMenu } from './components/hlw-menu/index.vue';
-export type { HlwMenuItem } from './components/hlw-menu/types';
-export { default as HlwMenuList } from './components/hlw-menu-list/index.vue';
-export { default as HlwPage } from './components/hlw-page/index.vue';
-export type { MenuItem } from './components/hlw-menu-list/types';
+export { default as HlwAd } from "./components/hlw-ad/index.vue";
+export { default as HlwAvatar } from "./components/hlw-avatar/index.vue";
+export { default as HlwCard } from "./components/hlw-card/index.vue";
+export { default as HlwEmpty } from "./components/hlw-empty/index.vue";
+export { default as HlwHeader } from "./components/hlw-header/index.vue";
+export { default as HlwLoading } from "./components/hlw-loading/index.vue";
+export { default as HlwMenu } from "./components/hlw-menu/index.vue";
+export type { HlwMenuItem } from "./components/hlw-menu/types";
+export { default as HlwPage } from "./components/hlw-page/index.vue";

package/dist/components/hlw-menu-list/types.d.ts

@@ -1,8 +0,0 @@
-export interface MenuItem {
-    key: string;
-    label: string;
-    icon?: string;
-    value?: string;
-    url?: string;
-    action?: () => void;
-}

package/src/components/hlw-menu-list/index.vue

@@ -1,94 +0,0 @@
-<template>
-    <view class="hlw-menu-list">
-        <view
-            v-for="item in items"
-            :key="item.key"
-            class="hlw-menu-list__item"
-            @tap="onTap(item)"
-        >
-            <view class="hlw-menu-list__left">
-                <text v-if="item.icon" class="hlw-menu-list__icon">{{ item.icon }}</text>
-                <text class="hlw-menu-list__label">{{ item.label }}</text>
-            </view>
-            <view class="hlw-menu-list__right">
-                <text v-if="item.value" class="hlw-menu-list__value">{{ item.value }}</text>
-                <text class="hlw-menu-list__arrow">›</text>
-            </view>
-        </view>
-    </view>
-</template>
-
-<script setup lang="ts">
-import type { MenuItem } from './types';
-
-const props = defineProps<{
-    items: MenuItem[];
-}>();
-
-const emit = defineEmits<{
-    (e: 'click', item: MenuItem): void;
-}>();
-
-function onTap(item: MenuItem) {
-    if (item.url) {
-        uni.navigateTo({ url: item.url });
-    } else if (item.action) {
-        item.action();
-    }
-    emit('click', item);
-}
-</script>
-
-<style scoped>
-.hlw-menu-list {
-    background: #fff;
-    border-radius: 16rpx;
-    overflow: hidden;
-}
-
-.hlw-menu-list__item {
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
-    padding: 28rpx 32rpx;
-    border-bottom: 1rpx solid #f5f5f5;
-}
-
-.hlw-menu-list__item:last-child {
-    border-bottom: none;
-}
-
-.hlw-menu-list__left {
-    display: flex;
-    align-items: center;
-    gap: 16rpx;
-}
-
-.hlw-menu-list__icon {
-    font-size: 36rpx;
-    width: 44rpx;
-    text-align: center;
-}
-
-.hlw-menu-list__label {
-    font-size: 30rpx;
-    color: #333;
-}
-
-.hlw-menu-list__right {
-    display: flex;
-    align-items: center;
-    gap: 8rpx;
-}
-
-.hlw-menu-list__value {
-    font-size: 28rpx;
-    color: #999;
-}
-
-.hlw-menu-list__arrow {
-    font-size: 36rpx;
-    color: #ccc;
-    line-height: 1;
-}
-</style>

package/src/components/hlw-menu-list/types.ts

@@ -1,8 +0,0 @@
-export interface MenuItem {
-    key: string;
-    label: string;
-    icon?: string;
-    value?: string;
-    url?: string;
-    action?: () => void;
-}