buddhism/components/custom-navbar

自定义变色导航栏组件

概述

这是一个支持滚动时动态变色的自定义导航栏组件，通过配合 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. 基础用法

<template>
  <view class="page">
    <custom-navbar ref="customNavbar" title="页面标题" />
    <!-- 页面内容 -->
  </view>
</template>

<script>
export default {
  // 无需额外配置，全局混入已自动处理
}
</script>

2. 自定义配置

<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. 多个组件监听

<template>
  <view class="page">
    <custom-navbar ref="customNavbar" title="页面标题" />
    <floating-button ref="floatingButton" />
  </view>
</template>

<script>
export default {
  scrollRefs: ['customNavbar', 'floatingButton']
}
</script>

4. 自定义右侧内容

<template>
  <custom-navbar title="页面标题">
    <template #right>
      <view class="custom-right">
        <text>自定义</text>
      </view>
    </template>
  </custom-navbar>
</template>

全局配置

main.js 中的配置

// 引入滚动混入
import PageScrollMixin from "./mixins/page-scroll-mixin.js";

// 注册全局混入
Vue.mixin(PageScrollMixin);

通过全局混入，所有页面都会自动支持滚动监听功能。

样式说明

核心样式类

.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. 滚动监听流程

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. 样式切换机制

// 动态样式绑定
:style="{
  backgroundColor: isScrolled ? backgroundColor : 'transparent',
}"

// 动态类名绑定
:class="{ 'navbar-scrolled': isScrolled }"

实际应用示例

activity.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: 优化性能，添加可配置选项