Introduction

TitleBar (NavBar) is a powerful title bar component that supports custom title, back button, and right-side action buttons. It automatically adapts to multiple environments (Mini Program, H5, App) and handles scenarios such as status bar height, orientation changes, and brand colors.

Usage

Configure it in the index.json of the page or component where it is needed:

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

The page must set "navigationStyle": "custom" to hide the native navigation bar and use the custom title bar instead.

Code Demos

Basic Usage

Centered Title

Custom Buttons

Custom Style

---

API

Properties

Property	Description	Type	Default
title	Title text	string	''
hasReturn	Whether to show the back button	boolean	true
hookBack	Whether to intercept the back event (when set to true, listen for the back event and handle the back action yourself)	boolean	false
titleCenter	Whether to center the title	boolean	false
showDivider	Whether to show the divider after the back button	boolean	true
btns	Right-side button configuration, see the btns data structure below	array	[]
foreColor	Foreground color (text and icon color)	string	''
backgroundColor	Background color	string	''
ignorePropertyColor	Whether to ignore property colors and use the brand color	boolean	false
forceShowTitleBar	Force show the title bar (in H5 with a custom view it is hidden; this property forces it to show)	boolean	false
forceShowBackBtn	Force show the back button	boolean	false
hasCustomView	Whether there is a custom view (affects H5 display logic)	boolean	false
titleBarPaddingTop	Top padding of the title bar, -1 means auto-adapt	number	-1

btns Data Structure

[
  {
    label: 'Button text',     // Button display text
    icon: 'icon-class',   // Icon class name or image link
    type: 'text',         // Button type: text / link
    api_name: 'btn1',     // Unique button identifier
    onClick() {           // Click callback
      // Handle click logic
    }
  }
]

Events

Event name	Description	Callback params
back	Triggered when the back button is clicked (requires hookBack to be true)	—

Slots

Slot name	Description
—	Default slot, title content
title_left	Content to the left of the title

External Style Classes

Class name	Description
i-class	Custom style class for the root node

---

Usage Examples

Basic Usage

<title-bar title="Page Title" />

Without Back Button

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

Centered Title

<title-bar title="Centered Title" titleCenter="{{true}}" />

Custom Colors

<title-bar
  title="Custom Colors"
  foreColor="#ffffff"
  backgroundColor="#007AFF"
/>

With Right-side Buttons

<title-bar title="Action Page" btns="{{buttons}}" />

Page({
  data: {
    buttons: [
      {
        label: 'Search',
        icon: 'search',
        api_name: 'search',
        onClick() { console.log('Search'); }
      },
      {
        label: 'More',
        icon: 'more',
        api_name: 'more',
        onClick() { console.log('More'); }
      }
    ]
  }
});

Intercept Back

<title-bar title="Intercept Back" hookBack="{{true}}" bind:back="onBack" />

Page({
  onBack() {
    wx.showModal({
      title: 'Prompt',
      content: 'Are you sure you want to leave?',
      success(res) {
        if (res.confirm) wx.navigateBack();
      }
    });
  }
});

Custom Title Content

<title-bar>
  <view class="custom-title">
    <image src="/images/logo.png" class="title-logo" />
    <text>Custom Title</text>
  </view>
</title-bar>

---

Display Logic Notes

Title Bar Display Condition

// Display: !(dIsH5 && hasCustomView && !btns.length) || forceShowTitleBar || dH5ShowTitleBar

Condition	Description
forceShowTitleBar is true	Force show
H5 environment + custom view + no buttons	Hide the title bar (H5 provides native navigation via the browser)
Other cases	Show by default

Back Button Display Condition

Environment	Condition
Mini Program	Not H5 + not a Tab page + hasReturn is true
H5	H5 environment + hasReturn is true + title bar shown + back button shown

Status Bar Height Adaptation

• Portrait: dTitleBarPaddingTop = statusBarHeight
• Landscape: dTitleBarPaddingTop = 0 (full screen)
• Android Tab page (version >= 770): dTitleBarPaddingTop = 0
• Manual override: use the titleBarPaddingTop property

---

Notes

1. The page must set "navigationStyle": "custom" to use the custom title bar
2. The component automatically handles status bar height adaptation; no manual calculation is needed
3. In H5, it automatically decides whether to show/hide based on the page type
4. The onClick callback in the btns array must be bound in the page data
5. foreColor / backgroundColor take precedence over brand color configuration

---

打开预览