Skip to content

导航组件

导航组件用于页面导航和内容切换,提供导航栏、标签栏、标签页、索引栏、分页器等核心功能。

组件列表

组件说明
Navbar导航栏,页面顶部导航
Tabbar标签栏,底部标签导航
Tabs标签页,内容切换
Sidebar侧边栏,侧边导航
IndexBar索引栏,字母索引
Pagination分页器,数据分页
Segmented分段器,分段选择
Backtop返回顶部

导航栏组件用于页面顶部导航,支持标题、左右操作按钮、胶囊组件、自动返回等功能。

基本用法

vue
<template>
  <!-- 基本标题 -->
  <wd-navbar title="页面标题" />

  <!-- 返回按钮 -->
  <wd-navbar title="详情页" show-back />

  <!-- 左侧自定义 -->
  <wd-navbar title="页面标题" left-icon="close" left-text="关闭" @click-left="handleClose" />

  <!-- 右侧操作 -->
  <wd-navbar title="页面标题" right-icon="search" @click-right="handleSearch" />
</template>

<script lang="ts" setup>
const handleClose = () => uni.navigateBack()
const handleSearch = () => console.log('搜索')
</script>

自定义插槽

vue
<template>
  <wd-navbar>
    <template #left>
      <wd-icon name="scan" size="40rpx" />
    </template>
    <template #title>
      <view class="flex items-center">
        <image src="/static/logo.png" class="w-48rpx h-48rpx mr-12rpx" />
        <text>应用名称</text>
      </view>
    </template>
    <template #right>
      <wd-icon name="more" size="40rpx" />
    </template>
  </wd-navbar>
</template>

胶囊模式

vue
<template>
  <wd-navbar title="胶囊导航" capsule show-back show-home @back="handleBack" @back-home="handleBackHome" />
</template>

<script lang="ts" setup>
const handleBack = () => uni.navigateBack()
const handleBackHome = () => uni.switchTab({ url: '/pages/index/index' })
</script>

自定义样式

vue
<template>
  <wd-navbar title="自定义样式" bg-color="#1989fa" title-color="#fff" left-icon-color="#fff" :bordered="false" />
</template>
参数说明类型默认值
title标题文字string-
title-size标题字体大小string | number-
title-bold标题是否加粗booleanfalse
title-color标题颜色string-
left-text左侧文字string-
left-icon左侧图标string-
left-icon-size左侧图标大小string | number32
left-icon-color左侧图标颜色string-
left-disabled是否禁用左侧按钮booleanfalse
right-text右侧文字string-
right-icon右侧图标string-
right-icon-size右侧图标大小string | number32
right-icon-color右侧图标颜色string-
right-disabled是否禁用右侧按钮booleanfalse
bg-color背景颜色string-
height导航栏高度string | number-
bordered是否显示下边框booleanfalse
fixed是否固定在顶部booleantrue
placeholder是否生成占位元素booleantrue
z-index层级number99
safe-area-inset-top是否适配顶部安全区booleantrue
capsule是否显示胶囊组件booleanfalse
show-back是否显示返回按钮booleanfalse
show-home是否显示首页按钮booleanfalse
auto-back是否自动处理返回操作booleantrue
auto-hide-in-wechat-h5在微信公众号H5中自动隐藏booleantrue
status-bar-text-style状态栏文字颜色'dark' | 'light''dark'
事件名说明回调参数
back点击返回按钮时触发-
back-home点击首页按钮时触发-
click-left点击左侧区域时触发-
click-right点击右侧区域时触发-
height-ready导航栏高度计算完成时触发height: number
名称说明
left自定义左侧内容
title自定义标题内容
right自定义右侧内容
capsule自定义胶囊组件

Tabbar 标签栏

底部标签栏组件,用于在不同页面之间进行切换。

基本用法

vue
<template>
  <!-- 子组件模式 -->
  <wd-tabbar v-model="active">
    <wd-tabbar-item icon="home" title="首页" />
    <wd-tabbar-item icon="category" title="分类" />
    <wd-tabbar-item icon="cart" title="购物车" />
    <wd-tabbar-item icon="user" title="我的" />
  </wd-tabbar>
</template>

<script lang="ts" setup>
const active = ref(0)
</script>

数据驱动模式

