Navbar 自定义导航栏 | uview-plus - 全面兼容nvue/鸿蒙/uni-app-x的uni-app生态框架

此组件一般用于在特殊情况下，需要自定义导航栏的时候用到，一般建议使用uni-app带的导航栏。

提示

右侧的演示中，导航栏上方有圆角，也有顶部的手机模型状态栏内容，以及返回图标和文字不对齐的情况。这是因为网页演示导致，实际中无此情况，请通过右上角的“演示”扫码查看实际效果。

# 平台差异说明

App（vue）	App（nvue）	H5	小程序
√	√	√	√

mode="ios" 的平台支持情况：

平台	大标题压缩	磨砂
H5 现代浏览器	√	√
App（vue）iOS	√	√
App（vue）Android	√	视 WebView 版本，否则 82% 不透明底色
鸿蒙（app-harmony）	√	√
App（nvue）	整体降级为 `default`	—
微信小程序 iOS	√	√
其余小程序	√	视端能力，否则 82% 不透明底色

# 基本使用

默认情况下，该组件只有向左的箭头，点击可以返回上一页，如果您想将自定义导航栏用在tabbar(不存在要返回的逻辑)页面，这样会隐藏左边的返回图标区域。

如果想在返回箭头的右边自定义类似"返回"字样，可以将left-text设置为"返回"
通过title参数传入需要显示的标题，通过title-width(rpx)设置标题区域的宽度，文字超出会通过省略号隐藏
通过fixed配置是否将导航栏固定在顶部

说明

在小程序中，导航栏会自动适配导航栏右侧的胶囊位置，避开该区域
组件底部默认有一条下边框，如您不需要，可以设置border为false即可

<template>
	<view>
		<!-- 2.0.19支持autoBack，默认为false -->
        <up-navbar
            title="个人中心"
            @rightClick="rightClick"
            :autoBack="true"
        >
        </up-navbar>
	</view>
</template>

<script setup>  
  
// 定义方法  
const rightClick = () => {  
    console.log('rightClick');  
};  
  
const leftClick = () => {  
    console.log('leftClick');  
};  

</script>

<script>
    methods:{
        rightClick() {
            console.log('rightClick');
        },
        leftClick() {
            console.log('leftClick');
        }
    }
</script>

# 注意事项

既然是要自定义导航栏，那么首先就要取消系统自带的导航栏，需要在uni-app目的根目录的"pages.json"中设置，同时在此设置状态栏字体的颜色(H5无效)，自定义导航栏后，如果想通过"uni.setNavigationBarColor"动态设置导航栏颜色相关参数，是可能会出问题的，请勿使用此方式。

// pages.json

"pages": [
	// navbar-自定义导航栏
	{
		"path": "/pages/navbar/index",
		"style": {
			"navigationStyle": "custom" ,// 隐藏系统导航栏
			"navigationBarTextStyle": "white" // 状态栏字体为白色，只能为 white-白色，black-黑色 二选一
		}
	}
]

# 导航栏高度

可以通过height(单位px，默认44，和uni-app统导航栏高度一致)配置导航栏的高度，此高度为导航栏内容的高度，不含状态栏的高度，组件内部会自动加上状态栏的高度，并填充状态栏的占位区域。

注意上方说的uni-app方的高度，这里指的是H5，和APP。至于各家小程序，由于受导航栏右侧胶囊的影响，目前组件内部给安卓设定的导航栏高度为48px，iOS设定的导航栏高度为44，这是结合了大量的实践的出来的结果，具备完好的兼容性。

# 自定义导航栏内容

通过自定义slot传入的内容

<template>
	<view>
        <up-navbar
            leftText="返回"
            title="个人中心"
            :safeAreaInsetTop="false"
        >
            <template #left>
                <view
                    class="u-nav-slot"
                >
                    <up-icon
                        name="arrow-left"
                        size="19"
                    ></up-icon>
                    <up-line
                        direction="column"
                        :hairline="false"
                        length="16"
                        margin="0 8px"
                    ></up-line>
                    <up-icon
                        name="home"
                        size="20"
                    ></up-icon>
                </view>
          </template>
	</up-navbar>
  </view>
</template>

# 自定义导航栏背景颜色

uview-plus提供了一个bgColor参数，可以自定义导航栏的背景颜色：

<template>
	<view>
		<up-navbar title="" :bgColor="bgColor">
			
		</up-navbar>
		<view class="content">
			<!-- 正文内容 -->
		</view>
	</view>
</template>

<script setup>  
import { ref } from 'vue';  
  
// 创建响应式数据  
const bgColor = ref('#001f3f');  
</script>

<script>
	export default {
		data() {
			return {
				bgColor: '#001f3f',
			}
		}
	}
</script>

# iOS 大标题模式 3.8.112

