n-navbar 自定义导航栏

页面在 pages.json 配置 "navigationStyle": "custom" 隐藏系统导航栏后，用本组件替代：状态栏占位 + 返回箭头 + 标题 + 左右操作区。微信端自动避让右上角胶囊按钮；固定在顶部时可生成等高占位防止内容塌陷；标题、图标、文字、颜色、分隔线均可配置。

平台兼容性

App	Web	微信小程序
✓	✓	✓

微信端左右操作区自动对称避让胶囊按钮（左区让开胶囊右缘、右区让开胶囊左缘，与原生导航栏箭头位置对齐），其他端无胶囊不避让。init 事件在布局就绪时上报一次导航栏高度、状态栏高度与胶囊信息（非微信端胶囊字段为 -1/0），供页面内容区自行计算顶部偏移。使用前需在目标页面 style 中配置 "navigationStyle": "custom"，并按需设置 "navigationBarTextStyle" 控制状态栏文字颜色（H5 无效）。

基本用法

组件放页面内容流的最前面（与普通节点同层）：fixed + placeholder 开启时，等高占位随组件落在文档流顶部，内容自然从导航栏下方开始；组件放内容之后占位推不动顶部内容，会被导航栏遮挡。

零配置：默认渲染返回箭头，点击自动返回上一页（页面栈只有当前页时不动作，leftClick 仍触发）：

<template>
　　<n-navbar title="个人中心" @rightClick="onRight" />
</template>

需要跳转到指定页面时关闭自动返回，在 leftClick 中按应用路由配置调用原生导航 API。目标路径必须已在应用 pages.json 注册；tabBar 页面使用 uni.switchTab，普通页面使用 uni.navigateTo。下面使用本工程 pages.json 中实际注册的 tabBar 页面：

<n-navbar title="个人中心" :auto-back="false" @leftClick="onLeftClick" />

function onLeftClick(): void {
	uni.switchTab({ url: "/pages/tabbar/component" });
}

临时禁用左侧返回操作时使用 backable：内置图标和左侧文字降低透明度，点击不会自动返回，也不会触发 leftClick。自定义 left 插槽的视觉状态由插槽内容负责；auto-back 仍只决定启用时由组件自动返回还是交给调用方处理。

<n-navbar title="个人中心" :backable="false" />

左侧"返回"文字与右侧操作（文字 / 图标任选）：

<n-navbar title="个人中心" left-text="返回" right-text="帮助" @rightClick="onRight" />
<n-navbar title="设置" right-icon="map" />

左侧图标样式通过 left-icon-style 透传到内置 n-icon，用于颜色以外的样式调整：

<n-navbar title="设置" left-icon-style="transform:scale(1.05);" />

left-icon-style 与 right-icon-style 左右对称，可调整对应侧图标外观；图标宽度、字号和行高始终由 left-icon-size / right-icon-size 控制。内置图标使用单字重字体，font-weight 不能保证字形变粗；需要指定粗细时，通过 left 插槽提供已具备目标粗细的图标。

固定顶部并生成等高占位、显示分隔线（通常页面主体从导航栏下方开始时开启）：

<n-navbar title="导航栏" fixed placeholder border />

自定义左右与中部内容（具名插槽替换对应区域，default 插槽整行接管）：

<n-navbar title="个人中心" left-text="返回">
　　<template #left>
　　　　<n-icon name="arrowleft" :size="19" />
　　</template>
　　<template #right>
　　　　<n-icon name="home" :size="20" />
　　</template>
</n-navbar>

深色背景导航栏：文字与图标颜色用 color 统一调整，标题细节用 title-style：

<n-navbar title="个人中心" bg-color="#007aff" color="#ffffff" />

title-style 接受 CSS 字符串或样式对象：

<n-navbar title="个人中心" :title-style="{ color: '#ffffff', fontSize: '16px', fontWeight: 600 }" />

API

属性