vue
<template>
  <wd-tabbar v-model="active" :items="tabbarItems" @change="handleChange" />
</template>

<script lang="ts" setup>
const active = ref(0)
const tabbarItems = ref([
  { icon: 'home', title: '首页', name: 'home' },
  { icon: 'category', title: '分类', name: 'category' },
  { icon: 'cart', title: '购物车', name: 'cart', value: 3 },
  { icon: 'user', title: '我的', name: 'mine' },
])
const handleChange = (value: string | number) => console.log('切换到:', value)
</script>

徽标与样式

vue
<template>
  <!-- 徽标显示 -->
  <wd-tabbar v-model="active">
    <wd-tabbar-item icon="home" title="首页" />
    <wd-tabbar-item icon="message" title="消息" :value="5" />
    <wd-tabbar-item icon="cart" title="购物车" :value="99" :max="99" />
    <wd-tabbar-item icon="user" title="我的" is-dot />
  </wd-tabbar>

  <!-- 自定义颜色 -->
  <wd-tabbar v-model="active" active-color="#07c160" inactive-color="#999">
    <wd-tabbar-item icon="home" title="首页" />
    <wd-tabbar-item icon="user" title="我的" />
  </wd-tabbar>

  <!-- 圆形样式 -->
  <wd-tabbar v-model="active" shape="round">
    <wd-tabbar-item icon="home" title="首页" />
    <wd-tabbar-item icon="user" title="我的" />
  </wd-tabbar>
</template>

Tabbar Props

参数说明类型默认值
v-model当前选中标签的索引或名称number | string0
items标签栏配置列表WdTabbarItemProps[][]
fixed是否固定在底部booleantrue
bordered是否显示顶部边框booleantrue
safe-area-inset-bottom是否适配底部安全区booleantrue
shape标签栏形状'default' | 'round''default'
active-color激活标签的颜色string-
inactive-color未激活标签的颜色string-
placeholder是否生成占位元素booleantrue
z-index层级number99

Tabbar Events

事件名说明回调参数
change切换标签时触发value: number | string

TabbarItem Props

参数说明类型默认值
name标签名称string | number-
icon图标名称string-
active-icon激活时的图标名称string-
title标题文字string-
value徽标显示值string | number-
is-dot是否显示小红点booleanfalse
max徽标最大值number99

Tabs 标签页

标签页组件用于在不同的内容区域之间进行切换。

基本用法

vue
<template>
  <wd-tabs v-model="activeTab">
    <wd-tab title="标签1">内容1</wd-tab>
    <wd-tab title="标签2">内容2</wd-tab>
    <wd-tab title="标签3">内容3</wd-tab>
  </wd-tabs>
</template>

<script lang="ts" setup>
const activeTab = ref(0)
</script>

数据驱动模式

vue
<template>
  <wd-tabs v-model="activeTab" :items="tabItems">
    <template #default="{ item }">
      <view class="tab-content">{{ item.title }} 的内容</view>
    </template>
  </wd-tabs>
</template>

<script lang="ts" setup>
const tabItems = [
  { title: '推荐', name: 'recommend' },
  { title: '热门', name: 'hot' },
  { title: '最新', name: 'latest' },
]
</script>

滑动与动画

vue
<template>
  <!-- 滑动切换 -->
  <wd-tabs v-model="activeTab" swipeable>
    <wd-tab title="标签1">内容1</wd-tab>
    <wd-tab title="标签2">内容2</wd-tab>
  </wd-tabs>

  <!-- 粘性布局 -->
  <wd-tabs v-model="activeTab" sticky :offset-top="0">
    <wd-tab title="标签1">
      <view style="height: 800rpx;">长内容1</view>
    </wd-tab>
  </wd-tabs>

  <!-- 切换动画 -->
  <wd-tabs v-model="activeTab" animated :duration="300">
    <wd-tab title="标签1">内容1</wd-tab>
    <wd-tab title="标签2">内容2</wd-tab>
  </wd-tabs>
</template>

自定义样式

vue
<template>
  <!-- 自定义颜色 -->
  <wd-tabs v-model="activeTab" color="#1989fa" inactive-color="#999">
    <wd-tab title="标签1">内容1</wd-tab>
  </wd-tabs>

  <!-- 底部条样式 -->
  <wd-tabs v-model="activeTab" line-width="40" line-height="4">
    <wd-tab title="标签1">内容1</wd-tab>
  </wd-tabs>
