外观
Navbar 自定义导航栏
约 1290 字大约 4 分钟
2025-10-31
此组件一般用于在特殊情况下,需要自定义导航栏的时候用到,一般建议使用uni-app带的导航栏。
基本使用
默认情况下,该组件只有向左的箭头,点击可以返回上一页,如果您想将自定义导航栏用在tabbar(不存在要返回的逻辑)页面, 这样会隐藏左边的返回图标区域。
- 如果想在返回箭头的右边自定义类似"返回"字样,可以将
left-text设置为"返回" - 通过
title参数传入需要显示的标题,通过title-width设置标题区域的宽度,文字超出会通过省略号隐藏 - 通过
fixed配置是否将导航栏固定在顶部
说明
- 在小程序中,导航栏会自动适配导航栏右侧的胶囊位置,避开该区域
<template>
<un-navbar title="个人中心" @rightClick="rightClick" @leftClick="leftClick" />
</template>
<script lang="ts" setup>
const rightClick = () => {
console.log('rightClick');
};
const leftClick = () => {
console.log('leftClick');
};
</script>注意事项
既然是要自定义导航栏,那么首先就要取消系统自带的导航栏,需要在uni-app目的根目录的"pages.json"中设置,同时在此设置状态栏字体的颜色(H5无效), 自定义导航栏后,如果想通过"uni.setNavigationBarColor"动态设置导航栏颜色相关参数,是可能会出问题的,请勿使用此方式。
"pages": [
// navbar-自定义导航栏
{
"path": "/pages/navbar/index",
"style": {
"navigationStyle": "custom" ,// 隐藏系统导航栏
"navigationBarTextStyle": "white" // 状态栏字体为白色,只能为 white-白色,black-黑色 二选一
}
}
]自定义文本
可以通过 leftText 和 rightIcon 属性自定义导航栏左右两侧的文本和图标。
<un-navbar title="个人中心" left-text="返回" rightIcon="map"></un-navbar>自定义导航栏内容
通过自定义 slot 传入的内容,可以完全自定义导航栏的左右两侧内容。
<template>
<view>
<un-navbar leftText="返回" title="个人中心">
<template #left>
<un-icon name="arrow-left" size="19"></un-icon>
<un-line direction="column" :hairline="false" length="16" margin="0 8px"></un-line>
<un-icon name="home" size="20"></un-icon>
</template>
</un-navbar>
</view>
</template>
<style lang="scss">
.u-nav-slot {
display: flex;
flex-direction: row;
align-items: center;
justify-content: space-between;
border-width: 0.5px;
border-radius: 100px;
border-color: #e4e7ed;
padding: 3px 7px;
opacity: 0.8;
}
</style>搜索框导航栏
可以在左侧插槽中放置搜索组件,实现搜索框导航栏效果。
<un-navbar rightIcon="map">
<template #left>
<un-search placeholder="搜索" :height="30"></un-search>
</template>
</un-navbar>自定义导航栏背景颜色
可以通过 bgColor 参数自定义导航栏的背景颜色,同时可以通过 leftIconColor 和 titleStyle 自定义图标和标题的颜色。
<un-navbar title="个人中心" bgColor="#007aff" leftIconColor="#fff" titleStyle="color:#ffffff;"></un-navbar>固定在顶部
通过设置 fixed 和 placeholder 属性,可以将导航栏固定在页面顶部,并自动处理占位空间。
<template>
<un-navbar fixed placeholder border title="导航栏" @rightClick="rightClick" @leftClick="leftClick" />
</template>
<script lang="ts" setup>
const rightClick = () => {
console.log('rightClick');
};
const leftClick = () => {
console.log('leftClick');
};
</script>API
Props
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| safeAreaInsetTop | 是否开启顶部安全区适配 | Boolean | true |
| placeholder | 固定在顶部时,是否生成一个等高元素,以防止塌陷 | Boolean | false |
| fixed | 导航栏是否固定在顶部 | Boolean | true |
| border | 导航栏底部是否显示下边框 | Boolean | false |
| leftIcon | 左边返回图标的名称,只能为uView自带的图标 | String | arrow-left |
| leftText | 左边的提示文字 | String | - |
| rightText | 右边的提示文字 | String | - |
| rightIcon | 右边返回图标的名称,只能为uView自带的图标 | String | - |
| rightIconSize | 右侧返回图标的大小 | String | Number | 20px |
| rightIconColor | 右侧返回图标的颜色 | String | #303133 |
| title | 导航栏标题,如设置为空字符,将会隐藏标题占位区域 | String | - |
| bgColor | 导航栏背景设置 | String | #ffffff |
| titleWidth | 导航栏标题的最大宽度,内容超出会以省略号隐藏,单位rpx | String | Number | 400rpx |
| height | 导航栏高度(不包括状态栏高度在内,内部自动加上),单位px | String | Number | 44px |
| leftIconSize | 左侧返回图标的大小 | String | Number | 20px |
| leftIconColor | 左侧返回图标的颜色 | String | #303133 |
| autoBack | 点击左侧区域(返回图标),是否自动返回上一页 | Boolean | false |
| titleStyle | 标题的样式,对象或字符串形式 | String | Object | - |
Event
| 名称 | 说明 | 类型 |
|---|---|---|
| leftClick | 点击左侧区域 | Handler |
| rightClick | 点击右侧区域 | Handler |
Slot
| 名称 | 说明 |
|---|---|
| left | 自定义左侧部分内容 |
| right | 自定义右侧部分内容 |
| center | 自定义中部内容 |
Scss 变量
| 变量名 | 默认值 | 说明 |
|---|---|---|
| $un-navbar-fixed-z-index | 10 | 导航栏固定定位层级 |
| $un-navbar-border | 0.5px solid $border-color | 导航栏边框样式 |
| $un-navbar-left-right-padding | 0 13px | 左右区域内边距 |
| $un-navbar-left-hover-opacity | 0.7 | 左侧区域点击透明度 |
| $un-navbar-left-right-text-font-size | 15px | 左右文字大小 |
| $un-navbar-left-right-text-margin-left | 3px | 左右文字左边距 |
| $un-navbar-title-font-size | 16px | 标题文字大小 |
| $un-navbar-title-color | $text-color | 标题文字颜色 |
提示
组件内部默认使用 scss 变量,如需修改,请查看 scss 变量使用 文档
