277 lines
6.4 KiB
Markdown
277 lines
6.4 KiB
Markdown
# 自定义变色导航栏组件
|
||
|
||
## 概述
|
||
|
||
这是一个支持滚动时动态变色的自定义导航栏组件，通过配合 `page-scroll-mixin.js` 实现页面滚动监听和导航栏样式自动切换。
|
||
|
||
## 功能特性
|
||
|
||
- ✅ **自适应系统状态栏**：自动适配不同设备的状态栏高度
|
||
- ✅ **滚动变色效果**：页面滚动时导航栏背景色和阴影自动切换
|
||
- ✅ **平滑过渡动画**：CSS 过渡效果让颜色变化更自然
|
||
- ✅ **可配置参数**：支持自定义滚动阈值、背景色等
|
||
- ✅ **事件系统**：提供丰富的滚动事件供父组件监听
|
||
- ✅ **插槽支持**：右侧支持自定义内容
|
||
- ✅ **全局混入**：通过 Mixin 实现滚动逻辑自动处理
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
components/custom-navbar/
|
||
├── custom-navbar.vue # 导航栏组件
|
||
├── README.md # 文档说明
|
||
mixins/
|
||
├── page-scroll-mixin.js # 滚动监听混入
|
||
main.js # 全局混入注册
|
||
```
|
||
|
||
## 核心组件
|
||
|
||
### 1. custom-navbar.vue
|
||
|
||
#### Props 配置
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| title | String | "" | 导航栏标题 |
|
||
| backIcon | String | CommonEnum.BACK_BUTTON | 返回按钮图标 |
|
||
| showBack | Boolean | true | 是否显示返回按钮 |
|
||
| backgroundColor | String | CommonEnum.BASE_COLOR | 滚动时的背景色 |
|
||
| scrollThreshold | Number | 20 | 滚动阈值（px） |
|
||
| enableScrollEffect | Boolean | true | 是否启用滚动效果 |
|
||
|
||
#### 事件
|
||
|
||
| 事件名 | 参数 | 说明 |
|
||
|--------|------|------|
|
||
| back | - | 点击返回按钮时触发 |
|
||
| scroll-change | { isScrolled, scrollTop } | 滚动状态变化时触发 |
|
||
| scroll | { scrollTop, isScrolled } | 滚动时触发 |
|
||
|
||
#### 方法
|
||
|
||
| 方法名 | 参数 | 说明 |
|
||
|--------|------|------|
|
||
| handlePageScroll | e | 处理页面滚动事件（供 Mixin 调用） |
|
||
| setScrollState | scrollTop | 手动设置滚动状态 |
|
||
|
||
### 2. page-scroll-mixin.js
|
||
|
||
#### 功能
|
||
- 自动监听页面滚动事件
|
||
- 将滚动事件传递给配置的组件
|
||
- 支持多个组件同时监听
|
||
|
||
#### 配置选项
|
||
- `scrollRefs`: 需要传递滚动事件的组件 ref 数组，默认为 `['customNavbar']`
|
||
|
||
## 使用方法
|
||
|
||
### 1. 基础用法
|
||
|
||
```vue
|
||
<template>
|
||
<view class="page">
|
||
<custom-navbar ref="customNavbar" title="页面标题" />
|
||
<!-- 页面内容 -->
|
||
</view>
|
||
</template>
|
||
|
||
<script>
|
||
export default {
|
||
// 无需额外配置，全局混入已自动处理
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 2. 自定义配置
|
||
|
||
```vue
|
||
<template>
|
||
<view class="page">
|
||
<custom-navbar
|
||
ref="customNavbar"
|
||
title="自定义标题"
|
||
:scroll-threshold="50"
|
||
background-color="#ff6b6b"
|
||
@scroll-change="onScrollChange"
|
||
/>
|
||
</view>
|
||
</template>
|
||
|
||
<script>
|
||
export default {
|
||
methods: {
|
||
onScrollChange(data) {
|
||
console.log('滚动状态:', data.isScrolled);
|
||
console.log('滚动距离:', data.scrollTop);
|
||
}
|
||
}
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 3. 多个组件监听
|
||
|
||
```vue
|
||
<template>
|
||
<view class="page">
|
||
<custom-navbar ref="customNavbar" title="页面标题" />
|
||
<floating-button ref="floatingButton" />
|
||
</view>
|
||
</template>
|
||
|
||
<script>
|
||
export default {
|
||
scrollRefs: ['customNavbar', 'floatingButton']
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 4. 自定义右侧内容
|
||
|
||
```vue
|
||
<template>
|
||
<custom-navbar title="页面标题">
|
||
<template #right>
|
||
<view class="custom-right">
|
||
<text>自定义</text>
|
||
</view>
|
||
</template>
|
||
</custom-navbar>
|
||
</template>
|
||
```
|
||
|
||
## 全局配置
|
||
|
||
### main.js 中的配置
|
||
|
||
```javascript
|
||
// 引入滚动混入
|
||
import PageScrollMixin from "./mixins/page-scroll-mixin.js";
|
||
|
||
// 注册全局混入
|
||
Vue.mixin(PageScrollMixin);
|
||
```
|
||
|
||
通过全局混入，所有页面都会自动支持滚动监听功能。
|
||
|
||
## 样式说明
|
||
|
||
### 核心样式类
|
||
|
||
```scss
|
||
.custom-navbar {
|
||
position: fixed;
|
||
top: 0;
|
||
left: 0;
|
||
right: 0;
|
||
z-index: 999;
|
||
background-color: transparent;
|
||
transition: background-color 0.3s ease; /* 平滑过渡 */
|
||
}
|
||
|
||
.navbar-scrolled {
|
||
box-shadow: 0 2rpx 10rpx rgba(0, 0, 0, 0.1); /* 滚动时阴影 */
|
||
}
|
||
```
|
||
|
||
### 自适应布局
|
||
|
||
- **状态栏适配**：`paddingTop: statusBarHeight`
|
||
- **胶囊按钮适配**：自动计算导航栏高度
|
||
- **填充区**：避免内容被导航栏遮挡
|
||
|
||
## 工作原理
|
||
|
||
### 1. 滚动监听流程
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[页面滚动] --> B[onPageScroll 触发]
|
||
B --> C[Mixin 分发事件]
|
||
C --> D[customNavbar.handlePageScroll]
|
||
D --> E[判断滚动阈值]
|
||
E --> F{超过阈值?}
|
||
F -->|是| G[设置 isScrolled = true]
|
||
F -->|否| H[设置 isScrolled = false]
|
||
G --> I[更新样式和阴影]
|
||
H --> I
|
||
I --> J[触发 scroll-change 事件]
|
||
```
|
||
|
||
### 2. 样式切换机制
|
||
|
||
```javascript
|
||
// 动态样式绑定
|
||
:style="{
|
||
backgroundColor: isScrolled ? backgroundColor : 'transparent',
|
||
}"
|
||
|
||
// 动态类名绑定
|
||
:class="{ 'navbar-scrolled': isScrolled }"
|
||
```
|
||
|
||
## 实际应用示例
|
||
|
||
### activity.vue 页面使用
|
||
|
||
```vue
|
||
<template>
|
||
<view class="page">
|
||
<custom-navbar ref="customNavbar" title="寺庙活动" />
|
||
<view class="header">
|
||
<!-- 页面内容 -->
|
||
</view>
|
||
</view>
|
||
</template>
|
||
|
||
<script>
|
||
export default {
|
||
// 自动支持滚动监听，无需额外配置
|
||
}
|
||
</script>
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 性能优化
|
||
- 使用 `enableScrollEffect` 控制是否启用滚动效果
|
||
- 合理设置 `scrollThreshold` 避免频繁切换
|
||
|
||
### 2. 样式定制
|
||
- 通过 `backgroundColor` 属性自定义滚动时的背景色
|
||
- 使用 CSS 变量实现主题切换
|
||
|
||
### 3. 事件处理
|
||
- 监听 `scroll-change` 事件处理滚动状态变化
|
||
- 使用 `scroll` 事件获取实时滚动信息
|
||
|
||
## 注意事项
|
||
|
||
1. **必须设置 ref**：组件必须有 `ref="customNavbar"` 属性
|
||
2. **全局混入**：确保在 `main.js` 中注册了 `PageScrollMixin`
|
||
3. **系统适配**：组件会自动适配不同设备的状态栏高度
|
||
4. **性能考虑**：滚动监听可能影响性能，建议在不需要时禁用
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
|
||
1. **滚动效果不生效**
|
||
- 检查是否正确设置了 `ref="customNavbar"`
|
||
- 确认 `enableScrollEffect` 为 `true`
|
||
|
||
2. **样式异常**
|
||
- 检查 `backgroundColor` 属性是否正确设置
|
||
- 确认 CSS 样式没有被其他样式覆盖
|
||
|
||
3. **事件不触发**
|
||
- 确认全局混入已正确注册
|
||
- 检查组件是否正确引入
|
||
|
||
## 更新日志
|
||
|
||
- **v1.0.0**: 初始版本，支持基础滚动变色功能
|
||
- **v1.1.0**: 添加全局混入支持，简化使用方式
|
||
- **v1.2.0**: 优化性能，添加可配置选项 |