Navbar 导航栏

17:06

说明

自定义顶部导航栏：返回图标与返回文字、居中标题、left / 默认 / right 三个插槽、渐变或纯色背景，以及固定与沉浸式。is-fixed 时自动加状态栏占位把内容压到状态栏之下（immersive 可取消占位）；默认高度 App / H5 为 44px，微信小程序 iOS 44px、Android 48px。多数场景可直接用 uni-app 原生导航栏，需要自定义时再用它。

兼容性

平台	支持情况
App	✅ 支持（默认高度 44px）
H5	✅ 支持（默认高度 44px）
微信小程序	✅ 支持（默认高度 iOS 44px / Android 48px）

示例

基础用法

固定于页面顶部，默认包含返回图标与居中标题，支持返回文字。

查看源码

<template>
    <ux-navbar :title="title" :is-fixed="false" />
    <ux-navbar :title="title" back-text="返回" :is-fixed="false" />
</template>

<script setup lang="uts">
const title = ref<string>('导航标题');
</script>

标题样式

通过 title-bold、title-size、title-color 定制标题，title-width 限制宽度并单行省略。

查看源码

<template>
    <ux-navbar :title="defaultTitle" :is-fixed="false" />
    <ux-navbar :title="boldTitle" title-bold title-size="18" :is-fixed="false" />
    <ux-navbar :title="primaryTitle" title-color="#2979ff" :is-fixed="false" />
    <!-- 超长标题：title-width 限制最大宽度，超出单行省略 -->
    <ux-navbar :title="longTitle" title-width="120" :is-fixed="false" />
</template>

<script setup lang="uts">
const defaultTitle = ref<string>('导航标题');
const boldTitle = ref<string>('加粗大标题');
const primaryTitle = ref<string>('主题蓝标题');
const longTitle = ref<string>('这是一个很长的标题，超出部分将显示省略号');
</script>

返回栏

is-back 控制返回是否显示，back-text、back-icon-name/size/color 定制返回栏。

查看源码

<template>
    <ux-navbar :title="title" :is-fixed="false" />
    <ux-navbar :title="noBackTitle" :is-back="false" :is-fixed="false" />
    <ux-navbar :title="title" back-text="上一页" back-icon-name="arrow-left" :is-fixed="false" />
    <ux-navbar :title="title" back-icon-color="#2979ff" back-icon-size="18" :is-fixed="false" />
</template>

<script setup lang="uts">
const title = ref<string>('返回栏');
const noBackTitle = ref<string>('隐藏返回');
</script>

背景颜色

background 支持线性渐变与纯色背景。

查看源码

<template>
    <ux-navbar :title="title" :background="gradient" back-icon-color="#ffffff" title-color="#ffffff" :is-fixed="false" />
    <ux-navbar :title="title" :background="{ background: '#39CCCC' }" back-icon-color="#ffffff" title-color="#ffffff" :is-fixed="false" />
    <ux-navbar :title="title" :background="{ background: '#B471CC' }" back-icon-color="#ffffff" title-color="#ffffff" :is-fixed="false" />
</template>

<script setup lang="uts">
const title = ref<string>('背景色');
const gradient = ref<UTSJSONObject>({
    'background-image': 'linear-gradient(90deg, rgb(28, 187, 180), rgb(141, 198, 63))'
});
</script>

自定义插槽

left / 默认 / right 三个插槽，自定义导航栏左、中、右区域内容。

查看源码

<template>
    <ux-navbar :background="gradient" back-icon-color="#ffffff" :is-fixed="false">
        <template #left>
            <text style="color:#ffffff;font-size:11px;">左侧</text>
        </template>
        <!-- 默认插槽：居中内容区 -->
        <text style="flex:1;color:#ffffff;font-size:14px;text-align:center;">轻舟已过万重山</text>
        <template #right>
            <ux-icon name="chat" size="18" color="#ffffff" />
            <ux-icon name="calendar-fill" size="18" color="#ffffff" />
        </template>
    </ux-navbar>
</template>

