更新记录

v1.0.0（2026-01-29）

内置状态栏/标题栏高度计算（适配胶囊按钮）

顶部背景图宽度 100% 等比自适应（mode="widthFix"）

导航 fixed，并自动生成占位，避免页面内容被遮挡

支持自定义标题、返回逻辑、z-index、分割线颜色/粗细

父组件可直接拿到导航高度（无需额外工具库）

平台兼容性

uni-app(4.87)

其他

::: container ::: {.section .section .quick-start}

🚀 快速开始 {#快速开始 .section-title}

安装并引入组件后，您可以快速在项目中使用CustomTopNavBar：

::: code-block ::: code-header Vue组件使用示例

复制代码 :::

<template>
  <CustomTopNavBar title="首页" />
  <view>页面内容...</view>
</template>

<script setup>
import CustomTopNavBar from '@/components/CustomTopNavBar.vue'
</script>

:::

::: nav-demo

::: nav-title 首页 :::

::: {style="width: 40px;"} :::

::: nav-border ::: ::: :::

::: {.section .section}

🔧 常用示例 {#常用示例 .section-title}

以下是一些常见的使用场景示例：

::: examples-grid ::: example-card ::: example-header 自定义背景图 :::

::: example-content ::: code-block

<CustomTopNavBar
  title="首页"
  bg="https://your-cdn.com/top-bg.svg"
/>

:::

::: {.nav-demo .bg-image}

::: nav-title 首页 :::

::: {style="width: 40px;"} :::

::: nav-border ::: ::: ::: :::

::: example-card ::: example-header 隐藏返回按钮 :::

::: example-content ::: code-block

<CustomTopNavBar
  title="首页"
  :showBack="false"
/>

:::

::: nav-demo ::: {.nav-title style="margin: 0 auto;"} 首页 :::

::: nav-border ::: ::: ::: :::

::: example-card ::: example-header 自定义返回逻辑 :::

::: example-content ::: code-block

<script setup>
const goHome = () => {
  uni.reLaunch({ url: '/pages/index/index' })
}
</script>

<template>
  <CustomTopNavBar title="详情页" :back="goHome" />
</template>

::: ::: ::: :::

::: {.examples-grid style="margin-top: 20px;"} ::: example-card ::: example-header 自定义标题/图标颜色 :::

::: example-content ::: code-block

<CustomTopNavBar
  title="设置"
  titleColor="#FFFFFF"
  iconColor="#FFFFFF"
/>

:::

::: {.nav-demo style="background-color: #3498db;"}

::: nav-title 设置 :::

::: {style="width: 40px;"} :::

::: nav-border ::: ::: ::: :::

::: example-card ::: example-header 自定义分割线样式 :::

::: example-content ::: code-block

<CustomTopNavBar
  :showBorder="true"
  borderColor="rgba(0,0,0,0.15)"
  :borderWidth="2"
/>

:::

::: nav-demo

::: nav-title 页面标题 :::

::: {style="width: 40px;"} :::

::: {.nav-border .thick} ::: ::: ::: :::

::: example-card ::: example-header 关闭分割线 :::

::: example-content ::: code-block

<CustomTopNavBar :showBorder="false" />

:::

::: nav-demo

::: nav-title 无边框导航 :::

::: {style="width: 40px;"} ::: ::: ::: ::: ::: :::

::: {.section .section}

⚙️ Props 参数说明 {#props-参数说明 .section-title}

组件支持以下配置参数：

参数 类型 默认值 说明

title String 自定义标题 页面标题 showBack Boolean true 是否显示返回按钮 back Function null 自定义返回逻辑 bg String 默认背景图 顶部背景图 titleColor String #D1D1D3 标题颜色 iconColor String #D1D1D3 返回图标颜色 navZIndex Number 10 导航层级 bgZIndex Number 0 背景层级 showBorder Boolean true 是否显示底部分割线 borderColor String rgba(255,255,255,0.08) 分割线颜色 borderWidth Number / String 1 分割线粗细 :::

::: {.section .section}

📏 获取导航高度（无需工具库） {#获取导航高度无需工具库 .section-title}

组件暴露了导航栏相关的高度信息，可直接在Vue组件中访问：

::: code-block ::: code-header 获取导航高度示例

复制代码 :::

<script setup>
import { ref, onMounted } from 'vue'

const navRef = ref(null)

onMounted(() => {
  console.log('状态栏高度:', navRef.value.statusBarHeight)
  console.log('标题栏高度:', navRef.value.titleBarHeight)
  console.log('导航总高度:', navRef.value.navBarHeight)
})
</script>

<template>
  <CustomTopNavBar ref="navRef" title="页面标题" />
</template>

:::

暴露字段 {#暴露字段 style="margin-top: 25px; color: var(--primary);"}

名称 说明

statusBarHeight 状态栏高度（px） titleBarHeight 标题栏高度（px） navBarHeight 导航总高度（px） getLeftIconLeft 抖音小程序左侧 LOGO 遮挡适配 :::

::: {.section .section}

⚠️ 使用说明 {#使用说明 .section-title}

::: warning-box

重要注意事项

• 本组件适合 顶部导航 + 视觉背景：组件设计用于提供视觉装饰性的顶部导航栏，与页面背景融合
• 背景不参与布局，仅作为装饰层：组件的背景图不会影响页面布局，仅作为视觉装饰
• 不推荐作为 Banner / 轮播组件使用：组件的主要功能是导航，不适合承载复杂的内容展示
• 兼容性：组件已适配多种小程序平台，包括微信、支付宝、抖音等
• 性能优化：建议对背景图进行压缩和CDN加速，以获得最佳性能 :::

最佳实践 {#最佳实践 style="margin-top: 25px; color: var(--primary);"}

::: code-block ::: code-header 完整示例

复制代码 :::

<template>
  <CustomTopNavBar
    title="用户中心"
    :showBack="true"
    bg="https://example.com/nav-bg.png"
    titleColor="#FFFFFF"
    iconColor="#FFFFFF"
    :showBorder="true"
    borderColor="rgba(255,255,255,0.2)"
    :borderWidth="1"
  />

  <view class="content">
    <!-- 页面内容 -->
  </view>
</template>

<script setup>
import CustomTopNavBar from '@/components/CustomTopNavBar.vue'
import { ref } from 'vue'

const navRef = ref(null)

// 在需要时获取导航高度
const getNavHeight = () => {
  if (navRef.value) {
    return navRef.value.navBarHeight
  }
  return 0
}
</script>

<style scoped>
.content {
  padding-top: calc(var(--nav-height) + 20px);
}
</style>

::: ::: :::

::: container CustomTopNavBar 组件教程 © 2023 | 本页面为静态示例，实际使用时请参考Vue组件文档

使用 HTML、CSS、JavaScript 构建 :::