</template>

禁用与导航地图

vue
<template>
  <!-- 禁用标签 -->
  <wd-tabs v-model="activeTab" @disabled="handleDisabled">
    <wd-tab title="标签1">内容1</wd-tab>
    <wd-tab title="标签2" disabled>内容2</wd-tab>
  </wd-tabs>

  <!-- 导航地图(标签数量超过 map-num 时显示) -->
  <wd-tabs v-model="activeTab" :map-num="6" map-title="全部分类">
    <wd-tab v-for="i in 12" :key="i" :title="`标签${i}`">内容{{ i }}</wd-tab>
  </wd-tabs>
</template>

Tabs Props

参数说明类型默认值
v-model当前激活标签的索引或名称number | string0
items标签页数据数组TabItem[][]
slidable-num标签数超过阈值可滑动number6
slidable滚动导航模式'auto' | 'always''auto'
map-num标签数超过阈值显示导航地图number10
map-title导航地图的标题string-
sticky是否开启粘性布局booleanfalse
offset-top粘性布局吸顶位置number0
swipeable是否开启手势滑动booleanfalse
auto-line-width是否自动调整底部条宽度booleanfalse
line-width底部条宽度string | number-
line-height底部条高度string | number-
color激活标签颜色string-
inactive-color非激活标签颜色string-
animated是否开启切换动画booleanfalse
duration切换动画时长(ms)number300

Tabs Events

事件名说明回调参数
change切换标签时触发{ index: number, name: string | number }
click点击标签时触发{ index: number, name: string | number }
disabled点击禁用标签时触发{ index: number, name: string | number }

Tab Props

参数说明类型默认值
title标签标题string-
name标签名称string | number-
disabled是否禁用booleanfalse
lazy是否开启懒加载booleantrue
badge-props徽标属性透传object-

Tabs Methods

方法名说明参数
setActive设置激活的标签页(value: string | number, init?: boolean, setScroll?: boolean) => void
scrollIntoView滚动到当前激活标签() => void
updateLineStyle更新底部指示线样式(animation?: boolean) => Promise<void>

侧边栏导航组件,用于在不同内容区域之间进行切换。

基本用法

vue
<template>
  <view class="flex h-screen">
    <wd-sidebar v-model="activeKey">
      <wd-sidebar-item title="分类1" />
      <wd-sidebar-item title="分类2" />
      <wd-sidebar-item title="分类3" />
    </wd-sidebar>
    <view class="flex-1 p-32rpx">当前选中: {{ activeKey }}</view>
  </view>
</template>

<script lang="ts" setup>
const activeKey = ref(0)
</script>

徽标与禁用

vue
<template>
  <wd-sidebar v-model="activeKey">
    <wd-sidebar-item title="分类1" />
    <wd-sidebar-item title="分类2" is-dot />
    <wd-sidebar-item title="分类3" :value="5" />
    <wd-sidebar-item title="分类4" disabled />
  </wd-sidebar>
</template>
参数说明类型默认值
v-model当前选中项的索引number0
事件名说明回调参数
change切换选项时触发value: number

SidebarItem Props

参数说明类型默认值
title选项标题string-
disabled是否禁用booleanfalse
is-dot是否显示小红点booleanfalse
value徽标显示值string | number-
max徽标最大值number-

IndexBar 索引栏

索引栏组件,用于联系人列表、城市选择等场景的快速定位导航。

基本用法

vue
<template>
  <wd-index-bar>
    <wd-index-anchor index="A" />
    <wd-cell title="阿里巴巴" />
    <wd-cell title="爱奇艺" />

    <wd-index-anchor index="B" />
    <wd-cell title="百度" />
    <wd-cell title="哔哩哔哩" />

    <wd-index-anchor index="C" />
    <wd-cell title="腾讯" />
  </wd-index-bar>
</template>

自定义索引

vue
<template>
  <wd-index-bar :index-list="['热门', 'A', 'B', 'C', 'D']">
    <wd-index-anchor index="热门" />
    <wd-cell title="北京" />
    <wd-cell title="上海" />

    <wd-index-anchor index="A" />
    <wd-cell title="安庆" />
  </wd-index-bar>
