@hlw-uni/mp-vue 1.1.0 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hlw-uni/mp-vue",
-    "version": "1.1.0",
+    "version": "1.1.2",
     "description": "hlw-uni Vue 组件库 — 供小程序业务方使用的 UI 组件集合",
     "main": "src/index.ts",
     "module": "src/index.ts",

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

@@ -14,6 +14,21 @@
 </template>
 
 <script setup lang="ts">
+/**
+ * HlwAvatar — 头像组件
+ *
+ * 显示用户头像，图片加载失败时自动回退到姓名首字母占位。
+ *
+ * @props
+ *   src   - 头像图片地址
+ *   name  - 用户名称，用于提取首字母（图片缺失时显示）
+ *   size  - 尺寸：small(56rpx) / medium(80rpx) / large(120rpx)，默认 medium
+ *
+ * @example
+ * ```vue
+ * <HlwAvatar src="/avatar.png" name="张三" size="large" />
+ * ```
+ */
 import { ref, computed } from 'vue';
 
 const props = defineProps<{

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

@@ -17,6 +17,31 @@
 </template>
 
 <script setup lang="ts">
+/**
+ * HlwButton — 主题按钮
+ *
+ * 跟随 --primary-color 主题色，支持多种类型、尺寸和状态。
+ *
+ * @props
+ *   type     - 按钮类型：primary / outline / text / ghost，默认 primary
+ *   size     - 尺寸：small / medium / large，默认 medium
+ *   loading  - 加载状态（显示 spinner 并禁止点击），默认 false
+ *   disabled - 禁用状态，默认 false
+ *   block    - 块级按钮（占满父容器宽度），默认 false
+ *   round    - 圆角药丸形状，默认 false
+ *   icon     - 左侧图标 class（如 i-fa6-solid-plus）
+ *   openType - 微信原生 open-type（如 share、getPhoneNumber）
+ *
+ * @events
+ *   click - 点击事件
+ *
+ * @example
+ * ```vue
+ * <HlwButton type="primary" @click="submit">提交</HlwButton>
+ * <HlwButton type="outline" loading>加载中</HlwButton>
+ * <HlwButton type="text" icon="i-fa6-solid-plus">新增</HlwButton>
+ * ```
+ */
 interface Props {
     type?: "primary" | "outline" | "text" | "ghost";
     size?: "small" | "medium" | "large";

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

@@ -33,6 +33,36 @@
 </template>
 
 <script setup lang="ts">
+/**
+ * HlwCell — 列表单元格
+ *
+ * 通用列表项：左侧 icon + 标题/描述 + 右侧内容/箭头。
+ * 传入 url 自动渲染为 navigator 组件。
+ *
+ * @props
+ *   title  - 标题文字
+ *   label  - 描述文字（标题下方灰色小字）
+ *   value  - 右侧内容文字
+ *   icon   - 左侧图标 class（如 i-fa6-solid-gear）
+ *   isLink - 是否显示右箭头，默认 false
+ *   url    - 跳转地址（有值则渲染为 navigator）
+ *   border - 是否显示底部分割线，默认 true
+ *
+ * @events
+ *   click - 点击事件（url 模式下由 navigator 处理跳转）
+ *
+ * @slots
+ *   icon  - 自定义左侧图标
+ *   title - 自定义标题区域
+ *   value - 自定义右侧内容
+ *   right - 自定义最右侧区域
+ *
+ * @example
+ * ```vue
+ * <HlwCell title="设置" icon="i-fa6-solid-gear" is-link url="/pages/settings/index" />
+ * <HlwCell title="版本号" value="1.0.0" />
+ * ```
+ */
 interface Props {
     title?: string;
     label?: string;

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

@@ -9,6 +9,26 @@
 </template>
 
 <script setup lang="ts">
+/**
+ * HlwDivider — 分割线
+ *
+ * 水平分割线，可带文字说明，支持虚线和文字位置调整。
+ *
+ * @props
+ *   text     - 分割线中间文字
+ *   position - 文字位置：left / center / right，默认 center
+ *   dashed   - 是否虚线，默认 false
+ *
+ * @slots
+ *   default - 自定义分割线中间内容（覆盖 text）
+ *
+ * @example
+ * ```vue
+ * <HlwDivider />
+ * <HlwDivider text="或" />
+ * <HlwDivider text="更多" position="left" dashed />
+ * ```
+ */
 interface Props {
     text?: string;
     position?: "left" | "center" | "right";

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

@@ -1,8 +1,8 @@
 <template>
     <view class="hlw-empty">
         <image v-if="image" class="hlw-empty__image" :src="image" mode="aspectFit" />
-        <text v-else class="hlw-empty__icon">📦</text>
-        <text class="hlw-empty__text">{{ text || '暂无数据' }}</text>
+        <view v-else class="hlw-empty__icon i-fa6-solid-box-open" />
+        <text class="hlw-empty__text">{{ text || "暂无数据" }}</text>
         <slot />
     </view>
 </template>
@@ -32,6 +32,7 @@ defineProps<{
 .hlw-empty__icon {
     font-size: 100rpx;
     margin-bottom: 20rpx;
+    color: #cbd5e1;
 }
 
 .hlw-empty__text {

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

@@ -34,6 +34,34 @@
 </template>
 
 <script setup lang="ts">
+/**
+ * HlwHeader — 页面顶部导航栏
+ *
+ * 自动适配状态栏高度和胶囊按钮位置（微信小程序），支持返回按钮、自定义标题和背景。
+ *
+ * @props
+ *   title       - 标题文字
+ *   titleAlign  - 标题对齐：center / left，默认 center
+ *   titleSize   - 标题字号，默认 var(--font-base)
+ *   titleWeight - 标题字重，默认 500
+ *   titleColor  - 标题颜色
+ *   isBack      - 是否显示返回按钮，默认 false
+ *   bgClass     - 自定义背景 CSS class
+ *   extraHeight - 额外高度（rpx），默认 0
+ *
+ * @events
+ *   back - 点击返回按钮
+ *
+ * @slots
+ *   bg        - 自定义背景层
+ *   title     - 自定义标题区域
+ *   back-icon - 自定义返回图标
+ *
+ * @example
+ * ```vue
+ * <HlwHeader title="我的" is-back @back="goBack" />
+ * ```
+ */
 import { ref, computed, useSlots } from "vue";
 
 const getNavBarContentHeight = (): number => {

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

@@ -6,6 +6,19 @@
 </template>
 
 <script setup lang="ts">
+/**
+ * HlwLoading — 加载动画组件
+ *
+ * 圆形旋转 spinner，可附带文字提示。
+ *
+ * @props
+ *   text - 加载提示文字（可选）
+ *
+ * @example
+ * ```vue
+ * <HlwLoading text="加载中..." />
+ * ```
+ */
 defineProps<{
     text?: string;
 }>();

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

@@ -1,14 +1,22 @@
 <template>
     <view v-if="show" class="hlw-modal-mask" @tap.self="onMask">
-        <view class="hlw-modal" :class="{ 'hlw-modal--show': show }">
+        <view class="hlw-modal" :class="{ 'hlw-modal--show': show }" @tap.stop>
             <view v-if="title" class="hlw-modal-title">{{ title }}</view>
             <view class="hlw-modal-body">
                 <slot />
             </view>
             <slot name="footer">
                 <view class="hlw-modal-footer">
-                    <view v-if="showCancel" class="hlw-modal-btn hlw-modal-btn--cancel" @tap="onCancel">{{ cancelText }}</view>
-                    <view class="hlw-modal-btn hlw-modal-btn--confirm" @tap="onConfirm">{{ confirmText }}</view>
+                    <view
+                        v-if="showCancel"
+                        class="hlw-modal-btn hlw-modal-btn--cancel"
+                        @tap.stop="onCancel"
+                    >
+                        {{ cancelText }}
+                    </view>
+                    <view class="hlw-modal-btn hlw-modal-btn--confirm" @tap.stop="onConfirm">
+                        {{ confirmText }}
+                    </view>
                 </view>
             </slot>
         </view>
@@ -25,7 +33,7 @@ interface Props {
     closeOnMask?: boolean;
 }
 
-withDefaults(defineProps<Props>(), {
+const props = withDefaults(defineProps<Props>(), {
     show: false,
     title: "",
     showCancel: true,
@@ -41,6 +49,7 @@ function close() {
 }
 
 function onMask() {
+    if (!props.closeOnMask) return;
     close();
 }
 
@@ -110,6 +119,7 @@ function onCancel() {
         color: #64748b;
         border-right: 1rpx solid var(--border-color-light, #f1f5f9);
     }
+
     &--confirm {
         color: var(--primary-color, #3b82f6);
     }

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

@@ -1,19 +1,19 @@
 <template>
     <view v-if="!closed" class="hlw-notice" :style="{ color, background }">
         <view v-if="leftIcon" :class="leftIcon" class="hlw-notice-left-icon" />
-        <view v-else class="hlw-notice-left-icon">&#128227;</view>
+        <view v-else class="hlw-notice-left-icon i-fa6-solid-bullhorn" />
         <view class="hlw-notice-wrap" @tap="$emit('click')">
             <view v-if="scrollable" class="hlw-notice-scroll" :style="animStyle">
                 <text class="hlw-notice-text">{{ text }}</text>
             </view>
             <text v-else class="hlw-notice-text hlw-notice-text--ellipsis">{{ text }}</text>
         </view>
-        <view v-if="closable" class="hlw-notice-close" @tap="onClose">&#215;</view>
+        <view v-if="closable" class="hlw-notice-close i-fa6-solid-xmark" @tap="onClose" />
     </view>
 </template>
 
 <script setup lang="ts">
-import { ref, computed, onMounted } from "vue";
+import { computed, ref } from "vue";
 
 interface Props {
     text?: string;
@@ -86,10 +86,10 @@ function onClose() {
 
 .hlw-notice-close {
     flex-shrink: 0;
-    font-size: 32rpx;
+    font-size: 28rpx;
     line-height: 1;
     opacity: 0.6;
-    padding: 0 4rpx;
+    padding: 4rpx;
 }
 
 @keyframes hlw-notice-scroll {

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

@@ -26,6 +26,30 @@
 </template>
 
 <script setup lang="ts">
+/**
+ * HlwPage — 页面布局容器
+ *
+ * 全屏 flex 布局：固定 header + 可滚动 content + 固定 footer。
+ * 传入 title/isBack 自动渲染 HlwHeader，也可通过 header 插槽完全自定义。
+ *
+ * @props
+ *   title   - 页面标题（自动渲染 HlwHeader）
+ *   isBack  - 是否显示返回按钮，默认 false
+ *   bgClass - header 背景 CSS class
+ *
+ * @slots
+ *   header  - 自定义顶部（覆盖默认 HlwHeader）
+ *   default - 主体可滚动内容
+ *   footer  - 固定底部
+ *
+ * @example
+ * ```vue
+ * <HlwPage title="首页" bg-class="header-bg">
+ *   <view>页面内容</view>
+ *   <template #footer><view>底部栏</view></template>
+ * </HlwPage>
+ * ```
+ */
 interface Props {
     title?: string;
     isBack?: boolean;

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

@@ -3,7 +3,7 @@
     <view class="hlw-popup" :class="[`hlw-popup--${position}`, { 'hlw-popup--show': show, 'hlw-popup--round': round }]">
         <view v-if="title || closable" class="hlw-popup-header">
             <text class="hlw-popup-title">{{ title }}</text>
-            <view v-if="closable" class="hlw-popup-close" @tap="onClose">&#215;</view>
+            <view v-if="closable" class="hlw-popup-close i-fa6-solid-xmark" @tap="onClose" />
         </view>
         <slot />
     </view>
@@ -95,10 +95,10 @@ function onClose() {
 }
 
 .hlw-popup-close {
-    font-size: 40rpx;
+    font-size: 32rpx;
     color: #94a3b8;
     line-height: 1;
-    padding: 0 8rpx;
+    padding: 4rpx;
 }
 
 @keyframes hlw-fade-in {

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

@@ -1,7 +1,7 @@
 <template>
     <view class="hlw-search" :style="background ? { background } : {}">
         <view class="hlw-search-box" :class="{ 'hlw-search-box--round': shape === 'round' }">
-            <view class="hlw-search-icon">&#128269;</view>
+            <view class="hlw-search-icon i-fa6-solid-magnifying-glass" />
             <input
                 class="hlw-search-input"
                 type="text"
@@ -14,7 +14,7 @@
                 @focus="$emit('focus')"
                 @blur="$emit('blur')"
             />
-            <view v-if="clearable && modelValue" class="hlw-search-clear" @tap="onClear">&#215;</view>
+            <view v-if="clearable && modelValue" class="hlw-search-clear i-fa6-solid-xmark" @tap="onClear" />
         </view>
     </view>
 </template>
@@ -46,8 +46,8 @@ const emit = defineEmits<{
     blur: [];
 }>();
 
-function onInput(e: { detail: { value: string } }) {
-    emit("update:modelValue", e.detail.value);
+function onInput(e: any) {
+    emit("update:modelValue", e?.detail?.value ?? "");
 }
 
 function onClear() {
@@ -86,10 +86,10 @@ function onClear() {
 }
 
 .hlw-search-clear {
-    font-size: 32rpx;
+    font-size: 28rpx;
     color: #94a3b8;
     line-height: 1;
     flex-shrink: 0;
-    padding: 0 4rpx;
+    padding: 4rpx;
 }
 </style>

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

@@ -10,6 +10,29 @@
 </template>
 
 <script setup lang="ts">
+/**
+ * HlwSkeleton — 骨架屏
+ *
+ * 数据加载占位，支持头像 + 标题 + 多行文字组合。loading 为 false 时显示默认插槽内容。
+ *
+ * @props
+ *   loading    - 是否显示骨架屏，默认 true
+ *   rows       - 文字行数，默认 3
+ *   avatar     - 是否显示头像占位，默认 false
+ *   title      - 是否显示标题占位，默认 true
+ *   animate    - 是否启用脉冲动画，默认 true
+ *   avatarSize - 头像尺寸：small / medium / large，默认 medium
+ *
+ * @slots
+ *   default - 加载完成后显示的真实内容
+ *
+ * @example
+ * ```vue
+ * <HlwSkeleton :loading="loading" avatar :rows="4">
+ *   <view>真实数据内容</view>
+ * </HlwSkeleton>
+ * ```
+ */
 interface Props {
     loading?: boolean;
     rows?: number;

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

@@ -20,6 +20,28 @@
 </template>
 
 <script setup lang="ts">
+/**
+ * HlwTabs — 选项卡
+ *
+ * 横向选项卡切换，支持文字 / 对象配置、徽标和滚动模式。
+ * 激活项跟随 --primary-color 主题色。
+ *
+ * @props
+ *   modelValue - 当前选中索引，支持 v-model，默认 0
+ *   items      - 选项列表：string[] 或 { label, badge? }[]
+ *   scrollable - 超出时是否可横向滚动，默认 false
+ *   lineWidth  - 底部指示线宽度，默认 40rpx
+ *
+ * @events
+ *   update:modelValue - 切换时触发
+ *   change            - 切换时触发（携带新索引）
+ *
+ * @example
+ * ```vue
+ * <HlwTabs v-model="activeTab" :items="['推荐', '热门', '最新']" />
+ * <HlwTabs v-model="tab" :items="[{ label: '消息', badge: '3' }, { label: '关注' }]" />
+ * ```
+ */
 export interface HlwTabItem {
     label: string;
     badge?: string;

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

@@ -6,7 +6,7 @@
         @tap="$emit('click')"
     >
         <slot />
-        <view v-if="closable" class="hlw-tag-close" @tap.stop="$emit('close')">&#215;</view>
+        <view v-if="closable" class="hlw-tag-close i-fa6-solid-xmark" @tap.stop="$emit('close')" />
     </view>
 </template>
 
@@ -68,7 +68,7 @@ $colors: (
 }
 
 .hlw-tag-close {
-    font-size: 1.2em;
+    font-size: 1em;
     line-height: 1;
     margin-left: 2rpx;
     opacity: 0.8;