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