</template>

IndexBar Props

参数说明类型默认值
index-list索引字符列表string[]A-Z
sticky是否开启锚点吸顶booleantrue
sticky-offset-top吸顶偏移量number0
highlight-color高亮颜色string-

IndexBar Events

事件名说明回调参数
select点击索引时触发index: string
change当前高亮索引变化时触发index: string

IndexAnchor Props

参数说明类型默认值
index索引字符string | number-

Pagination 分页器

分页器组件,用于数据分页展示。

基本用法

vue
<template>
  <!-- 默认多页模式 -->
  <wd-pagination v-model="current" :total="100" :page-size="10" @change="handleChange" />

  <!-- 简单模式 -->
  <wd-pagination v-model="current" :total="100" mode="simple" />

  <!-- 显示总数 -->
  <wd-pagination v-model="current" :total="100" show-total />

  <!-- 自定义按钮 -->
  <wd-pagination v-model="current" :total="100">
    <template #prev><text>上一页</text></template>
    <template #next><text>下一页</text></template>
  </wd-pagination>
</template>

<script lang="ts" setup>
const current = ref(1)
const handleChange = (page: number) => console.log('当前页:', page)
</script>

Pagination Props

参数说明类型默认值
v-model当前页码number1
total数据总数number0
page-size每页数量number10
mode显示模式'multi' | 'simple''multi'
show-total是否显示总数booleanfalse
prev-text上一页按钮文字string-
next-text下一页按钮文字string-
hide-on-single-page只有一页时是否隐藏booleanfalse

Pagination Events

事件名说明回调参数
change页码变化时触发page: number

Pagination Slots

名称说明
prev自定义上一页按钮
next自定义下一页按钮

Segmented 分段器

分段器组件,用于在几个选项中进行切换选择。

基本用法

vue
<template>
  <wd-segmented v-model="activeValue" :options="options" @change="handleChange" />
</template>

<script lang="ts" setup>
const activeValue = ref('day')
const options = [
  { label: '日', value: 'day' },
  { label: '周', value: 'week' },
  { label: '月', value: 'month' },
  { label: '年', value: 'year' },
]
const handleChange = (value: string) => console.log('选中:', value)
</script>

禁用与样式

vue
<template>
  <!-- 禁用选项 -->
  <wd-segmented v-model="activeValue" :options="[
    { label: '选项1', value: '1' },
    { label: '选项2', value: '2', disabled: true },
    { label: '选项3', value: '3' },
  ]" />

  <!-- 自定义颜色 -->
  <wd-segmented v-model="activeValue" :options="options" active-color="#1989fa" />
</template>

Segmented Props

参数说明类型默认值
v-model当前选中值string | number-
options选项数组SegmentedOption[][]
disabled是否整体禁用booleanfalse
active-color激活颜色string-
size尺寸'small' | 'medium' | 'large''medium'

Segmented Events

事件名说明回调参数
change选项变化时触发value: string | number

SegmentedOption 类型

typescript
interface SegmentedOption {
  label: string
  value: string | number
  disabled?: boolean
}

Backtop 返回顶部

返回顶部按钮,当页面滚动超过一定距离时显示。

基本用法

vue
<template>
  <scroll-view scroll-y @scroll="onScroll" style="height: 100vh;">
    <view v-for="i in 100" :key="i" class="p-20rpx">内容项 {{ i }}</view>
    <wd-backtop :scroll-top="scrollTop" @click="handleBacktop" />
  </scroll-view>
</template>

<script lang="ts" setup>
const scrollTop = ref(0)

const onScroll = (e: any) => {
  scrollTop.value = e.detail.scrollTop
}

const handleBacktop = () => {
  uni.pageScrollTo({ scrollTop: 0, duration: 300 })
}
</script>

自定义样式

vue
<template>
  <!-- 自定义位置 -->
  <wd-backtop :scroll-top="scrollTop" :right="60" :bottom="200" @click="handleBacktop" />

  <!-- 显示时机 -->
  <wd-backtop :scroll-top="scrollTop" :top="300" @click="handleBacktop" />

  <!-- 方形样式 -->
  <wd-backtop :scroll-top="scrollTop" shape="square" @click="handleBacktop" />

  <!-- 自定义内容 -->
  <wd-backtop :scroll-top="scrollTop" @click="handleBacktop">
    <view class="flex flex-col items-center text-20rpx">
      <wd-icon name="arrow-up" />
      <text>顶部</text>
    </view>
  </wd-backtop>
