# TopNavBar 组件使用指南

## 组件概述

TopNavBar 是一个功能完整的顶部导航栏组件，专为 uni-app 项目设计。该组件支持固定定位、自定义样式、插槽内容等功能，可以满足大部分页面的导航需求。

## 核心特性

### 1. 可配置固定定位
- **默认行为**: 组件默认不固定，跟随页面滚动
- **固定模式**: 设置 `fixed="true"` 可将导航栏固定在页面顶部
- **自动适配**: 固定模式下自动处理状态栏高度和安全区域

### 2. 智能状态栏适配
- 自动获取系统状态栏高度
- 支持不同平台的导航栏高度适配（iOS: 44px, Android: 48px）
- 可选择隐藏状态栏占位区域

### 3. 灵活的自定义选项
- 支持自定义背景色、标题色、图标色
- 可控制返回按钮显示/隐藏
- 支持自定义 z-index 层级
- 支持标题对齐方式配置（居中/左对齐）

## 快速开始

### 基础使用

```vue
<!-- 最简单的使用方式 -->
<TopNavBar title="页面标题" />
```

### 固定在顶部

```vue
<!-- 固定导航栏，适合长页面滚动 -->
<template>
  <view class="page-container">
    <TopNavBar title="商品详情" :fixed="true" />
    <view class="page-content">
      <!-- 页面内容 -->
    </view>
  </view>
</template>

<style>
.page-content {
  /* 为固定导航栏预留空间 */
  padding-top: calc(var(--status-bar-height, 44px) + 44px);
}
</style>
```

### 自定义样式

```vue
<!-- 深色主题导航栏 -->
<TopNavBar 
  title="深色导航栏" 
  backgroundColor="#1a1a1a"
  titleColor="#ffffff"
  backIconColor="#ffffff"
/>

<!-- 品牌色导航栏 -->
<TopNavBar 
  title="品牌导航栏" 
  backgroundColor="#007AFF"
  titleColor="#ffffff"
  backIconColor="#ffffff"
/>

<!-- 左对齐标题 -->
<TopNavBar 
  title="左对齐标题" 
  titleAlign="left"
/>

<!-- 居中标题（默认） -->
<TopNavBar 
  title="居中标题" 
  titleAlign="center"
/>
```

## 高级用法

### 使用插槽自定义内容

```vue
<template>
  <TopNavBar>
    <!-- 自定义标题区域 -->
    <template #title>
      <view class="custom-title">
        <image src="/static/logo.png" class="logo" />
        <text class="brand-name">品牌名称</text>
      </view>
    </template>
    
    <!-- 自定义右侧操作 -->
    <template #right>
      <view class="nav-actions">
        <uni-icons type="search" size="20" @click="handleSearch" />
        <uni-icons type="more" size="20" @click="showMore" />
      </view>
    </template>
  </TopNavBar>
</template>

<style>
.custom-title {
  display: flex;
  align-items: center;
  
  .logo {
    width: 24px;
    height: 24px;
    margin-right: 8px;
  }
  
  .brand-name {
    font-size: 18px;
    font-weight: 600;
  }
}

.nav-actions {
  display: flex;
  align-items: center;
  gap: 15px;
}
</style>
```

### 监听返回事件

```vue
<template>
  <TopNavBar 
    title="自定义返回" 
    @back="handleCustomBack"
  />
</template>

<script setup>
const handleCustomBack = () => {
  // 自定义返回逻辑
  uni.showModal({
    title: '提示',
    content: '确定要离开当前页面吗？',
    success: (res) => {
      if (res.confirm) {
        uni.navigateBack()
      }
    }
  })
}
</script>
```

## 实际应用场景

### 1. 商品详情页

```vue
<template>
  <view class="goods-detail">
    <TopNavBar 
      title="商品详情" 
      :fixed="true"
      backgroundColor="rgba(255, 255, 255, 0.95)"
    >
      <template #right>
        <uni-icons type="share" size="20" @click="shareGoods" />
      </template>
    </TopNavBar>
    
    <view class="goods-content">
      <!-- 商品内容 -->
    </view>
  </view>
</template>
```

### 2. 订单列表页

```vue
<template>
  <view class="order-list">
    <TopNavBar>
      <template #title>
        <Tabs 
          :tabs="orderTabs" 
          :active="activeTab" 
          @change="switchTab"
        />
      </template>
    </TopNavBar>
    
    <view class="order-content">
      <!-- 订单列表 -->
    </view>
  </view>
</template>
```

### 3. 聊天页面

```vue
<template>
  <view class="chat-page">
    <TopNavBar 
      title="客服小沐" 
      :fixed="true"
      backgroundColor="#f8f9fa"
    >
      <template #right>
        <uni-icons type="phone" size="20" @click="makeCall" />
      </template>
    </TopNavBar>
    
    <view class="chat-content">
      <!-- 聊天内容 -->
    </view>
  </view>
</template>
```

## 最佳实践

### 1. 固定导航栏的页面布局

```scss
// 推荐的页面结构
.page-container {
  .page-content {
    // 方法1: 使用 padding-top
    padding-top: calc(var(--status-bar-height, 44px) + 44px);
    
    // 方法2: 使用 margin-top
    // margin-top: calc(var(--status-bar-height, 44px) + 44px);
  }
}
```

### 2. 响应式设计

```scss
// 适配不同屏幕尺寸
@media screen and (max-width: 375px) {
  .page-content {
    padding-top: calc(var(--status-bar-height, 44px) + 40px);
  }
}
```

### 3. 主题适配

```vue
<script setup>
import { computed } from 'vue'

// 根据系统主题动态调整颜色
const navBarStyle = computed(() => {
  const isDark = uni.getSystemInfoSync().theme === 'dark'
  return {
    backgroundColor: isDark ? '#1a1a1a' : '#ffffff',
    titleColor: isDark ? '#ffffff' : '#333333',
    backIconColor: isDark ? '#ffffff' : '#333333'
  }
})
</script>

<template>
  <TopNavBar 
    title="自适应主题" 
    :backgroundColor="navBarStyle.backgroundColor"
    :titleColor="navBarStyle.titleColor"
    :backIconColor="navBarStyle.backIconColor"
  />
</template>
```

## 注意事项

1. **固定定位的性能考虑**: 固定导航栏会创建新的层叠上下文，在复杂页面中可能影响性能

2. **状态栏适配**: 在不同设备上状态栏高度可能不同，组件会自动处理，但建议在测试时验证各种设备

3. **插槽内容**: 使用插槽时注意内容的响应式设计，确保在不同屏幕尺寸下都能正常显示

4. **z-index 管理**: 如果页面中有其他固定定位元素，注意调整 z-index 避免层级冲突

5. **返回按钮**: 默认返回行为是 `uni.navigateBack()`，如需自定义请监听 `@back` 事件

## 故障排除

### 常见问题

**Q: 固定导航栏下的内容被遮挡了？**
A: 需要为页面内容添加顶部间距，参考上面的最佳实践。

**Q: 在某些设备上状态栏高度不正确？**
A: 组件会自动获取状态栏高度，如果仍有问题，可以手动设置 `hideStatusBar="true"` 并自行处理。

**Q: 自定义颜色不生效？**
A: 确保传入的颜色值格式正确，支持 hex、rgb、rgba 等标准 CSS 颜色格式。

**Q: 插槽内容显示异常？**
A: 检查插槽内容的样式，确保没有影响导航栏布局的 CSS 属性。