hy-app 0.5.2 → 0.5.4

package/components/hy-tabbar-group/README.md

@@ -0,0 +1,326 @@
+# Hy Tabbar 组件
+
+## 介绍
+
+Tabbar 是一个底部标签导航组件，用于在应用不同页面之间进行快速切换。支持自定义样式、图标、文字、徽章、激活状态和路由跳转等功能。
+
+## 组件关系
+
+- `hy-tabbar-group`: 作为容器，管理多个 tabbar-item
+- `hy-tabbar-item`: 作为单个标签项，包含图标、文字和徽章等元素
+
+## 引入方式
+
+### 全局引入
+
+```typescript
+// 在 main.ts 或 index.ts 中引入
+import { createApp } from 'vue'
+import App from './App.vue'
+import HyDesignUni from '@/package'
+
+const app = createApp(App)
+app.use(HyDesignUni)
+app.mount('#app')
+```
+
+### 局部引入
+
+```vue
+<template>
+  <hy-tabbar-group v-model="current">
+    <hy-tabbar-item index="0" icon="home" text="首页"></hy-tabbar-item>
+    <hy-tabbar-item index="1" icon="discover" text="发现"></hy-tabbar-item>
+  </hy-tabbar-group>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import HyTabbarGroup from '@/package/components/hy-tabbar-group/hy-tabbar-group.vue'
+import HyTabbarItem from '@/package/components/hy-tabbar-item/hy-tabbar-item.vue'
+
+const current = ref('0')
+</script>
+```
+
+## HyTabbarGroup API
+
+### Props
+
+| 参数 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| v-model | `string \| number` | - | 是 | 当前选中项的索引 |
+| fixed | `boolean` | `false` | 否 | 是否固定在底部 |
+| safe-area-inset-bottom | `boolean` | `false` | 否 | 是否适配底部安全区域 |
+| background | `string` | `#fff` | 否 | 背景色 |
+| height | `string \| number` | `50px` | 否 | 高度 |
+| border-style | `string` | - | 否 | 边框样式，可选值：`solid`、`dashed`、`dotted` |
+| shadow-level | `0 \| 1 \| 2 \| 3` | `0` | 否 | 阴影等级 |
+| active-color | `string` | `#1677ff` | 否 | 激活状态颜色 |
+| inactive-color | `string` | `#606266` | 否 | 非激活状态颜色 |
+| icon-size | `string \| number` | `24` | 否 | 图标大小 |
+| fontSize | `string \| number` | `12` | 否 | 文字大小 |
+| icon-text-space | `string \| number` | `4` | 否 | 图标与文字间距 |
+| indicator-mode | `'none' \| 'bottom' \| 'top' \| 'full'` | `'none'` | 否 | 指示器模式 |
+| indicator-color | `string` | `#1677ff` | 否 | 指示器颜色 |
+| indicator-height | `string \| number` | `3px` | 否 | 指示器高度 |
+| indicator-length | `string \| number` | `20px` | 否 | 指示器长度 |
+| indicator-radius | `string \| number` | `4px` | 否 | 指示器圆角 |
+| transition-duration | `string \| number` | `300` | 否 | 过渡动画时长 |
+| customClass | `string` | - | 否 | 自定义类名 |
+| customStyle | `object` | - | 否 | 自定义样式 |
+| activeClass | `string` | - | 否 | 激活时的自定义类名 |
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| click | 点击标签项时触发 | `index: string \| number` | 选中项的索引 |
+| change | 选中项改变时触发 | `index: string \| number` | 选中项的索引 |
+| active | 选中项被激活时触发 | `index: string \| number` | 选中项的索引 |
+| update:active | 更新激活状态时触发 | `index: string \| number` | 选中项的索引 |
+
+### Slots
+
+| 名称 | 说明 | 子标签 |
+| --- | --- | --- |
+| default | 容纳 hy-tabbar-item 子组件 | `<hy-tabbar-item>` |
+
+### Expose
+
+| 方法名 | 说明 | 参数 |
+| --- | --- | --- |
+| selectItem | 选中指定标签项 | `index: string \| number` | 要选中的索引 |
+| updateRectInfo | 更新位置信息 | - |
+| registerTabItem | 注册标签项 | `item: object` | 标签项信息 |
+| unregisterTabItem | 注销标签项 | `item: object` | 标签项信息 |
+| handleClick | 处理点击事件 | `index: string \| number` | 点击的索引 |
+
+## HyTabbarItem API
+
+### Props
+
+| 参数 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| index | `string \| number` | - | 是 | 标签项的索引 |
+| icon | `string` | - | 否 | 图标名称 |
+| text | `string` | - | 否 | 文字内容 |
+| route | `string` | - | 否 | 路由路径 |
+| show-icon | `boolean` | `true` | 否 | 是否显示图标 |
+| hide-text | `boolean` | `false` | 否 | 是否隐藏文字 |
+| disabled | `boolean` | `false` | 否 | 是否禁用 |
+| click-effect | `'none' \| 'feedback' \| 'ripple'` | `'none'` | 否 | 点击效果 |
+| ripple-duration | `string` | `'300ms'` | 否 | 波纹动画时长 |
+| width | `string \| number` | - | 否 | 宽度 |
+| height | `string \| number` | - | 否 | 高度 |
+| show-active-bg | `boolean` | `false` | 否 | 是否显示激活背景 |
+| active-bg-color | `string` | - | 否 | 激活背景颜色 |
+| icon-color | `string` | - | 否 | 图标颜色 |
+| active-icon-color | `string` | - | 否 | 激活时图标颜色 |
+| inactive-icon-color | `string` | - | 否 | 非激活时图标颜色 |
+| text-color | `string` | - | 否 | 文字颜色 |
+| active-text-color | `string` | - | 否 | 激活时文字颜色 |
+| inactive-text-color | `string` | - | 否 | 非激活时文字颜色 |
+| icon-size | `string \| number` | `24` | 否 | 图标大小 |
+| icon-text-space | `string \| number` | `4` | 否 | 图标与文字间距 |
+| badge | `string \| number \| null` | - | 否 | 徽章内容 |
+| badge-offset | `[number, number]` | `[0, 0]` | 否 | 徽章偏移量 |
+| badge-max | `number` | `99` | 否 | 徽章最大值 |
+| badge-is-dot | `boolean` | `false` | 否 | 是否显示为点 |
+| badge-inverted | `boolean` | `false` | 否 | 是否使用浅色背景 |
+| badge-bg-color | `string` | `#ff4d4f` | 否 | 徽章背景色 |
+| badge-text-color | `string` | `#fff` | 否 | 徽章文字颜色 |
+| badge-show-zero | `boolean` | `false` | 否 | 徽章为0时是否显示 |
+| customClass | `string` | - | 否 | 自定义类名 |
+| customStyle | `object` | - | 否 | 自定义样式 |
+| activeClass | `string` | - | 否 | 激活时的自定义类名 |
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| click | 点击标签项时触发 | `{ index, icon, text }` | 标签项信息 |
+| active | 标签项被激活时触发 | `index: string \| number` | 标签项索引 |
+| change | 标签项状态改变时触发 | `index: string \| number` | 标签项索引 |
+| update:active | 更新激活状态时触发 | `index: string \| number` | 标签项索引 |
+
+### Slots
+
+| 名称 | 说明 |
+| --- | --- |
+| default | 自定义文字内容 |
+| icon | 自定义图标内容 |
+
+## 使用示例
+
+### 基础用法
+
+```vue
+<hy-tabbar-group v-model="current">
+  <hy-tabbar-item index="0" icon="home" text="首页"></hy-tabbar-item>
+  <hy-tabbar-item index="1" icon="discover" text="发现"></hy-tabbar-item>
+  <hy-tabbar-item index="2" icon="shopping-cart" text="购物车"></hy-tabbar-item>
+  <hy-tabbar-item index="3" icon="user" text="我的"></hy-tabbar-item>
+</hy-tabbar-group>
+```
+
+### 固定在底部
+
+```vue
+<hy-tabbar-group 
+  v-model="current"
+  fixed
+  safe-area-inset-bottom
+  background="#fff"
+  border-style="solid"
+>
+  <hy-tabbar-item index="0" icon="home" text="首页"></hy-tabbar-item>
+  <hy-tabbar-item index="1" icon="discover" text="发现"></hy-tabbar-item>
+</hy-tabbar-group>
+```
+
+### 添加徽章
+
+```vue
+<hy-tabbar-group v-model="current">
+  <hy-tabbar-item index="0" icon="home" text="首页"></hy-tabbar-item>
+  <hy-tabbar-item index="1" icon="message" text="消息" :badge="5"></hy-tabbar-item>
+  <hy-tabbar-item index="2" icon="notification" text="通知" badge-is-dot></hy-tabbar-item>
+</hy-tabbar-group>
+```
+
+### 自定义激活样式
+
+```vue
+<hy-tabbar-group 
+  v-model="current"
+  active-color="#ff6b81"
+>
+  <hy-tabbar-item 
+    index="0" 
+    icon="home" 
+    text="首页" 
+    show-active-bg
+    active-bg-color="rgba(255, 107, 129, 0.1)"
+  ></hy-tabbar-item>
+  <hy-tabbar-item 
+    index="1" 
+    icon="discover" 
+    text="发现" 
+    show-active-bg
+    active-bg-color="rgba(255, 107, 129, 0.1)"
+  ></hy-tabbar-item>
+</hy-tabbar-group>
+```
+
+### 点击效果
+
+```vue
+<hy-tabbar-group v-model="current">
+  <hy-tabbar-item 
+    index="0" 
+    icon="home" 
+    text="首页" 
+    click-effect="ripple"
+  ></hy-tabbar-item>
+  <hy-tabbar-item 
+    index="1" 
+    icon="discover" 
+    text="发现" 
+    click-effect="feedback"
+  ></hy-tabbar-item>
+</hy-tabbar-group>
+```
+
+### 路由跳转
+
+```vue
+<hy-tabbar-group v-model="current">
+  <hy-tabbar-item 
+    index="0" 
+    icon="home" 
+    text="首页" 
+    route="/pages/index/index"
+  ></hy-tabbar-item>
+  <hy-tabbar-item 
+    index="1" 
+    icon="mine" 
+    text="我的" 
+    route="/pages/mine/index"
+  ></hy-tabbar-item>
+</hy-tabbar-group>
+```
+
+### 指示器模式
+
+```vue
+<hy-tabbar-group 
+  v-model="current"
+  indicator-mode="bottom"
+  indicator-color="#1677ff"
+  indicator-height="3px"
+>
+  <hy-tabbar-item index="0" icon="home" text="首页"></hy-tabbar-item>
+  <hy-tabbar-item index="1" icon="discover" text="发现"></hy-tabbar-item>
+</hy-tabbar-group>
+```
+
+## 多端兼容性说明
+
+### H5 端
+- 支持 `vue-router` 路由跳转
+- 支持完整的触摸反馈和波纹效果
+- 支持所有 CSS 动画和过渡效果
+
+### 小程序端
+- 使用 `uni.navigateTo` 进行路由跳转
+- 优化了触摸事件处理，确保流畅的交互体验
+- 适配小程序的样式和布局特性
+
+### APP 端
+- 支持原生的触摸事件
+- 优化了性能，减少不必要的渲染
+- 适配不同设备的屏幕尺寸和安全区域
+
+## 常见问题
+
+### 1. 如何实现标签项的动态增减？
+
+通过 `v-if` 或 `v-for` 动态渲染 `hy-tabbar-item` 组件，组件会自动注册和注销。
+
+### 2. 如何自定义图标？
+
+可以使用 `icon` slot 来自定义图标内容，例如：
+
+```vue
+<hy-tabbar-item index="0" text="首页">
+  <template #icon>
+    <image src="/static/custom-icon.png" style="width: 24px; height: 24px;"></image>
+  </template>
+</hy-tabbar-item>
+```
+
+### 3. 如何处理路由跳转？
+
+设置 `route` 属性，组件会根据不同端自动选择合适的跳转方式。
+
+### 4. 如何适配 iPhone 的底部安全区域？
+
+设置 `safe-area-inset-bottom` 属性为 `true`。
+
+### 5. 如何自定义徽章样式？
+
+使用 `badge-*` 系列属性可以自定义徽章的各种样式，如颜色、大小、位置等。
+
+## 组件源码
+
+- [hy-tabbar-group](https://github.com/example/hy-design-uni/blob/main/src/package/components/hy-tabbar-group)
+- [hy-tabbar-item](https://github.com/example/hy-design-uni/blob/main/src/package/components/hy-tabbar-item)
+
+## 更新日志
+
+### v1.0.0
+- 初始版本发布
+- 支持基础的 tabbar 功能
+- 支持自定义样式和交互效果
+- 支持多端适配

package/components/hy-tabbar-group/hy-tabbar-group.vue

@@ -0,0 +1,87 @@
+<template>
+    <view
+        :class="{
+            'hy-tabbar-group__placeholder':
+                fixed && placeholder && safeAreaInsetBottom && shape === 'round'
+        }"
+    >
+        <view :class="rootClass" :style="rootStyle">
+            <slot></slot>
+        </view>
+    </view>
+</template>
+
+<script lang="ts">
+export default {
+    name: 'hy-tabbar-group',
+    options: {
+        addGlobalClass: true,
+        virtualHost: true,
+        styleIsolation: 'shared'
+    }
+}
+</script>
+
+<script lang="ts" setup>
+import { computed, provide, toRefs, type CSSProperties, ref, onUnmounted } from 'vue'
+import tabbarGroupProps from './props'
+import type { ITabBarGroupEmits } from './typing'
+
+/**
+ * 底部导航栏，用于在不同页面之间进行切换。
+ * @displayName hy-tabbar-group
+ */
+defineOptions({})
+
+const props = defineProps(tabbarGroupProps)
+const emit = defineEmits<ITabBarGroupEmits>()
+
+const index = ref(0) // 递增用
+const getIndex = () => {
+    return index.value++
+}
+
+provide('hy-tabbar', {
+    ...toRefs(props),
+    setChange,
+    getIndex
+})
+
+// 父属性值
+const rootStyle = computed(() => {
+    const style: CSSProperties = {
+        background: props.bgColor,
+        zIndex: props.zIndex
+    }
+    return Object.assign(style, props.customStyle)
+})
+// 父类名
+const rootClass = computed(() => {
+    return [
+        'hy-tabbar-group',
+        `hy-tabbar-group--${props.shape}`,
+        props.customClass,
+        props.fixed && 'is-fixed',
+        props.safeAreaInsetBottom && 'is-safe',
+        props.border && 'is-border'
+    ]
+})
+
+onUnmounted(() => {
+    index.value = 0
+})
+
+/**
+ * 子项状态变更
+ * @param index 子项
+ */
+function setChange(index: string | number) {
+    emit('update:modelValue', index)
+    emit('change', {
+        value: index
+    })
+}
+</script>
+<style lang="scss" scoped>
+@import './index.scss';
+</style>

package/components/hy-tabbar-group/index.scss

@@ -0,0 +1,57 @@
+@use "../../libs/css/theme" as *;
+@use "../../libs/css/mixin.scss" as *;
+
+@include b(tabbar-group) {
+  display: flex;
+  align-items: center;
+  flex-wrap: nowrap;
+  position: relative;
+  background: $hy-background--container;
+  height: 100rpx;
+
+  @include e(placeholder) {
+    box-sizing: content-box;
+    padding-bottom: constant(safe-area-inset-bottom);
+    padding-bottom: env(safe-area-inset-bottom);
+    height: 100rpx;
+  }
+
+  @include m(circle) {
+    margin-left: $hy-border-margin-padding-lg;
+    margin-right: $hy-border-margin-padding-lg;
+    border-radius: $hy-border-radius-semicircle;
+    box-shadow: $hy-box-shadow;
+
+    @include is(fixed) {
+      @include is(safe) {
+        bottom: constant(safe-area-inset-bottom);
+        bottom: env(safe-area-inset-bottom);
+      }
+    }
+
+  }
+
+  @include m(square) {
+
+    @include is(fixed) {
+      @include is(safe) {
+        box-sizing: content-box;
+        padding-bottom: constant(safe-area-inset-bottom);
+        padding-bottom: env(safe-area-inset-bottom);
+      }
+    }
+
+
+    @include is(border) {
+      border-top: $hy-border-line;
+    }
+  }
+
+  @include is(fixed) {
+    position: fixed;
+    left: 0;
+    bottom: 0;
+    right: 0;
+    z-index: 500;
+  }
+}

package/components/hy-tabbar-group/props.ts

@@ -0,0 +1,78 @@
+import type { CSSProperties, PropType } from 'vue'
+import type HyBadgeProps from '../hy-badge/typing'
+
+const tabbarGroupProps = {
+    /** 选中项的索引值 */
+    modelValue: {
+        type: Number,
+        default: 0
+    },
+    /** 是否固定在底部 */
+    fixed: {
+        type: Boolean,
+        default: false
+    },
+    /** 是否显示顶部边框 */
+    border: {
+        type: Boolean,
+        default: true
+    },
+    /** 是否显示占位元素 */
+    placeholder: {
+        type: Boolean,
+        default: true
+    },
+    /**
+     * 导航栏的形状
+     * @values square, circle
+     * */
+    shape: {
+        type: String,
+        default: 'square'
+    },
+    /** 背景颜色 */
+    bgColor: {
+        type: String,
+        default: ''
+    },
+    /** 激活颜色 */
+    activeColor: {
+        type: String,
+        default: ''
+    },
+    /** 非激活颜色 */
+    inactiveColor: {
+        type: String,
+        default: ''
+    },
+    /** 底部安全区域适配 - 主要用于iPhone X及以上机型 */
+    safeAreaInsetBottom: {
+        type: Boolean,
+        default: true
+    },
+    /** 图标大小 */
+    iconSize: {
+        type: [String, Number],
+        default: ''
+    },
+    /** 文字大小 */
+    fontSize: {
+        type: [String, Number],
+        default: ''
+    },
+    /** 徽标部分属性 */
+    badgeProps: {
+        type: Object as PropType<HyBadgeProps>
+    },
+    /** z-index层级 */
+    zIndex: {
+        type: Number,
+        default: 10086
+    },
+    /** 定义需要用到的外部样式 */
+    customStyle: Object as PropType<CSSProperties>,
+    /** 自定义外部类名 */
+    customClass: String
+} as const
+
+export default tabbarGroupProps

package/components/hy-tabbar-group/typing.ts

@@ -0,0 +1,16 @@
+import type { ExtractPropTypes, ToRefs } from 'vue'
+import type tabbarGroupProps from './props'
+
+export type TabBarGroupProps = ToRefs<ExtractPropTypes<typeof tabbarGroupProps>>
+
+export type ParamType = {
+    value: string | number
+}
+
+// ITabBarGroupEmits 接口定义组件的自定义事件
+export interface ITabBarGroupEmits {
+    /** 更新选中索引 */
+    (e: 'update:modelValue', value: string | number): void
+    /** 变化事件 */
+    (e: 'change', param: ParamType): void
+}

package/components/hy-tabbar-item/hy-tabbar-item.vue

@@ -0,0 +1,103 @@
+<template>
+    <view class="hy-tabbar-item" @click="handleClick">
+        <view class="hy-tabbar-item__body">
+            <hy-badge
+                :value="value"
+                :show="!!value"
+                absolute
+                :offset="tabbarConfig?.badgeProps.value?.offset || [-10, 18]"
+                :isDot="tabbarConfig?.badgeProps.value?.isDot"
+                :max="tabbarConfig?.badgeProps.value?.max"
+                :type="tabbarConfig?.badgeProps.value?.type"
+                :bgColor="tabbarConfig?.badgeProps.value?.bgColor"
+                :color="tabbarConfig?.badgeProps.value?.color"
+                :shape="tabbarConfig?.badgeProps.value?.shape"
+                :numberType="tabbarConfig?.badgeProps.value?.numberType"
+                :inverted="tabbarConfig?.badgeProps.value?.inverted"
+            >
+            </hy-badge>
+            <slot v-if="$slots.icon" name="icon" :active="active"></slot>
+            <hy-icon
+                v-else
+                :name="icon"
+                :color="iconColor"
+                :size="tabbarConfig?.iconSize?.value"
+                :custom-class="`hy-tabbar-item__body-icon ${active ? 'is-active' : 'is-inactive'}`"
+            ></hy-icon>
+            <text
+                v-if="title"
+                :style="{ color: iconColor, fontSize: tabbarConfig?.fontSize?.value }"
+                :class="`hy-tabbar-item__body-title ${active ? 'is-active' : 'is-inactive'}`"
+            >
+                {{ title }}
+            </text>
+        </view>
+    </view>
+</template>
+
+<script lang="ts">
+export default {
+    name: 'hy-tabbar-item',
+    options: {
+        addGlobalClass: true,
+        virtualHost: true,
+        styleIsolation: 'shared'
+    }
+}
+</script>
+
+<script lang="ts" setup>
+import { computed, inject, ref } from 'vue'
+import tabbarItemProps from './props'
+import type { ITabbarConfig } from './typing'
+
+// 组件
+import HyBadge from '../hy-badge/hy-badge.vue'
+import HyIcon from '../hy-icon/hy-icon.vue'
+
+/**
+ * 底部导航栏，用于在不同页面之间进行切换。
+ * @displayName hy-tabbar-item
+ */
+defineOptions({})
+
+const props = defineProps(tabbarItemProps)
+
+// 尝试从父组件注入配置
+const tabbarConfig = inject<ITabbarConfig>('hy-tabbar')
+// 获取唯一 ID
+const uid = ref<number>(tabbarConfig?.getIndex()!)
+
+const iconColor = computed(() => {
+    if (tabbarConfig) {
+        if (active.value && tabbarConfig.activeColor?.value) {
+            return tabbarConfig.activeColor.value
+        }
+        if (!active.value && tabbarConfig.inactiveColor?.value) {
+            return tabbarConfig.inactiveColor.value
+        }
+    }
+})
+
+const active = computed(() => {
+    const name = props.name || uid.value
+    if (tabbarConfig) {
+        return tabbarConfig.modelValue.value === name
+    } else {
+        return false
+    }
+})
+
+/**
+ * 点击tabbar选项
+ */
+function handleClick() {
+    const index: string | number = props.name || uid.value
+    if (tabbarConfig && index !== tabbarConfig?.modelValue?.value) {
+        tabbarConfig.setChange(index)
+    }
+}
+</script>
+<style lang="scss" scoped>
+@import './index.scss';
+</style>