YGChatCS/components/TopNavBar/README.md

TopNavBar 顶部导航栏组件

一个功能完整的顶部导航栏组件，支持固定定位、自定义样式和插槽内容。

功能特性

• ✅ 支持固定在页面顶部（可配置）
• ✅ 自动适配状态栏高度
• ✅ 支持自定义标题和颜色
• ✅ 支持插槽自定义内容
• ✅ 内置返回按钮功能
• ✅ 响应式设计
• ✅ 深色模式支持
• ✅ 安全区域适配

基础用法

简单使用

<template>
  <TopNavBar title="页面标题" />
</template>

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

固定在顶部

<template>
  <TopNavBar title="页面标题" :fixed="true" />
</template>

自定义样式

<template>
  <TopNavBar 
    title="页面标题" 
    backgroundColor="#007AFF"
    titleColor="#ffffff"
    backIconColor="#ffffff"
  />
</template>

标题对齐方式

<template>
  <!-- 标题居中显示（默认） -->
  <TopNavBar title="居中标题" titleAlign="center" />
  
  <!-- 标题左对齐显示 -->
  <TopNavBar title="左对齐标题" titleAlign="left" />
</template>

使用插槽

<template>
  <TopNavBar>
    <template #title>
      <view class="custom-title">
        <text>自定义标题内容</text>
      </view>
    </template>
    
    <template #right>
      <uni-icons type="more" size="20" color="#333" />
    </template>
  </TopNavBar>
</template>

API

Props

参数	类型	默认值	说明
title	String	''	导航栏标题
fixed	Boolean	false	是否固定在页面顶部
showBack	Boolean	true	是否显示返回按钮
backgroundColor	String	'#ffffff'	背景颜色
titleColor	String	'#333333'	标题文字颜色
backIconColor	String	'#333333'	返回按钮图标颜色
hideStatusBar	Boolean	false	是否隐藏状态栏占位
zIndex	Number	999	层级索引
titleAlign	String	'center'	标题对齐方式，可选值：'center'、'left'

Events

事件名	说明	参数
back	点击返回按钮时触发	-

Slots

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

使用示例

订单列表页面

<template>
  <view>
    <TopNavBar>
      <template #title>
        <Tabs 
          :tabs="tabList" 
          :defaultActive="currentTabIndex" 
          @change="handleTabChange" 
        />
      </template>
    </TopNavBar>
    
    <!-- 页面内容 -->
    <view class="page-content">
      <!-- 内容区域 -->
    </view>
  </view>
</template>

商品详情页面

<template>
  <view>
    <TopNavBar 
      title="商品详情" 
      :fixed="true"
      @back="handleBack"
    >
      <template #right>
        <uni-icons type="share" size="20" color="#333" />
      </template>
    </TopNavBar>
    
    <!-- 页面内容 -->
    <view class="page-content">
      <!-- 内容区域 -->
    </view>
  </view>
</template>

<script setup>
const handleBack = () => {
  // 自定义返回逻辑
  console.log('自定义返回处理')
}
</script>

注意事项

1. 固定定位使用：当设置 fixed="true" 时，组件会固定在页面顶部，此时需要为页面内容添加适当的顶部间距。

2. 状态栏适配：组件会自动获取系统状态栏高度并进行适配，无需手动处理。

3. 返回按钮：默认点击返回按钮会执行 uni.navigateBack()，如果需要自定义返回逻辑，请监听 @back 事件。

4. 样式覆盖：如需自定义样式，建议通过 props 传入颜色值，或在父组件中使用深度选择器覆盖样式。

5. 插槽使用：title 插槽会完全替换默认的标题显示，right 插槽用于添加右侧操作按钮。

更新日志

v1.0.0

• 初始版本发布
• 支持基础导航栏功能
• 支持固定定位配置
• 支持自定义样式和插槽