176 lines
3.9 KiB
Markdown
176 lines
3.9 KiB
Markdown
# TopNavBar 顶部导航栏组件
|
||
|
||
一个功能完整的顶部导航栏组件，支持固定定位、自定义样式和插槽内容。
|
||
|
||
## 功能特性
|
||
|
||
- ✅ 支持固定在页面顶部（可配置）
|
||
- ✅ 自动适配状态栏高度
|
||
- ✅ 支持自定义标题和颜色
|
||
- ✅ 支持插槽自定义内容
|
||
- ✅ 内置返回按钮功能
|
||
- ✅ 响应式设计
|
||
- ✅ 深色模式支持
|
||
- ✅ 安全区域适配
|
||
|
||
## 基础用法
|
||
|
||
### 简单使用
|
||
```vue
|
||
<template>
|
||
<TopNavBar title="页面标题" />
|
||
</template>
|
||
|
||
<script setup>
|
||
import TopNavBar from '@/components/TopNavBar/index.vue'
|
||
</script>
|
||
```
|
||
|
||
### 固定在顶部
|
||
```vue
|
||
<template>
|
||
<TopNavBar title="页面标题" :fixed="true" />
|
||
</template>
|
||
```
|
||
|
||
### 自定义样式
|
||
```vue
|
||
<template>
|
||
<TopNavBar
|
||
title="页面标题"
|
||
backgroundColor="#007AFF"
|
||
titleColor="#ffffff"
|
||
backIconColor="#ffffff"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
### 标题对齐方式
|
||
```vue
|
||
<template>
|
||
<!-- 标题居中显示（默认） -->
|
||
<TopNavBar title="居中标题" titleAlign="center" />
|
||
|
||
<!-- 标题左对齐显示 -->
|
||
<TopNavBar title="左对齐标题" titleAlign="left" />
|
||
</template>
|
||
```
|
||
|
||
### 使用插槽
|
||
```vue
|
||
<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 | 自定义右侧内容 |
|
||
|
||
## 使用示例
|
||
|
||
### 订单列表页面
|
||
```vue
|
||
<template>
|
||
<view>
|
||
<TopNavBar>
|
||
<template #title>
|
||
<Tabs
|
||
:tabs="tabList"
|
||
:defaultActive="currentTabIndex"
|
||
@change="handleTabChange"
|
||
/>
|
||
</template>
|
||
</TopNavBar>
|
||
|
||
<!-- 页面内容 -->
|
||
<view class="page-content">
|
||
<!-- 内容区域 -->
|
||
</view>
|
||
</view>
|
||
</template>
|
||
```
|
||
|
||
### 商品详情页面
|
||
```vue
|
||
<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
|
||
- 初始版本发布
|
||
- 支持基础导航栏功能
|
||
- 支持固定定位配置
|
||
- 支持自定义样式和插槽 |