更新记录

1.0.0（2026-08-08） 下载此版本

• 初始发布
• 支持固定定位、玻璃效果、胶囊安全区
• 保留 up-icon 依赖
• 提供返回按钮、标题、左右插槽
• 新增 backIconSize、backIconColor、titleStyle、zIndex、rightMargin 等灵活配置项
• 优化事件处理逻辑：监听 back 事件后自动跳过默认返回

平台兼容性

uni-app(5.23)

wc-navbar 自适应导航栏组件

一款灵活、美观的 uni-app 导航栏组件，支持自定义背景、玻璃特效、自动适配微信胶囊按钮，并提供返回按钮和标题插槽。保留 up-icon 依赖，与 uview-plus 无缝结合。

✨ 功能特性

• ✅ 自动适配不同机型的状态栏高度
• ✅ 兼容微信小程序右上角胶囊按钮安全区域
• ✅ 支持固定定位 / 普通流式布局
• ✅ 内置返回按钮（自动判断入口页或内部页跳转逻辑）
• ✅ 可选的圆形玻璃返回按钮样式
• ✅ 标题文字直接配置，或使用插槽自定义中间内容
• ✅ 左右插槽提供更多扩展能力
• ✅ 液态玻璃效果 (green / white) 或纯色 / 渐变背景
• ✅ 背景图片支持
• ✅ 全宽 / 自定义宽度模式
• ✅ 可控制导航栏底部超出胶囊的高度
• ✅ 向外暴露 totalNavHeight 供页面布局使用
• ✅ 事件 back 可拦截默认返回行为
• ✅ 自定义返回图标大小、颜色
• ✅ 自定义标题样式（如颜色、字号）- 支持 titleColor 快捷设置
• ✅ 自定义导航栏层级和右侧外边距

📦 安装

1. 下载组件

将 wc-navbar 目录完整复制到你的 uni-app 项目 components/ 下。

推荐结构：

components/
  └── wc-navbar/
      └── wc-navbar.vue

2. 依赖安装

本组件内部使用了 up-icon（uview-plus 图标组件），请确保已正确安装并配置 uview-plus。

npm install uview-plus

在 main.js 中引入并注册：

import App from './App'
import uviewPlus from 'uview-plus'

// #ifdef VUE3
import { createSSRApp } from 'vue'
export function createApp() {
  const app = createSSRApp(App)
  app.use(uviewPlus)
  return { app }
}
// #endif

// #ifdef VUE2
import Vue from 'vue'
Vue.use(uviewPlus)
// #endif

3. 配置 easycom（可选，全局免引入）

在 pages.json 中添加以下配置，即可无需手动 import 直接使用 <wc-navbar>。

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "wc-navbar": "@/components/wc-navbar/wc-navbar.vue"
    }
  }
}

🚀 快速使用

基础用法

<template>
  <view>
    <wc-navbar title="页面标题" :showBack="true" />
    <view style="padding-top: 20px;">页面内容</view>
  </view>
</template>

<script setup>
// 注意：本组件符合 uni-app 插件规范。如果您是通过 uni-app 插件市场导入本组件，您可以在任何页面的 <template> 中直接使用，无需额外引入；
import WcNavbar from '@/components/wc-navbar/wc-navbar.vue'
</script>

使用玻璃效果

<wc-navbar title="透明玻璃" glass="white" :showBack="true" />

自定义背景

<wc-navbar 
  title="渐变背景" 
  bgColor="linear-gradient(135deg, #667eea 0%, #764ba2 100%)" 
/>

快速修改标题颜色

<wc-navbar title="红色标题" titleColor="#e74c3c" :showBack="true" />

自定义左右内容（插槽）

<wc-navbar>
  <template #left>
    <text>返回</text>
  </template>
  <template #center>
    <text>自定义中间</text>
  </template>
  <template #right>
    <up-icon name="scan" size="22" color="#333" />
  </template>
</wc-navbar>

拦截返回事件

<wc-navbar title="监听返回" :showBack="true" @back="handleBack" />

<script setup>
const handleBack = () => {
  // 自定义返回逻辑，此时组件不会自动 navigateBack/switchTab
  uni.showModal({ title: '确认退出吗？', success: (res) => {
    if (res.confirm) uni.navigateBack()
  }})
}
</script>

自定义标题样式和图标

<wc-navbar 
  title="个性化标题" 
  :titleStyle="{ color: '#ff6b6b', fontSize: '36rpx', fontWeight: 'bold' }"
  :showBack="true"
  backIconColor="#ff6b6b"
  :backIconSize="24"
  backShape="circle"
/>

📋 Props 参数

📡 Events 事件

如果监听了 back 事件，组件将不会自动执行内置返回或首页跳转逻辑，完全交由开发者处理。

🧩 Slots 插槽

🔧 方法（通过 ref 调用）

totalNavHeight

组件向外暴露的总高度（Number），可用于页面顶部占位计算。

<wc-navbar ref="navbar" title="示例" />
<view :style="{ height: navbarHeight + 'px' }" />

<script setup>
import { ref, onMounted } from 'vue'
const navbar = ref(null)
const navbarHeight = ref(0)

onMounted(() => {
  // 注意：组件渲染后 totalNavHeight 才有效
  navbarHeight.value = navbar.value?.totalNavHeight || 0
})
</script>

⚠️ 注意事项

1. 仅微信小程序会自动获取胶囊按钮位置，其他平台会使用默认的右侧安全宽度（90px）。
2. 全宽模式 (contentWidth='100%') 下不会预留胶囊占位区域，右侧内容可能被胶囊遮挡，请视情况使用。
3. 使用玻璃效果 (glass) 时，建议将 bgColor 设为 'transparent'（默认），以确保玻璃纹理正常。
4. 组件内部通过 getCurrentPages() 判断是否为入口页，该行为仅对页面栈有效，Tabbar 页面请配置 homePath。
5. 若遇到返回逻辑不生效，请检查是否在 pages.json 中正确配置了页面路径，且未禁用默认返回手势。
6. up-icon 的名称为 uview-plus 内置图标库，请确保图标可用。
7. titleColor 优先级低于 titleStyle，若同时设置，titleStyle.color 会覆盖 titleColor。

📱 兼容性

• ✅ 微信小程序（完美适配胶囊）
• 由于业务需求，目前仅在微信小程序上调试过。您可以自行下载在其它平台调试。如需帮助，欢迎联系我～

🔖 更新日志

v1.0.1

• 新增 titleColor 属性，可快速设置标题颜色

v1.0.0

• 初始发布
• 支持固定定位、玻璃效果、胶囊安全区
• 保留 up-icon 依赖
• 提供返回按钮、标题、左右插槽
• 新增 backIconSize、backIconColor、titleStyle、zIndex、rightMargin 等灵活配置项
• 优化事件处理逻辑：监听 back 事件后自动跳过默认返回

📄 许可

MIT License

如有问题或建议，欢迎在插件市场评论区留言或提 issue。
Enjoy! 🎉