【亲测免费】小程序组件 `navigationBar` 技术文档

2026-01-25 04:24:30作者：袁立春Spencer

本篇文档旨在详尽指导您如何使用navigationBar组件，以实现定制化的顶部导航栏，优化小程序界面体验。

1. 安装指南

无需额外的npm包安装，您只需按照以下步骤将组件集成到您的小程序项目中：

复制组件: 将navigationBar组件文件夹(/components/navBar)从项目仓库下载至您小程序的相应目录。

引入组件: 在需要使用该导航栏的页面的page.json文件中加入如下代码:

{
  "usingComponents": {
    "navBar": "/path/to/navBar/navBar" // 替换/path/to/为实际路径
  }
}

2. 项目的使用说明

布局与展示

在页面的.wxml文件中，通过标签形式插入导航栏，并根据需求设置属性：

<navBar title="首页" background="#fff" bindback="goBackHandler" />

您可以根据需要调整title、background等属性，甚至通过监听bindback等事件来控制逻辑。

自定义行为

事件绑定: 如上例中的bindback，您可定义相应的处理函数（例如goBackHandler）于对应的.js文件中。
插槽(Slot)利用: 当需要更复杂的布局，如自定义左侧或右侧按钮时，利用left、center、right插槽。

3. 项目API使用文档

属性

属性名	类型	默认值	描述
title	string		导航栏标题，若无则使用center插槽内容
background	string	#fff	导航栏背景色
...	...	...	属性表继续包含color, iconTheme, back, home, searchBar等，具体如ReadMe所列

事件

事件名	描述
bindback	返回按钮点击事件
bindhome	Home按钮点击事件，需要自定义处理方法
bindsearch	搜索按钮点击事件

注意事项

使用特殊主题（iconTheme: 'white'）时，确保全局设置navigationBarTextStyle为白色。
解决Android键盘弹出导致的布局问题，给页面设定固定高度。
对于渐变背景等问题，请参考特定issue的讨论及解决方案。

4. 示例代码深化理解

假设在某个页面使用导航栏，您应确保在.json配置后，在.wxml中这样使用：

<!-- 在.wxml -->
<navBar
  title="导航实例"
  background="#EFEFEF"
  bindback="handleBack"
  bindhome="handleHome"
>
  <!-- 可选的插槽内容 -->
  <view slot="left" class="custom-back">返回</view>
</navBar>

随后在.js中定义对应的方法：

// 在.js
Page({
  handleBack() {
    wx.navigateBack(); // 或自定义跳转逻辑
  },
  handleHome() {
    // 自定义主页跳转或其他操作
    wx.switchTab({ url: '/pages/index/index' });
  },
});