</template>

Backtop Props

参数说明类型默认值
scroll-top页面滚动距离(必填)number-
top显示按钮的滚动阈值(rpx)number600
duration滚动动画时长(ms)number100
z-index层级number99
shape按钮形状'circle' | 'square''circle'
right距离屏幕右边距离(rpx)number40
bottom距离屏幕底部距离(rpx)number200

Backtop Events

事件名说明回调参数
click点击按钮时触发-

Backtop Slots

名称说明
default自定义按钮内容

最佳实践

1. Navbar 配置

vue
<template>
  <wd-navbar
    :title="pageTitle"
    :show-back="canGoBack"
    :show-home="!canGoBack"
    @back="handleBack"
    @back-home="handleBackHome"
  />
</template>

<script lang="ts" setup>
const canGoBack = computed(() => getCurrentPages().length > 1)
const handleBack = () => uni.navigateBack()
const handleBackHome = () => uni.switchTab({ url: '/pages/index/index' })
</script>

2. Tabbar 页面切换

vue
<template>
  <wd-tabbar v-model="activePage" :items="tabbarItems" @change="handleTabChange" />
  <view v-show="activePage === 'home'">首页内容</view>
  <view v-show="activePage === 'mine'">我的内容</view>
</template>

<script lang="ts" setup>
const activePage = ref('home')
const tabbarItems = [
  { icon: 'home', title: '首页', name: 'home' },
  { icon: 'user', title: '我的', name: 'mine' },
]
</script>

3. Tabs 懒加载

vue
<template>
  <wd-tabs v-model="activeTab" :items="tabItems">
    <template #default="{ item }">
      <template v-if="item.loaded">
        <AsyncContent :type="item.name" />
      </template>
    </template>
  </wd-tabs>
</template>

常见问题

1. Navbar 高度计算不正确

使用 @height-ready 事件获取准确高度:

vue
<template>
  <wd-navbar title="标题" @height-ready="onHeightReady" />
</template>

<script lang="ts" setup>
const onHeightReady = (height: number) => {
  console.log('导航栏高度:', height)
}
</script>

2. Tabbar 切换页面闪烁

使用 v-show 替代 v-if 避免频繁重建:

vue
<template>
  <view v-show="active === 0">首页</view>
  <view v-show="active === 1">分类</view>
</template>

3. Tabs 底部指示线不显示

手动更新指示线样式:

vue
<script lang="ts" setup>
const tabsRef = ref()

onMounted(() => {
  nextTick(() => {
    tabsRef.value?.updateLineStyle()
  })
})
</script>

4. Backtop 按钮不显示

确保正确传递 scroll-top 值:

vue
<template>
  <scroll-view scroll-y @scroll="onScroll" style="height: 100vh;">
    <wd-backtop :scroll-top="scrollTop" @click="handleBacktop" />
  </scroll-view>
</template>

<script lang="ts" setup>
const scrollTop = ref(0)
const onScroll = (e: any) => {
  scrollTop.value = e.detail.scrollTop
}
</script>

主题定制

scss
// Navbar 导航栏
$-navbar-height: 88rpx;
$-navbar-background: #fff;
$-navbar-color: #333;
$-navbar-title-font-size: 32rpx;
$-navbar-capsule-height: 64rpx;

// Tabbar 标签栏
$-tabbar-height: 100rpx;
$-tabbar-active-color: #1989fa;
$-tabbar-inactive-color: #7d7e80;
$-tabbar-item-icon-size: 48rpx;
$-tabbar-item-title-font-size: 24rpx;

// Tabs 标签页
$-tabs-nav-height: 88rpx;
$-tabs-nav-fs: 30rpx;
$-tabs-nav-color: #333;
$-tabs-nav-active-color: #1989fa;
$-tabs-nav-line-height: 6rpx;
$-tabs-nav-line-bg-color: #1989fa;

// Backtop 返回顶部
$-backtop-bg: rgba(255, 255, 255, 0.9);
$-backtop-icon-size: 40rpx;