buddhism/components/custom-navbar/README.md

# 自定义变色导航栏组件

## 概述

这是一个支持滚动时动态变色的自定义导航栏组件，通过配合 `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**: 优化性能，添加可配置选项