简介

TitleBar（NavBar）是一个功能强大的标题栏组件，支持自定义标题、返回按钮、右侧操作按钮等功能。自动适配多端环境（小程序、H5、App），处理状态栏高度、横竖屏切换、品牌色等场景。

使用方法

在需要使用的页面或组件的 index.json 中配置：

"usingComponents": {
  "title-bar": "ava-ui/fxui/TitleBar/TitleBar"
}

页面需设置 "navigationStyle": "custom" 以隐藏原生导航栏，使用自定义标题栏替代。

代码演示

基础用法

标题居中

自定义按钮

自定义样式

---

API

属性

属性	说明	类型	默认值
title	标题文字	string	''
hasReturn	是否显示返回按钮	boolean	true
hookBack	是否拦截返回事件（设为 true 后需监听 back 事件自行处理返回）	boolean	false
titleCenter	标题是否居中显示	boolean	false
showDivider	是否显示返回按钮后的分割线	boolean	true
btns	右侧按钮配置，见下方 btns 数据结构	array	[]
foreColor	前景色（文字和图标颜色）	string	''
backgroundColor	背景色	string	''
ignorePropertyColor	是否忽略属性颜色，使用品牌色	boolean	false
forceShowTitleBar	强制显示标题栏（H5 环境有自定义视图时隐藏，此属性可强制显示）	boolean	false
forceShowBackBtn	强制显示返回按钮	boolean	false
hasCustomView	是否有自定义视图（影响 H5 环境显示逻辑）	boolean	false
titleBarPaddingTop	标题栏顶部内边距，-1 表示自动适配	number	-1

btns 数据结构

[
  {
    label: '按钮文字',     // 按钮显示文字
    icon: 'icon-class',   // 图标类名或图片链接
    type: 'text',         // 按钮类型：text / link
    api_name: 'btn1',     // 按钮唯一标识
    onClick() {           // 点击回调
      // 处理点击逻辑
    }
  }
]

Events

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

Slots

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

外部样式类

类名	说明
i-class	根节点自定义样式类

---

使用示例

基础用法

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

无返回按钮

<title-bar title="首页" hasReturn="{{false}}" />

居中标题

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

自定义颜色

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

带右侧按钮

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

Page({
  data: {
    buttons: [
      {
        label: '搜索',
        icon: 'search',
        api_name: 'search',
        onClick() { console.log('搜索'); }
      },
      {
        label: '更多',
        icon: 'more',
        api_name: 'more',
        onClick() { console.log('更多'); }
      }
    ]
  }
});

拦截返回

<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>

---

显示逻辑说明

标题栏显示条件

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

条件	说明
forceShowTitleBar 为 true	强制显示
H5 环境 + 自定义视图 + 无按钮	隐藏标题栏（H5 由浏览器提供原生导航）
其他情况	默认显示

返回按钮显示条件

环境	条件
小程序	非 H5 + 非 Tab 页 + hasReturn 为 true
H5	H5 环境 + hasReturn 为 true + 显示标题栏 + 显示返回按钮

状态栏高度适配

• 竖屏：dTitleBarPaddingTop = statusBarHeight
• 横屏：dTitleBarPaddingTop = 0（全屏状态）
• Android Tab 页（版本 >= 770）：dTitleBarPaddingTop = 0
• 手动指定：可通过 titleBarPaddingTop 属性覆盖

---

注意事项

1. 页面需设置 "navigationStyle": "custom" 才能使用自定义标题栏
2. 组件会自动处理状态栏高度适配，无需手动计算
3. H5 环境下会根据页面类型自动决定显示/隐藏
4. btns 数组中的 onClick 回调需在页面 data 中绑定
5. foreColor / backgroundColor 优先级高于品牌色配置

---

打开预览