自定义导航栏文档更新
This commit is contained in:
WindowBird
parent
d3b70eaf59
commit
238578b1f4
|
|
@ -1,171 +1,277 @@
|
||||||
# Custom Navbar 组件使用说明
|
# 自定义变色导航栏组件
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
|
||||||
|
这是一个支持滚动时动态变色的自定义导航栏组件，通过配合 `page-scroll-mixin.js` 实现页面滚动监听和导航栏样式自动切换。
|
||||||
|
|
||||||
## 功能特性
|
## 功能特性
|
||||||
|
|
||||||
- 自动监听页面滚动
|
- ✅ **自适应系统状态栏**：自动适配不同设备的状态栏高度
|
||||||
- 滚动时导航栏变为纯色背景
|
- ✅ **滚动变色效果**：页面滚动时导航栏背景色和阴影自动切换
|
||||||
- 回到顶部时导航栏变为透明
|
- ✅ **平滑过渡动画**：CSS 过渡效果让颜色变化更自然
|
||||||
- 支持自定义背景色和滚动阈值
|
- ✅ **可配置参数**：支持自定义滚动阈值、背景色等
|
||||||
- 提供滚动状态事件回调
|
- ✅ **事件系统**：提供丰富的滚动事件供父组件监听
|
||||||
|
- ✅ **插槽支持**：右侧支持自定义内容
|
||||||
|
- ✅ **全局混入**：通过 Mixin 实现滚动逻辑自动处理
|
||||||
|
|
||||||
## 基本用法
|
## 文件结构
|
||||||
|
|
||||||
```vue
|
```
|
||||||
<template>
|
components/custom-navbar/
|
||||||
<view>
|
├── custom-navbar.vue # 导航栏组件
|
||||||
<custom-navbar title="页面标题" />
|
├── README.md # 文档说明
|
||||||
<!-- 页面内容 -->
|
mixins/
|
||||||
</view>
|
├── page-scroll-mixin.js # 滚动监听混入
|
||||||
</template>
|
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
|
```vue
|
||||||
<template>
|
<template>
|
||||||
<view>
|
<view class="page">
|
||||||
<custom-navbar
|
<custom-navbar ref="customNavbar" title="页面标题" />
|
||||||
title="古刹巡礼"
|
|
||||||
:backgroundColor="'#FAF8F3'"
|
|
||||||
:scrollThreshold="100"
|
|
||||||
:enableScrollEffect="true"
|
|
||||||
@scroll-change="onScrollChange"
|
|
||||||
@scroll="onScroll"
|
|
||||||
>
|
|
||||||
<template #right>
|
|
||||||
<view class="right-button">更多</view>
|
|
||||||
</template>
|
|
||||||
</custom-navbar>
|
|
||||||
|
|
||||||
<!-- 页面内容 -->
|
<!-- 页面内容 -->
|
||||||
</view>
|
</view>
|
||||||
</template>
|
</template>
|
||||||
|
|
||||||
<script>
|
<script>
|
||||||
export default {
|
export default {
|
||||||
methods: {
|
// 无需额外配置，全局混入已自动处理
|
||||||
onScrollChange(data) {
|
}
|
||||||
console.log('滚动状态变化:', data.isScrolled)
|
|
||||||
},
|
|
||||||
onScroll(data) {
|
|
||||||
console.log('滚动位置:', data.scrollTop)
|
|
||||||
},
|
|
||||||
},
|
|
||||||
}
|
|
||||||
</script>
|
</script>
|
||||||
```
|
```
|
||||||
|
|
||||||
## Props 参数
|
### 2. 自定义配置
|
||||||
|
|
||||||
| 参数 | 类型 | 默认值 | 说明 |
|
```vue
|
||||||
| ------------------ | ------- | ---------------------- | ---------------- |
|
<template>
|
||||||
| title | String | '' | 导航栏标题 |
|
<view class="page">
|
||||||
| backIcon | String | CommonEnum.BACK_BUTTON | 返回按钮图标 |
|
<custom-navbar
|
||||||
| showBack | Boolean | true | 是否显示返回按钮 |
|
ref="customNavbar"
|
||||||
| backgroundColor | String | '#ffffff' | 滚动时的背景色 |
|
title="自定义标题"
|
||||||
| scrollThreshold | Number | 50 | 滚动阈值（像素） |
|
:scroll-threshold="50"
|
||||||
| enableScrollEffect | Boolean | true | 是否启用滚动效果 |
|
background-color="#ff6b6b"
|
||||||
|
@scroll-change="onScrollChange"
|
||||||
|
/>
|
||||||
|
</view>
|
||||||
|
</template>
|
||||||
|
|
||||||
## Events 事件
|
<script>
|
||||||
|
export default {
|
||||||
|
methods: {
|
||||||
|
onScrollChange(data) {
|
||||||
|
console.log('滚动状态:', data.isScrolled);
|
||||||
|
console.log('滚动距离:', data.scrollTop);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
</script>
|
||||||
|
```
|
||||||
|
|
||||||
| 事件名 | 参数 | 说明 |
|
### 3. 多个组件监听
|
||||||
| ------------- | ------------------------- | ------------------ |
|
|
||||||
| back | - | 点击返回按钮时触发 |
|
|
||||||
| scroll-change | { isScrolled, scrollTop } | 滚动状态变化时触发 |
|
|
||||||
| scroll | { scrollTop, isScrolled } | 页面滚动时触发 |
|
|
||||||
|
|
||||||
## 方法
|
```vue
|
||||||
|
<template>
|
||||||
|
<view class="page">
|
||||||
|
<custom-navbar ref="customNavbar" title="页面标题" />
|
||||||
|
<floating-button ref="floatingButton" />
|
||||||
|
</view>
|
||||||
|
</template>
|
||||||
|
|
||||||
| 方法名 | 参数 | 说明 |
|
<script>
|
||||||
| -------------- | --------- | ---------------- |
|
export default {
|
||||||
| setScrollState | scrollTop | 手动设置滚动状态 |
|
scrollRefs: ['customNavbar', 'floatingButton']
|
||||||
|
}
|
||||||
|
</script>
|
||||||
|
```
|
||||||
|
|
||||||
## 样式定制
|
### 4. 自定义右侧内容
|
||||||
|
|
||||||
组件会自动添加以下 CSS 类：
|
```vue
|
||||||
|
<template>
|
||||||
|
<custom-navbar title="页面标题">
|
||||||
|
<template #right>
|
||||||
|
<view class="custom-right">
|
||||||
|
<text>自定义</text>
|
||||||
|
</view>
|
||||||
|
</template>
|
||||||
|
</custom-navbar>
|
||||||
|
</template>
|
||||||
|
```
|
||||||
|
|
||||||
- `.navbar-scrolled`: 滚动状态下的样式
|
## 全局配置
|
||||||
- 过渡动画：背景色变化有 0.3s 的过渡效果
|
|
||||||
- 阴影效果：滚动时自动添加阴影
|
### 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. **重要**：需要在父页面的 `onPageScroll` 生命周期中调用组件的 `handlePageScroll` 方法
|
1. **必须设置 ref**：组件必须有 `ref="customNavbar"` 属性
|
||||||
2. 滚动效果默认启用，可通过 `enableScrollEffect` 关闭
|
2. **全局混入**：确保在 `main.js` 中注册了 `PageScrollMixin`
|
||||||
3. 背景色变化有平滑过渡动画
|
3. **系统适配**：组件会自动适配不同设备的状态栏高度
|
||||||
4. 组件使用 `ref` 引用，确保在页面中正确引用
|
4. **性能考虑**：滚动监听可能影响性能，建议在不需要时禁用
|
||||||
|
|
||||||
## 完整使用示例
|
## 故障排除
|
||||||
|
|
||||||
### 方法一：使用 Mixin（推荐）
|
### 常见问题
|
||||||
|
|
||||||
```vue
|
1. **滚动效果不生效**
|
||||||
<template>
|
- 检查是否正确设置了 `ref="customNavbar"`
|
||||||
<view>
|
- 确认 `enableScrollEffect` 为 `true`
|
||||||
<custom-navbar
|
|
||||||
ref="customNavbar"
|
|
||||||
title="页面标题"
|
|
||||||
backgroundColor="#FAF8F3"
|
|
||||||
:scrollThreshold="50"
|
|
||||||
@scroll-change="onScrollChange"
|
|
||||||
/>
|
|
||||||
<!-- 页面内容 -->
|
|
||||||
</view>
|
|
||||||
</template>
|
|
||||||
|
|
||||||
<script>
|
2. **样式异常**
|
||||||
import CustomNavbar from '@/components/custom-navbar/custom-navbar.vue'
|
- 检查 `backgroundColor` 属性是否正确设置
|
||||||
import PageScrollMixin from '@/mixins/page-scroll-mixin.js'
|
- 确认 CSS 样式没有被其他样式覆盖
|
||||||
|
|
||||||
export default {
|
3. **事件不触发**
|
||||||
mixins: [PageScrollMixin], // 自动处理滚动事件
|
- 确认全局混入已正确注册
|
||||||
components: {
|
- 检查组件是否正确引入
|
||||||
CustomNavbar,
|
|
||||||
},
|
|
||||||
methods: {
|
|
||||||
onScrollChange(data) {
|
|
||||||
console.log('滚动状态变化:', data.isScrolled)
|
|
||||||
},
|
|
||||||
},
|
|
||||||
}
|
|
||||||
</script>
|
|
||||||
```
|
|
||||||
|
|
||||||
### 方法二：手动处理
|
## 更新日志
|
||||||
|
|
||||||
```vue
|
- **v1.0.0**: 初始版本，支持基础滚动变色功能
|
||||||
<template>
|
- **v1.1.0**: 添加全局混入支持，简化使用方式
|
||||||
<view>
|
- **v1.2.0**: 优化性能，添加可配置选项
|
||||||
<custom-navbar
|
|
||||||
ref="customNavbar"
|
|
||||||
title="页面标题"
|
|
||||||
backgroundColor="#FAF8F3"
|
|
||||||
:scrollThreshold="50"
|
|
||||||
@scroll-change="onScrollChange"
|
|
||||||
/>
|
|
||||||
<!-- 页面内容 -->
|
|
||||||
</view>
|
|
||||||
</template>
|
|
||||||
|
|
||||||
<script>
|
|
||||||
import CustomNavbar from '@/components/custom-navbar/custom-navbar.vue'
|
|
||||||
|
|
||||||
export default {
|
|
||||||
components: {
|
|
||||||
CustomNavbar,
|
|
||||||
},
|
|
||||||
// 页面生命周期 - 必须添加
|
|
||||||
onPageScroll(e) {
|
|
||||||
// 将页面滚动事件传递给导航栏组件
|
|
||||||
if (this.$refs.customNavbar) {
|
|
||||||
this.$refs.customNavbar.handlePageScroll(e)
|
|
||||||
}
|
|
||||||
},
|
|
||||||
methods: {
|
|
||||||
onScrollChange(data) {
|
|
||||||
console.log('滚动状态变化:', data.isScrolled)
|
|
||||||
},
|
|
||||||
},
|
|
||||||
}
|
|
||||||
</script>
|
|
||||||
```
|
|
||||||
Loading…
Reference in New Issue
Block a user