@hlw-uni/mp-vue 1.0.35 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hlw-uni/mp-vue",
-    "version": "1.0.35",
+    "version": "1.1.1",
     "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

@@ -0,0 +1,141 @@
+<template>
+    <button
+        class="hlw-btn"
+        :class="[
+            `hlw-btn--${type}`,
+            `hlw-btn--${size}`,
+            { 'hlw-btn--block': block, 'hlw-btn--round': round, 'hlw-btn--disabled': disabled, 'hlw-btn--loading': loading },
+        ]"
+        :disabled="disabled || loading"
+        :open-type="openType"
+        @tap="$emit('click')"
+    >
+        <view v-if="loading" class="hlw-btn-spinner" />
+        <view v-else-if="icon" :class="icon" class="hlw-btn-icon" />
+        <slot />
+    </button>
+</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";
+    loading?: boolean;
+    disabled?: boolean;
+    block?: boolean;
+    round?: boolean;
+    icon?: string;
+    openType?: string;
+}
+
+withDefaults(defineProps<Props>(), {
+    type: "primary",
+    size: "medium",
+    loading: false,
+    disabled: false,
+    block: false,
+    round: false,
+    icon: "",
+    openType: "",
+});
+
+defineEmits<{ click: [] }>();
+</script>
+
+<style lang="scss" scoped>
+.hlw-btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 8rpx;
+    border: none;
+    font-weight: 500;
+    line-height: 1;
+    transition: opacity 0.2s;
+
+    &::after { display: none; }
+    &:active { opacity: 0.7; }
+
+    &--primary {
+        background: var(--primary-color);
+        color: #fff;
+    }
+    &--outline {
+        background: transparent;
+        color: var(--primary-color);
+        border: 2rpx solid var(--primary-color);
+    }
+    &--text {
+        background: transparent;
+        color: var(--primary-color);
+    }
+    &--ghost {
+        background: transparent;
+        color: #fff;
+        border: 2rpx solid rgba(255, 255, 255, 0.6);
+    }
+
+    &--small {
+        padding: 8rpx 20rpx;
+        font-size: var(--font-xs, 20rpx);
+        border-radius: var(--radius-sm, 8rpx);
+    }
+    &--medium {
+        padding: 16rpx 32rpx;
+        font-size: var(--font-sm, 24rpx);
+        border-radius: var(--radius-md, 16rpx);
+    }
+    &--large {
+        padding: 24rpx 48rpx;
+        font-size: var(--font-base, 28rpx);
+        border-radius: var(--radius-md, 16rpx);
+    }
+
+    &--block { display: flex; width: 100%; }
+    &--round { border-radius: 999rpx; }
+    &--disabled { opacity: 0.4; &:active { opacity: 0.4; } }
+    &--loading { opacity: 0.7; }
+}
+
+.hlw-btn-icon {
+    font-size: 1.1em;
+}
+
+.hlw-btn-spinner {
+    width: 28rpx;
+    height: 28rpx;
+    border: 3rpx solid currentColor;
+    border-top-color: transparent;
+    border-radius: 50%;
+    animation: hlw-spin 0.6s linear infinite;
+}
+
+@keyframes hlw-spin {
+    to { transform: rotate(360deg); }
+}
+</style>

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