属性	类型	默认值	说明
custom-class	string	""	挂到根节点的额外 class（类须在组件样式表内定义，页面 class 打不进组件）
custom-style	string	""	根节点行内样式
title	string | number	""	标题文字或数字；空字符串/空值不渲染标题（中区仍占位居中）
left-text	string	""	左侧返回箭头旁的提示文字，如"返回"
right-text	string	""	右侧提示文字
left-icon	string	"left"	左侧图标名（n-icon 内置表或 registerIconFont 注册名）；空字符串隐藏图标；默认为系统返回键同形细箭头
right-icon	string	""	右侧图标名；空字符串不渲染
left-icon-size	number | string	20	左侧图标尺寸，数字或 px/rpx 字符串
right-icon-size	number | string	20	右侧图标尺寸，数字或 px/rpx 字符串
left-icon-color	string	""	左侧图标颜色；空字符串跟随 color，color 也为空时用主题文字色
left-icon-style	string	""	透传到内置左侧 n-icon 的 customStyle；图标宽度、字号、行高及 backable 禁用透明度由组件控制，不受此样式覆盖；内置字形只有常规字重，font-weight 不保证加粗；left 插槽接管时不生效
right-icon-style	string	""	透传到内置右侧 n-icon 的 customStyle；图标宽度、字号、行高由组件控制，不受此样式覆盖；right 插槽接管时不生效
right-icon-color	string	""	右侧图标颜色；空字符串跟随 color，color 也为空时用主题文字色
color	string	""	导航栏文字与图标的统一颜色；空字符串用主题文字色（深浅自适应）
bg-color	string	""	导航栏背景色，支持实色与渐变（如 linear-gradient(to right,#a,#b)，App 端请用方向关键词形式）；空字符串用主题表面色（深浅自适应）
title-style	string | UTSJSONObject	""	标题文字外观样式；接受 CSS 字符串或样式对象
title-width	number | string	"400rpx"	标题最大宽度，超出省略号截断，数字或 px/rpx 字符串；标题与 center 插槽均受左右实测操作区和微信胶囊边界限制；0 或负值表示只按安全边界限宽
height	number | string	44	导航行高度，数字或 px/rpx 字符串（不含状态栏高度，状态栏自动加上）
safe-area-inset-top	boolean	true	是否垫状态栏高度（自定义导航页应开启；页面仍有系统导航栏时关闭）
fixed	boolean	false	是否固定在页面顶部
placeholder	boolean	false	固定时是否生成等高占位元素防止内容塌陷
border	boolean	false	是否显示底部分隔线
backable	boolean	true	是否启用左侧返回操作；关闭后内置图标和文字半透明且不触发 leftClick；自定义 left 插槽外观由调用方处理
auto-back	boolean	true	点击左侧区域时是否自动返回上一页（页面栈只有当前页时不动作）
z-index	number | string	996	层级；支持数字字符串
padding	number | string	8	左右操作区基础内边距，数字或 px/rpx 字符串（微信端胶囊避让在此基础上叠加）
line-color	string	""	底部分隔线颜色；空字符串使用主题分隔线色（深浅自适应）

事件

事件	参数	说明
leftClick	—	启用 backable 时点击左侧区域触发；auto-back 开启且存在上一页时组件已先执行返回。关闭 auto-back 后由调用方在此事件中执行自定义导航，包含 tabBar 跳转
rightClick	—	点击右侧区域时触发
titleClick	—	点击标题时触发（title 非空且未使用 center 插槽）
init		布局信息就绪时触发一次；height 为导航行高（不含状态栏），胶囊三字段非微信端为 -1/0

插槽

名称	说明	参数
default	整行接管导航行内容（内置左中右全部不渲染，状态栏占位保留）	—
left	替换左侧区域内容（返回图标与文字不再渲染；backable 启用时点击触发 leftClick）	—
center	替换中部标题（title 与 title-style 不再生效，titleClick 不触发）	—
right	替换右侧区域内容（右侧图标与文字不再渲染，点击仍触发 rightClick）	—

实现说明（机制对照）

机制	参考做法	本库做法	分歧理由
布局结构	一参考左右区绝对定位 + 标题弹性居中；另一参考左右各 150rpx 定宽 + 标题弹性居中	左右区绝对定位盖在中区两端，中区弹性居中并按实测操作区收窄	标题保持屏幕居中，同时避开实际左右内容尺寸
胶囊避让	一参考组件内自动避让；另一参考 init 上报胶囊信息由使用者处理	微信端左右操作区按胶囊边界留空，标题按胶囊及实际操作区边界裁切；init 仍上报胶囊信息	内部避让零接线，上报保留页面自行布局入口
返回逻辑	一参考默认可返回、支持返回到指定路径；另一参考 autoBack 属性控制	autoBack 默认 true：页面栈深度大于 1 时 uni.navigateBack；关闭后由 leftClick 执行自定义导航	自动返回与工程路由解耦；页面路径和 tabBar 目标由调用方按项目配置选择原生 API
返回禁用	Cool 提供 backable，false 时返回图标半透明且阻止返回	backable=false 时内置左侧内容半透明并阻止导航和 leftClick；自定义 left 插槽外观由调用方处理；autoBack 独立控制自动返回或自定义事件	禁用反馈覆盖内置箭头及其提示文字，插槽内容由调用方控制
状态栏占位	三参考分别名 safeAreaTop / statusBar / safeAreaInsetTop	safeAreaInsetTop，默认 true	跟随自定义导航场景的主流默认（自定义导航页必须垫状态栏）
固定与占位	一参考固定即自带占位；一参考 fixed + placeholder 两开关；一参考 isFixed + isOccupy	fixed + placeholder 两开关（placeholder 默认 false）	占位独立可控：非滚动页可省一个占位节点
分隔线	border / splitLine	border，默认 false；颜色走主题分隔线令牌	跟随语义化命名；深浅主题自适应
标题限宽	titleWidth 默认 400rpx，超出省略	同款默认与省略行为	标题与 center 插槽均受实测可用宽度约束，内置标题额外遵守 title-width
标题字号字重	一参考 size（17px）/ fontWeight 属性	默认 16px 常规字重（系统导航栏标题即默认字号不单设），不设专属属性，title-style 承接全部排版	行内样式可表达全部排版细节，避免属性面重复；字号对齐官方导航栏组件实现（标题继承默认字号）
标题类型	一参考元数据 title 允许数字	title 接受 string | number，内部统一字符串化判断	数字标题（计数等场景）直接可用，0 等 falsy 值不被误判为空
左侧图标字重	本地参考元数据列有 leftIconBold；在线属性表未列该项	当前内置字体只有常规字形，不提供无法由字体资产兑现的加粗承诺；left-icon-style 仅用于普通样式调整	单字重自定义字体不能依靠 CSS font-weight 跨平台保证加粗；需要增加经验证的粗体字形资产后才能提供此能力
渐变背景	一参考 background 传 linear-gradient(...) 演示	bgColor 兼容：含 gradient 走 background-image 变量类（节点重建），实色走 background-color 变量类	对齐参考渐变导航能力；App 端禁 background 简写与角度形式，示例用方向关键词
左右区内边距	一参考 padding 属性（默认 8px）	padding 属性（数字或 px/rpx），微信端胶囊避让在其上叠加	padding 是左右区域唯一的基础内边距来源
分隔线颜色	一参考 lineColor 属性	line-color 属性，空值走主题分隔线令牌	实例级覆盖与主题自适应并存
自定义返回	一参考通过路由器 backPath 导航；另一参考提供 autoBack	autoBack 默认返回上一页；关闭后通过 leftClick 事件由调用方选择 navigateTo、switchTab 等原生 API	组件不依赖应用路由表；自定义路径与 tabBar 目标交由调用方根据工程配置选择原生导航 API
init 事件	created 时上报 windowWidth / height(44) / statusBarHeight / 胶囊 left·width·height（非微信 -1/0）	onMounted 同载荷上报一次	载荷与参考逐字段一致；供页面内容区自行计算顶部偏移
图标样式通道	三参考均未提供图标样式透传属性	left-icon-style / right-icon-style 左右对称透传到内置 n-icon 的 customStyle；宽度、字号、行高殿后守卫	同侧图标细调不必整区插槽替换；几何不开放覆盖，避免与 iconSize 形成双事实源
插槽	一参考 left/right/center 三具名；一参考 default 整行接管（custom 开关）	left/right/center 三具名 + default 整行接管（有 default 即接管，无开关）	功能面并集；default 接管与本库整钮/整区替换惯例一致（如返回顶部组件）
图标默认值	左侧默认返回箭头（arrow-left，chevron 细箭头形）	left-icon 默认 left（本库内置表中的同形细箭头）	与参考及系统返回键同形，不用带杆箭头；参考实现不可核实的加粗能力不收
颜色体系	文字色/背景色/图标色逐项属性	color 统一文字与图标色、bgColor 背景、leftIconColor/rightIconColor 逐侧覆盖；空值走主题令牌（深浅自适应）	深色背景一处改色全覆盖；需要精细区分时用逐侧覆盖