xm-uniapp-navbar

UniApp 导航栏组件

一个适用于uniapp的导航栏组件，支持app和h5端，兼容vue2和vue3。导航栏高度为44px，顶部包含安全区域，左侧有返回键与标题，右侧是类似微信小程序的胶囊按钮。

特性

• 🔄 兼容 Vue2 和 Vue3
• 📱 支持 App 和 H5 端
• 🔒 顶部安全区域自适应
• 🔙 可定制的返回按钮
• 🧩 右侧胶囊按钮，保留微信小程序样式
• 📝 可插入自定义内容

安装

npm install uniapp-navbar --save
# 或
yarn add uniapp-navbar
# 或
pnpm add uniapp-navbar

使用方法

Vue2

<template>
  <view>
    <x-navbar 
      title="页面标题" 
      :show-back="true"
      :show-capsule="true"
    >
      <template #right>
        <!-- 自定义右侧内容 -->
        <text>自定义</text>
      </template>
    </x-navbar>
    
    <!-- 页面内容 -->
    <view>页面内容</view>
  </view>
</template>

<script>
import XNavbar from 'uniapp-navbar'

export default {
  components: {
    XNavbar
  }
}
</script>

Vue3

<template>
  <view>
    <x-navbar 
      title="页面标题" 
      :show-back="true"
      :show-capsule="true"
      @back="handleBack"
      @capsuleClick="handleCapsuleClick"
    >
      <template #right>
        <!-- 自定义右侧内容 -->
        <text>自定义</text>
      </template>
    </x-navbar>
    
    <!-- 页面内容 -->
    <view>页面内容</view>
  </view>
</template>

<script setup>
import XNavbar from 'uniapp-navbar'

const handleBack = () => {
  console.log('返回按钮点击')
}

const handleCapsuleClick = (type) => {
  console.log('胶囊按钮点击', type) // type: 'close' 或 'menu'
}
</script>

参数说明

参数	说明	类型	默认值
title	标题文字	String	''
showBack	是否显示返回按钮	Boolean	true
backText	返回按钮文字	String	''
showCapsule	是否显示胶囊按钮	Boolean	true
titleCenter	标题是否居中	Boolean	false
backgroundColor	导航栏背景色	String	'#fff'
textColor	文字颜色	String	'#000'
capsuleColor	胶囊按钮颜色	String	'#000'

事件

事件名	说明	参数
back	点击返回按钮时触发	-
capsuleClick	点击胶囊按钮时触发	type: 'close'或'menu'

插槽

插槽名	说明
right	右侧自定义内容

开发与调试

使用CLI方式

本项目包含一个完整的示例应用，可用于调试和测试组件：

# 安装主项目依赖
npm install

# 安装示例项目依赖 
npm run install:example

# 运行示例项目
npm run dev      # 运行到微信小程序
npm run dev:h5   # 运行到H5
npm run dev:app  # 运行到App

也可以直接在示例项目目录中运行：

cd example
npm install --legacy-peer-deps
npm run dev:h5   # 运行H5版本

示例项目位于/example目录下，提供了多种组件使用场景和配置方式的演示。

使用HBuilderX方式（推荐）

由于UniApp CLI配置复杂，建议使用HBuilderX开发和调试：

• 下载并安装HBuilderX
• 在HBuilderX中创建uni-app项目
• 将components/navbar目录复制到项目的components目录下
• 创建示例页面，引入并使用组件
• 使用HBuilderX的"运行"功能直接在浏览器或模拟器中查看效果

示例页面代码：

<template>
  <view class="container">
    <x-navbar title="导航栏示例" :show-back="true" @back="handleBack"></x-navbar>
    <view class="content">
      <!-- 页面内容 -->
      <text>页面内容</text>
    </view>
  </view>
</template>

<script>
import XNavbar from '@/components/navbar/navbar.vue'

export default {
  components: {
    XNavbar
  },
  methods: {
    handleBack() {
      uni.showToast({
        title: '点击了返回按钮',
        icon: 'none'
      })
    }
  }
}
</script>

自定义图标

组件默认提供了返回、关闭和菜单三个SVG图标，存放在components/navbar/assets目录下。您可以通过以下方式自定义这些图标：

• 直接修改components/navbar/assets/index.js中的SVG字符串
• 修改组件代码，使用自己的图标组件或图片资源

示例：在项目中使用自定义图标

<template>
  <x-navbar title="自定义图标">
    <template #right>
      <view @click="handleClick">
        <image src="/static/icons/custom-icon.png" style="width: 24px; height: 24px;"></image>
      </view>
    </template>
  </x-navbar>
</template>

发布与使用公司私有包

如果需要将包发布为公司私有包，可以：

• 修改package.json中的包名，添加公司作用域：

  {
    "name": "@company-name/uniapp-navbar"
  }
  

• 配置私有npm仓库：

  npm config set @company-name:registry=https://your-private-registry-url/
  

• 发布到私有仓库：

  npm login --scope=@company-name
  npm publish
  

许可证

MIT