打开

通过 mode="ios" 启用现代 iOS 系统应用的导航栏体验：进入页面时导航栏背景透明、标题以大字号靠左显示；向下滚动时大标题被压缩进导航栏，标题过渡为常规居中形态，同时出现毛玻璃磨砂背景。

组件内部无法获取页面级的 onPageScroll，因此必须由页面把滚动距离通过 scrollTop 传入。

<template>
	<view>
		<up-navbar
			mode="ios"
			title="设置"
			:scrollTop="scrollTop"
			:autoBack="true"
		></up-navbar>
		<view><!-- 页面内容 --></view>
	</view>
</template>

<script setup>
import { ref } from 'vue';
import { onPageScroll } from '@dcloudio/uni-app';

const scrollTop = ref(0);

onPageScroll((e) => {
	scrollTop.value = e.scrollTop;
});
</script>

<script>
	export default {
		data() {
			return {
				scrollTop: 0
			}
		},
		onPageScroll(e) {
			this.scrollTop = e.scrollTop;
		}
	}
</script>

注意

mode="ios" 下 fixed 与 placeholder 会被忽略：导航栏恒定固定，大标题所在的占位层恒定渲染。因为该层承载的是大标题这一实际内容，而非可选占位
不传 scrollTop 时导航栏会停留在大标题展开态，不会报错。这是有意的静默降级
bgColor 传入后会作为压缩态背景并仍按曲线淡入；传入不透明颜色会掩盖模糊效果
title 为空字符串时不渲染大标题行，导航栏初始即为磨砂态
使用 center 插槽时，插槽内容随压缩过程淡入上浮，但大标题始终取 title 属性渲染。若需要大标题，必须同时传 title
nvue 端不支持该模式，传入 mode="ios" 时渲染为 default 形态

# 压缩过程

滚动距离与大标题行高（52px）的比值构成压缩进度，两段过渡刻意错开先后，因此任何位置都不会出现两段标题文字互相透出：

滚动距离	磨砂背景	居中标题
0	完全透明	未出现
26px	已完全不透明	未出现
39px	完全不透明	此刻才开始浮现
52px 及以上	完全不透明	完全就位

居中标题在淡入的同时会由下方 12px 上浮就位，并带 0.15s 过渡以填补离散滚动事件之间的空隙。大标题本身不做淡出，由导航栏边缘自然裁切，这与 iOS 原生行为一致。

磨砂底色与模糊半径可通过 --up-navbar-glass-bg-color 与 --up-navbar-glass-blur 两个主题变量调整，默认跟随明暗模式切换。底色的 0.82 不透明度是 backdrop-filter 不生效时的文字可读性下限，不建议显著降低。

# 右侧演示页面源代码地址

点击以下链接以查看右侧演示页面的源码

iOS 大标题模式的演示页源码

# API

# Props

参数	说明	类型	默认值	可选值
safeAreaInsetTop	是否开启顶部安全区适配	Boolean	true	false
placeholder	固定在顶部时，是否生成一个等高元素，以防止塌陷	Boolean	false	true
fixed	导航栏是否固定在顶部	Boolean	true	false
border	导航栏底部是否显示下边框	Boolean	false	true
leftIcon	左边返回图标的名称，只能为uview-plus自带的图标	String	arrow-left	-
leftText	左边的提示文字	String	-	-
rightText	右边的提示文字	String	-	-
rightIcon	右边返回图标的名称，只能为uview-plus自带的图标	String	-	-
title	导航栏标题，如设置为空字符，将会隐藏标题占位区域	String	-	-
bgColor	导航栏背景设置	String	#ffffff	-
titleWidth	导航栏标题的最大宽度，内容超出会以省略号隐藏，单位rpx	String \| Number	400rpx	-
height	导航栏高度(不包括状态栏高度在内，内部自动加上)，单位px	String \| Number	44px	-
leftIconSize	左侧返回图标的大小	String \| Number	20px	-
leftIconColor	左侧返回图标的颜色	String	#303133	-
autoBack 2.0.19	点击左侧区域(返回图标)，是否自动返回上一页	Boolean	false	true
titleStyle 2.0.23	标题的样式，对象或字符串形式	String \| Object	-	-
mode 3.8.112	导航栏模式，`ios` 为大标题磨砂模式	String	default	ios
scrollTop 3.8.112	页面滚动距离，仅 `ios` 模式使用，需由页面 `onPageScroll` 传入	String \| Number	0	-

# Event

名称	说明	类型
leftClick	点击左侧区域	Handler
rightClick	点击右侧区域	Handler

# Slot

名称	说明
left	自定义左侧部分内容
right	自定义右侧部分内容
center 2.0.17	自定义中部内容

← BackTop 返回顶部 NavbarMini 迷你导航栏 →