TitleBar(NavBar)

约 1473 字大约 5 分钟

2026-06-25

简介

TitleBar(NavBar) 是一个功能强大的标题栏组件，支持自定义标题、返回按钮、右侧操作按钮等功能，适配多端环境（小程序、H5、App）。

使用场景

页面顶部标题栏展示
自定义导航栏
带操作按钮的标题栏
多端适配的标题栏解决方案

代码演示

基础用法

标题居中

自定义按钮

自定义样式

API

属性

属性	说明	类型	可选值	默认值
title	标题文字	string	—	''
hasReturn	是否显示返回按钮	boolean	true/false	true
titleCenter	标题是否居中显示	boolean	true/false	false
hookBack	是否拦截返回事件	boolean	true/false	false
showDivider	是否显示返回按钮后的分割线	boolean	true/false	true
btns	右侧按钮配置	array	—	[]
foreColor	前景色（文字和图标颜色）	string	—	''
backgroundColor	背景色	string	—	''
forceShowTitleBar	强制显示标题栏	boolean	true/false	false
hasCustomView	是否有自定义视图	boolean	true/false	false
titleBarPaddingTop	标题栏顶部内边距	number	—	-1
ignorePropertyColor	忽略属性颜色设置	boolean	true/false	false

btns 数据结构

[
  {
    label: '按钮文字',     // 按钮显示文字
    icon: 'icon-class',   // 图标类名
    type: 'text',         // 按钮类型：text/link
    api_name: 'btn1',     // 按钮标识
    onClick: function() { // 点击事件
      // 处理点击逻辑
    }
  }
]

btns 属性说明

属性	说明	类型	可选值	默认值
label	按钮显示文字	string	—	—
icon	图标类名或图片链接	string	—	—
type	按钮类型	string	text/link	text
api_name	按钮唯一标识	string	—	—
onClick	点击回调函数	function	—	—

事件

事件名	说明	回调参数
back	返回按钮点击时触发（需设置 hookBack 为 true）	—

插槽

插槽名	说明
—	默认插槽，标题内容
title_left	标题左侧内容

使用方法

基础标题栏

<title-bar title="页面标题" />

居中标题

<title-bar 
  title="居中标题" 
  titleCenter="{{true}}" 
/>

带操作按钮

<title-bar 
  title="操作页面" 
  btns="{{buttons}}" 
/>

Page({
  data: {
    buttons: [
      {
        label: '搜索',
        icon: 'icon-search',
        api_name: 'search',
        onClick: () => {
          console.log('搜索按钮点击');
        }
      },
      {
        label: '更多',
        icon: 'icon-more',
        api_name: 'more',
        onClick: () => {
          console.log('更多按钮点击');
        }
      }
    ]
  }
});

自定义颜色

<title-bar 
  title="自定义颜色" 
  foreColor="#ffffff"
  backgroundColor="#007AFF"
/>

拦截返回事件

<title-bar 
  title="拦截返回" 
  hookBack="{{true}}"
  bind:back="onBack"
/>

Page({
  onBack() {
    wx.showModal({
      title: '提示',
      content: '确定要离开吗？',
      success: (res) => {
        if (res.confirm) {
          wx.navigateBack();
        }
      }
    });
  }
});

自定义标题内容

<title-bar>
  <view class="custom-title">
    <image src="/images/logo.png" class="title-logo" />
    <text>自定义标题</text>
  </view>
</title-bar>

设计说明

多端适配

小程序：完整功能支持，自动适配状态栏高度
H5：根据环境自动显示/隐藏标题栏
App：支持横竖屏切换，自动调整布局

样式特性

响应式设计：自动适配不同屏幕尺寸
主题支持：支持品牌色和自定义颜色
图标系统：集成 iconfont 图标库
RTL 支持：支持从右到左的文字方向

交互体验

返回逻辑：支持默认返回和自定义返回处理
按钮操作：支持多个操作按钮，灵活配置
视觉层次：清晰的视觉层次和间距设计

技术特点

性能优化：使用 styleIsolation 优化样式隔离
事件处理：支持事件冒泡控制
生命周期：完整的组件生命周期管理

显示逻辑说明

标题栏显示条件

TitleBar 组件的显示遵循以下逻辑：

// 显示条件：!(dIsH5 && hasCustomView && !btns.length) || forceShowTitleBar || dH5ShowTitleBar

详细说明：

基础显示条件：
- 当 forceShowTitleBar 为 true 时，强制显示标题栏
- 当 dH5ShowTitleBar 为 true 时，在 H5 环境下显示标题栏
H5 环境特殊逻辑：
- 在 H5 环境下，如果同时满足以下条件，则隐藏标题栏：
  - dIsH5 为 true（当前是 H5 环境）
  - hasCustomView 为 true（有自定义视图）
  - btns.length 为 0（没有右侧按钮）

H5 显示判断（来自 page.base.js）：

isShowTitleBar() {
  // 非 H5 环境或小程序环境或非移动端或中化环境时显示标题栏
  return !config.isH5() || 
         config.h5Env.isMiniProgram || 
         !(config.h5Env.isAndroid || config.h5Env.isIOS) || 
         config.h5Env.isSinochemit
}

返回按钮显示逻辑

返回按钮的显示条件：

// 小程序环境：(!dIsH5 && !dIsFromTab && hasReturn)
// H5 环境：(dIsH5 && hasReturn && dH5ShowTitleBar && dH5ShowBackBtn)

详细说明：

小程序环境：
- 非 H5 环境
- 非 Tab 页面
- hasReturn 为 true
H5 环境：
- 是 H5 环境
- hasReturn 为 true
- dH5ShowTitleBar 为 true
- dH5ShowBackBtn 为 true

H5 返回按钮判断：

// 通过 wx.utilAction 获取是否显示返回按钮
dH5ShowBackBtn: (wx.utilAction ? wx.utilAction({action: "getIsShowBackBtnOfTitleBar"}) : true) || this.data.forceShowBackBtn

环境适配逻辑

状态栏高度适配：

横屏模式：dTitleBarPaddingTop = 0（全屏状态）
竖屏模式：dTitleBarPaddingTop = statusBarHeight
Android 特殊处理：在 Tab 页面且版本 >= 770 时，dTitleBarPaddingTop = 0

标题居中样式：

当 titleCenter 为 true 且非 Tab 页面时，添加 padding: 0 30px 保持标题居中

品牌色处理：

优先使用组件传入的 foreColor 和 backgroundColor
其次使用品牌色配置 brandColor.appColor
可通过 ignorePropertyColor 忽略属性颜色设置

注意事项

状态栏适配：组件会自动处理状态栏高度，无需手动设置
H5 环境：在 H5 环境下会根据页面类型自动显示/隐藏
按钮配置：btns 数组中的 onClick 函数需要在页面中定义
颜色设置：foreColor 和 backgroundColor 会覆盖默认的品牌色
横屏适配：在支持横屏的页面中会自动调整布局
显示逻辑：组件会根据环境、页面类型、配置参数自动判断是否显示标题栏和返回按钮

预览

打开预览