@@ -0,0 +1,143 @@
+<template>
+    <navigator v-if="url" :url="url" 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>
+        <view class="hlw-cell-body">
+            <view class="hlw-cell-title">
+                <slot name="title">{{ title }}</slot>
+                <view v-if="label" class="hlw-cell-label">{{ label }}</view>
+            </view>
+            <view class="hlw-cell-value">
+                <slot name="value">{{ value }}</slot>
+            </view>
+        </view>
+        <view class="hlw-cell-arrow" />
+    </navigator>
+    <view v-else class="hlw-cell" :class="{ 'hlw-cell--border': border, 'hlw-cell--link': isLink }" :hover-class="isLink ? 'hlw-cell--hover' : ''" @tap="$emit('click')">
+        <view v-if="icon || $slots.icon" class="hlw-cell-icon">
+            <slot name="icon"><view :class="icon" /></slot>
+        </view>
+        <view class="hlw-cell-body">
+            <view class="hlw-cell-title">
+                <slot name="title">{{ title }}</slot>
+                <view v-if="label" class="hlw-cell-label">{{ label }}</view>
+            </view>
+            <view class="hlw-cell-value">
+                <slot name="value">{{ value }}</slot>
+            </view>
+        </view>
+        <view v-if="isLink" class="hlw-cell-arrow" />
+        <slot name="right" />
+    </view>
+</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;
+    value?: string;
+    icon?: string;
+    isLink?: boolean;
+    url?: string;
+    border?: boolean;
+}
+
+withDefaults(defineProps<Props>(), {
+    title: "",
+    label: "",
+    value: "",
+    icon: "",
+    isLink: false,
+    url: "",
+    border: true,
+});
+
+defineEmits<{ click: [] }>();
+</script>
+
+<style lang="scss" scoped>
+.hlw-cell {
+    display: flex;
+    align-items: center;
+    padding: 24rpx 32rpx;
+    background: #fff;
+    gap: 20rpx;
+
+    &--border {
+        border-bottom: 1rpx solid var(--border-color-light, #f1f5f9);
+        &:last-child { border-bottom: none; }
+    }
+    &--hover { background: #f8fafc; }
+}
+
+.hlw-cell-icon {
+    font-size: var(--font-lg, 36rpx);
+    color: var(--primary-color, #3b82f6);
+    flex-shrink: 0;
+}
+
+.hlw-cell-body {
+    flex: 1;
+    min-width: 0;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+}
+
+.hlw-cell-title {
+    font-size: var(--font-base, 28rpx);
+    color: #1e293b;
+}
+
+.hlw-cell-label {
+    font-size: var(--font-xs, 20rpx);
+    color: #94a3b8;
+    margin-top: 4rpx;
+}
+
+.hlw-cell-value {
+    font-size: var(--font-sm, 24rpx);
+    color: #94a3b8;
+    flex-shrink: 0;
+}
+
+.hlw-cell-arrow {
+    width: 16rpx;
+    height: 16rpx;
+    border-top: 3rpx solid #c0c4cc;
+    border-right: 3rpx solid #c0c4cc;
+    transform: rotate(45deg);
+    flex-shrink: 0;
+}
+</style>

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

@@ -0,0 +1,72 @@
+<template>
+    <view class="hlw-divider" :class="[`hlw-divider--${position}`, { 'hlw-divider--dashed': dashed }]">
+        <view class="hlw-divider-line" />
+        <view v-if="text || $slots.default" class="hlw-divider-text">
+            <slot>{{ text }}</slot>
+        </view>
+        <view class="hlw-divider-line" />
+    </view>
+</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";
+    dashed?: boolean;
+}
+
+withDefaults(defineProps<Props>(), {
+    text: "",
+    position: "center",
+    dashed: false,
+});
+</script>
+
+<style lang="scss" scoped>
+.hlw-divider {
+    display: flex;
+    align-items: center;
+    padding: 24rpx 0;
+}
+
+.hlw-divider-line {
+    flex: 1;
+    height: 1rpx;
+    background: var(--border-color, #e2e8f0);
+
+    .hlw-divider--dashed & {
+        background: none;
+        border-top: 1rpx dashed var(--border-color, #e2e8f0);
+    }
+}
+
+.hlw-divider-text {
+    padding: 0 24rpx;
+    font-size: var(--font-xs, 20rpx);
+    color: #94a3b8;
+    white-space: nowrap;
+}
+
+.hlw-divider--left .hlw-divider-line:first-child { max-width: 60rpx; }
+.hlw-divider--right .hlw-divider-line:last-child { max-width: 60rpx; }
+</style>

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

@@ -0,0 +1,157 @@
+<template>
+    <view v-if="show" class="hlw-modal-mask" @tap.self="onMask">
+        <view class="hlw-modal" :class="{ 'hlw-modal--show': show }">
+            <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>
+            </slot>
+        </view>
+    </view>
+</template>
+
+<script setup lang="ts">
+/**
+ * HlwModal — 模态弹窗
+ *
+ * 比 uni.showModal 更灵活：支持插槽自定义内容和底部按钮。
+ * 使用 v-model:show 控制显隐。
+ *
+ * @props
+ *   show        - 是否显示，支持 v-model:show
+ *   title       - 标题文字
+ *   showCancel  - 是否显示取消按钮，默认 true
+ *   confirmText - 确认按钮文字，默认 "确定"
+ *   cancelText  - 取消按钮文字，默认 "取消"
+ *   closeOnMask - 点击蒙层是否关闭，默认 true
+ *
+ * @events
+ *   update:show - 显隐状态变更
+ *   confirm     - 点击确认
+ *   cancel      - 点击取消
+ *
+ * @slots
+ *   default - 弹窗内容
+ *   footer  - 自定义底部按钮区域（覆盖默认确认/取消）
+ *
+ * @example
+ * ```vue
+ * <HlwModal v-model:show="visible" title="提示" @confirm="onOk">
+ *   <text>确定要删除吗？</text>
+ * </HlwModal>
+ * ```
+ */
+interface Props {
+    show?: boolean;
+    title?: string;
+    showCancel?: boolean;
+    confirmText?: string;
+    cancelText?: string;
+    closeOnMask?: boolean;
+}
+
+withDefaults(defineProps<Props>(), {
+    show: false,
+    title: "",
+    showCancel: true,
+    confirmText: "确定",
+    cancelText: "取消",
+    closeOnMask: true,
+});
+
+const emit = defineEmits<{ "update:show": [value: boolean]; confirm: []; cancel: [] }>();
+
+function close() {
+    emit("update:show", false);
+}
+
+function onMask() {
+    close();
+}
+
+function onConfirm() {
+    emit("confirm");
+    close();
+}
+
+function onCancel() {
+    emit("cancel");
+    close();
+}
+</script>
+
+<style lang="scss" scoped>
+.hlw-modal-mask {
+    position: fixed;
+    inset: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: rgba(0, 0, 0, 0.5);
+    z-index: 1000;
+    animation: hlw-fade-in 0.2s;
+}
+
+.hlw-modal {
+    width: 80%;
+    max-width: 600rpx;
+    background: #fff;
+    border-radius: var(--radius-xl, 32rpx);
+    overflow: hidden;
+    animation: hlw-scale-in 0.25s ease;
+}
+
+.hlw-modal-title {
+    padding: 40rpx 32rpx 0;
+    text-align: center;
+    font-size: var(--font-md, 32rpx);
+    font-weight: 600;
+    color: #1e293b;
+}
+
+.hlw-modal-body {
+    padding: 32rpx;
+    font-size: var(--font-base, 28rpx);
+    color: #475569;
+    text-align: center;
+    line-height: 1.6;
+}
+
+.hlw-modal-footer {
+    display: flex;
+    border-top: 1rpx solid var(--border-color-light, #f1f5f9);
+}
+
+.hlw-modal-btn {
+    flex: 1;
+    padding: 24rpx 0;
+    text-align: center;
+    font-size: var(--font-base, 28rpx);
+    font-weight: 500;
+
+    &:active { background: #f8fafc; }
+
+    &--cancel {
+        color: #64748b;
+        border-right: 1rpx solid var(--border-color-light, #f1f5f9);
+    }
+    &--confirm {
+        color: var(--primary-color, #3b82f6);
+    }
+}
+
+@keyframes hlw-fade-in {
+    from { opacity: 0; }
+    to { opacity: 1; }
+}
+
+@keyframes hlw-scale-in {
+    from { transform: scale(0.9); opacity: 0; }
+    to { transform: scale(1); opacity: 1; }
+}
+</style>