<script setup lang="uts">
const gradient = ref<UTSJSONObject>({
    'background-image': 'linear-gradient(90deg, rgb(28, 187, 180), rgb(141, 198, 63))'
});
</script>

自定义返回事件

custom-back 覆盖默认返回行为，实现拦截或定制逻辑。

查看源码

<template>
    <ux-navbar title="自定义返回" :custom-back="customBack" :is-fixed="false" />
    <text>点击返回按钮不会退出页面，而是触发自定义事件</text>
</template>

<script setup lang="uts">
const customBack = () => {
    uni.showToast({ title: '拦截了返回事件', icon: 'none' });
};
</script>

边框与高度

border-bottom 控制下边框，height 自定义导航栏高度。

查看源码

<template>
    <ux-navbar :title="noBorder" :border-bottom="false" :is-fixed="false" />
    <ux-navbar :title="customHeight" height="56" :is-fixed="false" />
</template>

<script setup lang="uts">
const noBorder = ref<string>('无下边框');
const customHeight = ref<string>('自定义高度');
</script>

固定与沉浸

is-fixed 固定顶部、immersive 沉浸式（取消 fixed 占位）、z-index 层级控制。

查看源码

<template>
    <!-- is-fixed=true 固定在页面顶部（默认），下方内容随页面滚动 -->
    <ux-navbar title="固定导航栏" back-text="返回"
        :background="{ 'background-image': 'linear-gradient(90deg, rgb(28,187,180), rgb(141,198,63))' }"
        back-icon-color="#ffffff" title-color="#ffffff" />
</template>

<script setup lang="uts">
const title = ref<string>('固定导航栏');
</script>

API

Props

属性	说明	类型	默认值	版本
height	导航栏高度，单位 px，非 px	string | number	''	-
backIconColor	返回箭头的颜色	string	''	-
backIconName	左边返回的图标	string	'nav-back'	-
backIconSize	左边返回图标的大小，px	string | number	'18'	-
backText	返回的文字提示	string	''	-
backTextColor	返回文字的颜色	string	''	-
backTextStyle	返回文字的样式	UTSJSONObject	-	-
title	导航栏标题	string	''	-
titleWidth	标题的宽度，单位 px	string | number	'180'	-
titleColor	标题的颜色	string	''	-
titleBold	标题字体是否加粗	boolean	false	-
titleSize	标题的字体大小	string | number	16	-
isBack	是否显示导航栏左边返回图标和辅助文字	boolean | string	true	-
background	导航栏背景设置	UTSJSONObject	-	-
isFixed	导航栏是否固定在顶部	boolean	true	-
immersive	是否沉浸式，允许 fixed 定位后导航栏塌陷，仅 fixed 定位下生效	boolean	false	-
borderBottom	是否显示导航栏的下边框	boolean	true	-
zIndex	固定在顶部时的 z-index 值	string | number	''	-
customBack	自定义返回逻辑方法	() => void	-	-
customClass	自定义类名	string	''	-
customStyle	自定义样式	string | UTSJSONObject	-	-

Events

ux-navbar 无事件。

Slots

插槽名	说明	版本
left	导航栏左侧自定义内容区（位于返回区之后、标题之前）	-
default	导航栏中间内容区（位于标题之后、右侧插槽之前，可用于自定义标题以外的居中内容）	-
right	导航栏右侧自定义内容区（位于导航栏最右端）	-

注意事项

• 默认高度按平台区分：App / H5 为 44px，微信小程序 iOS 44px、Android 48px；height 不含状态栏高度，组件内部会自动补上状态栏占位。
• is-fixed=true 时自动加状态栏占位，把内容压到系统状态栏之下；不需要占位（沉浸式）时用 immersive（仅 is-fixed 下生效）。
• 返回文字必须落在 <text> 上：App 端 color 只作用于 text，裸文本还会丢失父容器颜色继承。
• 标题单行省略：App 端走 <text max-lines="1"> 原生省略，H5 / 微信小程序走 -webkit-line-clamp。
• 自定义插槽内容在 App 端样式不继承，插槽内的文字与图标需自行显式设色。
• 传入 custom-back 后返回按钮不再执行 uni.navigateBack()，由回调接管。