312 lines
6.6 KiB
Markdown
312 lines
6.6 KiB
Markdown
# 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 属性。 |